记忆协议 Makarov7646/engramory

Engramory

一套有主见的、零基础设施的记忆协议，面向小规模、本地、基于文件的智能体记忆 —— 严格的整理纪律，外加一个校验器（tools/engramory_doctor.py），以常驻规则的形式加载（CLAUDE.md / AGENTS.md / 你宿主环境的规则文件）。它不是数据库，不是框架，也不是按相关性加载的技能。记忆就是一个文件夹，里面放着一堆小而可读的 markdown 文件，外加一份始终加载的索引。没有数据库，没有向量嵌入，没有服务器 —— 只有纯文本文件，你可以在任何编辑器里打开、阅读、编辑、做 diff（实际存储本身保持 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 | 索引优先 + 搜索 | ✅ | 按文件夹分类型 | ✅ 对账/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 发布」），但绝不记当前状态——你现在用的版本、最新提交、当前测试数。它记的是去哪里读这些。

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

安装

钩子和 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 做过内部试用：那套 blo