记忆协议 mMulder84/engramory

Engramory

一套有主见的、零基础设施的记忆协议，面向小规模、本地、基于文件的智能体记忆 —— 严格的整理纪律，外加一个校验器（tools/engramory_doctor.py），以常驻规则的形式加载（CLAUDE.md / AGENTS.md / 你宿主环境的规则文件）。它不是数据库，不是框架，也不是按相关性加载的技能。记忆就是一个文件夹，里面装着若干小而可读的 markdown 文件，外加一份始终加载的索引。没有数据库，没有向量嵌入，没有服务器 —— 只有纯文本文件，你在任何编辑器里都能打开、阅读、编辑、做 diff（实际存储本身保持 git 忽略）。

Engramory —— 由 engram（记忆在大脑中留下的物理痕迹）和 memory 拼成。在这里：一个文件 = 一条事实。

⚠️ 有无关项目用了同一个名字。 engram + memory 是个很自然的造词，至少还有一个仓库独立想到了它。本项目只可能是 tinqiao-oss/engramory（npm：dsh-engramory）；换个 owner 的同名仓库不是它的分支、镜像，也不是它的新版本。

🤖 你是 AI 智能体，被要求安装或检查这个项目？ 请从 AGENT-SETUP.md 开始，不要看下面的安装步骤。那份文档讲的是：怎么弄清楚你的宿主环境实际能强制什么、存储是否已经存在、哪些东西你不能碰、该告诉用户什么 —— 这些正是智能体临场发挥时最容易搞错的地方。

状态：0.12.1 —— 实验性。 硬性索引上限（一个 PreToolUse 钩子）对匹配到的直接编辑工具（Edit | Write | MultiEdit）是确定性的，但不是全局写入防护（shell 工具 —— Bash、PowerShell、后台 Monitor 命令 —— 加上 MCP 文件工具、外部编辑器、同步客户端都能绕过它）；纪律以常驻规则的形式加载，由模型自行遵守，所以是尽力而为，不保证每个任务都生效（见 SKILL.md §8）。假定单写入者 / 串行写入。暂时别把它当成「强制、可靠、跨智能体」的记忆层来依赖。

这是什么 —— 以及不是什么

Engramory 不是新的记忆架构。「markdown 文件 + 一小份加载进上下文的索引 + 模型自己整理」这套模式，如今已是智能体记忆的主流形态，而且已经在好几个地方落地了。Engramory 站在这些之上：

- Claude Code 原生自动记忆 —— 同样的 markdown MEMORY.md 索引 + 懒加载详情文件的模式；它的系统提示词甚至用了同一套 user | feedback | project | reference 类型词汇（据 anthropics/claude-code#58840； 公开文档只描述索引和主题文件）。Engramory 是这个默认做法的规范化超集。
- basic-memory — markdown 作为事实来源，YAML frontmatter type，[[wikilink]] 图，本地优先。
- obsidian-second-brain、 claude-memory-compiler （「在个人规模下，加载索引胜过向量搜索」），以及更广泛的 markdown 记忆技能家族。

Engramory 贡献的是有主见的打包 + 纪律，不是这些基础构件。不要在 markdown、frontmatter、wikilink、加载索引、一事一文件的笔记、整理卫生上声称新颖——这些都是已有先例。

真正有差异的地方

1. 角色/用途本体，以 feedback = 程序性记忆为首。 语义 / 情景 / 程序性的划分是已有先例——CoALA 分类法，以及 LangMem 和 mem0 中命名的程序性类型——所以 Engramory 不声称拥有这个类别。它做的是把程序性的 feedback 变成一套刻意精简、手工编写、人类可读的集合的脊柱，要求写 Why: / How to apply: 行，而不是自动抽取到向量/图存储里。贡献在于打包和纪律，不在本体。

2. 把整理契约变成具体行为，由协议执行（模型遵循，不是硬性关卡）：写前去重、更新而非重复、错了就删，以及一条负向范围规则（「不要存 git/CLAUDE.md/代码已经记录的东西」）。各类调研一致把修改/删除/遗忘列为实现最少的记忆操作——Engramory 把它变成脊柱。

3. 有界索引，设计上不会悄悄腐烂。 索引每个会话都会加载，Claude Code 读取前 200 行 / 25 KB（有文档记录的行为），所以无界索引会悄悄把记忆丢到末尾之外。Engramory 在 150 行 / 20 KB 时警告，在 200 / 25 KB 之前压缩或询问，并附带硬性 PreToolUse 钩子兜底（只阻止增长超过上限——缩小/压缩编辑总是通过）。行数和字节上限都生效——先触发的那个生效（索引可能行数没超但字节超了，当行很长时）。

