常驻记忆协议 Roussel27423/engramory

Engramory

一套有主见的、零基础设施的记忆协议，面向小规模、本地、基于文件的智能体记忆 —— 一套严格的整理纪律，外加一个校验器（tools/engramory_doctor.py），以常驻规则的形式加载（CLAUDE.md / AGENTS.md / 你宿主机的规则文件）。它不是数据库，不是框架，也不是按相关性加载的技能。记忆就是一个文件夹，里面装着一个个短小、人类可读的 markdown 文件，外加一份始终加载的索引。没有数据库，没有嵌入向量，没有服务器 —— 只有纯文本文件，你在任何编辑器里都能打开、阅读、编辑、对比差异（实际存储本身保持 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 的价值在于宿主没有提供的部分：显式的整理契约（写入前先去重、错了就删、仓库里已有的不要存）、带必需 Why/How 的程序性 feedback 笔记，以及可移植的尺寸上限执行方式。
目标是在任何智能体上保持同一套纪律——靠的是搭上真正的跨智能体轨道，而不是另造一套标准。 把 rules-snippet.md 粘贴进宿主常驻加载的规则里，纪律就会在每个任务上生效。如果宿主只给你一个扁平规则文件或裸文件存储，这已经是实打实的升级；如果宿主本来就带结构化记忆，Engramory 就是叠在上面的一层薄纪律——它自己也这么说。

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

不用第二个交接存储也能保持连续性

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

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

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

安装

钩子和 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

它会往 $DSH_HOME/AGENTS.md 里写入一段带标记的 Engramory 区块——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 做过实际验证：那套臃肿的