一句话定位

engramory 把 Engramory 记忆纪律带到 DSH：宿主里始终加载一份"索引不超过 200 行 / 25 KB"的常驻规则，并把这条上限变成真正会被拒绝的硬卡口（一旦返回拒绝原因，后面的监听器无法再翻案），同时向宿主注册一条同名 skill，确保协议随插件一起到位。

核心能力

• 把 MEMORY.md 的 200 行 / 25 KB 双维度上限作为同步拒绝规则植入 DSH 的写前守卫，超 cap 且继续变大的写入会直接被拦下
• 渐进式压缩始终放行：超 cap 的索引只要被缩小就允许写入，210 → 205 → 198 这种逐次瘦身可以一路走通
• 智能判断"只读 vs 改写"：read、view、ls 和任何未识别的工具一律放行，超 cap 的索引必须仍可被读取，否则压缩无从下手
• 自动模拟可还原的部分编辑（edit / str_replace 等携带 old_str/new_str 的写入），按模拟结果而非参数大小判定是否拒绝
• 整文件覆写与 str_replace_editor 的 create / str_replace / insert 三种命令都被覆盖，未能模拟的局部写入在已超 cap 的索引上也会拒绝并提示改用整文件覆写
• 索引文件名按大小写不敏感匹配（Windows/macOS 上 memory.md 即 MEMORY.md），但只看 basename，不影响其它同名目录里的无关文件

技术实现

• 语言: JavaScript (ESM)
• 关键依赖: 零依赖（仅用 node:fs 的 readFileSync、node:path 的 basename）；通过 peerDependencies 声明对 @deepseek-ai/dsh-tools >=0.0.1-rc.1 的接口依赖
• 架构模式: 通过 dsh.bundle 把 cordis.patch.yml 注入 profile 的插件树，补丁插入一行 id: engramory 的配置（含 indexName / maxLines / maxBytes 默认值）；运行时通过 ctx.tools.guard() 注册同步写前守卫、并可选地通过 ctx.skills.register() 以 source: 'runtime' 贡献同名 skill
• 入口文件: adapters/dsh/plugin/index.js

适用场景

你在 DSH 里跑长任务，希望用一个轻量的本地文件记忆库（一个 MEMORY.md 索引 + 多个 detail 笔记）跨会话记住关键事实，但担心索引越长越失控——超出加载窗口的那部分会被静默丢掉、永远不会被召回。装上这个插件之后，写入越界会被直接拒绝、提示你按规约压缩，普通 read 仍能正常进行。如果你只用 DSH 但其它宿主（Claude Code 等）的原生 cap 已经够用，本插件的作用就是把"规则 + 让模型自己跑 check 工具"的弱保证升级成"工具调用层就被截住"的强保证。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:tinqiao-oss/engramory

配置项

DSH profile 的 patch 层会在插件加载时插入一行 id: engramory，其 config 字段即下表内容；若想自定义请在你的 profile 里以 - id: engramory 覆写整段，并把想保留的键重新列全（patch 会整段替换而非合并）。

常见问题

Q: 安装这个插件之后会自动生成我的记忆库吗？

A: 不会。插件只负责把 200 行/25 KB 上限变成硬卡口、再向宿主注册一条名为 engramory 的 skill；记忆库和常驻规则文件需要单独跑 Engramory 仓库里的 python tools/engramory_init.py dsh --install-skill 创建。

Q: 索引被改超之后还能不能压缩？

A: 能，而且必须能。判定规则是"写入让索引超过上限且比当前文件更大才拒绝"——一个 210 行的索引被压缩到 205、再到 198 都会放行，渐进式压缩始终可行，不会把你锁死。

Q: 看到拒绝提示该怎么办？

A: 拒绝原因里会直接告诉你当前行数 / 字节数与上限。把长行拆成"一句话要点 + 链接"，合并重复条目，归档冷笔记，然后用整文件覆写（write 或 str_replace_editor 的 create）一次性压缩；下一次整文件写入就会通过。

Q: 想调整上限大小去哪改？