Claude Code 后来原生跟进了这一点：v2.1.186（2026-06-22 发布）在索引接近上限时提醒智能体压缩，v2.1.210（2026-07-14 发布）把超上限写入变成显式错误，而不是静默截断。但两者都是事后警报——写入仍然落地，超过上限的条目在有人压缩之前一直不可见。Engramory 的钩子在写入发生之前就拒绝，所以通过匹配的编辑工具进行的写入，永远不会让索引处于超上限状态，在第一次（写到这些目录之外的操作——shell、MCP 文件工具——不受门控；见上方状态说明和 SKILL.md §8）。原生提醒会校验方向，是很好的第二层防线——但旧版本和其他宿主两者都没有。

对比

| | 存储 | 召回 | 人类可读 | 类型化本体 | 治理纪律 | 有界索引 | 基础设施 |
| Engramory | md 文件 | 加载索引 → 打开文件 | ✅ | ✅ 基于角色（4 种） | ✅ 契约（模型执行） | ✅ 150/200 + 钩子 | 无 |
| CC auto-memory | md 文件 | 加载索引 → 打开文件 | ✅ | ✅ 同样 4 种类型 | 部分（自动） | ~200 行窗口* | 无（内置） |
| basic-memory | md + SQLite | 语义/FTS 搜索 | ✅ | ✅ 自由类型 | schema + 覆盖检查 | ❌（无加载索引） | SQLite + embeddings |
| obsidian-second-brain | md vault | 索引优先 + 搜索 | ✅ | 按文件夹分类型 | ✅ 对账/lint | 部分 | 无 |
| mem0 / Zep | 向量/图数据库 | 语义 | ❌（数据库） | 类型化（偏好/情景/程序性；Zep 可自定义） | 自动抽取 | 不适用 | 数据库 + embeddings |
| agentmemory | SQLite + 向量索引（+可选图） | 混合 BM25+向量（+可选图），RRF | ❌（数据库/引擎） | ✅ 4 层生命周期（工作/情景/语义/程序性） | 自动（捕获 + 去重 + 衰减） | 不适用 | iii 引擎（本地）+ 可选 embeddings |

Engramory 的定位：极简 + 可操作的按角色分类型 + 治理纪律，零基础设施。 它不打算在搜索上超过 basic-memory、在规模上超过 mem0、在捕获上超过 agentmemory——那些方案解决的是另一个问题（大规模自动捕获/自动摄入），成本点也不同。agentmemory 是最接近的重量级对照：同样本地优先，但它押注自动捕获（生命周期钩子）+ 混合检索（BM25 + 向量 + 可选图），跑在 SQLite/iii 引擎上；Engramory 则押注手工治理 + 一个始终加载的小索引，完全不附带引擎。

\* Claude Code 的记忆文档写得很明确：“每次对话开始时加载 MEMORY.md 的前 200 行，或前 25KB，以先到者为准。” 其他宿主各有差异，所以窗口大小保持可配置，通过钩子的环境变量调整。

适用场景与目标

Engramory 是一套可移植的记忆纪律，不是产品——不是数据库，不是框架，不是按相关性加载的技能，也不是 Claude Code 专属插件。它依托的管道（markdown 索引 + 每条事实一个文件的笔记、user | feedback | project | reference 类型、有界加载索引）正越来越多地由宿主原生提供——Claude Code 内置的 auto-memory 已经做到了。所以 Engramory 的价值在于宿主没有提供的那部分：显式的治理契约（写前去重、错了就删、仓库已有的不要存）、程序性的 feedback 笔记（必须写清 Why/How），以及可移植的尺寸上限执行方式。
目标是在任何智能体上保持同一套纪律——靠接入真正跨智能体的现成轨道，而不是另造一套标准。 把 rules-snippet.md 粘贴进宿主的常驻规则，让纪律在每个任务上都生效。如果宿主只提供一份扁平规则文件或裸文件存储，这已经是实打实的升级；如果宿主本来就自带结构化记忆，Engramory 就是叠在上面的一层薄纪律——它也如实这么说。

关于 MCP：对已经能读文件、能加载常驻规则的宿主，刻意不走这条路。 用 MCP 提供记忆会带来两个问题：(a) 打开第二条写入通道，绕过写前钩子——这是本项目唯一的确定性保证，而它列出的漏网清单里本来就有 MCP 文件工具；(b) 把召回从「宿主每个会话都加载的索引」降级成「模型得记得去调用的工具」，也就是退回 §8 里最弱的那一档。对缺少文件或常驻规则的宿主，MCP 入口是唯一的进入方式，值得作为补充加上；但它替代不了协议，也不是跨智能体方案。

