四大Agent源码级对比：记忆系统

横向对比 Claude Code、DeerFlow、Hermes Agent、OpenClaw 四个项目的 Memory 系统设计与实现

一、总览

二、Claude Code — 四层存储 + 一层召回

2.1 架构概览

存储层（各自持有真实落盘数据）
  Layer 1: CLAUDE.md          → 人类预写指令，多级目录遍历 + @include 引用
  Layer 2: Auto Memory(memdir) → AI 自主写入的持久知识，4 类闭合分类法
  Layer 3: Session Memory      → 当前会话的结构化笔记（10 段固定模板）
  Layer 4: Agent Memory        → 自定义 Agent 的专属记忆（user/project/local）

召回层（无自身存储，纯读）
  Relevant Memories → 按需召回：findRelevantMemories 扫描 Layer 2 的 topic files，
                      用 Sonnet sideQuery 挑出最多 5 个文件路径注入，本身不产出、
                      不存储任何数据——它是 Layer 2 的读侧。

2.2 核心特点

闭合分类法驱动质量

MEMORY_TYPES = ['user', 'feedback', 'project', 'reference']

每种类型不仅定义了"写入什么"，更定义了"不写入什么"（5 类排除项：代码模式、Git 历史、调试方案、CLAUDE.md 已有、临时任务状态）。分类法还规定了即使用户明确要求保存某些内容，AI 也应反问"什么是令人惊讶的"——通过 Prompt 设计约束 AI 行为。

后台 Forked Agent 提取

• 与主 Agent 互斥：扫描助手消息是否有 tool_use 写入了 isAutoMemPath() 范围，有则跳过

• 权限沙箱：允许只读 tools + 限制 memory 目录内写入，禁止 MCP、Agent、写型 Bash

• 闭包管理游标：lastMemoryMessageUuid 标记处理进度，inProgress 互斥锁 + pendingContext trailing run 合并

• 提取 Agent 采用两步并行策略：turn 1 并行读取所有可能需要更新的文件，turn 2 并行写入

双路径注入（Feature Gate 控制）

传统路径: MEMORY.md 始终注入用户上下文 (tengu_moth_copse=off)
新路径:   完全异步预取 + Relevant Memories sideQuery (tengu_moth_copse=on)

SideQuery 选择流程：

• 阶段一：scanMemoryFiles 读取所有 topic 文件的 frontmatter（单遍扫描，stat + read 合并）

• 阶段二：selectRelevantMemories 用 Sonnet 模型做轻量 side query，最多选择 5 个相关文件

Session Memory 与 Compact 协同

• 10 段固定模板（Session Title → Worklog），标题不可变

• 双阈值触发：token 阈值（必要条件）+ tool call 阈值

• Compact 时直接复用，免去昂贵的总结 API 调用

Auto Dream 巩固

• 门控（按成本从低到高）：① 能力门控 isGateOpen()（KAIROS/Remote 模式、AutoMemory 关闭、Dream 关闭则直接跳过）→ ② 时间 ≥24h → ③ 扫描节流 10min（时间门控通过但会话门控不通过时防止每 turn 重复扫描）→ ④ ≥5 新会话 → ⑤ 文件锁

• 失败回滚 mtime，下次重新通过时间门控（扫描节流即回滚后的 backoff）

其他精妙设计

• DIR_EXISTS_GUIDANCE：Prompt 中告知 AI "目录已存在直接写"，省去 ls/mkdir -p 的浪费

• memoryAge() 预计算：避免"今天"变成"昨天"导致 Prompt Cache 失效

• MEMORY.md 索引截断保护：200 行 + 25KB 双重限制

三、Hermes Agent — 内置 + 插件双轨制

3.1 架构概览

MemoryManager (统一编排)
├── Builtin Provider: MEMORY.md + USER.md
│   └── 通过 memory 工具读写（前台 Agent + 后台 review fork 共用）
└── External Provider (8 选 1)
    ├── Honcho / OpenViking / Mem0 / Hindsight / ...
    └── 镜像 builtin 写入 + 独立 prefetch/sync

3.2 核心特点

Agent 自管理的 Markdown 记忆

~/.hermes/memories/
├── MEMORY.md      ← Agent 笔记：环境、约定、经验（上限 2,200 字符）
└── USER.md        ← 用户画像：偏好、风格、技能（上限 1,375 字符）

• 使用 § 作为条目分隔符

• Frozen Snapshot 模式：会话开始注入，会话内修改不立即可见（保护 Prompt Cache）

• 严格字符上限，超限返回 error 而非静默丢弃

三级容量管理流程

add → 检查是否超限
  ├─ 未超限 → 写入成功
  └─ 超限 → 返回 error + 当前条目列表
       → Agent 自行 consolidate/remove → retry add（同一 turn 内）

写入审批机制（write_approval）

会话搜索（Session Search）