A: 不要在原 profile 里再加一条 - insert:，那样会出现两个 engramory 行、原 caps 仍生效。正确做法是在你 profile 自己的 patch 层里以 - id: engramory 覆写该行的 config，并且把全部想保留的键重新列出来（patch 是整段替换）。

Q: 是否包含原生模块？

A: 不包含。插件是纯 ESM，只用 node:fs 和 node:path 两个内置模块，没有 node-gyp、不挑 Node ABI，三个主流操作系统都能跑。

Q: 读 MEMORY.md 会被拦吗？

A: 不会。守卫只对已知会改文件的工具（write/edit/str_replace 等）做裁决，read、view、ls 和任何未识别的工具一律放行——这正是设计选择：超 cap 的索引必须仍可被读，否则就陷入"想压缩却看不到内容"的死锁。

Q: 为什么 dsh plugin add 在 dsh 0.1.0-rc.6 上装不上？

A: 这是上游 dsh 的 preview 打包问题：dsh plugin 命令走未捆绑的 pnpm，并且依赖的 @deepseek-ai/dsh-type-meta 在 registry 上找不到。修复发布前，插件本体的决定表仍由仓库自带的 21 个 node --test 用例守住，可信度未受影响。

上手难度

入门 — 安装就是一条命令；cordis.patch.yml 已把合理的默认 caps 注入 profile，普通用户基本不需要再改配置，只有"想换索引文件名"或"想放宽上限"的进阶用户需要动 patch。

已知问题与限制

• insert 这类无法从参数还原结果的局部写入，若从"未超 cap"一次性跨过 cap，当前守卫不会立刻发现；下一次整文件覆写会被拦下，或通过外部 engramory_check.py 检出。已超 cap 的索引再做这类不可模拟的局部写入一定会被拦下。
• 守卫的工具名单按 dsh 文档化的 tool-fs 契约覆盖（write / edit 用 file_path、str_replace_editor 用 path），对未知工具一律放行；这是纪律护栏而不是安全边界，误拦 read 的代价远高于漏放一次写。
• DSH 仍是开发者预览，宿主插件 API 可能再变；本插件只触碰 ctx.tools.guard() 与 ctx.skills.register() 两个面，迁移成本被刻意压到最低。
• 第三方插件通过 dsh plugin 命令安装到 profile 在 dsh 0.1.0-rc.6 上尚不可用（上游打包问题，不是本插件缺陷），期间只能用源码级方式直接挂载插件本体。
• 插件不会替你创建 MEMORY.md 或常驻规则文件——记忆库本身需要按 Engramory 协议另行初始化。

English | 简体中文

Engramory