不另建交接存储的连续性

Engramory 只用一份规范存储。它不新增 handoff 类型，也不建平行的交接文件夹。未完成的任务最多保留一条活跃的 project 笔记——这是上限，不是配额——里面放当前目标、状态、决策、约束、阻塞项，以及恢复任务所需的下一步具体动作。这条笔记原地更新：绝不按日期堆一串状态文件，也绝不在旁边建一份按轮次索引的交接日志。feedback 笔记范围更窄：只记该任务之外仍应复用的纠正或工作流。

在有意压缩上下文、清理或换新线程之前，智能体做一次连续性同步：扫描任务，去重或更新已有笔记，刷新项目状态，把可复用的反馈提升出来，保留长期有效的引用指针，退役过期或已完成的临时状态，跑一遍体积检查和 doctor，并确认冷启动的智能体仅凭仓库和记忆就能接着干。连续性记录绝不复制代码或 git：笔记可以留一个稳定指针（分支名、issue/PR 编号、文件路径）供复查，也可以记一条已定事实（「2.0 于 2026-01-15 发布」），但绝不记当前状态——你现在用的版本、最新提交、当前测试数。它只记去哪里读这些。

写入之后，智能体要报告新增、更新、归档、跳过了什么（附原因，归档下的删除要指明），外加索引体积和检查结果。宿主的生命周期钩子可以提醒、把任务标记为脏、或把手动切换卡住；它们不执行也不保证这次语义同步。

安装

钩子和 tools/ 下的脚本需要 Python 3.9+。下面的命令写作 python；在 macOS 和大多数 Linux 发行版上，裸 python 会不存在，所以那里用 python3（Windows 上用 python，因为 python3 往往是 Microsoft Store 的占位程序，什么也不做）。

Claude Code

1. 把纪律作为常驻规则加载（主要方式）： 把 rules-snippet.md 粘贴到始终加载的规则里—— ~/.claude/CLAUDE.md（所有项目）或项目的 CLAUDE.md——这样协议会在每个任务上触发，而不只是在某个技能恰好按相关性加载时才触发。
2. （可选）把完整规范注册为技能： 把这个文件夹复制或软链接到你的 Claude Code 技能目录，命名为 engramory/，这样 SKILL.md 就能按需作为详细参考使用（路径见 hooks/INSTALL.md）。
3. 添加硬上限钩子： 在 settings.json 里注册 hooks/ 中的钩子（片段见 hooks/settings.snippet.json）。
4. 把 <MEMORY_ROOT> 指向你的记忆目录；如果它在某个仓库内，确保它被 .gitignore 忽略。

可选——读取记忆背后的对话记录。 笔记保存结论；宿主的对话记录保存实际说过的话。当笔记过于简略、你想看推理过程时，当你怀疑它已过时、想看原始证据时，或者当某件事讨论过却从未写下来时， tools/engramory_trace.py 会搜索这些对话记录——本地、只读，不上传、不建索引、不做嵌入：

python tools/engramory_trace.py "streaming parser" # search this project
python tools/engramory_trace.py --show <session-id> # replay one session

默认只搜索说过的内容，不搜索工具输出——否则从记忆里取的一个词会匹配到每一轮重新注入该记忆的对话，把产生它的讨论淹没。如果宿主在笔记上标记了来源会话， --show 会直接跳到那里。仅限 Claude Code：它解析该宿主的 JSONL 布局。
这是给你的便利，不属于协议的一部分——SKILL.md 里的纪律既不需要它，也不提及它。

Codex

用 Codex 初始化助手把纪律接入 AGENTS.md，创建记忆模板，可选地把完整协议安装为 Codex 技能，并在存储位于项目内时添加一条 .gitignore 条目：

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

还可以用 --install-hooks --mode explicit（默认）安装可选的 Codex 生命周期辅助，或用 --mode assisted 在关键里程碑请求同样的智能体执行同步。两种模式都不会悄悄生成语义摘要；请审查并信任项目钩子，再用 /hooks 确认。
钩子有界的 .engramory-codex-state.json 只保存同步记账信息，绝不保存提示词、对话记录或笔记正文。

默认会创建 <project>/.engramory-memory/。传 --memory-root 可改用已有文件夹。
把这个存储与 Codex 原生 Memories 分开：Codex Memories 是生成的状态，而 Engramory 是用户可审计的纯文件夹，也是 Engramory 协议的规范存储。完整的 Codex 说明在 adapters/codex/README.md，其中写明了显式同步与可选生命周期钩子辅助的区别——如果每条进来的消息都会单独开一个 Codex 会话，先读它的聊天桥接说明：Codex 从不自动加载 Engramory 的索引，所以那里的每次召回都是一次真实的文件读取。

