agentmemory — 架构与原理
30 秒导读： agentmemory 给 AI 编码 agent（Claude Code、Cursor、Copilot CLI 等）装一块跨会话持久记忆。它靠 hook 自动捕获你和 agent 的每一次工具调用，脱敏、去重、压缩成结构化「观察」，存进本地数据库并建好 BM25 + 向量 + 知识图谱三套索引；下次开新会话时，它把相关的过去召回并注入上下文——于是「不用再重新解释一遍」。
1. 这是什么(零基础也能懂)
一句话定义： agentmemory 是一个常驻本地的记忆服务，专门服务 AI 编码助手——把「这个 agent 过去做过什么、决定过什么、踩过什么坑」记下来，需要时再找回来。
解决什么问题 / 给谁用。 假设你天天用 Claude Code 改一个大项目。每开一个新会话，agent 都是「失忆」的：你上周告诉它「这个仓库的认证逻辑在 auth/ 下、别动 legacy.ts」，今天它全忘了，你得再讲一遍。agentmemory 就是给这个 agent 接上一块「硬盘」：会话之间的知识不再蒸发。
它能做什么。
- 自动捕获：通过 agent 的 hook 机制，每次工具调用（读文件、跑命令、编辑）都被记下来——你不用手动做任何事。
- 显式保存：agent 也能主动调
memory_save把一条「决定/模式/偏好」存成长期记忆。 - 语义召回：用关键词、向量、知识图谱三路融合搜索，把相关的过去找回来。
- 上下文注入：开新会话时，把项目画像 + 相关记忆塞进 agent 的第一轮上下文。
- 记忆演化：记忆会版本化、互相取代、随时间衰减 、过期自动遗忘。
用起来什么样。 装好后大致是这样：
npm install -g @agentmemory/agentmemory
agentmemory # 启动常驻记忆服务(:3111)
agentmemory connect claude-code # 把 MCP + hooks 接进你的 agent
接好之后，agent 内部会自动多出一批 memory_* 工具。一次典型召回（agent 自己调用，不用你敲）：
memory_recall(query="我们上次怎么处理 OAuth 回调的")
-> 返回过去会话里关于 OAuth 的观察 + 你保存过的决定
一句话直觉 / 类比。 把 agent 的上下文窗口当内存(RAM)，把 agentmemory 当磁盘。会话进行时知识在「内存」里；会话结束「内存」清空，但重要的东西被刷到了「磁盘」，下次开机再加载回来。
2. 顶层全景(它大概怎么转)
agentmemory 的本体是一个 iii-engine 的 worker 进程(src/index.ts)。它启动时把 200 多个「函数」注册到一个本地引擎上，对外暴露三个面：REST API、MCP 工具、以及给 agent 装的 hook 脚本。
怎么读下面这张图： 左边是「写入侧」（agent 干活 → 记忆被捕获），右边是「读取侧」（开新会话 → 记忆被召回）。中间那条竖线是核心服务。
写入侧(捕获) agentmemory worker 读取侧(召回)
┌──────────────┐ HTTP ┌───────────────────────────┐ stdout ┌──────────────┐
│ PostToolUse │──────────▶ │ REST API (:3111) │ ◀──────── │ SessionStart │
│ hook 脚本 │ │ /observation │ │ hook 脚本 │
└──────────────┘ │ /search /save ... │ └──────────────┘
│ │
│ iii functions (mem::*) │
│ observe / remember │
│ search / context │
└───────────┬───────────────┘
│ state::get/set/list
▼
┌───────────────────────────┐
│ iii-engine StateModule │ + 内存里的索引:
│ 本地 SQLite (KV 仓库) │ BM25 倒排 / 向量 / 图谱
└───────────────────────────┘
部件一句话职责：
| 部件 | 干什么 | 在哪 |
|---|---|---|
| hook 脚本 | 独立 Node 脚本，从 stdin 读 agent 事件，HTTP 打到 REST API | src/hooks/*.ts |
| REST API | 128 个 HTTP 端点，是 hook 和外部客户端的入口 | src/triggers/api.ts |
| MCP server | 把 53 个 memory_* 工具映射到内部函数 | src/mcp/server.ts |
| iii functions | 真正的业务逻辑，名字都以 mem:: 开头 | src/functions/*.ts |
| StateKV | 对 iii-engine state::* 的薄封装(get/set/list) | src/state/kv.ts |
| 索引 | 进程内存里的 BM25 倒排表 + 向量表 + 知识图谱 | src/state/*.ts |
| iii-engine | 外部引擎进程，提供持久 KV、触发器、WebSocket | iii-sdk(ws://localhost:49134) |
主线走一遍(高层，不进代码)。
写入：agent 调用一个工具(比如读文件) → Claude Code 触发 PostToolUse hook → hook 脚本把事件 POST 到 /agentmemory/observation → REST 转给 mem::observe 函数 → 去重、脱敏、压缩、写库、建索引。
读取：你开一个 新会话 → SessionStart hook 触发 → 打到 /agentmemory/session/start → mem::context 函数把项目画像和最近会话拼成一段 XML 上下文 → 写回 hook 的 stdout → Claude Code 把它注入第一轮对话。
召回：agent 中途想找东西 → 调 MCP 工具 memory_recall / memory_smart_search → 走 mem::search / mem::smart-search → 三路索引融合检索 → 返回结构化结果。
3. 接下来读哪一章
这个项目很大(174 个源文件、约 37,800 行)。本库把它拆成五章，建议按顺序读——每章聚焦一条端到端路径或一个核心机制：
- 01-capture-pipeline.md — 写入侧主线。一次工具调用从 hook 到落库的完整旅程：SHA-256 去重、密钥脱敏、零 LLM「合成压缩」、BM25+向量双索引。看懂这章就懂了「记忆是怎么进来的」。
- 02-retrieval.md — 读取侧核心。三路检索(BM25 倒排 / 向量余弦 / 图谱遍历)各自怎么打分，再怎么用 RRF(倒数排名融合)合并、按会话去重。这是项目「检索质量」的所在。
- 03-memory-lifecycle.md — 记忆怎么活与死。显式记忆的 Jaccard 相似度取代/版本化、4 层记忆巩固(工作→情景→语义→程序)、Ebbinghaus 衰减与自动遗忘。
- 04-iii-foundation.md — 底座。为什么整个系统「只有三个原语」(Worker/Function/Trigger)，KV 状态层长什么样，并发怎么用 keyed-mutex 串行化。
- 05-clever-and-boundaries.md — 精华与边界。可借鉴的设计技巧、刻意不做的事、会在哪崩、与兄弟项目的取舍对比，以及完整代码地图。
如果你只想了解一个点：搜索质量看第 2 章，记忆模型看第 3 章，「它凭什么不用外部数据库」看第 4 章。