记忆协议 lacroix68050/engramory

Engramory

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

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

⚠️ 有无关项目用了同一个名字。 engram + memory 是个显而易见的生造词，至少还有一个仓库独立想到了它。本项目只可能是 tinqiao-oss/engramory（npm：dsh-engramory）；其他所有者名下的同名仓库不是它的分支、镜像，也不是它的新版本。

🤖 你是 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 | 索引优先 + 搜索 | ✅ | 按文件夹分类型 | ✅ reconcile/lint | 部分 | 无 |
| mem0 / Zep | 向量/图数据库 | 语义 | ❌（数据库） | 类型化（偏好/情景/程序；Zep 可自定义） | 自动抽取 | 不适用 | 数据库 + embeddings |
| agentmemory | SQLite + 向量索引（+可选图） | 混合 BM25+向量（+可选图），RRF | ❌（数据库/引擎） | ✅ 4 层生命周期（工作/情景/语义/程序） | 自动（捕获 + 去重 + 衰减） | 不适用 | iii 引擎（本地）+ 可选 embeddings |

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

\* Claude Code 的记忆文档正是这样写的："the first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation." 其他宿主各不相同，所以窗口仍可通过钩子的环境变量配置。

适用场景——以及目标

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 发布」），但绝不记当前状态——你现在用的版本、最新提交、当前测试数。它记的是去哪里读这些。

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

安装

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

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

默认会创建 <project>/.engramory-memory/。传入 --memory-root 可使用已有文件夹。把这个存储与 Codex 原生 Memories 分开：Codex Memories 是生成的状态，而 Engramory 是用户可审计的纯存放 Engramory 协议规范存储的文件夹。完整 Codex 说明见 adapters/codex/README.md，其中写明了显式同步与可选生命周期钩子辅助的区别——如果每条传入消息都会开启独立的 Codex 会话，请先读它的 chat-bridge 说明：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 做过内部试用：那套 blo