• 使用 SQLite FTS5 全文索引，存储所有 CLI 和消息平台会话

• 三个调用形态：discovery（跨会话搜索）、scroll（单会话浏览）、browse（列出会话）

• 特点：FTS5 检索本身无 LLM 调用（可选 Gemini Flash 摘要增强）、~20ms 查询延迟、支持回溯数周前的对话

8 个外部 Memory Provider 插件

class MemoryProvider(ABC):
    initialize()           # 连接、创建资源
    system_prompt_block()  # 静态 system prompt 注入
    prefetch(query)        # 每 turn 前异步召回
    sync_turn(user, asst)  # 每 turn 后异步写入
    get_tool_schemas()     # 暴露给模型的自定义工具
    handle_tool_call()     # 工具调用分发
    # 可选 hooks:
    on_session_end()       # 会话结束提取
    on_pre_compress()      # 上下文压缩前提取
    on_memory_write()      # 镜像 builtin 写入
    on_delegation()        # 子 Agent 观察

所有外部写入通过单一 worker 线程串行化，保证 turn N 写入先于 turn N+1。

与 Claude Code 关键差异

• Hermes Agent 采用双轨：Agent 前台主动调用 memory 工具 + 后台 background_review 提取（每 N 轮 fork 子 Agent 评估对话、决定是否存记忆）；Claude Code 则是后台 extractMemories 提取。两者都有后台提取，并非"主动 vs 被动"的对立

• Hermes Agent 有显式审批流（/memory pending）；Claude Code 无

• Hermes Agent 的 session_search 是特有的会话全文搜索能力，与 persistent memory 形成互补

四、OpenClaw — 插件化多后端记忆

4.1 架构概览

文件层:      MEMORY.md / memory/YYYY-MM-DD.md / DREAMS.md
搜索层:      memory_search（混合搜索） + memory_get（文件读取）
后端层:      Builtin(SQLite) / QMD(Local Sidecar) / Honcho
主动层:      Active Memory（插件拥有的阻塞子 Agent）
巩固层:      Dreaming（Deep Promotion）/ Memory Flush
知识层:      Memory Wiki（结构化知识库）

4.2 核心特点

纯 Markdown 文件存储

混合语义搜索

Query → Embedding → Vector Search ┐
                                  ├→ Weighted Merge → Top Results
Query → Tokenize → BM25 Search ───┘

• 支持 8 种 Embedding Provider（OpenAI/Gemini/Voyage/Ollama/Bedrock/Mistral/Local/Copilot）

• 自动检测可用 API key

• 可选增强：

  • Temporal Decay：旧笔记权重衰减（默认 30 天半衰期），MEMORY.md 永不过期

  • MMR (Maximal Marginal Relevance)：减少冗余结果

Active Memory — 主动召回子 Agent

• 阻塞式子 Agent 在主回复前运行

• 仅能使用 memory_search 和 memory_get 两个工具

• 三种 Query Mode：

• 六种 Prompt Style：balanced / strict / contextual / recall-heavy / precision-heavy / preference-only

• 可配置 timeoutMs、maxSummaryChars、thinking 级别

• 通过 /verbose on 和 /trace on 查看诊断输出

Memory Flush

与 Claude Code 的 Session Memory Compact 不同：

• Claude Code：复用已有的 session memory 文件（被动）

• OpenClaw：运行一个静默 turn 要求 Agent 把重要上下文写入文件（主动）

触发条件：tokenCount ≥ contextWindow - reserveTokensFloor - softThreshold

Dreaming — 后台记忆巩固

• Opt-in，默认不启用

• 收集短期信号、评分候选、按门槛晋升

• Live Dreaming：实时处理 .dreams/ 目录中的候选

• Grounded Backfill：重放历史日记，重新评估持久性，可通过 CLI 命令操作：

  openclaw memory rem-backfill --path ./memory --stage-short-term
  openclaw memory rem-backfill --rollback

• 通过 DREAMS.md 提供人类可审查的审计轨迹

插件化注册接口

registerMemoryCapability(pluginId, capability)      // 统一注册 prompt + flush + runtime
registerMemoryCorpusSupplement(pluginId, supplement) // 扩展搜索数据源
registerMemoryPromptSupplement(pluginId, builder)    // 扩展 system prompt

Memory Wiki 是 Companion Plugin，在基础记忆之上添加结构化知识库层，提供 wiki_search、wiki_get、wiki_apply、wiki_lint 等专属工具。

五、DeerFlow — 结构化事实存储

5.1 架构概览

MemoryMiddleware (after_agent 触发)
        ↓
MemoryManager (backend 抽象层)
        ↓
DeerMem backend → memory.json（结构化 JSON）
        ↓
注入 System Prompt

5.2 核心特点

两种工作模式

高度结构化的记忆模型