An opinionated, zero-infrastructure memory protocol for small-scale, local, file-based agent memory — a strict curation discipline plus a validator (tools/engramory_doctor.py), loaded as standing rules (CLAUDE.md / AGENTS.md / your host's rules file). It is not a database, a framework, or a relevance-loaded skill. Memory is a folder of small, human-readable markdown files plus one always-loaded index. No database, no embeddings, no server — just plain-text files you can open, read, edit, and diff in any editor (the live store itself stays git-ignored).

Engramory — coined from engram (the physical trace a memory leaves in the brain) + memory. Here: one file = one fact.

🤖 Are you an AI agent, asked to install or check this? Start at AGENT-SETUP.md, not at the install steps below. It is the procedure for working out what your host can actually enforce, whether a store already exists, what you must not touch, and what to tell the user — the parts agents reliably get wrong when improvising.

Status: 0.8.0 — experimental. The hard index cap (a PreToolUse hook) is deterministic for the matched direct-edit tools (Edit | Write | MultiEdit) but NOT a global write guard (shell tools — Bash, PowerShell, a background Monitor command — plus MCP file tools, external editors, and sync clients bypass it); the discipline loads as standing rules the model follows, so it's best-effort, not guaranteed on every task (see SKILL.md §8). Assumes a single writer / serialized writes. Don't rely on it as a "mandatory, reliable, cross-agent" memory layer yet.

---

What this is — and is NOT

Engramory is not a new memory architecture. The "markdown files + a small index loaded into context + the model curates it" pattern is now the mainstream shape for agent memory, and it ships in several places already. Engramory stands on:

• Claude Code native auto-memory — the same markdown-MEMORY.md-index + lazy detail-file pattern; its system prompt even uses the same user | feedback | project | reference type vocabulary (per anthropics/claude-code#58840; the public docs describe only the index + topic files). Engramory is a disciplined superset of this default.
• basic-memory — markdown source-of-truth, YAML frontmatter type, [[wikilink]] graph, local-first.
• obsidian-second-brain, claude-memory-compiler ("a loaded index beats vector search at personal scale"), and the broader family of markdown-memory skills.

What Engramory contributes is the opinionated bundle + the discipline, not the primitives. Do not claim novelty on markdown, frontmatter, wikilinks, a loaded index, one-file-per-fact notes, or curation hygiene — all are prior art.

What's actually differentiated

1. A role/purpose ontology, headed by feedback = procedural memory. The semantic / episodic / procedural split is established prior art — the CoALA taxonomy, and a named procedural type in LangMem and mem0 — so Engramory does not claim the category. What it does is make procedural feedback the spine of a deliberately tiny, hand-authored, human-readable set, with required Why: / How to apply: lines, instead of auto-extracting it into a vector/graph store. The contribution is the packaging and discipline, not the ontology.

2. The curation contract as concrete behaviour the protocol applies (model-followed, not a hard gate): dedup-before-write, update-don't-duplicate, delete-when-wrong, and a negative-scope rule ("don't store what git/CLAUDE.md/the code already records"). Surveys consistently name modify/delete/forget as the most under-implemented memory operation — Engramory makes it the spine.

3. A bounded index designed not to silently rot. The index loads every session and Claude Code reads the first 200 lines / 25 KB (documented behavior), so an unbounded index silently drops memories off the end. Engramory warns at 150 lines / 20 KB, compacts-or-asks before 200 / 25 KB, and ships a hard PreToolUse hook backstop (it blocks only growth past the cap — shrinking/compaction edits always pass). Both the line and byte caps apply — whichever is hit first triggers (an index can be under the line count yet over on bytes when the lines run long).

   Claude Code has since followed up on this natively: v2.1.186 (released 2026-06-22) reminds the agent to compact the index when it nears the cap, and v2.1.210 (released 2026-07-14) turned an over-cap write into an explicit error instead of a silent truncation. Both are after-the-fact alerts, though — the write still lands, and entries past the cap stay invisible until someone compacts. Engramory's hook denies the write before it happens, so a write through the matched edit tools never leaves the index over-cap in the first place (writes outside them — a shell, an MCP file tool — are not gated; see the status note above and SKILL.md §8). The native alerts validate the direction and make a welcome second layer — and older versions and other hosts still have neither.

How it compares

Engramory's lane: minimalism + actionable role typing + curation discipline, zero infra. It does not try to out-search basic-memory, out-scale mem0, or out-capture agentmemory — those solve a different problem (auto-capture / auto-ingest at volume) at a different cost point. agentmemory is the closest heavyweight foil: also local-first, but it bets on automatic capture (lifecycle hooks) + hybrid retrieval (BM25 + vectors + optional graph) on a SQLite/iii engine, where Engramory bets on hand-curation + a tiny always-loaded index and ships no engine at all.

* Claude Code's memory docs document this exactly: "the first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation." Other hosts vary, so the window stays configurable via the hook's env vars.

Where it fits — and the goal

Engramory is a portable memory discipline, not a product — not a database, not a framework, not a relevance-loaded skill, not a Claude-Code-only plugin. The plumbing it rides on (a markdown index + one-file-per-fact notes, the user | feedback | project | reference types, a bounded loaded index) is increasingly shipped natively by the host — Claude Code's built-in auto-memory already does it. So Engramory's value is the part hosts don't ship: the explicit curation contract (dedup-before-write, delete-when-wrong, don't-store-what-the-repo- already-has), procedural feedback notes with required Why/How, and a portable way to enforce the size cap.

The goal is the same discipline on any agent — by riding the real cross-agent rails, not by inventing a new standard. Paste rules-snippet.md into the host's always-loaded rules so the discipline fires every task. On a host that only gives you a flat rules file or a raw file store, that is a real upgrade; on a host that already ships structured memory, Engramory is a thin discipline layer on top — and says so.

On MCP: deliberately not the route for a host that can already read files and load standing rules. Serving memory over MCP would (a) open a second write channel that bypasses the pre-write hook — the single deterministic guarantee this project has, and one that already lists MCP file tools among the things that slip past it — and (b) demote recall from an index the host loads every session to a tool the model has to remember to call, i.e. back to the weakest rung in §8. For a host that lacks files or standing rules, an MCP entry point is the only way in and is worth adding as a supplement; it is not a replacement for the protocol, and it is not the cross-agent plan.

---

Continuity without a second handoff store

Engramory uses one canonical store. It does not add a handoff type or a parallel handoff folder. A live project note may hold the current goal, status, decisions, constraints, blockers, and next concrete step needed to resume an unfinished task. A feedback note is narrower: only a correction or workflow that should be reused beyond that task.

Before a deliberate compact, clear, or move to a new thread, the agent performs one continuity sync: scan the task, dedup/update existing notes, refresh project state, promote reusable feedback, keep durable reference pointers, retire stale or completed transient state, run the size check plus doctor, and verify that a cold-started agent could continue from the repo and memory alone. Continuity never duplicates code or git: a note may keep a stable pointer (branch name, issue/PR number, file path) to re-check, and may record a settled fact ("2.0 shipped on 2026-01-15"), but never current state — the version you are on now, the tip commit, the current test count. It records where to read those.

After a write, the agent reports what was added, updated, archived, and skipped (with reasons, identifying any deletion under archived), plus the index size and check result. Host lifecycle hooks can remind, mark a task dirty, or gate a manual transition; they do not perform or guarantee this semantic sync.

---

Install

Requires Python 3.9+ for the hook and the tools/ scripts (python3 on most systems).

Claude Code

1. Load the discipline as standing rules (primary): paste rules-snippet.md into your always-loaded rules — ~/.claude/CLAUDE.md (all projects) or the project CLAUDE.md — so the protocol fires on every task, not just when a skill happens to load by relevance.
2. (Optional) register the full spec as a skill: copy or symlink this folder into your Claude Code skills directory as engramory/, so SKILL.md is available on demand as the detailed reference (path in hooks/INSTALL.md).
3. Add the hard-cap hook: register the hook from hooks/ in your settings.json (snippet in hooks/settings.snippet.json).
4. Point <MEMORY_ROOT> at your memory directory; ensure it's .gitignored if inside a repo.

Codex

Use the Codex init helper to wire the discipline into AGENTS.md, create the memory template, optionally install the full protocol as a Codex skill, and add a .gitignore entry when the store lives inside the project:

python tools/engramory_init.py codex --project-root /path/to/project --install-skill

Optional Codex lifecycle assistance can also be installed with --install-hooks --mode explicit (default), or --mode assisted to ask for the same agent-run sync at meaningful milestones. Neither mode silently creates a semantic summary; review/trust project hooks and confirm them with /hooks. The hook's bounded .engramory-codex-state.json stores only synchronization bookkeeping, never prompts, transcripts, or note bodies.

By default this creates <project>/.engramory-memory/. Pass --memory-root to use an existing folder. Keep this store separate from Codex native Memories: Codex Memories are generated state, while Engramory is a user-auditable plain folder and the canonical store for the Engramory protocol. Full Codex notes, including explicit sync versus optional lifecycle-hook assistance, are in adapters/codex/README.md.

Read-only readers (recall another agent's memory)

Point any host at a store another agent owns and writes (e.g. Claude Code's native auto-memory) so a delegated run is grounded in the same project memory — read-only, so the owner stays the sole writer (Engramory assumes a single writer; many readers are fine):

python tools/engramory_init.py codex-reader   --project-root ~/.codex \
  --memory-root ~/.claude/projects/<project>/memory
# same shape for any host — it lands in that host's own rules file:
python tools/engramory_init.py cursor-reader  --project-root /path/to/repo --memory-root <store>

Reader hosts: codex-reader and dsh-reader (both dogfooded) plus claude-reader, cursor-reader, kiro-reader, cline-reader, windsurf-reader, openclaw-reader, hermes-reader (wired from each host's documented rules-file format, printed with an "unverified" note). It creates no store and never writes; --memory-root must be an existing store. See adapters/reader/README.md (incl. the tested-host table + data-egress note).

OpenClaw

Use the OpenClaw init helper (defaults to the workspace ~/.openclaw/workspace):

python tools/engramory_init.py openclaw --install-skill

It writes a marked Engramory block into the workspace AGENTS.md (auto-loaded every session), installs the protocol under .agents/skills/engramory (OpenClaw auto-discovers it), and keeps a separate .engramory-memory/ store. The index cap on OpenClaw is rules + engramory_check.py, not a deterministic deny hook (that would need a before_tool_call plugin) — see adapters/openclaw/README.md.

Kiro

Kiro (AWS's agentic IDE/CLI) is a strong host — always-loaded steering files, an agent that reads/writes workspace markdown, and a real pre-write deny hook. Wiring is manual (no init helper yet): copy adapters/kiro/steering-engramory.md to .kiro/steering/engramory.md (it is inclusion: always and pulls in the live index via #[[file:.engramory-memory/MEMORY.md]]), and keep your notes in a non-steering .engramory-memory/ folder.

⚠️ Do not drop notes into .kiro/steering/. A steering file with no inclusion front-matter defaults to inclusion: always, so every note would load into every request and blow up your context — the #1 Kiro install mistake. Only the index belongs in always-loaded steering; notes stay in .engramory-memory/ and open on demand. Cap is rules + engramory_check.py for now (a deterministic Kiro PreToolUse hook is possible but not yet shipped/tested). Full notes: adapters/kiro/README.md.

DeepSeek Harness (dsh)

Use the dsh init helper (defaults to $DSH_HOME — the env var wins when set, else ~/.dsh):

python tools/engramory_init.py dsh --install-skill

It writes a marked Engramory block into $DSH_HOME/AGENTS.md — dsh's agent-instructions plugin loads a hardcoded ["AGENTS.md", "CLAUDE.md"] candidate list at the start of every session — installs the protocol under <DSH_HOME>/skills/engramory (dsh's user skill root; with --project-root it goes to <project>/.dsh/skills/engramory instead, the root dsh scans there — not .agents/skills, which dsh does not scan in either place; install into an unscanned root and the copy lands but is never listed), and keeps a separate .engramory-memory/ store. The user-global block renders ABSOLUTE paths (dsh's file tools resolve relative paths against the session cwd); a project block stays relative so the repo can move. The index cap from those steps is rules + engramory_check.py, not a deterministic deny hook — though adapters/dsh/plugin/ (dsh-engramory) implements one against ctx.tools.guard(), whose refusal is monotonic. What blocks it today is dsh's own preview packaging, not the plugin.

Wiring and model behavior were dogfooded against deepseek-v4-flash: the block arrives as a <system-reminder>, a question answerable only from a stored note made the model open that note unprompted, and one durable fact came back as a conforming note plus index pointer. See adapters/dsh/README.md.

Any other agent (Hermes, Cursor, Cline, Windsurf, …)

Engramory is model-agnostic (DeepSeek, GPT, Llama, …) and rides on the host's own memory store. Full wiring is in PORTING.md; in short: paste rules-snippet.md into the host's always-loaded rules (so the discipline is always-on, not just a by-relevance skill), import SKILL.md if the host supports skills, point <MEMORY_ROOT> at the host's memory dir when that dir is plain files you control (against a host that manages its own memory — Codex, OpenClaw, Hermes — use a separate folder instead), and wire the size cap at the strongest rung the host supports: PreToolUse hook → tools/engramory_check.py after each index write → model discipline, with tools/engramory_doctor.py as a periodic backstop. A deterministic cap needs a pre-write deny hook. Claude Code's is written, tested, and RUNNING here; dsh's shim (adapters/dsh/plugin/, dsh-engramory 0.2.1+) installs and activates on current dsh builds — 0.2.0 never activated (issue #8); some other hosts expose an equivalent seam too (Hermes; Cursor, though its is newer/flaky), so the cap is portable with a per-host I/O shim you write and verify yourself — while OpenClaw can only block via a before_tool_call plugin and some hosts have none. See PORTING.md for the per-host picture. Where no such hook exists (or plain chat), the cap degrades to best-effort discipline (see SKILL.md §9).

First connecting a pre-existing store to the strict doctor surfaces a wall of mechanical issues (missing created/updated, Why/How not yet in canonical form) — don't blindly fix them. See PORTING.md's Adopting an existing store: run --no-schema for structure first, batch-backfill dates with the snippet, then hand-write Why/How.

A plain chat UI with no file access / no rules mechanism cannot run Engramory — it needs a host that executes skills/rules and can read & write files.

Configuration

• <MEMORY_ROOT> — where memory lives. Keep it somewhere you'll actually look; .gitignore it inside repos.
• Index limits — soft warn / hard cap default 150 / 200 lines and 20 / 25 KB; override via the hook's env vars (see hooks/).

Security & privacy

The store is plain, unencrypted text that any local process can read. .gitignore keeps it out of git — it is not encryption, and it does nothing against cloud-sync clients (Dropbox / iCloud / OneDrive), OS backups, or desktop search. If your <MEMORY_ROOT> sits in a synced or backed-up folder, its contents leave your machine.

• Never write a secret's value into memory — keys, tokens, passwords, cookies, recovery codes. Record only where the secret lives (e.g. "in the password manager / env var FOO"). An IP / path / serial used as a locator is fine; a credential value never is.
• Minimize partial PII (phone, email, address) — prefer a pointer.

This discipline is unenforced (no hook scans memory content — see SKILL.md §5/§8); treat it as best-effort and be deliberate.

Known limitations

Engramory is a single-project, single-writer, personal-scale protocol. It does not yet have:

• Versioning / migration — the semantic memory store has no schema_version; there is no defined upgrade path if the frontmatter format changes. (The optional Codex hook's bookkeeping file is versioned, but it contains no memory.) For onboarding a pre-existing store, PORTING.md's "Adopting an existing store" has a triage recipe + a date-backfill snippet.
• Provenance / trust — no source, confidence, last_verified, expiry, or superseded-by fields. Recalled memory is advisory and attacker-influenceable (see SKILL.md §4); there is no authentication of memory content.
• Scope / multi-project — a note CAN carry an optional scope: global | repo (SKILL.md §2.1, doctor-validated), but there is still no project_id, and one flat slug namespace means a store shared across projects/agents would hit slug collisions and project bleed. A store-level manifest (protocol version + scope + host config) is the planned first step — not built yet.
• Concurrency — semantic note/index writes assume one serialized writer and have no store-level lock. The optional Codex hook locks only its bookkeeping state; it does not make memory writes concurrent-safe.
• Scale — the always-loaded flat index bounds the active set to what fits the cap (~200 pointers). It is a personal / curated-scale tool, not a large corpus; above that, a retrieval-based system (basic-memory, mem0) is the right tool.

Prior art & credits

Andrej Karpathy's LLM Wiki / Knowledge Base (the markdown-over-RAG pattern, the most prominent statement of this approach — note it targets a knowledge encyclopedia, where Engramory targets agent working memory: who the user is, how the agent should behave, project state) · Claude Code auto-memory · basic-memory · obsidian-second-brain · claude-memory-compiler (itself Karpathy-inspired) · the Anthropic memory tool · OpenAI Codex memory (and its earlier topics-memory proposal #19758) · agentmemory (a heavyweight, local-first counterpart — auto-capture + SQLite/iii engine + hybrid BM25/vector retrieval; the opposite design point to Engramory's zero-infra hand-curation) · the wider markdown-memory community.

License

MIT — see LICENSE.