LLM 记忆 2026-05-15 Claude Code · agentmemory

Claude Code x agentmemory 系统工作原理图解

把 agentmemory 的整体设计压缩成一篇可顺读、可检索、可复用的机制说明：从三层架构、12 个 Hook、写入与读取流水线，到四层记忆巩固与一次端到端时序。

你会看到什么 三层拓扑、12 个触发点、6 步写入、4 步读取、4 层记忆巩固。
适合谁读 想快速理解 Claude Code 如何接入长期记忆、以及 Hook 驱动链路的工程师。
阅读方式 先看全景，再按“触发点 → 流水线 → 巩固 → 时序”一路往下读。
SECTION · 01

三层全景Three-Layer Topology

整套系统由三个独立的进程组成。它们之间没有任何 SDK 级耦合——通信的唯一介质是 HTTP 请求和子进程的 stdin/stdout。

FIG · 1.1 · TOPOLOGY OVERVIEW
LAYER 01 · FRONTEND Claude Code IDE 用户对话界面 ~/.claude/settings.json 不知道 agentmemory 存在 通过 12 个 Hook 触发外部命令 LAYER 02 · BRIDGE Hook Bridge 12 个生命周期脚本 stdin → HTTP → exit Node.js 子进程 · 不依赖 SDK try/catch + AbortSignal.timeout LAYER 03 · ENGINE agentmemory Server (iii-engine) :3111 REST · :3113 Viewer :49134 ws · MCP SQLite + 内存向量索引 123 functions · 34 KV scopes spawn JSON via stdin HTTP POST localhost:3111 response PROCESS BOUNDARY · INDEPENDENT PROCESSES Anthropic 出品 用户编辑 settings.json 注册 npx @agentmemory/agentmemory
三层进程之间唯一的耦合是 JSON。Claude Code 把它当成"出口指令"，agentmemory 把它当成"入口请求"——中间的 Hook 只是个翻译。
关键认知 · KEY INSIGHT Claude Code 自己不知道 agentmemory 的存在。所有连接都通过 ~/.claude/settings.json 里注册的 Hook 脚本完成。Hook 是 Claude Code 在每个生命周期点会自动 spawn 的子进程，这些脚本读取 stdin 的 JSON、调用 agentmemory 的 REST API、再退出。这种"零侵入"设计意味着：换一个 Memory 后端，只需改 Hook 脚本里的 URL，前端无感知。
SECTION · 02

12 个 Hook 触发点Lifecycle Hook Reference

Hook 是整个系统的"采集神经"。Claude Code 把生命周期切成 12 个时刻点，agentmemory 在每个点上挂一个动作——要么写入，要么召回，要么巩固。

FIG · 2.1 · HOOK LIFECYCLE TIMELINE
T₀ T_END 会话开始 会话结束 SessionStart 召回 · 注入 PreToolUse 召回 + 捕获 PreCompact 重新注入 UserPromptSubmit 捕获 prompt PostToolUse ★ 核心写入点 PostToolUseFailure 错误捕获 Subagent×2 Stop 巩固 + 知识图谱 SessionEnd Working→Episodic 召回类（向 Agent 注入上下文） 捕获/巩固类（向库写入数据） 异常类 辅助/可选
12 个 Hook 沿会话时间轴分布：墨绿在上（召回类），赤陶橙在下（捕获/巩固类）。PostToolUse 是写入主力，几乎承担了 80% 的数据采集量。
Hook 名触发时机agentmemory 干什么
SessionStart用户打开新会话召回：拉项目画像 + 三流检索 + 注入上下文
UserPromptSubmit用户回车送出 prompt捕获：记录用户提示（隐私过滤）
PreToolUseAgent 决定调用工具前召回 + 捕获：注入文件历史 + 记录意图
PostToolUse工具执行完毕捕获：核心写入点，记录 tool/input/output
PostToolUseFailure工具调用失败捕获：错误上下文，用于学习避坑
PreCompact上下文窗口即将压缩召回：把记忆重新注入避免遗忘
SubagentStart子 Agent 启动捕获：sub-agent 生命周期标记
SubagentStop子 Agent 结束捕获：sub-agent 结果汇总
StopAgent 完成本轮回复巩固：会话总结 + 知识图谱抽取
SessionEnd会话结束巩固：Working → Episodic 转化
SECTION · 03

写入流水线 · 6 步Write Pipeline (6 Stages)

每次 PostToolUse 触发，数据要走完 6 道工序才能成为可被检索的"记忆"。这是 agentmemory 把"原始观察"变成"结构化记忆"的核心通道。

