记忆系统 on Yison's Blog

AI Agent 的记忆革命：MemPalace 如何用'宫殿隐喻'重构 LLM 记忆

Sun, 17 May 2026 00:00:00 +0000

金鱼记忆的 AI Agent

用 AI Agent 写代码的人，大概都有过这样的时刻：

你花了三个小时跟 Agent 讨论架构方案，做了十几轮代码迭代，终于把认证模块从 OAuth 1.0 迁移到 OAuth 2.0。第二天打开新会话，Agent 一脸茫然：“请问您想实现什么功能？”

三个小时的上下文，就这么蒸发了。

这不是 Agent 笨——这是记忆系统的根本性缺陷。当前所有主流方案（Mem0、Mastra、Supermemory）都在做同一件事：用 LLM 决定记什么。它们提取事实、生成摘要、压缩上下文，然后把原始对话丢进垃圾桶。

问题在于：当 LLM 提取出"用户喜欢 PostgreSQL"并丢弃原始对话时，它丢失了为什么喜欢、考虑过哪些替代方案、讨论了哪些权衡。

MemPalace 说：别提取了，把原文存下来。

这个反直觉的方案，在 LongMemEval 基准上跑出了 96.6% 的检索召回率——不需要任何 API，不需要云端，不需要 LLM。

一、MemPalace：不只是另一个 RAG

1.1 核心理念

MemPalace 的设计哲学可以用一句话概括：

原始文本 > LLM 提取。简单的事情做对了，比复杂的事情做错了更好。

维度	传统方案（Mem0 等）	MemPalace
存储内容	LLM 提取的事实/摘要	原始对话文本（verbatim）
信息损耗	高（提取过程丢失上下文）	零（原文存储）
检索方式	向量语义搜索	BM25 + 向量 + Closet Boost 混合搜索
LLM 依赖	必须（提取和检索都需要）	可选（核心路径零 API）
隐私性	数据通常上传云端	本地优先，数据不出机器

1.2 灵感来源

MemPalace 的架构灵感来自两个经典方法论：

卢曼卡片笔记法（Zettelkasten）：德国社会学家尼克拉斯·卢曼用小的、交叉引用的索引卡片管理知识。每张卡片是一个原子想法，通过链接形成知识网络。

古希腊记忆宫殿法（Method of Loci）：把需要记忆的内容"放置"在想象中的空间位置，通过"行走"回忆。MemPalace 的 Wings、Rooms、Drawers 就是这个隐喻的代码实现。

二、宫殿架构：四层结构深度剖析

MemPalace 的核心是一个四层递进的存储结构：