{
  "user": {
    "workContext":     { "summary": "...", "shouldUpdate": false },
    "personalContext": { "summary": "...", "shouldUpdate": false },
    "topOfMind":       { "summary": "...", "shouldUpdate": true }
  },
  "history": {
    "recentMonths":       { "summary": "...", "shouldUpdate": true },
    "earlierContext":     { "summary": "...", "shouldUpdate": false },
    "longTermBackground": { "summary": "...", "shouldUpdate": false }
  },
  "facts": [
    { "content": "...", "category": "preference", "confidence": 0.95, "expected_valid_days": 365 }
  ]
}

6 类 Fact 分类 + 置信度 + 有效期

事实生命周期管理

expected_valid_days:
  ≤14:    高瞬态 — 活跃 bug、即时任务
  15-60:  短期 — 当前实验、在进行的副项目
  60-180: 中期 — 当前角色、活跃技术栈
  180-365: 稳定 — 职业背景、既定工作模式
  >365:   非常稳定 — 核心技能、母语、人格特征

自动维护机制

• Staleness Review：定期检查过期事实，按配置的 staleness_age_days 触发

• Consolidation：合并相似事实，max_facts: 100 上限，超过 consolidation_min_facts 时触发

• Correction Detection：自动识别用户纠正 Agent 错误的模式，标记为高置信度 correction 类事实

• Per-Agent 隔离：不同 agent 的 memory.json 存放在 agents/{agent_name}/ 目录

• 注入预算控制：max_injection_tokens: 2000 限制注入到 system prompt 的记忆量

六、横向对比矩阵

6.1 存储策略

6.2 写入机制

6.3 记忆召回

6.4 记忆质量保障

6.5 多 Agent 支持

七、技术亮点（每项目独有）

八、设计哲学差异

graph TD
    subgraph "Claude Code — 工程化"
        CC1["后台被动提取"]
        CC2["分类法驱动质量"]
        CC3["Feature Gate 控制演化"]
        CC4["Prompt Cache 极致优化"]
    end
    subgraph "Hermes Agent — 可扩展"
        HA1["前台工具 + 后台 review 提取"]
        HA2["双轨制（内置+插件）"]
        HA3["审批流 + 会话搜索"]
        HA4["8 个外部 Provider"]
    end
    subgraph "OpenClaw — 可组合"
        OC1["Agent 主动写文件"]
        OC2["混合语义搜索"]
        OC3["多后端 + Dreaming"]
        OC4["插件化 + Wiki 层"]
    end
    subgraph "DeerFlow — 结构化"
        DF1["中间件被动摘要"]
        DF2["高度结构化 JSON"]
        DF3["事实生命周期管理"]
        DF4["置信度 + 分类维度"]
    end

九、设计经验总结

9.1 通用设计原则

通过对比四个项目的 Memory 系统，可以归纳出以下通用设计原则：

1. 分类法 > 自由存储：放任 AI 自由保存内容会导致信息噪音。Claude Code 的 4 类闭合分类法和 DeerFlow 的 6 类 Fact 分类都证明了明确的分类体系能显著提高记忆质量。

2. 定义"不存什么"和"存什么"同样重要：可从当前状态派生的信息（代码模式、Git 历史、调试方案）不需要存储。Claude Code 的 WHAT_NOT_TO_SAVE_SECTION 是这一原则的最佳实践。

3. 存储和召回的架构分离：轻量索引 + 按需召回的模式（Claude Code 的 MEMORY.md + sideQuery，OpenClaw 的向量搜索）优于全量注入，特别是在记忆体量增长后。

4. Prompt Cache 稳定性是隐藏的性能关键：跨 turn 的字节稳定性直接影响 API 成本。Claude Code 的 memoryAge() 预计算和 Hermes Agent 的 Frozen Snapshot 模式都体现了这一点。

5. 后台提取优于内联提取：在对话主路径中做记忆提取会增加用户感知延迟。四个项目都采用了某种形式的异步/后台处理（fire-and-forget、debounce、队列化）。

9.2 可迁移的设计模式

十、结论

四个项目的 Memory 系统代表了 AI Agent 记忆设计的四条不同路径：

• Claude Code 构建了最完整、最工程化的"四层存储 + 一层召回"记忆体系，适合对成本和可靠性要求极高的商业产品。

• Hermes Agent 的双轨制（内置简洁 + 外部插件丰富）和审批流设计，适合开源社区中需要灵活性和用户控制权的场景。

• OpenClaw 的模块化、多后端、混合搜索架构，适合需要自由组合和深度定制的平台型产品。

• DeerFlow 通过高度结构化的 JSON 模型和事实生命周期管理，适合需要精确用户画像和知识管理的场景。

没有"最好"的 Memory 系统，只有最匹配场景的选择。这四个项目的设计决策都值得在构建自己的 AI Agent 记忆系统时参考借鉴。