FIG · 3.1 · WRITE PIPELINE · DATA FLOW
tool_name tool_input tool_output session_id JSON · STDIN 捕获 CAPTURE 01 /observe SHA-256 DEDUP 02 5 分钟窗口 隐私过滤 PRIVACY 03 strip secrets 原始入库 SQLITE 04 Working 层 LLM 压缩 COMPRESS 05 可选 · 默认关 BM25 索引 向量 索引 06 DUAL INDEX FROM RAW OBSERVATION TO STRUCTURED MEMORY ⚠ 这一步是 token 大头 默认 OFF 避免成本爆炸 本地 all-MiniLM-L6-v2 免费 · 离线 · +8pp
写入流水线全图。Step 1-4 是必经环节，Step 5（LLM 压缩）默认关闭以避免 token 成本，Step 6 的双索引是检索精度的关键。

捕获 · Capture

Hook 子进程读取 stdin 的 JSON：{tool_name, tool_input, tool_output, session_id, cwd}，HTTP POST 到 localhost:3111/agentmemory/observe。这一步必须在 AbortSignal.timeout() 保护下进行，避免拖累 Agent 主流程。

SHA-256 去重 · Dedup

对 observation 内容做指纹，5 分钟窗口内的重复内容直接丢弃。这一步专治"循环调用工具产生的噪声"——比如 Agent 反复 Read 同一个文件。

隐私过滤 · Privacy

正则扫描，剥离 API Key、密码、Token、<private> 标签包裹的内容。这一步在落库前完成——这是一道硬约束，确保敏感信息永远不进入持久化层。

原始入库 · Persist

落到 SQLite 的 Working 层（./data/state_store.db），打时间戳、session_id、project 标签。Raw observation 永久保留作为 ground truth，是后续所有 citation provenance 的源头。

LLM 压缩 · Compress（可选）

仅当 AGENTMEMORY_AUTO_COMPRESS=true 时启用。调用 LLM 把 raw observation 压成结构化的 {facts, concepts, narrative}。这一步是 token 大头——所以默认关闭，让用户按需开启。

双索引 · Dual Index

同时构建 BM25 倒排索引（词干 + 同义词扩展）和 Vector embedding（默认本地 all-MiniLM-L6-v2，免费）。这两个索引是后续"三流融合检索"中的两条主流，决定召回精度。

SECTION · 04

读取流水线 · 4 步Read Pipeline (4 Stages)

每次 SessionStart 触发，agentmemory 要在毫秒级内决定"这次会话该让 Agent 知道哪些历史"。这就是读取流水线的工作。

FIG · 4.1 · TRI-STREAM RETRIEVAL ARCHITECTURE
用户 Query + project context 项目画像 PROJECT PROFILE 概念 + 文件 + 模式 STEP 01 BM25 流 KEYWORD STREAM Vector 流 SEMANTIC STREAM Graph 流 GRAPH STREAM STEP 02 · 三流并行 RRF 融合 k = 60 + session 多样化 STEP 03 Token 预算 ≤ 2000 tok 按相关性截断 TOKEN BUDGET STEP 04 注入 → Claude Code first turn stem + syn cosine sim BFS entity 三流并行执行 · 互补不冲突 Reciprocal Rank Fusion 硬约束 · 不超过 2K token
读取流水线的精髓在 RRF 融合：BM25 抓精确关键词、Vector 抓语义相似、Graph 抓关系结构。三者互补，最终合并出一个排序，再按 token 预算截断注入。

三流的分工逻辑

流算法何时启用擅长什么
BM25词干匹配 + 同义词扩展始终精确关键词、类名、变量名
Vector余弦相似度（dense embedding）配置了 embedding provider语义相似、概念召回
Graph知识图谱 BFS 遍历查询中检测到实体关系类查询（A 用了什么）
设计取舍 · DESIGN TRADE-OFF 为什么三流融合而不是单纯 vector？ Vector 召回会漏精确关键词（如类名、变量名）。BM25 精确但不懂语义。Graph 处理关系类查询。RRF 让三者互补，LongMemEval-S 上 R@5 达到 95.2%，比 BM25-only 提升 9 个百分点。
SECTION · 05

4 层记忆巩固Four-Tier Consolidation

这是 agentmemory 最有"哲学味"的设计——它仿照人脑睡眠记忆巩固机制，把记忆按"短期 → 长期 → 知识 → 习惯"四级流转。