只读读取方（召回另一个智能体的记忆）

把任意宿主指向另一个智能体拥有并写入的存储（例如 Claude Code 原生的自动记忆），让委派出去的运行基于同一份项目记忆——只读，所以所有者始终是唯一的写入方（Engramory 假定单写入方；多个读取方没问题）：

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>

读取方宿主：codex-reader 和 dsh-reader（两者都已内部试用），外加 claude-reader、cursor-reader、kiro-reader、cline-reader、windsurf-reader、openclaw-reader、hermes-reader（按各宿主文档中的规则文件格式接入，输出时会带「未验证」标注）。它不创建存储，也从不写入；--memory-root 必须是已存在的存储。见 adapters/reader/README.md（含已测试宿主表和出网数据说明）。

OpenClaw

用 OpenClaw 初始化助手（默认指向工作区 ~/.openclaw/workspace）：

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

它会把一段带标记的 Engramory 块写进工作区的 AGENTS.md（每个会话自动加载），把协议安装到 .agents/skills/engramory（OpenClaw 会自动发现），并单独维护一个 .engramory-memory/ 存储。OpenClaw 上的索引上限靠规则 + engramory_check.py，不是确定性的拒绝钩子（那需要 before_tool_call 插件）——见 adapters/openclaw/README.md。

Kiro

Kiro（AWS 的智能体 IDE/命令行）是强力宿主——常驻加载的 steering 文件、能读写工作区 markdown 的智能体，还有真正的前置写入拒绝钩子。接入靠手动（暂无初始化助手）：把 adapters/kiro/steering-engramory.md 复制到 .kiro/steering/engramory.md（它是 inclusion: always，并通过 #[[file:.engramory-memory/MEMORY.md]] 引入实时索引），笔记则放在非 steering 的 .engramory-memory/ 文件夹里。

⚠️ 不要把笔记丢进 .kiro/steering/。 没有 inclusion front-matter 的 steering 文件默认 inclusion: always，于是每条笔记都会加载进每次请求，把你的上下文撑爆——这是 Kiro 安装的头号错误。常驻加载的 steering 里只该放索引；笔记留在 .engramory-memory/，按需打开。目前上限靠规则 + engramory_check.py（确定性的 Kiro PreToolUse 钩子可行，但尚未发布/测试）。完整说明见： adapters/kiro/README.md。

DeepSeek Harness (dsh)

这张卡片是 dsh-xray 对插件做的静态能力扫描，C2 读起来比实际情况更糟：该等级由 manifest.bundle.patch 触发，扫描过的生态里有 74.6% 都声明了它，因为插件一旦省略这个字段，就会静默地永远挂载不上。这张卡片上就只有这一个标记。在扫描过的 4,092 个插件中，42.6% 带 exec，14.0% 带 base64_decode，10.4% 会读取形似凭据的环境变量——本插件这些都没有，没有 eval，没有安装脚本，也没有对外域名。

用 dsh init 辅助脚本（默认指向 $DSH_HOME——设置了这个环境变量就以它为准，否则用 ~/.dsh）：

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

它会把一段带标记的 Engramory 内容写入 $DSH_HOME/AGENTS.md——dsh 的 agent-instructions 插件在每个会话开始时加载一份写死的候选列表 ["AGENTS.md", "CLAUDE.md"]——再把协议装到 <DSH_HOME>/skills/engramory（dsh 的用户技能根目录；加上 --project-root 则改写到 <project>/.dsh/skills/engramory，那是 dsh 在该项目下扫描的根目录——不是 .agents/skills，dsh 在两处都不扫描它；装到不被扫描的根目录，文件会落地，但永远不会被列出），并单独保留一个 .engramory-memory/ 存储。用户全局那段写的是绝对路径（dsh 的文件工具按会话 cwd 解析相对路径）；项目那段保持相对路径，这样仓库可以整体搬走。这些步骤带来的索引约束是规则加上 engramory_check.py，不是确定性的拒绝钩子——不过 adapters/dsh/plugin/（dsh-engramory）基于 ctx.tools.guard() 实现了一个，它的拒绝是单调的。请安装 0.2.1 或更高版本：dsh 预览期「无法安装第三方插件」的 bug 已在上游修复（rc.7），而 0.2.0 能装上却永远不会激活（issue #8——旧版 Cordis 的 inject 语法）。

接线和模型行为都对着 deepseek-v4-flash 做过实测：那套臃肿的