graph TD
 A[🏰 Palace 宫殿] --> B[🦋 Wing 翼楼]
 B --> C[🚪 Room 房间]
 C --> D[🗄️ Closet 衣柜]
 D --> E[📄 Drawer 抽屉]
 
 B --> |"人物/项目/主题"| B1["wing_kai
wing_driftwood
wing_auth-system"]
 C --> |"主题/时间段"| C1["auth-migration
graphql-switch
ci-pipeline"]
 D --> |"AAAK压缩索引"| D1["§ W-042/R-11/D-007
@p noah~son.age=6
@e birthday~party"]
 E --> |"原始文本"| E1["完整的对话内容
代码片段
决策记录"]
 
 style A fill:#1e293b,stroke:#22d3ee,color:#e2e8f0
 style B fill:#1e3a5f,stroke:#38bdf8,color:#e2e8f0
 style C fill:#1e3a5f,stroke:#38bdf8,color:#e2e8f0
 style D fill:#1e3a5f,stroke:#38bdf8,color:#e2e8f0
 style E fill:#1e3a5f,stroke:#38bdf8,color:#e2e8f0

2.1 Wing（翼楼）—— 顶层组织单元

每个 Wing 代表一个实体：一个人、一个项目、或一个主题。

wing_kai → 某个人的所有对话
wing_driftwood → 某个项目的所有记录
wing_auth-system → 认证系统相关的所有内容

设计意图：当搜索"Kai 的认证方案"时，可以限定在 wing_kai 范围内搜索，避免其他项目的噪音干扰。

2.2 Room（房间）—— 主题分组

每个 Wing 下有多个 Room，代表具体主题或时间段：

wing_kai/
 ├── room_auth-migration → OAuth 迁移相关
 ├── room_graphql-switch → GraphQL 切换相关
 └── room_ci-pipeline → CI 流水线相关

Room 通常从文件夹结构自动检测，也可以手动创建。

2.3 Closet（衣柜）—— AAAK 压缩索引

这是 MemPalace 最精妙的设计。Closet 是一个压缩的索引层，用一种叫 AAAK 的密集符号语言编写，LLM 可以一眼扫描数千条索引，精确定位到需要的 Drawer。

§ W-042/R-11/D-007  # 定位符：翼楼-042/房间-11/抽屉-007
@p noah~son.age=6~dob=09-12 # 人物：Noah，儿子6岁，生日9月12日
@l glebe-pt-rd.park  # 地点：Glebe Point Road 公园
@e birthday~party(n≈8)  # 事件：生日派对，约8人
@i therizinosaurus~claws  # 兴趣：镰刀龙的爪子
@t 2026-04-14T09:41  # 时间戳
§ ptr → D-007 (verbatim)  # 指针：指向抽屉-007的原始文本

为什么需要 Closet？

直接搜索所有 Drawer 效率太低。Closet 就像图书馆的目录卡片——先看目录，再去找书。LLM 扫描 Closet 可以瞬间知道"关于 Noah 生日的信息在 D-007"，然后直接读取那个 Drawer 的完整内容。

2.4 Drawer（抽屉）—— 原始文本存储

最底层，存储原始对话的完整文本。不做任何摘要、压缩或改写。

Drawer D-007:
 "Noah's birthday party was at the park on Glebe Point Road.
 About 8 kids came. He was really into therizinosaurus claws
 at the time, so the cake had a dinosaur theme..."

2.5 Hall（大厅）—— 概念分类

每个 Wing 内还有隐含的 Hall 分类：

Hall	内容
`hall_facts`	做出的决定、锁定的选择
`hall_events`	会话、里程碑、调试过程
`hall_discoveries`	突破、新洞察
`hall_preferences`	习惯、偏好、观点
`hall_advice`	建议和解决方案

2.6 Tunnel（隧道）—— 跨翼楼连接

当两个 Wing 有相同的 Room 名称时，自动建立 Tunnel 连接：

wing_kai / hall_events / auth-migration → "Kai 调试了 OAuth token refresh"
wing_driftwood / hall_facts / auth-migration → "团队决定迁移到 Clerk"
wing_priya / hall_advice / auth-migration → "Priya 批准了 Clerk 而非 Auth0"

搜索"auth-migration"时，可以通过 Tunnel 找到所有相关 Wing 的内容。

三、核心实现原理

3.1 混合搜索算法

MemPalace 的搜索不是简单的向量检索，而是一个三阶段混合管道：

sequenceDiagram
 participant U as 用户查询
 participant V as 向量搜索引擎
 participant B as BM25 关键词搜索
 participant C as Closet Boost
 participant R as 混合排序器
 participant N as 邻居扩展
 
 U->>V: 语义相似度搜索
 V->>R: 返回 Top-K 候选（cosine distance）
 
 U->>B: 关键词匹配
 B->>R: 返回 BM25 候选（Okapi-BM25）
 
 R->>R: 合并候选集（Union Merge）
 R->>R: 混合排序
score = 0.6 × vector_sim + 0.4 × bm25_norm
 
 R->>C: 查询 Closet 索引
 C->>R: 返回 Boost 信号
boost = [0.40, 0.25, 0.15, 0.08, 0.04]
 R->>R: 应用 Boost
effective_dist = max(0, raw_dist - boost)
 
 R->>N: 对 Top 结果扩展 ±1 邻居
 N->>U: 返回最终结果（含上下文）
 
 Note over U,N: 整个过程零 API 调用，纯本地执行

BM25 实现细节

MemPalace 使用 Okapi-BM25 算法，参数经过精心调优：

# BM25 参数
k1 = 1.5 # 词频饱和度（term-frequency saturation）
b = 0.75 # 长度归一化（length normalization）

# IDF 计算：使用 Lucene/BM25+ 平滑公式
# 避免除零错误，对罕见词给予更高权重
idf = log(1 + (N - n + 0.5) / (n + 0.5))

# 最终分数归一化到 [0, 1]，与向量分数可比较
bm25_norm = (score - min_score) / (max_score - min_score)

Closet Boost 机制

Closet 不是搜索的"门"，而是"助推器"：

CLOSET_RANK_BOOSTS = [0.40, 0.25, 0.15, 0.08, 0.04] # 基于排名的 Boost
CLOSET_DISTANCE_CAP = 1.5 # 距离 > 1.5 的 Closet 信号太弱，忽略

# 有效距离 = max(0, min(2, 原始距离 - boost))
# 效果：匹配 Closet 的 Drawer 被拉到更前面

关键设计决策：Closet 只是排序信号，不是过滤器。即使 Closet 没命中，直接搜索 Drawer 也能找到结果。这避免了"Closet 质量差导致搜不到"的问题。

邻居扩展

当找到一个匹配的 Drawer 时，自动扩展其前后各 1 个 Drawer：

def expand_with_neighbors(drawers_col, matched_doc, matched_meta, radius=1):
 """扩展匹配的 Drawer，包含 ±radius 的兄弟块。"""
 # 解决"对话被切断"的问题
 # 例如：Drawer 5 讨论了方案 A，Drawer 6 讨论了方案 B
 # 搜索"方案 A"时，返回 Drawer 5 + 6，提供完整上下文

BM25-Only 降级方案

当 HNSW 索引损坏时，自动降级到纯 BM25 搜索：

def bm25_only_via_sqlite(query, palace_path, ...):
 """BM25-only 搜索，直接从 chroma.sqlite3 读取。"""
 # 绕过 ChromaDB 的 Python 客户端
 # 使用 ChromaDB 内部的 FTS5 三元组索引
 # 当 HNSW 段损坏或不可加载时自动触发

3.2 知识图谱：时间感知的实体关系

MemPalace 内置了一个时间感知的实体关系图谱，用 SQLite 实现（不是 Neo4j）：

-- 实体表
CREATE TABLE entities (
 id TEXT PRIMARY KEY, -- 规范化名称（小写，下划线）
 name TEXT NOT NULL, -- 原始名称
 type TEXT DEFAULT 'unknown', -- person, project, tool, concept
 properties TEXT DEFAULT '{}', -- JSON 元数据
 created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

-- 关系三元组表
CREATE TABLE triples (
 id TEXT PRIMARY KEY,
 subject TEXT NOT NULL, -- FK → entities.id
 predicate TEXT NOT NULL, -- 关系类型
 object TEXT NOT NULL, -- FK → entities.id
 valid_from TEXT, -- 生效时间
 valid_to TEXT, -- 失效时间（NULL = 仍有效）
 confidence REAL DEFAULT 1.0, -- 置信度
 source_closet TEXT, -- 链接到原始记忆
 source_drawer_id TEXT -- 溯源信息
);

使用示例：

from mempalace.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()

# 添加事实（带时间窗口）
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")

# 查询：Kai 的所有关系
kg.query_entity("Kai")

# 时间旅行查询：2026年1月的事实
kg.query_entity("Maya", as_of="2026-01-20")

# 时间线：Orion 项目的历史
kg.timeline("Orion")

# 失效旧事实
kg.invalidate("Kai", "works_on", "Orion", ended="2026-03-01")

3.3 Hook 系统：零 Token 的自动保存

MemPalace 的 Hook 系统是零 Token 消耗的自动保存机制：

sequenceDiagram
 participant U as 用户
 participant A as AI Agent
 participant H as Hook 系统
 participant P as Palace 存储
 
 U->>A: 发送消息（第15条）
 A->>A: 正常处理消息
 
 Note over H: Stop Hook 触发
（每15条消息）
 H->>A: 注入提示词：
"保存关键话题/决策/引用到 Palace"
 A->>P: 调用 mempalace_add_drawer
保存本次会话内容
 P-->>A: 确认保存
 A->>U: 继续正常对话
 
 Note over H: PreCompact Hook 触发
（上下文压缩前）
 H->>A: 紧急保存提示：
"上下文即将压缩，保存所有内容"
 A->>P: 批量保存所有未保存内容
 P-->>A: 确认保存
 
 Note over U,P: Hook 是本地 bash 脚本
不消耗 API Token

Hook 配置：

在 .claude/settings.local.json 中配置（详见第六章安装指南）。

性能指标：

Stop Hook 执行时间：< 500ms
PreCompact Hook 执行时间：< 500ms
启动注入（wake-up）：< 100ms
测试规模：150K+ Drawers

四、MCP 工具生态：30 个工具全景

MemPalace 通过 MCP（Model Context Protocol）暴露了 30 个工具，覆盖记忆系统的完整生命周期：

4.1 读取工具（7 个）

工具	功能
`mempalace_status`	宫殿概览：总 Drawer 数、Wing/Room 计数、AAAK 规范
`mempalace_list_wings`	列出所有 Wing 及其 Drawer 数量
`mempalace_list_rooms`	列出指定 Wing 下的 Room
`mempalace_get_taxonomy`	完整的 Wing → Room → Drawer 数量树
`mempalace_search`	语义搜索：返回原始 Drawer 内容 + 相似度分数
`mempalace_check_duplicate`	检查内容是否已存在（阈值 0.85-0.87）
`mempalace_get_aaak_spec`	返回 AAAK 索引规范

4.2 写入工具（6 个）

工具	功能
`mempalace_add_drawer`	将原始内容存入 Palace
`mempalace_delete_drawer`	删除 Drawer（不可逆）
`mempalace_sync`	清理已删除/移动的源文件对应的 Drawer
`mempalace_get_drawer`	获取单个 Drawer 的完整内容
`mempalace_list_drawers`	分页列出 Drawer
`mempalace_update_drawer`	更新 Drawer 内容/元数据

4.3 知识图谱工具（5 个）

工具	功能
`mempalace_kg_query`	查询实体关系（支持时间过滤）
`mempalace_kg_add`	添加事实三元组
`mempalace_kg_invalidate`	标记事实失效
`mempalace_kg_timeline`	实体的时间线
`mempalace_kg_stats`	图谱概览

4.4 导航工具（7 个）

工具	功能
`mempalace_traverse`	从某个 Room 开始遍历，找到跨 Wing 的关联内容
`mempalace_find_tunnels`	找到连接两个 Wing 的 Tunnel
`mempalace_graph_stats`	宫殿图概览：节点、隧道、边、连通性
`mempalace_create_tunnel`	创建跨 Wing 的 Tunnel
`mempalace_list_tunnels`	列出所有 Tunnel
`mempalace_delete_tunnel`	删除 Tunnel
`mempalace_follow_tunnels`	跟踪 Tunnel 到达其他 Wing

4.5 Agent 日记工具（2 个）

工具	功能
`mempalace_diary_write`	写入 Agent 个人日记
`mempalace_diary_read`	读取最近的日记条目

4.6 系统工具（3 个）

工具	功能
`mempalace_hook_settings`	获取/设置自动保存 Hook 行为
`mempalace_memories_filed_away`	检查最近的 Palace 检查点是否已保存
`mempalace_reconnect`	强制重连 Palace 数据库

五、性能基准：96.6% 的真实含义

5.1 LongMemEval 结果

模式	R@5	是否需要 LLM	成本
Raw（纯语义搜索）	96.6%	❌	$0
Hybrid v4（held-out 450题）	98.4%	❌	$0
Hybrid v4 + Haiku rerank	100%	✅ Haiku	~$0.001/次
Hybrid v4 + Sonnet rerank	100%	✅ Sonnet	~$0.003/次

重要说明：

96.6% 是检索召回率（R@5），不是 QA 准确率
100% 的最后 0.6% 是通过检查 3 个特定错误答案达到的（属于"教学生应付考试"）
诚实的泛化数字是 held-out 450 题的 98.4%

5.2 与其他系统对比

系统	分数	指标类型	说明
MemPalace (raw)	96.6%	R@5 召回率	零 API，纯本地
Mastra	94.87%	QA 准确率	不同指标，不可直接比较
Supermemory ASMR	~99%	QA 准确率	实验性，8-12 Agent 集成
Hindsight	91.4%	未验证	需要检查方法论
Mem0	~66.9%	QA 准确率（LoCoMo）	不同基准

关键洞察：Mem0 在 ConvoMem 基准上只有 30-45%，而 MemPalace 是 92.9%——2 倍以上的差距。原因是 Mem0 用 LLM 提取记忆，提取错了记忆就丢了；MemPalace 存原始文本，什么都不丢。

5.3 社区争议

Hacker News 上对 MemPalace 的基准分数有质疑：

100% 分数被揭穿：GitHub issues #27、#29、#39、#125、#242 有详细的揭穿记录
LoCoMo 100% 有问题：使用 top-k=50 超过了会话数量；诚实的 top-10 无 rerank 是 88.9%
名人效应：作者是演员 Milla Jovovich，带来了关注度但也带来了质疑
安全警告：相关域名被发现传播恶意软件（GitHub issue #326）

客观来看：基准分数有水分，但核心理念（原始文本 > LLM 提取）是成立的。96.6% 的 raw 分数仍然很亮眼——不需要任何 API 就能达到这个水平，说明"简单的事情做对了"这个思路是对的。

六、安装与使用指南

6.1 安装

推荐使用 uv 安装（Python 包管理器）：

# 安装 uv（如果没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 MemPalace
uv tool install mempalace

# 或者用 pip
pip install mempalace

安装完成后，mempalace CLI 就可以直接使用了。

6.2 初始化与挖掘

# 初始化项目记忆（交互式，会自动检测实体）
mempalace init ~/projects/myapp

# 非交互式初始化（适合脚本）
mempalace init --yes ~/projects/myapp

# 挖掘项目文件
mempalace mine ~/projects/myapp

# 挖掘 Claude Code 会话历史
mempalace mine ~/.claude/projects/ --mode convos

# 挖掘时指定 Wing（按项目分组）
mempalace mine ~/.claude/projects/myapp --mode convos --wing myapp

6.3 搜索模式

MemPalace 提供三种搜索模式，按需选择：

模式	命令	特点
Raw（默认）	`mempalace search "查询内容"`	纯向量语义搜索，零 API，96.6% R@5
Hybrid	`mempalace search --mode hybrid "查询内容"`	BM25 + 向量混合搜索，98.4% R@5
Hybrid + Rerank	`mempalace search --mode hybrid --llm-rerank "查询内容"`	混合搜索 + LLM 重排，≥99% R@5

# 基础语义搜索
mempalace search "为什么选择 GraphQL 而不是 REST"

# 混合搜索（推荐，效果最好）
mempalace search --mode hybrid "OAuth 迁移遇到的问题"

# 限定 Wing 范围搜索
mempalace search --wing myapp "认证方案设计"

# 限定 Room 范围搜索
mempalace search --wing myapp --room auth-migration "token 刷新逻辑"

6.4 配置 Claude Code Hook

在项目的 .claude/settings.local.json 中添加 Hook，实现自动保存：

{
 "hooks": {
 "Stop": [{
 "matcher": "",
 "hooks": [{
 "type": "command",
 "command": "mempalace-hook-stop"
 }]
 }],
 "PreCompact": [{
 "matcher": "",
 "hooks": [{
 "type": "command",
 "command": "mempalace-hook-precompact"
 }]
 }]
 }
}

Stop Hook：每 15 条用户消息自动触发，保存关键内容
PreCompact Hook：上下文压缩前紧急保存，防止记忆丢失

6.5 唤醒上下文

在新会话开始前，用 wake-up 注入历史记忆：

# 自动注入相关历史上下文
mempalace wake-up

执行后，Agent 会自动获得最近的项目记忆，不再"失忆"。

6.6 知识图谱操作

# 查看知识图谱统计
mempalace kg stats

# 通过 Python API 操作
python3 -c "
from mempalace.knowledge_graph import KnowledgeGraph
kg = KnowledgeGraph()
kg.add_triple('Kai', 'works_on', 'Orion', valid_from='2025-06-01')
print(kg.query_entity('Kai'))
"

七、实际应用场景

7.1 代码开发：跨会话的项目记忆

效果：Agent 可以回忆起三个月前讨论的技术选型理由、考虑过的替代方案、以及最终决策的上下文。

7.2 知识管理：个人知识图谱

用知识图谱记录学到的知识和关系，支持时间旅行查询——“这个知识是怎么积累的”。

7.3 团队协作：共享记忆库

每个团队成员有自己的 Wing，通过 Tunnel 连接相关工作。搜索时可以跨 Wing 找到所有相关内容。

7.4 私有化部署：数据不出机器

MemPalace 的本地优先设计特别适合私有化场景：

所有数据存储在本地 SQLite + ChromaDB
核心路径零 API 调用
可选的 LLM rerank 可以用本地模型（Ollama）
适合对数据安全要求高的企业环境

八、启发与未来展望

8.1 AI 记忆系统的设计思路

MemPalace 给我们最大的启发是：

不要让 AI 决定记什么。存原始文本，让搜索算法决定找什么。

这个思路可以应用到很多场景：

代码审查记录：存完整的 diff 和讨论，而不是摘要
需求文档：存原始的用户对话，而不是需求分析师的理解
故障排查：存完整的日志和排查过程，而不是事后总结
会议记录：存原始的发言内容，而不是会议纪要

简单的事情做对了，比复杂的事情做错了更好——这个工程哲学值得每一个系统设计者铭记。

8.2 从搜索到记忆组织

MemPalace 的四层结构（Wing → Room → Closet → Drawer）暗示了一个更大的趋势：

AI 需要的不是更好的搜索，而是更好的记忆组织。

当前的 RAG 系统大多是"扁平"的——所有文档扔进一个向量库，搜索时暴力匹配。MemPalace 的分层结构让搜索可以限定范围，就像在图书馆里先找到对应楼层、对应书架，再找具体那本书。

未来的记忆系统可能会：

自动学习用户的记忆模式（哪些信息关联在一起）
主动推送相关记忆（“你三个月前讨论过类似的问题”）
支持记忆的"遗忘"（过时信息自动降权）

8.3 记忆系统的标准化

当前 AI 记忆系统处于"战国时代"——每个项目都有自己的架构和接口。未来可能会出现：

统一的记忆协议（类似 MCP 之于工具调用）
可互操作的记忆后端（MemPalace 的可插拔后端是好的开始）
记忆交换格式（让不同 Agent 共享记忆）

8.4 记忆的隐私与所有权

MemPalace 的本地优先设计提出了一个重要问题：

AI 的记忆应该归谁所有？

用户的对话记忆应该存储在用户控制的地方
企业内部的知识记忆应该有访问控制
记忆的"删除权"应该被尊重

这不仅是技术问题，更是产品伦理问题。当 AI 越来越了解我们，谁拥有这些"了解"，将成为一个绕不开的议题。

参考资料

MemPalace GitHub: https://github.com/MemPalace/mempalace
官方文档: https://mempalaceofficial.com
LongMemEval 基准: https://github.com/MemPalace/mempalace/tree/main/benchmarks
Hacker News 讨论: https://news.ycombinator.com/item?id=43554262
Mem0 Research: https://mem0.ai/research
Mastra Observational Memory: https://mastra.ai/research/observational-memory
卢曼卡片笔记法: https://zettelkasten.de/

本文基于 MemPalace v3.3.5（2026-05-09）版本分析。项目仍在活跃开发中，部分细节可能随版本更新而变化。

Claude Code 的记忆系统是怎么工作的？源码级拆解

Tue, 12 May 2026 00:00:00 +0000

Claude Code 的记忆系统是怎么工作的？源码级拆解

你周五用 Claude Code 调 bug 到凌晨两点，周一打开新会话，它张嘴就说：“上次那个 auth 模块的 bug 修好了吗？测试记得起 Redis。“你愣住了——你没告诉过它这些。

一、一个细思极恐的瞬间

用过 Claude Code 的开发者大概都经历过这个瞬间：

你关掉终端，第二天重新打开，开始一个新对话。Claude 什么都没问，直接开始干活。它知道你的项目用 pnpm 而不是 npm，知道测试需要本地 Redis，知道你讨厌 verbose 的输出。

你仔细回想：我什么时候告诉它这些的？

答案是：你没有直接告诉它。是它自己"记住"的。

Claude Code 每次启动都是一个全新的上下文窗口，不携带任何历史对话。所有它"知道"的东西，都必须在第一轮对话之前从磁盘加载。

我花了一周时间读 Claude Code 的 TypeScript 源码（是的，它是开源的），发现它的记忆系统比官方文档描述的复杂得多。今天来拆解一下。

二、两套记忆系统：你写的 vs AI 写的

Claude Code 有两套完全独立的记忆系统，各司其职：

graph TB
 subgraph "Claude Code 记忆全景"
 subgraph "CLAUDE.md（你写的）"
 A1[手动维护]
 A2[指令/规则/偏好]
 A3[通过 git 同步]
 A4[加载后不变化]
 end
 
 subgraph "Auto Memory（AI 写的）"
 B1[自动提取]
 B2[用户画像/行为纠正]
 B3[项目状态/外部引用]
 B4[每轮对话可能更新]
 end
 
 A1 --> C[启动时加载到上下文]
 B1 --> C
 end
 
 style A1 fill:#0f3460,stroke:#e94560,color:#fff
 style A2 fill:#0f3460,stroke:#e94560,color:#fff
 style A3 fill:#0f3460,stroke:#e94560,color:#fff
 style A4 fill:#0f3460,stroke:#e94560,color:#fff
 style B1 fill:#533483,stroke:#e94560,color:#fff
 style B2 fill:#533483,stroke:#e94560,color:#fff
 style B3 fill:#533483,stroke:#e94560,color:#fff
 style B4 fill:#533483,stroke:#e94560,color:#fff
 style C fill:#e94560,stroke:#fff,color:#fff

关键区别：

维度	CLAUDE.md	Auto Memory
谁写的	你手动写	Claude 自动写
存储位置	项目目录 / 用户目录	`~/.claude/projects/` 下
同步方式	Git（可提交）	本地（不同步）
更新频率	你改才变	每轮对话可能更新
大小限制	40KB（建议）	索引 200 行 / 25KB
加载方式	启动时全部加载	索引全加载，topic 按需

2.1 CLAUDE.md 的加载链

优先级（高→低）：

1. 管理级 /etc/claude-code/CLAUDE.md ← IT 管理员写的，无法覆盖
2. 用户级 ~/.claude/CLAUDE.md ← 你的个人偏好
3. 项目级 ./CLAUDE.md 或 ./.claude/CLAUDE.md ← 团队共享（git 提交）
4. 本地级 ./CLAUDE.local.md ← 你的个人覆盖（不提交）

加载顺序：
 工作目录 → 向上遍历目录树 → 加载沿途所有 CLAUDE.md
 离工作目录近的优先级高

一个细节： CLAUDE.local.md 不在官方文档里，但源码中存在。它在项目 CLAUDE.md 之后、Auto Memory 之前加载。适合放个人的数据库密码、调试开关之类的——不提交到 git，但本地有效。

2.2 Auto Memory 的四种类型

Auto Memory 不是随意的笔记，而是有严格的分类：

graph TB
 subgraph "四种记忆类型"
 subgraph "user（用户画像）"
 U1[角色/偏好/知识水平]
 U2[始终私有]
 end
 
 subgraph "feedback（行为纠正）"
 F1[验证过的模式]
 F2[默认私有]
 end
 
 subgraph "project（项目状态）"
 P1[工作进展/决策]
 P2[倾向团队共享]
 end
 
 subgraph "reference（外部引用）"
 R1[系统指针]
 R2[通常团队共享]
 end
 end
 
 style U1 fill:#0f3460,stroke:#e94560,color:#fff
 style U2 fill:#0f3460,stroke:#e94560,color:#fff
 style F1 fill:#533483,stroke:#e94560,color:#fff
 style F2 fill:#533483,stroke:#e94560,color:#fff
 style P1 fill:#16213e,stroke:#e94560,color:#fff
 style P2 fill:#16213e,stroke:#e94560,color:#fff
 style R1 fill:#1a1a2e,stroke:#e94560,color:#fff
 style R2 fill:#1a1a2e,stroke:#e94560,color:#fff

为什么这样分？ 因为团队协作时，你的编码偏好（user）不应该泄露给队友，但项目进度（project）应该共享。这种分类直接影响记忆的加载和同步策略。

三、三个时间尺度：实时 / 会话 / 梦境

这是整套系统最精妙的部分。Auto Memory 不是"Claude 注意到什么就随手记下来”，而是有三个独立的后台进程，在不同时间尺度上提取信息：

graph LR
 subgraph "时间轴"
 A[Per-Turn
实时提取] -->|每轮对话| B[Per-Session
会话记忆]
 B -->|每个会话| C[autoDream
梦境整合]
 end
 
 subgraph "成本"
 D[极低
共享cache] 
 E[低
偶尔触发]
 F[中
24h+5会话门槛]
 end
 
 A --- D
 B --- E
 C --- F
 
 style A fill:#e94560,stroke:#fff,color:#fff
 style B fill:#533483,stroke:#fff,color:#fff
 style C fill:#0f3460,stroke:#fff,color:#fff
 style D fill:transparent,stroke:#e94560,color:#e94560
 style E fill:transparent,stroke:#533483,color:#533483
 style F fill:transparent,stroke:#0f3460,color:#0f3460

3.1 Per-Turn：实时提取（每轮对话后）

触发：每次完整查询循环结束
方式：fork 一个子 Agent 在后台运行
成本：极低（共享父 Agent 的 prompt cache）
权限：只读项目文件，只写记忆目录

一个细节： 如果主 Agent 在本轮已经写过记忆（你明确说"记住这个”），提取步骤会跳过那个范围，避免重复。

3.2 Per-Session：会话记忆（上下文增长时）

这是一个独立于 Auto Memory 的系统，目的是让当前会话的上下文在压缩后还能保留。

触发条件（三个同时满足）：

✅ 总上下文 ≥ 10,000 tokens
✅ 上下文增长 ≥ 5,000 tokens（自上次提取后）
✅ 工具调用 ≥ 3 次

提取的结构化笔记：

┌─────────────────────────────────────────┐
│ Session Memory 模板 │
├─────────────────────────────────────────┤
│ ## Current State │
│ 当前正在做什么，进展到哪一步 │
│ （上限 ~2000 tokens） │
├─────────────────────────────────────────┤
│ ## Files and Functions │
│ 涉及的文件、函数、关键代码位置 │
│ （上限 ~2000 tokens） │
├─────────────────────────────────────────┤
│ ## Errors & Corrections │
│ 遇到的错误、尝试过的方案、最终解决方案 │
│ （上限 ~2000 tokens） │
├─────────────────────────────────────────┤
│ ## Worklog │
│ 工作日志：做了什么、还剩什么 │
│ （上限 ~2000 tokens） │
└─────────────────────────────────────────┘
总计上限 ~12,000 tokens

为什么需要这个？ 当对话太长需要压缩时，有这些结构化笔记，auto-compact 可以复用它们，而不是从头重新摘要整个对话。效果好很多——因为笔记是增量提取的，上下文还完整时就记录了关键信息。

3.3 autoDream：梦境整合（每天/每几天）

这是最让人惊讶的部分。源码中明确把这叫做 “DreamTask”，UI 中会显示进度条。

graph TB
 subgraph "autoDream 触发条件"
 G1[Gate 1: 时间检查
≥ 24小时] -->|✅| G2[Gate 2: 会话检查
≥ 5个会话修改]
 G2 -->|✅| G3[Gate 3: 锁检查
.consolidate-lock 未占用]
 G3 -->|✅| EXEC[执行整合]
 
 G1 -->|❌| SKIP[跳过]
 G2 -->|❌| SKIP
 G3 -->|❌| SKIP
 end
 
 style G1 fill:#0f3460,stroke:#e94560,color:#fff
 style G2 fill:#0f3460,stroke:#e94560,color:#fff
 style G3 fill:#0f3460,stroke:#e94560,color:#fff
 style EXEC fill:#e94560,stroke:#fff,color:#fff
 style SKIP fill:#1a1a2e,stroke:#533483,color:#533483

整合流程（四阶段）：

Phase 1: 定向
 ├── 读取 MEMORY.md 索引
 └── 浏览现有 topic 文件
 目的：了解当前记忆状态

Phase 2: 发现
 └── 搜索日志和会话记录中的新知识
 目的：找到需要整合的信息

Phase 3: 写入
 ├── 写入/更新 topic 文件
 ├── 合并新信号到现有文件
 └── 相对日期 → 绝对日期（"昨天" → "2026-05-11"）
 目的：持久化新知识

Phase 4: 清理
 ├── 修剪 MEMORY.md 至 200 行以下
 ├── 移除过期指针
 └── 解决新旧事实矛盾
 目的：保证记忆质量

一个有趣的细节： 如果你杀掉整合进程，锁的修改时间会回滚，让下一个会话可以重试。这个错误处理很体贴。

它什么时候运行？ 不是等你关掉电脑或睡觉，而是在一次对话结束时——只要满足那三个 Gate。只是因为 24 小时和 5 个会话的门槛，大多数时候不会触发。

四、记忆召回：Sonnet 替你选

记忆存下来了，但怎么在需要的时候找到正确的记忆？

Claude Code 的方案是：让 Sonnet 替你选，不是关键词匹配。

graph TB
 subgraph "记忆召回流程"
 START[启动时] --> A[读取 MEMORY.md 索引
前 200 行]
 A --> B[扫描 topic 文件 frontmatter]
 B --> C[构建 manifest
filename + description]
 
 C --> D[每轮对话]
 D --> E[用户输入 + 工具结果]
 E --> F[调用 Sonnet 选择相关文件
最多 5 个]
 F --> G[读取选中文件
每文件 4KB 限制]
 G --> H[注入到 prompt]
 end
 
 subgraph "限制"
 L1[每轮最多 5 个文件]
 L2[每文件 4KB]
 L3[每轮预算 20KB]
 L4[会话累计 60KB]
 end
 
 style START fill:#e94560,stroke:#fff,color:#fff
 style A fill:#0f3460,stroke:#e94560,color:#fff
 style B fill:#0f3460,stroke:#e94560,color:#fff
 style C fill:#0f3460,stroke:#e94560,color:#fff
 style D fill:#533483,stroke:#fff,color:#fff
 style E fill:#533483,stroke:#fff,color:#fff
 style F fill:#533483,stroke:#fff,color:#fff
 style G fill:#533483,stroke:#fff,color:#fff
 style H fill:#e94560,stroke:#fff,color:#fff
 style L1 fill:transparent,stroke:#e94560,color:#e94560
 style L2 fill:transparent,stroke:#e94560,color:#e94560
 style L3 fill:transparent,stroke:#e94560,color:#e94560
 style L4 fill:transparent,stroke:#e94560,color:#e94560

为什么用 Sonnet 而不是关键词？ 因为语义理解更好。比如用户问"怎么跑测试"，关键词匹配可能找不到 feedback_testing.md，但 Sonnet 能理解这个意图。

但这里有一个结构性缺陷： 没有向量搜索，没有语义索引。如果 MEMORY.md 中的描述写得不好，或者 topic 文件太多（最多扫描 200 个，按修改时间排序），记忆就可能被"遗忘"。

五、什么能活过压缩？

长对话会被压缩。压缩后，什么能保留？

graph TB
 subgraph "压缩后存活分析"
 subgraph "✅ 能活过的（从磁盘重新加载）"
 A1[CLAUDE.md 文件]
 A2[Auto Memory 文件]
 A3[Session Memory 文件]
 end
 
 subgraph "❌ 活不过的"
 B1[只在对话中说过
没有保存到记忆系统的内容]
 end
 end
 
 style A1 fill:#0f3460,stroke:#e94560,color:#fff
 style A2 fill:#0f3460,stroke:#e94560,color:#fff
 style A3 fill:#0f3460,stroke:#e94560,color:#fff
 style B1 fill:#1a1a2e,stroke:#e94560,color:#e94560

源码中的清理代码：

// 压缩时，强制清除所有缓存，从磁盘重新加载
getUserContext.cache.clear()
resetGetMemoryFilesCache('compact')
clearSystemPromptSections()

教训： 如果你在对话中告诉 Claude 什么重要的东西，确保它写入了记忆。否则压缩后就没了。

六、与其他工具的对比

维度	Claude Code	Aider	Cursor	DeepSeek-TUI
记忆系统	✅ 三层架构	❌ 无	⚠️ 简单 rules	✅ 基础记忆
自动提取	✅ per-turn	❌	❌	⚠️ 手动
梦境整合	✅ autoDream	❌	❌	❌
记忆分类	✅ 4 种类型	❌	❌	❌
模型辅助召回	✅ Sonnet 选择	❌	❌	❌
团队同步	⚠️ feature flag	❌	❌	❌
记忆持久化	✅ 文件系统	❌	⚠️ 配置文件	✅ 文件系统

结论： Claude Code 的记忆系统是目前 AI 编程工具中最完善的。Aider 完全没有记忆，Cursor 只有简单的 rules 文件，DeepSeek-TUI 有基础记忆但没有自动提取和整合。

七、这套系统的局限

读完源码，我认为有几个结构性局限：

7.1 记忆是 per-repo 的

你在项目 A 教 Claude 的偏好，不会自动带到项目 B。用户级的 ~/.claude/CLAUDE.md 可以处理一部分，但它是静态的——Claude 不能在会话中自动更新它。

7.2 记忆是 machine-local 的

项目目录名经过 sanitize（非字母数字替换为连字符），但不同机器、不同用户名、不同挂载点会产生不同的目录名。同一项目，不同机器，不同记忆。

7.3 没有记忆衰减

所有记忆都是平等的。一个月前的偏好和今天的偏好权重一样。没有"热度"概念，没有自动遗忘机制。

7.4 依赖 Sonnet 的选择能力

如果 Sonnet 选错了记忆文件，或者描述写得不好，记忆就"丢了"。没有 fallback 机制。

八、对我们的启示

这套系统给我们什么启发？

8.1 记忆是 AI 工具的核心差异化

目前市面上的开源 AI 编程工具（Aider、OpenCode、Continue），没有一个有真正意义上的记忆系统。这是差异化机会。

8.2 梦境整合是一个优雅的设计

不是每次对话都提取记忆（太频繁，噪音多），也不是完全不提取（会丢失）。三个时间尺度的设计——实时、会话、梦境——是一个很好的平衡。

8.3 模型辅助召回比关键词匹配更好

让 Sonnet 选择相关的记忆文件，而不是 grep 关键词。这在语义理解上好很多，但成本也更高。

对于开源工具，可以考虑一个折中方案：先用关键词过滤缩小范围，再用小模型选择。

8.4 记忆质量 > 记忆数量

Claude Code 严格限制记忆的大小（200 行索引、4KB 单文件、60KB 会话累计）。这不是偷懒，而是有意为之——太多记忆反而会干扰。

九、写在最后

读完 Claude Code 的记忆系统源码，我最大的感受是：

好的 AI 工具不是模型能力的比拼，而是工程设计的比拼。

同样的 Claude 模型，有记忆系统和没有记忆系统，用户体验天差地别。记忆系统本身不需要更强大的模型，它需要的是精心的工程设计——什么时候提取、怎么存储、如何召回、何时整合。

这些工程细节，才是真正的壁垒。

本文基于 Claude Code TypeScript 源码分析。源码地址：github.com/anthropics/claude-code 参考文章：How Claude Code memory actually works