FIG · 5.1 · MEMORY HIERARCHY · BIO-INSPIRED
Working SHORT-TERM · 短期记忆 原始 observation PostToolUse 实时写入 · raw 数据 ~小时 短保留 SessionEnd 触发 Episodic EPISODIC · 情景记忆 压缩后的会话摘要 "发生了什么" · Stop / SessionEnd 触发 ~天 中保留 cron / consolidate Semantic SEMANTIC · 语义记忆 抽取的事实与模式 "我知道什么" · 后台周期巩固 ~月 长保留 高频 + 低衰减 Procedural PROCEDURAL · 程序记忆 工作流与决策模式 "怎么做" · 周期性 + 矛盾检测 ~永久 核心知识 L1 L2 L3 L4 EBBINGHAUS DECAY
从上往下，记忆在四层之间流转：raw observation → 摘要 → 知识 → 习惯。每一层的保留时间和重要性递增，访问越频繁的记忆越往下"沉淀"。

衰减规则

Ebbinghaus 曲线，常访问的记忆强化（importance score 上升），陈旧的自动驱逐。检测到矛盾时新事实覆盖旧事实，但旧事实保留在 audit trail 可追溯——这是 citation provenance 的根基。

SECTION · 06

端到端时序 · 一次"加 Auth"任务End-to-End Sequence

把所有零件串起来。下面是真实场景的完整时序：用户让 Claude Code 给 API 加 JWT 认证，agentmemory 在背景里默默地完成了从召回到捕获到巩固的全过程。

FIG · 6.1 · TIMELINE · USER ASKS "ADD JWT AUTH"
用户 USER Claude Code AGENT FRONTEND Hook BRIDGE agentmemory SERVER T₀ 打开 会话 opens SessionStart Hook /start 召回 + 注入 1.8K tok 上下文 T₁ "加 JWT 认证" UserPromptSubmit /observe 捕获 prompt T₂ PreToolUse · Read 查文件历史 (空) PostToolUse · Read 写入: 读取 middleware T₃ PostToolUse · Write 写入: auth.ts + jose T₄ PostToolUse · Bash 写入: test 12/12 ✓ T₅ 收到回复 Stop Hook 巩固 + 知识图谱 JWT—uses—jose T₆ 关闭 SessionEnd Working → Episodic
UML 风格的时序图。注意三件事：（1）召回类（绿）只发生在 T₀ 和 PreToolUse；（2）写入类（橙）密集分布在每次工具调用；（3）巩固类（T₅ T₆）发生在会话末，是 Working → Episodic 的关键转化时刻。
收益时刻 · PAYOFF MOMENT 下次会话用户开口"给 API 加限流"时，agentmemory 已经在 SessionStart 时把这些注入了：auth 用的是 jose middleware、测试在 test/auth.test.ts、你选了 jose 而非 jsonwebtoken（有 Edge 兼容理由）。零重新解释。这就是整个系统存在的意义。
SECTION · 07

关键设计取舍Architectural Trade-offs

读完机制只是入门，理解为什么这么设计才是真正的洞察。下面是四个核心问题。

① 为什么用 Hook 而不是 MCP 主动调？

Hook 由 Claude Code 强制触发，模型无权决定要不要记——这是"零人工成本"的根基。MCP 工具需要模型主动调用，会受 prompt 工程影响。Trae、Cursor 这些还没有 Hook 体系的客户端，体验就明显打折扣。

② 为什么先 raw 入库再 LLM 压缩？

LLM 压缩会丢细节。raw observation 永久保留作为 ground truth，压缩版用于检索召回。两者通过 citation provenance 链接，任何检索结果都可回溯到原始观察。这一双层设计是审计与信任的关键。

③ 为什么三流融合而不是单纯 vector？

Vector 召回会漏精确关键词（如类名、变量名）。BM25 精确但不懂语义。Graph 处理关系类查询。RRF 让三者互补，LongMemEval-S 上 R@5 达到 95.2%，比 BM25-only 提升 9 个百分点。

④ 为什么默认本地 embedding？

all-MiniLM-L6-v2 离线、免费、+8pp recall over BM25-only。年成本 $0，对比 OpenAI text-embedding-3-small 的 $0.02/1M token，对长期使用极友好。"开箱即用且免费"是社区采纳率的护城河。

SECTION · 08

一句话总结TL;DR

PRINCIPLE · ONE-LINER

Hook 是手，让 Claude Code 在 12 个时机自动喂数据；流水线是胃，把 raw observation 消化成结构化记忆；三流融合是嘴，把对的记忆在对的时机吐回去。三者构成一个不需要用户操心的"长期记忆器官"。