图解agent-memory核心概念为什么Markdown才是记忆真相而SQLite只是可随时删除的缓存【免费下载链接】agent-memoryLong-term memory runtime for AI agents — plain Markdown as the source of truth, local ranked retrieval, and an independent sleep-time Manage layer. Claude Code and Codex share one store. No API key.项目地址: https://gitcode.com/gh_mirrors/age/agent-memoryagent-memory 是一款面向 AI Agent 的长期记忆运行时它把普通 Markdown 文件当作唯一事实来源Single Source of Truth旁边的 SQLite 索引只是可以随时rm -rf掉再重建的缓存。Claude Code、Codex CLI 等多个 Agent 共享同一个记忆库全程无需任何 API Key。今天用一篇图解文章带你读懂它最核心的设计取舍。一、先想清楚Agent 的健忘症是怎么回事任何一个 Agent 关掉会话后就忘记了会话里学到的所有东西。市面上的 Agent 记忆方案大致走两条路线各有硬伤路线做法问题检索引擎派向量库、知识图谱、排序管线返回的是不可检视的黑盒片段换存储系统等于数据绑架文件系统派一堆 Markdown直接lsgrep可读、零成本但没有排序能力文件多了就翻不动agent-memory 的做法是把两者合进同一个存储检索引擎给一个 Agent 可以直接读的文件系统建索引。关系就藏在记忆内部的链接里每次召回都落回磁盘上一个完整的 Markdown 文件。更关键的是读取路径上不调用任何模型、不跨网络所以它始终很快。一句话概括真相是文件索引是投影删掉投影不丢知识。二、核心概念①Markdown 文件才是记忆真相在 agent-memory 里一条记忆 一个 Markdown 文件存放在固定布局的目录树中$AGENT_MEMORY_STORE/ ├── MEMORY.md 根索引每条记忆一行唯一常驻注入 ├── config.toml 所有可调参数 ├── schemas/ 每种记忆类型的字段定义 ├── decision/ 记忆按 类型/分组/名称.md 存放 ├── archive/ 只追加蒸馏证据、完整会话副本 ├── dream-reports/ 每次睡眠的管理报告 ├── .index/ ⚠️ 可完全重建内容哈希、FTS5、访问日志 └── .state/ 运行时状态水位线、写锁每个记忆文件 frontmatter结构化元数据 自由 Markdown 正文。frontmatter 里带稳定名称、一句话摘要、类型、时间戳、链接、权重和来源出处正文则是随便写的自由 Markdown。这带来三个实打实的好处可 grep、可 git、可迁移记忆就是你的文档任何编辑器、任何工具链都能操作它可审计Agent 更新了什么、为什么更新打开文件就能看到不存在黑盒用户主权哪天你不想要这套系统了把目录拷走就行。布局定义在 paths.py那里是全项目唯一知道目录名的模块。三、核心概念②SQLite 只是可随时删除的缓存这是 agent-memory 最重要、也最反直觉的一条承诺rm -rf .index/ mem rebuild—— 知识零损失。注意这不是文档里的承诺而是被测试强制执行的不变量。database.py 的模块注释直接写着The index database. Every table here is a cache — deleting the file loses no knowledge.index.db里的表——文件哈希清单、FTS5 全文搜索面、向量分块、访问日志——全部是从 Markdown 投影出来的。重建逻辑在 indexer.pyrebuild()就是丢弃数据库 → 重新扫描所有 Markdown → 重新索引和增量同步走的是同一套代码路径。项目甚至专门写了系统测试来证明这一点test_cli.py 中的test_rebuild_from_the_command_line_is_lossless验证重建前后召回结果完全一致test_indexer.py 则断言删掉索引后重建返回同样的召回集合且重建是幂等的。这条不变量的完整表述以及它背后的四个理由迁移自由、git 友好、寄生平台能力、用户主权都写在 CLAUDE.md 的 Invariants 一节里。那为什么还需要 SQLite因为纯文件系统派最大的痛点是没有排序。SQLite 在这里承担的是加速层角色FTS5 全文索引BM25 排序毫秒级返回相关记忆列表可选向量索引默认关闭开启后与 BM25 用倒数排名融合RRF固定评测集上 Recall5 从 79.0% 提升到 86.6%访问日志记录谁、在什么时候、用什么查询召回了哪条记忆——但注意统计只进索引不改真相文件避免每次召回都引发重索引和 git 噪音。四、图解一次召回的三条读路径agent-memory 刻意设计了三条并行的读路径任何一条失败都不代表系统失败确定性注入会话开始时MEMORY.md里的根索引被直接塞进上下文——每条记忆一行按权重取最重的且受字节预算硬约束超限就丢最轻的行。渲染逻辑见 memory_md.pyBM25 召回查询走 SQLite 的 FTS5 索引想要语义召回就再融上向量索引裸目录树两条都失手时Agent 还可以用ls和grep直接翻目录——因为文件就在磁盘上永远找得到。召回时还有一个精巧设计只回路径不贴正文。系统先返回一个L0 清单一行摘要 文件路径 锚点 分数Agent 按需选择打开哪条、打开到多深mem recall 为什么用文件而不是数据库 # 只回 L0 清单 mem read name --level outline # 只要标题大纲 mem read name --level full # 才读全文 mem trace name # 追到被引用的原始消息索引行 → 摘要 → 全文 → 原始素材每一层代价是上一层的十倍每一层都是一个可以停手的地方。五、写入不用靠 Agent 自觉边界触发 睡眠整理记忆的两大难题是写不进去和越积越乱。agent-memory 的答案是把写入从 Agent 的自觉里解放出来写覆盖是系统的事蒸馏在对话边界Stop、SessionEnd、PreCompact自动触发不等 Agent想起来才写。并且完整会话轨迹会先被原样拷进archive/——蒸馏器漏掉了永远不等于系统弄丢了原始材料只追加蒸馏只是投影不是搬移独立时钟的 Manage 层mem sleep跑一次睡眠整理按价值合并、降权、建链接。它借用宿主 Agent 自己的 CLI 来推理零 API Key但无人值守时绝不允许物理删除——删除只能以提案形式出现由你确认mem sleep --reason host # 合并整理 mem proposals # 看看有什么在等你拍板 mem decide id --accept # 确认提案更新即取代Supersede新记忆取代旧记忆时旧文件仍在库里recall --as-of还能按日期回答过去某个时刻的记忆状态——更新永远不销毁。六、自己动手验证三行命令见证删库不丢知识最快的理解方式是自己试一遍。克隆仓库 https://link.gitcode.com/i/fdd4d82658357368e0db7470add82520需要 Python 3.12 和 uvuv sync --all-packages uv run mem init uv run mem record --type decision --field projectagent-memory \ --abstract Markdown文件是单一事实来源 \ --body 索引是可重建的缓存。 uv run mem --json recall source of truth # 见证时刻砸掉整个索引重建 rm -rf ~/agent-memory-store/.index uv run mem rebuild重新recall试试——结果和砸索引之前一模一样。这条无损性质被系统测试守着一份随时可复验。七、接入你的 Agent一条 setup 命令mem setup --host claude-code # 或 --host codex / muse-codesetup 会探测宿主、按宿主的钩子方言追加mem-hook命令、装好 agent-memory skill其余配置原样保留。支持 MCP 的 Agent 还可以通过mem-mcp拿到同一套核心调用memory_recall、memory_record等任何能跑 shell 命令的 Agent 直接用 CLI 兜底。多宿主互写互读经过验证Claude Code 写进去的Codex 找得到细节不丢。总结一张表看懂核心取舍概念agent-memory 的选择收益事实来源Markdown 文件一条记忆一个文件可读、可 grep、可 git、可迁移检索加速SQLiteFTS5 可选向量毫秒级排序随删随建读取策略先给路径清单按需逐层加深上下文成本可控写入时机会话边界自动触发不等 Agent 自觉覆盖率高原始轨迹保底记忆治理睡眠期独立 Manage 层删除只出提案无人值守也安全可逆模型依赖库内零 LLM 客户端借用宿主 CLI零 Key、零账单、写入可见想深入架构设计可以从 docs/design/index.md 开始想直接动手skill 说明在 skills/agent-memory/SKILL.md。核心就一句把记忆写成你能看懂的文件把数据库当随时可扔的加速器——这就是 agent-memory 的全部哲学。【免费下载链接】agent-memoryLong-term memory runtime for AI agents — plain Markdown as the source of truth, local ranked retrieval, and an independent sleep-time Manage layer. Claude Code and Codex share one store. No API key.项目地址: https://gitcode.com/gh_mirrors/age/agent-memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考