Agent 记忆系统架构总览：Codex、Claude Code、Hermes、Mem0、Letta 与 Graphiti

本文定位为 Agent Memory Engineering 专栏总览与选型地图：用统一生命周期横向比较六种路线；每个系统的源码、状态机、一致性与生产化细节进入独立深挖文章。

顺序	独立深挖	核心问题
1	Codex Memory：两阶段语义 ETL、Git 巩固与可追溯召回	历史任务如何形成未来经验
2	Claude Code Memory：CLAUDE.md、Auto Memory 与渐进式上下文披露	文件层级如何编译成动态 Instruction Working Set
3	Hermes Memory：受限自管理、快照隔离与事务化巩固	Agent 如何在有限预算下安全地管理自己的记忆
4	Mem0 Memory Pipeline：ADD-only 提取、混合检索与多存储一致性	如何把记忆做成可观测的数据管线
5	Letta / MemGPT Memory：虚拟上下文与 Agent-controlled Paging	Agent 如何在 Hot / Cold Context 之间主动调页
6	Graphiti Temporal Memory：双时间、实体消歧与事实失效	动态世界中的事实何时成立、何时失效

0. 阅读说明与研究边界#

本文资料与源码基线截至 2026 年 7 月 15 日。

研究对象分成两组：

产品级实践：

OpenAI Codex
Anthropic Claude Code
Nous Research Hermes Agent

开源记忆框架：

Mem0
Letta / MemGPT
Graphiti

本文不会按照“短期记忆、长期记忆、向量记忆”依次做概念科普。真正要研究的是：

Agent 到底应该记什么？
谁决定一条信息值得写入记忆？
什么时候写？
写入什么结构？
记忆属于哪个用户、Agent、任务或业务实体？
Agent 如何找到过去真正有用的信息？
找到记忆后，多少内容应该重新进入 Context？
新旧记忆冲突怎么办？
历史事实发生变化怎么办？
记忆满了以后，谁决定删除什么？
Memory 和 Context Compaction 是不是同一件事？
一次任务执行能否转化成未来可复用的经验？

0.1 引用方法与事实边界#

本文只引用公开源码中的极少量关键签名或关键语句。较长流程统一使用 “结构化源码还原”：依据公开源码真实调用顺序整理成更易学习的伪代码，不逐字搬运原仓库。

Claude Code 的核心 Runtime 并未完整公开，因此 Claude Code 一章严格依据 Anthropic 官方公开行为契约做架构还原，不把推测伪装成源码事实。

0.2 源码版本与复现基线#

系统	研究基线
Codex	`openai/codex`，commit `8604689ec5e3437eb79802d8d72249b7722fbf5b`
Hermes	`NousResearch/hermes-agent`，commit `77d5b2d573f82fc514fbef02f0b6303c44149805`
Mem0	`mem0ai/mem0`，commit `ccbe5861a138c7583e01bb3a3aa6168e52526a23`
Letta	`letta-ai/letta`，commit `b76da9092518cbaa2d09042e52fdcbde69243e18`
Graphiti	`getzep/graphiti`，commit `526dcad7a300f3c5c506ff96a68bcdc7ca9f97ed`
Claude Code	Anthropic 官方 Memory 文档行为契约

本文插图均为依据上述官方文档与固定版本源码重新绘制的机制图，用于压缩跨文件调用关系与故障语义；它们不是厂商官方架构图。图中若同时出现“当前实现”和“生产化补强”，会用分区和图注明确区分，避免把本文建议误读为框架已经提供的保证。

Part I：问题模型与统一生命周期#

1. Agent Memory 真正解决什么问题#

1.1 Context Window 不等于 Memory#

大模型的 Context Window 解决的是：

当前这一次模型调用能够看到什么。

Memory 解决的是：

系统如何跨时间保存、组织、选择、修正并重新提供过去的信息。

1
Context Window
2
=
3
当前推理工作集
4

5
Memory System
6
=
7
跨时间的信息生命周期系统

所以：

1
Raw History ≠ Memory
2
Vector Database ≠ Memory System
3
Context Window ≠ Long-Term Memory

把所有历史消息放进数据库，只完成了 Persistence。

把历史消息做 Embedding 放进 Vector DB，只完成了 Semantic Retrieval Primitive。

真正的 Memory 至少还要回答：

1
哪些事件值得进入记忆？
2
        ↓
3
从事件中抽取什么？
4
        ↓
5
属于谁？
6
        ↓
7
是事实、偏好、经验还是状态？
8
        ↓
9
与旧记忆是否重复或冲突？
10
        ↓
11
如何持久化？
12
        ↓
13
未来什么时候召回？
14
        ↓
15
召回以后放多少进 Context？
16
        ↓
17
事实变化以后如何修正？
18
        ↓
19
什么时候过期、压缩或遗忘？

因此，一个工业级 Agent Memory 更接近 Memory Lifecycle Engine，而不是 vector_store.add(text)。

1.2 从 Stateless LLM 到 Stateful Agent#

普通 LLM：

1
Input → Model → Output → End

Stateful Agent：

1
Current Task
2
    ↓
3
Working State
4
    ↓
5
Context Builder
6
    ↓
7
Historical Memory Recall
8
    ↓
9
Agent Decision
10
    ↓
11
Tool / Environment Action
12
    ↓
13
Observation
14
    ↓
15
Task Result
16
    ↓
17
Memory Update
18
    ↓
19
Future Task

真正的变化发生在：

1
Task Result
2
    ↓
3
Memory Update
4
    ↓
5
Future Task

历史执行开始改变未来决策。

但“历史影响未来”不等于把全部历史塞给模型。Memory Engineering 追求的是：

用最小、最准确、最相关的历史信息改变当前决策。

1.3 为什么 Full History 是糟糕的默认方案#

假设 Agent 执行 1,000 个任务，每个任务产生 20,000 tokens：

1
1,000 × 20,000
2
=
3
20,000,000 tokens

问题不只在成本。

Context Pollution#

真正相关的信息可能只有：

1
项目使用 Gradle
2
数据库迁移命令是 ./gradlew flywayMigrate
3
integration test 必须启动 Docker

但模型看到数百轮 Debug 历史，Relevant Signal 被噪声淹没。

Historical Conflict#

1
2025-01: 用户住北京
2
2025-09: 用户搬到上海
3
2026-05: 用户搬到深圳

“能召回三条”不代表“知道当前哪条有效”。

History 不是 Knowledge#

原始过程：

1
Agent: 可能是 Redis。
2
User: 不是。
3
Agent: 可能是 MySQL。
4
User: 也不是。
5
Agent: 找到了，是时区序列化。

如果完整保存，三个假设都存在。真正应该形成的 Memory 是：

1
该项目订单时间解析异常的根因是时区序列化配置，
2
不是 Redis/MySQL 连接。

所以：

1
History
2
↓
3
Extraction
4
↓
5
Distillation
6
↓
7
Memory

Memory 的第一道价值不是“存”，而是 从经历中提炼未来有用的信息。

1.4 Memory 和 RAG 的根本区别#

RAG 的主要输入通常是：

1
Document Corpus

Memory 的主要输入更接近：

1
Agent Experience Stream

包括：

1
User Message
2
Agent Message
3
Tool Call
4
Tool Result
5
Execution Trace
6
Error
7
Human Feedback
8
Reflection
9
Task Outcome

因此：

1
RAG
2
→ 外部知识如何被检索
3

4
Memory
5
→ 运行历史如何形成未来可复用状态与经验

二者可以共享 Embedding、BM25、Reranker、Graph，但数据语义不同。不要因为都能用向量数据库，就把它们做成同一个逻辑模块。

2. 用统一生命周期理解 Agent Memory#

1
Experience / Event
2
        ↓
3
      Capture
4
        ↓
5
      Extract
6
        ↓
7
      Evaluate
8
        ↓
9
       Write
10
        ↓
11
     Organize
12
        ↓
13
 Retrieve / Route
14
        ↓
15
      Inject
16
        ↓
17
       Use
18
        ↓
19
Update / Consolidate / Invalidate / Forget

Agent Memory 从事件捕获、抽取、评估、写入到召回、注入与维护的完整生命周期

图 1：Memory 不是单一存储组件，而是一条带写策略、检索预算和反馈维护的闭环数据管线。

这就是本文统一采用的 Agent Memory Lifecycle。

2.1 Capture：捕获什么事件#

完整 Event Source 可以包括：

1
User Message
2
Assistant Message
3
Tool Call
4
Tool Result
5
Plan
6
State Transition
7
Environment Change
8
Error
9
Retry
10
Verifier Result
11
Human Approval
12
Human Correction
13
Final Task Result
14
Evaluation Score

Coding Agent 第一次进入仓库：

1
mvn test → 失败
2
检查仓库 → 发现 Gradle
3
./gradlew test → 成功

可以抽取两种不同记忆：

1
Semantic Fact:
2
Project build system = Gradle
3

4
Procedural Experience:
5
When build command is uncertain, inspect build descriptors before selecting Maven/Gradle.

Capture 不是“把聊天存下来”，而是建立可重放的事实日志#

如果 Capture 层只保存 role + content，后面很难回答“这条结论来自哪个工具结果”“重试后哪个结果才是最终结果”“同一个事件是否被消费过”。更稳妥的事件信封至少需要：

1
class MemorySourceEvent(BaseModel):
2
    event_id: str                 # 全局幂等键
3
    trace_id: str                 # 一次 Agent Run
4
    span_id: str                  # 某次模型或工具调用
5
    sequence: int                 # 同一 trace 内的稳定顺序
6
    schema_version: int
7

8
    occurred_at: datetime         # 事件实际发生时间
9
    ingested_at: datetime         # Memory 系统观察到它的时间
10

11
    producer: str                 # user / model / tool / verifier / human
12
    trust_domain: str             # first_party / third_party / untrusted
13
    payload_ref: str | None       # 大对象放对象存储，不复制进消息队列
14
    payload_hash: str             # 内容完整性与去重
15
    sensitivity: str

这里有三个不能省略的工程不变量：

事件不可变：修正通过追加 correction 或 supersedes 事件完成，不原地改历史。
消费幂等：Extractor 以 (pipeline_version, event_id) 去重；消息队列采用 at-least-once 投递时，重复事件不能生成重复记忆。
来源可追踪：Memory 永远保存 source_event_ids，否则它只是模型生成的无来源文本。

数据库事务与消息队列之间还需要 Transactional Outbox：业务状态与 outbox event 在一个本地事务中提交，再由 relay 发布。否则“任务已完成但事件没有发出”会形成永久的 Memory Recall Ceiling。

2.2 Extract：从事件中抽取什么#

好的 Memory Candidate 应该尽量：

1
Self-contained
2
Future-useful
3
Low ambiguity
4
Scoped
5
Source-linked

例如用户说：

1
以后 Java 项目我一般优先 Maven，除非仓库明确用了 Gradle。

长期 Memory 不应该机械保存整句聊天，而可以抽成：

1
User prefers Maven for new Java projects unless the existing repository already uses Gradle.

Candidate 不是 Canonical Fact#

Extractor 的输出应该进入候选区，而不是直接成为“系统相信的事实”。一个候选至少要区分：

1
claim            模型抽出的陈述
2
evidence         支持它的原始事件与片段
3
subject          这是谁或什么对象的事实
4
scope            user / agent / project / organization
5
modality         explicit / observed / inferred
6
source_trust     来源可信度
7
extractor_score  抽取模型置信度
8
valid_time       事实在哪个时间区间成立

extractor_score 不能替代 source_trust。模型可以非常确信地复述一个恶意网页中的指令，但来源仍然是不可信外部数据。生产系统应保留 PROPOSED → ACCEPTED / REJECTED / QUARANTINED 状态，使评测、人工审核和安全策略能够在持久化之前介入。

2.3 Evaluate：不是所有信息都值得记#

可以使用一个工程启发式：

1
Memory Utility
2
≈
3
Importance
4
× Reusability
5
× Confidence
6
× Expected Future Usage
7
-
8
Context Cost
9
-
10
Risk Penalty

这不是标准学术公式，而是工程建模思路。

Importance：信息重要吗？
Reusability：未来任务会复用吗？
Confidence：是用户明确事实还是 Agent 猜测？
Expected Future Usage：未来多久可能再次使用？
Context Cost：常驻 Context 的成本多大？
Risk Penalty：敏感性、错误传播风险多大？

2.4 Write：Memory Control Plane 在哪里#

四种典型控制模型：

1
Harness 自动写
2
→ Codex / Mem0
3

4
Agent 主动写
5
→ Hermes / Letta
6

7
Human 写
8
→ CLAUDE.md / AGENTS.md
9

10
Hybrid
11
→ System + Agent + Human

Memory 架构的核心区别，经常不是“文件还是数据库”，而是：

谁拥有 Memory Control Plane。

Write Path 需要显式状态机#

后台生成不是一个布尔任务，而是一组可恢复的状态转换：

1
PENDING
2
  └─ claim(lease, ownership_token, input_watermark)
3
       ↓
4
RUNNING
5
  ├─ commit(output, expected_version) → SUCCEEDED
6
  ├─ commit_no_output()               → SUCCEEDED_NO_OUTPUT
7
  ├─ retryable_error                  → RETRY_WAIT
8
  └─ permanent_error / retry=0        → DEAD_LETTER

关键字段不是 status 一个枚举，而是：

1
ownership_token   防止旧 Worker 在租约过期后覆盖新 Worker
2
lease_expires_at  允许崩溃恢复
3
input_watermark   这次处理到哪个源版本
4
retry_remaining   有界重试
5
next_retry_at     指数退避与抖动
6
last_error        可观测性与人工修复

其中 SUCCEEDED_NO_OUTPUT 必须是一等状态：一次任务没有值得记的内容，是有效业务结果，不应该被无限重试。Codex 固定版本源码就显式实现了 mark_stage1_job_succeeded_no_output，并区分“本来就没有旧输出”和“本次需要删除旧输出后触发全局巩固”两种情况。[S5]

2.5 Organize：Memory 不只是 Text Chunk#

Memory Representation 可以是：

1
Markdown Entry
2
Memory Block
3
Summary
4
Fact
5
Preference
6
Episode
7
Procedure
8
Entity
9
Relationship
10
Temporal Edge
11
Skill
12
Task Experience

Representation 决定系统以后能回答什么问题。

Text Chunk 很适合：

1
“用户现在住深圳”

但如果要回答：

1
用户 2025 年住在哪里？
2
什么时候从上海搬走？
3
过去住过哪些城市？

就开始需要 Temporal Representation。

Canonical Record 与派生索引必须分层#

向量库、BM25 索引和知识图谱不应该同时被当成独立真相源。更稳妥的模型是：

1
Canonical Memory Record
2
  ├── Dense Vector Index
3
  ├── Lexical / BM25 Index
4
  ├── Entity Link Index
5
  ├── Temporal Graph Projection
6
  └── Prompt-ready Summary Cache

Canonical Record 保存版本、来源、权限、有效期和删除状态；其他结构都是可重建的 Materialized View。这样才能定义一致性：

1
class CanonicalMemory(BaseModel):
2
    memory_id: str
3
    version: int
4
    content: str
5
    kind: str
6
    namespace: tuple[str, ...]
7
    source_event_ids: list[str]
8
    valid_at: datetime | None
9
    invalid_at: datetime | None
10
    expires_at: datetime | None
11
    trust_level: str
12
    sensitivity: str
13
    status: Literal["active", "invalid", "deleted"]

写路径先以 Optimistic Concurrency Control 更新 canonical row，再通过 outbox 异步刷新各索引。检索结果必须带 memory_id + version，Context Builder 在注入前回查当前版本，避免旧向量索引把已经删除或失效的内容重新送进 Prompt。

2.6 Retrieve：召回不是只有 Vector TopK#

可用策略包括：

1
Always Inject
2
Exact Lookup
3
Metadata Filter
4
BM25
5
Semantic Search
6
Hybrid Search
7
Graph Traversal
8
Temporal Filter
9
Agentic File Search
10
Hierarchical Routing

一个可靠的 Retrieval Plan 通常是“硬过滤在前、召回在中、效用排序在后”：

1
Authorization / Namespace / Status / Valid-time Filter
2
                         ↓
3
BM25 ─┬─ Dense ─┬─ Entity ─┬─ Graph / Temporal
4
      └──────── Candidate Union ─────────┘
5
                         ↓
6
RRF / Learned Fusion
7
                         ↓
8
Utility Rerank + Diversity

RRF 不要求不同通道的原始分数可比，适合融合 BM25、向量和图检索：

$\operatorname{RRF}(d)=\sum_{r\in R}\frac{1}{k+\operatorname{rank}_r(d)}$

但融合分数仍不是最终效用。生产排序常需要额外乘上或约束 confidence、freshness、scope_match、temporal_validity 与 permission。Graphiti 的固定版本源码把 Edge、Node、Episode、Community 的 Search Config 和 Reranker 分开，正说明不同检索单元不应共享一个粗糙 TopK。[S9]

2.7 Inject：检索到不等于全部塞进 Prompt#

Retriever 回 50 条 Memory 后，Context Builder 还要决定：

1
哪些进入 Context？
2
顺序是什么？
3
放在哪一层？
4
是否需要摘要？
5
是否存在冲突？
6
是否过期？
7
Token Budget 是多少？

所以：

1
Retriever
2
→ 找到什么相关
3

4
Context Builder
5
→ 模型现在应该看到什么

这两个模块应该分离。

Context Packing 是有约束的组合优化#

假设候选记忆 $m_i$ 的预计任务效用为 $u_i$ ，Token 成本为 $c_i$ ，总预算为 $B$ ，最简单的目标是：

$\max \sum_i u_i x_i \quad \text{s.t.}\quad \sum_i c_i x_i\le B,\;x_i\in\{0,1\}$

真实系统还要加入冲突对不能同时作为“当前事实”注入、同主题去重、来源多样性、核心记忆保底额度等约束。因此 top_k=20 后直接拼接不是 Context Builder，只是把检索噪声转移给模型。

注入格式也应把内容与指令隔离：

1
<memory_item id="m_123" trust="observed" valid_at="2026-07-01">
2
  <content>Integration tests require Docker Compose.</content>
3
  <provenance>trace_8/tool_result_4</provenance>
4
</memory_item>

Memory 是不完全可信的数据，不应因为被放进 system prompt 就自动升级为高优先级指令。

2.8 Maintenance：Memory 必须会变化#

完整 Memory Lifecycle 需要：

1
ADD
2
UPDATE
3
MERGE
4
CONSOLIDATE
5
INVALIDATE
6
EXPIRE
7
DELETE
8
FORGET

如果系统只有 add() 和 search()，更像 Retrievable Event Store，而不是完整 Memory System。

删除也不是 DELETE FROM memories 一条语句。它必须沿派生关系传播：

1
Canonical Tombstone
2
  ├── Vector delete / deny-list
3
  ├── BM25 document delete
4
  ├── Graph node/edge invalidation
5
  ├── Summary regeneration
6
  ├── Prompt cache purge
7
  ├── Audit event
8
  └── Backup retention workflow

在所有派生索引确认删除前，读路径应优先检查 canonical tombstone。否则“向量库删除成功、摘要缓存仍保留”会让用户删除请求在行为层面失效。

2.9 统一分析维度#

维度	核心问题
Memory Source	记忆从哪里产生
Write Policy	谁决定写
Write Timing	什么时候写
Representation	记忆如何表示
Storage	存在哪里
Retrieval	如何召回
Context Injection	如何进入 Context
Compaction	历史如何压缩
Conflict	新旧信息冲突怎么办
Forgetting	如何删除、过期或遗忘
Agent Control	Agent 有多少控制权

这个分析框架也能被其他主流实现交叉验证。LangGraph 官方文档把 thread-scoped short-term state 交给 checkpointer 持久化，把 cross-thread long-term memory 放入自定义 namespace，并明确区分 hot-path write 与 background write；同时讨论 Profile 与 Memory Collection 在更新复杂度、召回率和检索成本上的权衡。[S13] 这说明 Scope、Write Timing 和 Representation 不是某一个产品的偶然实现细节，而是跨框架反复出现的架构变量。

Part II：产品级 Agent 的记忆实践#

3. Codex：后台记忆抽取与任务经验沉淀#

独立源码深挖：Codex Memory：两阶段语义 ETL、SQLite Job 状态机、Git 巩固与渐进式召回。

3.1 Coding Agent 的 Memory Workload#

Coding Agent 长期工作的真实环境包含：

1
Repository
2
Build System
3
Test Commands
4
Architecture Conventions
5
Hidden Constraints
6
Tool Quirks
7
Past Debugging Experience
8
User Workflow Preferences

第一次任务发现：

1
mvn test → 失败
2
检查仓库 → Gradle
3
./gradlew test → 成功

下一次再从 Maven 开始，说明历史任务没有转化为未来能力。

Codex Memory 的核心问题是：

过去任务中有哪些工作经验值得未来 Coding Task 复用？

3.2 官方公开的 Memory 边界#

OpenAI 当前公开说明中有几个非常重要的行为约束：

Local Codex 使用独立的本地 Memory Store。
从符合条件的历史任务中生成 Memory。
活跃或过短的 Session 可以被跳过。
Memory 后台更新，而不是任务结束立即更新。
生成 Memory 字段会做 Secret Redaction。
主 Memory 文件位于 ~/.codex/memories/。
必须遵守的团队规则应该放在 AGENTS.md 或受版本控制的文档中，而不是只依赖 Memory。[S1]

因此：

1
Required Policy
2
→ AGENTS.md / checked-in rules / enforcement
3

4
Learned Experience
5
→ Memory

即：

Policy ≠ Memory。

3.3 两阶段后台流水线#

公开源码：

1
codex-rs/memories/write/src/phase1.rs
2
codex-rs/memories/write/src/phase2.rs

能够看到非常明确的两阶段设计：

1
Historical Rollouts
2
        ↓
3
Phase 1
4
Per-Rollout Extraction
5
        ↓
6
Raw Memory
7
+
8
Rollout Summary
9
        ↓
10
Phase 2
11
Global Consolidation
12
        ↓
13
Durable Memory Workspace

这是一套典型的：

Extract → Consolidate

架构。

3.4 Phase 1：Rollout Extraction#

Phase 1 模型输出被限制为三个字段。公开源码中的关键结构很短：

1
struct StageOneOutput {
2
    raw_memory: String,
3
    rollout_summary: String,
4
    rollout_slug: Option<String>,
5
}

源码：openai/codex/codex-rs/memories/write/src/phase1.rs

三者职责不同：

1
raw_memory
2
→ 单次 Rollout 中提炼的详细记忆
3

4
rollout_summary
5
→ 紧凑摘要，适合 Routing / Indexing
6

7
rollout_slug
8
→ 可选 artifact naming

这说明 Codex 至少区分：

1
Detailed Memory
2
vs
3
Compact Routing Summary

3.5 Eligibility：Memory Write 之前先决定“这次任务能不能写”#

Phase 1 不是遍历全部历史直接总结，而是先 Claim Eligible Rollout Jobs。

当前源码参数包括：

1
scan_limit
2
max_claimed
3
max_age_days
4
min_rollout_idle_hours
5
allowed_sources
6
lease_seconds

结构化源码还原：

1
# 非 Codex 原始源码
2

3
candidates = state_db.claim_memory_jobs(
4
    scan_limit=THREAD_SCAN_LIMIT,
5
    max_claimed=config.max_rollouts_per_startup,
6
    max_age_days=config.max_rollout_age_days,
7
    min_idle_hours=config.min_rollout_idle_hours,
8
    allowed_sources=interactive_session_sources,
9
    lease_seconds=JOB_LEASE_SECONDS,
10
)

这背后有五层含义。

Memory Generation 是 Background Job

不是用户请求主链路中的同步副作用。

Idle Threshold 防止 Premature Commit

1
Task 暂时停止
2
≠
3
Task 完成

如果用户十分钟后继续 Debug，过早写 Memory 可能固化半成品结论。

Age Limit 控制处理窗口

过旧 Rollout 不一定值得重新处理。

Source Filter 控制来源

不是所有 Session Source 都应进入记忆流水线。

Lease 防重复处理

后台 Worker 需要 Ownership / Lease，避免重复消费同一任务。

所以 Codex Phase 1 本质是：

带资格筛选、租约、并发和生命周期管理的 Memory ETL Job System。

3.6 为什么 Phase 1 可以并行#

源码通过并发流执行 Rollout Extraction。

结构化还原：

1
async def phase1():
2
    candidates = claim_eligible_rollouts()
3

4
    outcomes = await parallel_map(
5
        candidates,
6
        extract_one_rollout,
7
        concurrency_limit=CONCURRENCY_LIMIT,
8
    )
9

10
    emit_metrics(aggregate(outcomes))

因为：

1
Rollout A → Raw Memory A
2
Rollout B → Raw Memory B
3
Rollout C → Raw Memory C

在这一阶段可以独立处理。

它非常像数据系统中的 Map Stage。

3.7 Structured Output：Memory Extraction 是 Semantic ETL#

Phase 1 使用受约束 JSON Schema，并禁止额外字段。

这不是为了“输出漂亮”。

而是让下游能够：

1
Validate
2
Persist
3
Index
4
Route
5
Consolidate
6
Measure

所以 Memory Extractor 的模型调用更适合理解为：

Semantic ETL Operator

而不是聊天节点。

3.8 Secret Redaction：Memory Write Path 是 Security Boundary#

Coding Agent 可能看到：

1
API Key
2
Database Password
3
Private Token
4
Credentials
5
Internal URL

如果一次 Session 中的 Secret 被写入 Memory：

1
Session A
2
↓
3
Memory
4
↓
5
Session B
6
↓
7
Session C
8
↓
9
Session D

风险被持久化并跨任务传播。

因此：

Memory Write Path 本身就是持久化安全边界。

生产系统至少要考虑：

1
PII Detector
2
Secret Detector
3
Credential Redaction
4
Sensitivity Classification
5
Namespace ACL
6
Retention Policy
7
Audit Log

3.9 Phase 2：Global Consolidation#

Phase 1 得到很多 Raw Memory：

1
A
2
B
3
C
4
...

直接全部塞进未来 Context 会产生：

1
重复
2
冲突
3
碎片
4
过期
5
噪声

所以需要 Phase 2。

真实控制流可重构为：

1
# 非 Codex 原始源码
2

3
async def phase2():
4
    claim = claim_global_consolidation_lock()
5

6
    prepare_git_backed_memory_workspace()
7

8
    agent_config = build_locked_down_consolidation_config()
9

10
    raw_memories = db.select_phase2_inputs(
11
        max_raw_memories=config.max_raw_memories,
12
        max_unused_days=config.max_unused_days,
13
    )
14

15
    sync_inputs_to_memory_workspace(raw_memories)
16

17
    diff = calculate_memory_workspace_diff()
18

19
    if no_change(diff) and artifacts_are_valid():
20
        mark_success()
21
        return
22

23
    write_diff_for_agent(diff)
24

25
    agent = spawn_consolidation_agent(
26
        config=agent_config,
27
        prompt=build_consolidation_prompt(),
28
    )
29

30
    handoff_completion_and_heartbeat(agent)

3.10 为什么 Phase 2 需要 Global Lock#

Phase 1 可独立抽取。

Phase 2 修改的是全局 Memory Workspace。

两个 Consolidator 同时工作：

1
Agent 1 读取 V10 → V11-A
2
Agent 2 读取 V10 → V11-B

容易产生 Lost Update。

因此 Phase 2 使用 Global Job Claim、Ownership Token 和 Watermark。

这已经非常接近 Stateful Stream Processing。

3.11 Git-backed Memory Workspace#

Phase 2 做了：

1
Prepare Workspace
2
↓
3
Ensure Git Baseline
4
↓
5
Sync Inputs
6
↓
7
Calculate Workspace Diff

核心源码中有一句：

1
let workspace_diff = memory_workspace_diff(&root).await?;

源码：codex-rs/memories/write/src/phase2.rs

为什么 Git 适合这里？

1
Old Memory Workspace
2
        ↓
3
New Inputs
4
        ↓
5
Agent Editing
6
        ↓
7
New Memory Workspace

Git 天然提供：

1
Baseline
2
Diff
3
Changed Files
4
Change Detection
5
Rollback Foundation
6
Auditability

因此 Codex 的 Consolidator 更像：

受限的 Memory Workspace Editing Agent

而不是一次 summarize(all_memory)。

3.12 为什么 Spawn 独立 Consolidation Agent#

Consolidation 的任务是：

1
理解已有长期记忆
2
↓
3
检查新增 Raw Memory
4
↓
5
发现重复
6
↓
7
识别新增知识
8
↓
9
整合冲突
10
↓
11
编辑持久记忆

这本身就是复杂 Agent Task。

所以 Codex 直接 Spawn 专门的 Consolidation Agent。

这代表一种重要架构：

1
Main Agent
2
→ 完成用户任务
3

4
Memory Agent
5
→ 维护长期记忆

即 Memory Sub-Agent。

3.13 Memory 和 Compaction 必须分开#

OpenAI 官方 Cookbook 给出的工程边界非常清楚：[S2]

1
Compaction
2
→ 当前 Long-running Run 如何继续
3

4
Memory
5
→ 未来 Run 如何复用过去经验

1
Current Run
2
messages...
3
↓
4
Context Too Long
5
↓
6
Compaction
7
↓
8
Current Run Continues

Memory：

1
Run A
2
↓
3
Experience
4
↓
5
Memory
6

7
Run B
8
↓
9
Recall Run A Experience

因此：

1
Compaction
2
= Intra-run Context Lifecycle
3

4
Memory
5
= Inter-run Experience Lifecycle

Conversation Summary 不能自动等同于 Long-Term Memory。

3.14 Read Path：Summary → Registry → Evidence / Skill#

前面的分析主要解释 Codex 如何写 Memory，但固定 Commit 的源码还公开了一条同样重要的读取路径。read_path.md 把本地目录设计成 Progressive Disclosure 层级：[S5]

1
memory_summary.md
2
  已注入的全局摘要，先判断是否可能相关
3
        ↓
4
MEMORY.md
5
  可搜索的 Registry，定位主题和证据路径
6
        ↓
7
skills/<skill-name>/SKILL.md
8
  可执行的流程知识
9
        ↓
10
rollout_summaries/*.jsonl
11
  原始任务回顾、命令、错误和工具证据

读取策略不是“把整个 ~/.codex/memories 塞进上下文”，而是：

从已注入摘要提取关键词。
搜索 MEMORY.md 注册表。
只打开 1～2 个最相关的 skill 或 rollout。
只有需要精确命令、错误文本或证据时，继续下钻。
没有命中就停止，而不是扩大扫描。

模板还给出理想的 4～6 次搜索步数预算。这体现了一个关键架构原则：Memory Recall 自身也有延迟、Token 和注意力预算，Agentic Retrieval 必须有停止条件。

3.15 MemoriesBackend：把存储能力与 Agent 工具协议分离#

codex-rs/ext/memories/src/backend.rs 定义的 MemoriesBackend 不是一个只有 search(text) 的接口，而是四组能力：[S5]

1
trait MemoriesBackend {
2
    add_ad_hoc_note(...);
3
    list(...);
4
    read(...);
5
    search(...);
6
}

其请求/响应里有几个容易忽略的工程细节：

list 和 search 都有 cursor、最大结果数与 truncated，因此大目录不会假装一次返回完整结果。
read 使用 1-based line_offset、max_lines 和 max_tokens 双重预算，并返回实际起始行号。
search 支持多 query、上下文行数、大小写与 normalized 模式。
匹配语义分为 Any、AllOnSameLine、AllWithinLines { line_count }，可以表达“多个证据词必须出现在同一局部窗口”，比单字符串 grep 更适合查命令与错误链。

固定版本默认上限是 List 2,000、Search 200、Read 20,000 tokens；注入的 summary 另有 2,500 tokens 上限。这里的重点不是具体数字，而是每一层都有独立预算，工具返回明确声明截断，调用者才能决定是否翻页或下钻。

3.16 Local Backend 的 Path Sandbox#

Memory 文件会被模型驱动的工具读取，因此本地路径解析本身就是安全边界。local.rs 与 local/path.rs 的实现拒绝：[S5]

1
Absolute Path / Windows Prefix
2
ParentDir (`..`)
3
Hidden Path Component
4
Traversing through a non-directory
5
Symlink at any traversed component

Symlink 拒绝尤其关键。只做字符串级 starts_with(memory_root) 检查无法阻止：

1
memories/evidence
2
  → symlink to ~/.ssh

Codex 使用 symlink_metadata 逐级检查路径组件，使 list/read/search 都被限制在 Memory Root 内。MemoriesBackend 接口同时要求实现返回相对路径，并允许未来的远程后端复用同一能力契约。换句话说，文件型 Memory 不是“让模型自由读磁盘”，而是一个有资源边界、分页和访问规则的虚拟文件系统。

3.17 Job State Machine：Watermark、租约与“无输出成功”#

codex-rs/state/src/runtime/memories.rs 展示了后台 Memory Job 的完整控制语义：[S5]

1
Stage 1 job key = thread_id
2
Stage 2 job key = "global"
3

4
claim:
5
  ownership_token + lease_expires_at + input_watermark
6

7
success:
8
  last_success_watermark = input_watermark
9
  clear lease
10
  upsert or delete stage1 output
11
  enqueue global consolidation when workspace may change
12

13
failure:
14
  clear lease
15
  persist last_error
16
  decrement retry_remaining
17
  schedule backoff

源码默认重试预算为 3；当同一线程出现更新的输入 watermark 时，即使旧输入已经耗尽重试，也可以恢复预算。这避免“一次坏输入永久封死整个线程的后续 Memory”。

Phase 2 使用全局单例租约，并在成功后设置 6 小时 cooldown。更微妙的是，数据库 input_watermark 主要用于调度与所有权，不作为“是否有实际工作”的唯一 dirty check；真正是否需要提交由 Git-backed Memory Workspace 的 diff 判断。这样把任务新鲜度与物化输出是否变化分开了。

线程还可以进入 polluted memory mode，Phase 2 输入选择会跳过这些线程；系统也会按 retention 清理旧 Stage 1 输出。这些设计共同说明，成熟的 Memory Pipeline 需要：来源隔离、可恢复租约、单调 watermark、有限重试、无输出成功、污染隔离与保留策略，而不只是一个后台 cron。

Codex 两阶段后台 Memory Job 的租约、水位线、重试、隔离与 Git Workspace 状态机

图 2：依据 Codex 固定版本源码 [S5] 简化绘制。Stage 1 以 thread 为并行单元，Stage 2 以 global lease 串行巩固；SUCCEEDED_NO_OUTPUT、新 Watermark 恢复重试和 polluted quarantine 都是控制语义，不是普通 cron 的附属细节。

3.18 Provenance、Drift 与受控更新#

读取模板要求在使用 Memory 后生成机器可解析的 <oai-mem-citation>，其中同时记录文件行号和 rollout ID；codex-rs/memories/read/src/citations.rs 再把它解析成结构化引用。[S5]

这解决两个问题：

用户可以知道结论来自哪个长期记忆与历史任务。
系统可以统计哪些 rollout 真正被复用，而不是只统计“检索过多少条”。

模板还明确区分“低漂移事实”和“高漂移事实”：高漂移且验证便宜时应实时验证；验证昂贵时可以使用 Memory，但必须说明它可能过时。这相当于把 freshness risk × verification cost 纳入 Recall Policy。

最后，生成的核心 Memory 文件不允许被 Agent 直接原地修改。只有用户明确要求更新时，才在 extensions/ad_hoc/notes/ 写一个小型变更说明，交给后续流水线处理。它类似 append-only command log，避免模型绕过 Consolidator 破坏生成状态。

3.19 Codex 的工程范式#

1
Eligible Task Selection
2
        ↓
3
Delayed Background Write
4
        ↓
5
Per-Rollout Extraction
6
        ↓
7
Structured Raw Memory
8
        ↓
9
Global Consolidation
10
        ↓
11
Git-backed Workspace Diff
12
        ↓
13
Dedicated Memory Agent
14
        ↓
15
Durable Recall Layer

Codex 代表：

System-Managed Background Experience Memory

最值得学习的九点：

Memory Extraction 从用户请求主链路移出。
任务稳定后再写 Memory。
单任务抽取与全局巩固分阶段。
Memory Maintenance 本身可以交给专用 Agent。
Policy 必须与 Recall Memory 分离。
读取采用 Summary → Registry → Evidence 的渐进披露。
Memory 工具必须有分页、Token 上限与截断语义。
本地文件后端必须实施路径沙箱与 symlink 防护。
每条被使用的 Memory 都应该可追溯到文件证据与历史 Run。

4. Claude Code：Memory as File 与 Progressive Disclosure#

独立行为契约深挖：Claude Code Memory：层级加载器、Auto Memory、Path Rules、Compaction 恢复与安全治理。

4.1 为什么先进 Coding Agent 仍大量使用 Markdown#

很多人第一次看到 Claude Code Memory 会问：

为什么不直接上 Vector Database？

Anthropic 官方当前公开两套跨 Session 机制：[S3]

1
CLAUDE.md
2
+
3
Auto Memory

二者职责不同：

1
CLAUDE.md
2
Who writes: Human
3
Purpose: Instructions / Rules
4

5
Auto Memory
6
Who writes: Claude
7
Purpose: Learnings / Patterns

这是第一层边界：

Human-authored Persistent Context vs Agent-authored Learned Context

4.2 CLAUDE.md：Hierarchical Persistent Instruction#

CLAUDE.md 可以存在于不同 Scope：

1
Organization
2
    ↓
3
User
4
    ↓
5
Project
6
    ↓
7
Local

项目可能是：

1
repo/
2
├── CLAUDE.md
3
├── backend/
4
│   └── CLAUDE.md
5
└── frontend/
6
    └── CLAUDE.md

Anthropic 当前公开行为是：

1
Working Directory 上层的 CLAUDE.md
2
↓
3
Launch 时加载
4

5
Subdirectory CLAUDE.md
6
↓
7
Claude读取相关目录文件时按需加载

这是一种：

Hierarchical Context Scoping

它避免：

1
frontend rule
2
永久污染 backend task context

传统 Memory Retrieval 常由 Query Similarity 决定，而这里：

1
Filesystem Scope

本身就是一种 Context Router。

4.3 Auto Memory：MEMORY.md 不是“大型记忆数据库”#

官方描述的 Auto Memory 目录采用：

1
memory/
2
├── MEMORY.md
3
├── debugging.md
4
├── api-conventions.md
5
└── project-notes.md

最关键的是：

MEMORY.md 更接近 Memory Index / Hot Working Set。

当前官方规则：

1
Session Start
2
↓
3
Load first 200 lines or 25 KB of MEMORY.md

超过阈值的内容不会自动全部加载。

详细信息进入 Topic Files：

1
MEMORY.md
2
=
3
Hot Memory Index
4

5
Topic Files
6
=
7
Warm / Cold Detailed Memory

4.4 这其实是一种 Context Cache Hierarchy#

概念类比：

1
                Fast / Small
2
                    ↑
3

4
          MEMORY.md Core Index
5
                    │
6
              Topic Files
7
                    │
8
            Repository Files
9
                    │
10
           External Resources
11

12
                    ↓
13
                Large / Slow

这里不是说 Claude Code 真按 CPU Cache 实现，而是其工程思想类似：

高频、短、关键的信息常驻；详细内容按需读取。

也就是：

Progressive Disclosure of Memory

4.5 Recall Path：Agentic Retrieval#

传统 Vector Memory：

1
Query
2
↓
3
Embedding
4
↓
5
TopK
6
↓
7
Inject

Claude Code 的文件路线更像：

1
Session Start
2
↓
3
Read MEMORY.md index
4

5
Current Task
6
↓
7
Agent发现需要 Debug 历史
8

9
Read debugging.md
10
↓
11
信息仍不足
12

13
Grep / Search
14
↓
15
定位更具体内容

Recall 不完全由 Middleware 自动决定。

而是：

1
Agent
2
↓
3
发现 Context Gap
4
↓
5
主动探索 Memory Space

这是：

Agentic Memory Retrieval

4.6 如何严谨地“还原” Claude Code 的 Memory 实现#

Claude Code Core Runtime 未完整开源，所以不能声称内部一定存在某个 MemoryManager 类。

但依据官方行为契约，可以做接口级还原：

1
# 行为级架构还原，不是 Claude Code 原始源码
2

3
def build_session_context(cwd):
4
    instruction_files = resolve_claude_md_hierarchy(cwd)
5

6
    auto_memory_index = load_memory_md(
7
        max_lines=200,
8
        max_bytes=25 * 1024,
9
    )
10

11
    return compose_context(
12
        instructions=instruction_files,
13
        auto_memory=auto_memory_index,
14
    )
15

16

17
def recall_topic_memory(topic):
18
    path = choose_topic_file(topic)
19
    return file_tool.read(path)

重要的不是类名，而是两个公开行为：

1
Always-load small index
2
+
3
On-demand detailed files

4.7 为什么文件系统在 Coding Agent 中可能优于 Vector DB#

不是 File Memory 全面优于 Vector Memory，而是 Workload 不同。

项目本身已经是 Filesystem World#

Coding Agent 已经有：

1
read
2
write
3
grep
4
glob
5
find
6
git diff

如果 Memory 也是文件，Agent 不需要新增一套操作抽象。

人类可读、可编辑#

1
MEMORY.md
2
debugging.md
3
architecture.md

可以直接审计。

Vector Store 中则可能是：

1
vector_id
2
payload
3
embedding
4
metadata

运维和人工编辑成本更高。

天然 Hierarchy#

路径本身就是 Metadata：

1
memory/debugging/database.md

表达：

1
memory
2
→ debugging
3
→ database

确定性更强#

如果 Index 写明：

1
数据库迁移经验见 database-migration.md

读取路径非常稳定。

Vector Retrieval 则受：

1
Embedding Model
2
Query Formulation
3
TopK
4
Threshold
5
Ranking

影响。

Git Friendly#

文件天然支持：

1
diff
2
review
3
rollback
4
version

4.8 File Memory 的边界#

规模增长到：

1
1,000 topic files
2
100,000 entries

问题出现：

1
Agent如何知道读哪个文件？

如果 Index 没有覆盖相关 Topic：

1
Recall Miss

对模糊问题：

1
“以前那个跟时间解析差不多的问题是什么？”

Semantic Retrieval 可能更合适。

所以 Claude 路线并不是“Vector DB 没用”，而是：

Coding Agent 的 Memory 应优先利用 Agent 原生掌握的 Filesystem + Search 能力。

4.9 200 行 / 25 KB：Always-on Memory 必须有预算#

如果 MEMORY.md 无限增长：

1
Session 1: 5 KB
2
Session 10: 100 KB
3
Session 100: 2 MB

最终每个任务都先支付巨大的：

1
Memory Context Tax

所以：

1
Hot Memory
2
必须 bounded
3

4
Detailed Memory
5
下沉到 Topic Files

这是 Memory Tiering。

4.10 Claude Code 的范式#

1
Human Persistent Instructions
2
        +
3
Agent Learned Memory
4
        ↓
5
Filesystem Hierarchy
6
        ↓
7
Small Core Index
8
        ↓
9
Topic Files
10
        ↓
11
Lazy Read
12
        ↓
13
Agentic Search

Claude Code 代表：

Memory as File + Progressive Context Disclosure

最值得学习的五点：

Memory Storage 应贴合 Agent 原生工作环境。
Hot Memory 必须有 Context Budget。
Index 和 Detailed Memory 可以分离。
Recall 可以由 Agent 主动探索，而不是全部自动 Push。
Hierarchical Scope 本身就是 Context Routing。

5. Hermes：Agent 自主管理 Memory 与 Learning Loop#

独立源码深挖：Hermes Memory：Frozen Snapshot、Live State、File Lock、Drift Guard、Batch 事务与 Write Approval。

5.1 Hermes 为什么特别值得研究#

Hermes Agent 把 Memory 定义为：

1
bounded
2
curated
3
persistent

官方当前设计有两个文件：[S4]

1
MEMORY.md
2
Agent personal notes
3

4
USER.md
5
User profile

默认容量：

1
MEMORY.md = 2,200 chars
2
USER.md   = 1,375 chars

很多系统追求“存更多”。

Hermes 反而主动限制：

1
只能记很少

因为它关注的是：

Curated Working Memory

而不是完整事件仓库。

5.2 USER.md 与 MEMORY.md：User Model 和 Agent Experience 分离#

1
用户喜欢简洁回答

属于：

1
USER.md

因为这是 User Model。

1
本机安装 Docker
2
项目使用 Axum + SQLx
3
某工具在当前环境有特殊行为

属于：

1
MEMORY.md

因为这是 Agent Learned Environment / Experience。

所以：

1
USER.md
2
=
3
Who is the user?
4

5
MEMORY.md
6
=
7
What has the agent learned?

企业 Agent 不应该把：

1
用户偏好
2
业务事实
3
Agent经验
4
工具经验

全部扔进一张 memory 表。

5.3 MemoryStore 的双状态模型#

源码：

1
NousResearch/hermes-agent
2
tools/memory_tool.py

MemoryStore 显式维护：

1
Frozen Snapshot
2
+
3
Live State

一个核心成员是：

1
self._system_prompt_snapshot: Dict[str, str] = {"memory": "", "user": ""}

架构可以表示成：

1
Disk
2
↓
3
Session Start
4
↓
5
Load MEMORY.md / USER.md
6
↓
7
Sanitize
8
↓
9
Frozen Snapshot
10
↓
11
System Prompt
12

13
--------------------------------
14

15
Mid-session memory.add()
16
↓
17
Live State Update
18
↓
19
Persist Disk
20
↓
21
Tool Response Reflects New State
22

23
BUT
24

25
System Prompt Snapshot
26
remains unchanged

这是：

Dual Memory State

5.4 为什么 Frozen Snapshot 不立即更新 Context#

直觉上：

1
Agent刚写Memory
2
↓
3
为什么不立即更新System Prompt？

Hermes 给出的工程理由是：

1
Preserve Prefix Cache

如果每次 Memory Mutation 都改变 System Prompt：

1
Prompt Prefix Changes
2
↓
3
Prefix Cache Miss
4
↓
5
重复计算
6
↓
7
Latency / Cost Impact

因此：

1
Persistent State
2
立即更新
3

4
Runtime Prompt Snapshot
5
当前 Session 不变

下一 Session 才重新 Load。

这是：

Persistence Freshness 与 Runtime Cache Stability 的 Trade-off

5.5 Session-level Snapshot Isolation#

可以做语义类比：

1
Session Start
2
↓
3
Read Memory Snapshot V10
4

5
During Session
6
↓
7
Write V11
8
↓
9
Write V12
10

11
Current Prompt
12
still sees V10
13

14
Next Session
15
↓
16
Snapshot V12

它不是数据库 MVCC 的同一实现，但 Context View 具有类似的 Session Snapshot 语义。

5.6 为什么用字符预算而不是 Token 预算#

源码注释指出 Character Count 是 model-independent。

Token Count 会随：

1
Tokenizer
2
Model Family
3
Language

变化。

Character Budget：

1
简单
2
稳定
3
可预测

代价是：

1
不能精确反映真实 Context Token Cost

这是 Implementation Simplicity 与 Token Precision 的取舍。

5.7 Bounded Memory：容量满了故意不自动压缩#

Hermes add 路径大体是：

1
new_total > limit
2
↓
3
Reject Write
4
↓
5
Return Current Entries
6
↓
7
Tell Agent:
8
replace overlapping entries
9
or
10
remove stale entries
11
↓
12
Retry

结构化源码还原：

1
# 非 Hermes 原始源码
2

3
def add_memory(content):
4
    validate(content)
5
    scan_security(content)
6

7
    with file_lock():
8
        state = reload_latest_memory()
9

10
        if duplicate(content):
11
            return success_noop()
12

13
        if current_size + size(content) > limit:
14
            return {
15
                "success": False,
16
                "current_entries": state,
17
                "instruction": "Consolidate or remove stale entries, then retry.",
18
            }
19

20
        append(content)
21
        persist()

系统知道 Memory 满了，但不自动决定删什么。

容量错误变成 Agent 的 Observation：

1
Memory Full

Agent 再执行：

1
replace
2
remove
3
add

这就是：

Agent-controlled Memory Management

5.8 Capacity Pressure 是一种认知压力#

自动 Compaction：

1
System Summarizer
2
↓
3
决定什么重要

Hermes：

1
Agent
2
↓
3
看到当前Task和Memory
4
↓
5
判断哪些经验仍有用
6
↓
7
主动整合

例如：

1
Entry 1: User prefers concise replies.
2
Entry 2: User dislikes long explanations.
3
Entry 3: User prefers direct technical answers.

可以 Consolidate 成：

1
User prefers concise, direct technical answers and dislikes unnecessary long explanations.

这不是字符压缩，而是 Semantic Consolidation。

5.9 Memory Poisoning 防御：Sanitized Snapshot#

Memory Poisoning 的危险是：

1
Malicious Tool Result
2
↓
3
Memory
4
↓
5
Future Session
6
↓
7
Persistent Prompt Injection

Hermes 对 Memory Content 使用 Strict Threat Pattern Scanning。

Snapshot Load 可结构化还原为：

1
# 非 Hermes 原始源码
2

3
for entry in disk_entries:
4
    findings = strict_scan(entry)
5

6
    if findings:
7
        snapshot_entry = "[BLOCKED: threat pattern detected]"
8
    else:
9
        snapshot_entry = entry

但 Live State 仍保留原始条目。

为什么？

如果静默删除：

1
攻击痕迹被隐藏

Hermes 选择：

1
System Prompt Snapshot
2
→ 不注入危险内容
3

4
Live / Disk State
5
→ 保留供用户审计和删除

这是：

Execution Safety 与 Forensic Visibility 分离

5.10 File Lock：Memory 同样有并发一致性问题#

两个 Session 同时修改：

1
MEMORY.md

可能出现：

1
A read V10
2
B read V10
3
A write V11-A
4
B write V11-B

导致 Lost Update。

Hermes 使用独立 .lock 文件互斥：

1
Unix → fcntl
2
Windows → msvcrt

这说明：

Memory Store 一旦成为持久化状态，就必须面对数据库系统同类的一致性问题。

Memory 不是 Prompt Feature，而是 State Infrastructure。

5.11 Drift Detection：防止 Tool 覆盖外部修改#

Memory 文件可能被：

1
Manual Edit
2
Patch Tool
3
Shell Append
4
Sister Session

修改。

如果 Parser 不能 round-trip 某段未知内容，而 Replace/Remove 又整体重写文件：

1
Unknown Content
2
↓
3
Silent Data Loss

Hermes 对 Replace / Remove 做 External Drift Detection。

发现 Drift：

1
Create Backup
2
↓
3
Refuse Mutation
4
↓
5
Tell Operator Resolve Drift

这是：

Fail Closed on Potential Data Loss

5.12 为什么 Add 可以弱化 Drift Guard#

Add

语义是 Append。

已有未知内容不会被整体重写。

Replace / Remove

需要：

1
Read
2
↓
3
Parse
4
↓
5
Modify
6
↓
7
Rewrite

如果 Parser 没正确理解全部磁盘内容，Rewrite 可能丢数据。

所以保护强度应该根据 Mutation Semantics 设计，而不是所有操作一刀切。

5.13 Memory Side Effect 不能阻塞用户主任务#

源码中：

1
_MAX_CONSOLIDATION_FAILURES_PER_TURN = 3

如果 Agent 因 Memory 满不断：

1
add → failed
2
replace → failed
3
add → failed
4
...

可能出现：

1
Memory Side Effect Loop
2
↓
3
耗尽 Turn Budget
4
↓
5
用户拿不到回答

超过失败上限后，Hermes 返回 Terminal Result，要求停止 Memory Retry，继续回答用户。

这是一个非常重要的 Runtime 原则：

Auxiliary Cognitive Side Effect must not starve the primary user task.

5.14 `apply_batch`：Memory Mutation 需要事务语义#

Hermes 支持 Batch Memory Operations：

1
Remove old
2
+
3
Replace duplicated
4
+
5
Add new

一次 Tool Call 完成。

其语义：

1
Validate all
2
↓
3
Apply to Working Copy
4
↓
5
Check FINAL budget
6
↓
7
Any failure → write nothing
8
Success → commit final state

即 All-or-Nothing。

结构化还原：

1
def apply_batch(operations):
2
    scan_all_new_content()
3

4
    with file_lock():
5
        working = copy(load_latest())
6

7
        for op in operations:
8
            apply_to_working_copy(working, op)
9

10
        if size(working) > limit:
11
            abort()
12

13
        persist(working)

旧流程：

1
remove
2
↓
3
LLM Round Trip
4
replace
5
↓
6
LLM Round Trip
7
add

Batch：

1
remove + replace + add
2
↓
3
one tool call

减少：

1
LLM Round Trips
2
Context Resend
3
Partial Mutation Risk

5.15 Memory 与 Learning Loop#

Hermes 的产品思路强调 Agent during-use learning。

可以形成：

1
Execute Task
2
↓
3
Observe Result
4
↓
5
Persist Useful Experience
6
↓
7
Repeated Pattern
8
↓
9
Procedure
10
↓
11
Skill
12
↓
13
Future Task Reuse

需要区分：

1
Memory System
2
≠
3
Skill Curator

但二者可以连接：

1
Episodic Experience
2
↓
3
Repeated Pattern
4
↓
5
Procedural Insight
6
↓
7
Stable Skill

也就是：

Experience → Procedure → Capability

5.16 Hermes 的范式#

1
MEMORY.md
2
+
3
USER.md
4
        ↓
5
Bounded Curated State
6
        ↓
7
Frozen Session Snapshot
8
        ↓
9
Agent Memory Tool
10
        ↓
11
Add / Replace / Remove
12
        ↓
13
Capacity Pressure
14
        ↓
15
Agent Consolidation
16
        ↓
17
Future Session

Hermes 代表：

Agent-Managed Bounded Curated Memory

最值得学习的七点：

User Model 与 Agent Experience 分 Namespace。
Always-on Memory 必须有限。
Runtime Snapshot 和 Persistent State 可以分离。
Memory Mutation 要有并发和数据损坏保护。
Memory Write 必须防持久化 Prompt Injection。
Memory Side Effect 不应阻塞主任务。
容量压力可以成为 Agent 主动 Consolidation 信号。

6. Codex、Claude Code、Hermes：三种产品路线比较#

维度	Codex	Claude Code	Hermes
核心目标	复用任务经验	持续化项目上下文	Agent 持续学习
控制者	System	Agent + Filesystem	Agent
写入时机	Task idle 后后台写	Session 中积累	Session 中 Tool Mutation
写入模式	Extraction + Consolidation	File Notes	Add/Replace/Remove
表示	Raw Memory + Summary + Workspace	MEMORY.md + Topic Files	Bounded Entries
Hot Memory	Consolidated recall context	MEMORY.md 前 200 行/25KB	Frozen Snapshot
Consolidation	Phase 2 Agent	Topic organization	Agent replace/remove
Security	Secret Redaction	Context 不是 enforcement	Strict scan + sanitized snapshot
Policy Source	AGENTS.md / docs	CLAUDE.md / hooks	Prompt / tool policy
最适合	Coding Task Experience	Repo Context	Persistent Personal Agent

三个短句概括：

1
Codex
2
=
3
System-managed Background Memory
4

5
Claude Code
6
=
7
Filesystem-oriented Progressive Memory
8

9
Hermes
10
=
11
Agent-managed Bounded Memory

真正的分水岭是：

Memory Control Plane 在哪里。

Part III：开源 Agent Memory 框架的实现机制#

7. Mem0：把 Memory 做成工业级 Pipeline#

独立源码深挖：Mem0 Memory Pipeline：V3 ADD-only、Batch Persist、Entity Link、Hybrid Ranking 与多存储故障窗口。

7.1 最值得学习的是“Memory Pipeline 化”#

很多 Memory Demo：

1
vector_store.add(text)
2
vector_store.search(query)

Mem0 当前源码明显超出这个阶段。

mem0/memory/main.py 中，Memory 初始化包含：

1
Embedder
2
Vector Store
3
LLM
4
History DB
5
Optional Reranker
6
Lazy Entity Store

所以：

1
Memory
2
≠
3
Vector Store Wrapper

而更接近：

1
Extraction
2
+
3
Identity Scope
4
+
5
Storage
6
+
7
History
8
+
9
Retrieval
10
+
11
Ranking
12
+
13
Entity Signal

7.2 Scope 是强约束，不是装饰性 Metadata#

当前 OSS Memory API 要求至少提供：

1
user_id
2
agent_id
3
run_id

之一。

即：

1
Memory
2
必须属于某个 Identity Scope

这是：

Memory Isolation Boundary

例如：

1
User A:
2
我对花生过敏
3

4
User B:
5
我喜欢花生酱

如果检索没有 User Scope：

1
Query:
2
推荐早餐
3
↓
4
错误召回 User A Memory

这不是普通 Retrieval Accuracy 问题，而是 Cross-tenant Memory Leakage。

因此：

Memory Namespace 同时是正确性与安全边界。

7.3 `infer=False`：Raw Persistence Path#

Mem0 支持：

1
infer=False

此时不让 LLM 抽取。

结构化源码还原：

1
# 非 Mem0 原始源码
2

3
for message in messages:
4
    if message.role == "system":
5
        continue
6

7
    embedding = embed(message.content)
8

9
    create_memory(
10
        text=message.content,
11
        embedding=embedding,
12
        metadata={
13
            "role": message.role,
14
            ...
15
        },
16
    )

它适合：

1
上游已经构造好的 Memory
2
需要保留原始内容
3
日志型数据

即 Raw Memory Ingestion。

7.4 `infer=True`：V3 Phased Batch Pipeline#

当前源码直接标记：

1
# === V3 PHASED BATCH PIPELINE ===

源码：mem0/memory/main.py

其真实流程是：

1
Phase 0
2
Context Gathering
3

4
Phase 1
5
Existing Memory Retrieval
6

7
Phase 2
8
Single-pass ADD-only Extraction
9

10
Phase 3
11
Batch Embedding
12

13
Phase 4 / 5
14
CPU Processing + Hash Dedup
15

16
Phase 6
17
Batch Persistence + ADD History
18

19
Phase 7
20
Entity Linking
21

22
Phase 8
23
Save Messages + Return

Phase 8 不是无关紧要的收尾：session messages 只有在前面的向量、History 与 Entity 路径处理之后才保存。它属于一次 add() 的可见副作用，但并没有与前三类存储共享原子事务；进程在阶段边界崩溃时，后续请求看到的会话上下文可能与已经写入的 Memory 投影不一致。

这就是 Mem0 的核心：把语义抽取拆成显式阶段，同时也暴露出跨阶段恢复语义必须由调用方认真处理。

7.5 Phase 0：Extraction 本身也需要 Context#

源码会：

1
build session scope
2
↓
3
load last 10 messages
4
↓
5
parse current messages

例如当前消息：

1
User:
2
改成深圳吧。

单看当前消息无法知道改什么。

7.6 Phase 1：Read-before-Write#

流程：

1
New Messages
2
↓
3
Embed
4
↓
5
Search Existing Memories
6
↓
7
Top Candidates
8
↓
9
Give to Extraction LLM

为什么先查旧 Memory？在 V3 中，这一步的目的不是让模型决定原地 UPDATE 或 DELETE，而是给去重、上下文补全和关联判断提供参照。

已有：

1
User prefers dark mode.

新消息：

1
Actually, I use light mode now.

Extractor 看到新消息后会得到一条新的事实：

1
ADD light mode

最终：

1
dark mode
2
light mode

共存。

看 Existing Memory 后，模型可以把它理解为一次偏好变化，并在 Prompt 输出中尝试关联旧记录：

1
ADD "User now prefers light mode"
2
linked_memory_ids = [old preference]

但必须注意，V3 自动提取仍然只执行 ADD：旧的 dark-mode Memory 不会在这个阶段被覆盖或删除，新旧记录会同时保留，当前偏好由检索排序与时间语义在读时解析。官方迁移文档将这一变化明确表述为“Single-pass ADD-only”；显式 update() / delete() API 是另一条管理路径。[S7]

所以这里的 Read-before-Write 更准确地说是：

Read-before-Append：用旧记忆帮助去重与理解变化，但不在自动提取中改写旧记忆。

7.7 UUID → Integer Mapping：设计意图与固定版本落地缺口#

源码把 Existing Memory 的 UUID 映射成：

再交给 LLM。

真实 ID：

1
8df39fe1-...
2
af77b902-...

模型可能抄错、漏字符、幻觉一个 ID。

改成：

1
0: User prefers dark mode
2
1: User works in Java
3
2: User lives in Shanghai

设计意图是让模型只需输出：

1
linked_memory_ids = ["0"]

再由系统映射回 UUID。这是合理的 Anti-hallucination Interface：模型侧使用 Short Alias，系统侧保存真实 ID。

但固定 Commit 还暴露了一个需要源码审计才能发现的落地缺口：同步 V3 路径虽然构造了 uuid_mapping[str(idx)] = mem.id，后续却没有消费这个映射；Phase 4 构造新 Memory Payload 时也没有保存 Extractor 返回的 linked_memory_ids。Phase 7 的 Entity Linking 是从新 Memory 文本重新抽取实体，不能等价为把 Prompt 里的旧 Memory Link 持久化。

因此，对这个固定版本只能准确地说：

1
Short Alias Map 已构造并送入 Prompt
2
≠
3
Prompt Link 已可靠映射并持久化

这也是一个通用审计原则：

不要只检查 Prompt 是否声明某个契约，还要沿 Parse → Mapping → Payload → Store 验证它是否真正落地。

7.8 Phase 2：Single-pass ADD-only Semantic Capture#

Extraction Prompt 输入：

1
Existing Memories
2
New Messages
3
Last K Messages
4
Custom Instructions

输出新的 Memory Candidates，每条候选包含自包含文本、attributed_to，并可带关联提示。V3 的 ADDITIVE_EXTRACTION_PROMPT 明确规定唯一操作是 ADD。[S7]

这不是普通总结。

它更像把会话增量转成可检索的语义事实：

1
Conversation Delta
2
↓
3
New Semantic Facts
4
↓
5
ADD-only Append

因此可以把它类比为 Semantic Capture，但不能把它画成会输出 ADD / UPDATE / DELETE / NONE 的 CDC Change Set。prompts.py 中虽然仍存在旧的 DEFAULT_UPDATE_MEMORY_PROMPT，固定版本 _add_to_vector_store(..., infer=True) 实际调用的是 ADDITIVE_EXTRACTION_PROMPT；不能因为旧常量仍在仓库中，就把旧算法行为归到 V3 主路径。

自动推断路径只追加；显式 CRUD 路径才会改写或删除指定 Memory。

7.9 Provider Failure 和“No Memory Extracted”必须分开#

两种状态：

正常空结果：本轮没有可写 Memory#

1
LLM正常
2
↓
3
没有值得记忆的信息
4
↓
5
[]

异常空结果：Extractor 没有完成工作#

1
LLM timeout / 429 / 5xx
2
↓
3
Extraction failed
4
↓
5
[]

如果都静默返回空列表，上游无法区分：

1
No Fact
2
vs
3
Provider Failure

当前 Mem0 源码选择在 Extraction Failure 时抛出 LLMError。

这样上游才能：

1
Retry
2
Fallback
3
Alert

这是数据管道的基本原则：

Empty Result ≠ Processing Failure

7.10 Phase 3：Batch Embedding + Graceful Fallback#

Memory Candidates：

1
mem_texts
2
↓
3
embed_batch()

Batch 失败：

1
fallback
2
↓
3
embed individually

即：

1
Fast Path
2
=
3
Batch
4

5
Degraded Path
6
=
7
Per-item

长期基础设施不能因为一个 Batch Failure 就让整批 Memory 全灭。

7.11 Hash Dedup 不替代 Semantic Dedup#

源码计算文本 MD5，并检查：

1
existing_hashes
2
seen_hashes

它解决：

1
Exact Duplicate

例如：

1
User prefers dark mode
2
User prefers dark mode

但：

1
User prefers dark mode
2
The user likes dark themes

Hash 不同。

所以：

1
Hash Dedup
2
=
3
Cheap Exact Dedup
4

5
Semantic Logic
6
=
7
LLM / Retrieval / Entity Signals

典型路线：

1
Cheap Deterministic Filter
2
↓
3
Expensive Semantic Processing

7.12 `text_lemmatized`：Memory Retrieval 不应该押注 Vector Only#

Mem0 为 Memory Text 保存 BM25 预处理文本。

例如查询：

1
ERR_PAYMENT_001

Error Code、Identifier、Exact Term 可能更适合 Keyword Search。

所以：

Hybrid Retrieval 往往比单一 Dense Retrieval 更稳。

7.13 Batch Persist + History：事件类型必须按路径解释#

Mem0 同时写：

1
Memory Record
2
+
3
History Event

History 记录类似：

1
memory_id
2
old_memory
3
new_memory
4
event
5
created_at
6
is_deleted

在 V3 自动提取的 Phase 6，所有 History Record 都是：

1
old_memory = null
2
new_memory = extracted text
3
event = ADD
4
is_deleted = 0

UPDATE 和 DELETE 仍会出现在 History 中，但只来自调用方显式执行 update(memory_id, ...) 或 delete(memory_id) 的独立路径，不是 Extraction LLM 的自动决策。History 因而记录的是存储层实际发生的 Mutation，而不是 V3 LLM 输出的多操作 Change Set。

这类 Change History 支持：

1
Audit
2
Debug
3
Evaluation
4
Failure Analysis

Memory Store 也应该拥有 Change History。

7.14 Entity Linking：从 Vector Similarity 到 Multi-signal Ranking#

当前源码会：

1
Extract Entities
2
↓
3
Dedup Entity
4
↓
5
Link Memory IDs

例如：

1
Entity:
2
PostgreSQL
3

4
linked_memory_ids:
5
[M1, M8, M27]

查询：

1
数据库最近遇到过什么问题？

Entity Signal 可以 Boost PostgreSQL 相关 Memory。

于是 Ranking 可以组合：

1
Semantic Score
2
BM25 Score
3
Entity Boost

Memory Search 已经从 Vector Similarity 升级成 Multi-signal Ranking。

7.15 Search Path：Semantic Candidate Pool → Signal Enrichment → Rank#

结构化源码还原：

1
# 非 Mem0 原始源码
2

3
query_keywords = lemmatize_for_bm25(query)
4
query_entities = extract_entities(query)
5
query_vector = embed(query)
6

7
internal_limit = max(top_k * 4, 60)
8

9
semantic_results = vector_search(
10
    query_vector,
11
    top_k=internal_limit,
12
)
13

14
keyword_results = keyword_search(
15
    query_keywords,
16
    top_k=internal_limit,
17
)
18

19
# 固定版本源码以 semantic_results 作为候选全集；
20
# keyword_results 只按 memory_id 提供归一化 BM25 分数。
21
results = score_and_rank(
22
    semantic_candidates=filter_expired(semantic_results),
23
    bm25_scores=normalize_by_id(keyword_results),
24
    entity_boosts=match_entities(query_entities),
25
)
26

27
if reranker_enabled:
28
    results = rerank(query, results)
29

30
return results[:top_k]

这里必须做一个容易被“Hybrid Search”术语掩盖的源码级区分：该固定版本并没有把 keyword-only 命中与 vector 命中做候选集合并集。score_and_rank() 遍历的是 semantic_results；BM25 与 Entity 只为这些语义候选补充分数。因此更准确的结构是：

1
Semantic Candidate Generation
2
↓
3
BM25 / Entity Signal Enrichment
4
↓
5
Normalized Multi-signal Ranking
6
↓
7
Optional Reranking

这带来三个直接后果：

只被关键词精确命中、却没有进入 semantic_results 的 Memory，后续 BM25 再高也无法“复活”。
internal_limit = max(limit × 4, 60) 通过 Over-fetch 缓解召回上限，但不能消除语义候选池的单路瓶颈。
如果 Semantic Threshold 在融合前过滤，强 lexical hit 仍可能提前丢失。

所以这一实现属于 semantic-first multi-signal reranking，不是严格意义上的 dense/sparse candidate union。生产系统若要求关键词召回兜底，需要显式合并两路 ID 集合，再做去重、归一化与排序。

而不是：

1
vector_search(top_k=5)
2
↓
3
done

7.16 Expiration：Memory 不是永久事实#

当前 OSS 支持 expiration_date。

过期 Memory 默认不会出现在普通 Search / Get All 中，除非显式要求查看。

例如：

1
User is visiting Tokyo this week.

六个月以后如果仍被当成 Current Fact，就是 Stale Memory。

因此部分 Memory 必须拥有：

1
TTL / Expiration

7.17 Procedural Memory：记住“如何做”#

Mem0 当前源码对 procedural_memory 有显式处理。

对比：

1
Fact:
2
Repository uses Gradle.
3

4
Procedure:
5
When tests fail in this repository,
6
run ./gradlew test --stacktrace first,
7
then inspect module reports.

后者对 Agent Capability 提升更直接。

7.18 多存储写入：吞吐优化不等于事务一致性#

固定 Commit 的 V3 路径先批量写 Vector Store，再批量写 SQLite History，最后更新 Entity Store 并保存 session messages。[S7]

1
Vector Store
2
    ↓
3
History SQLite
4
    ↓
5
Entity Store
6
    ↓
7
Session Messages

源码对吞吐和可用性做了大量降级处理：批量 embedding 失败后逐条 embedding；批量 vector insert 失败后逐条 insert；批量 history 失败后逐条记录；entity linking 失败只记 warning，不让主 add 失败。这种策略能让部分结果继续可用，但它不是跨存储事务。

例如，逐条 vector insert 中某条失败后，当前实现仍会基于原始 records 构造全部 History，返回值也来自全部 records。于是可能出现：

1
History says ADD succeeded
2
but Vector Store has no corresponding record

反方向也可能发生：Vector Store 已写入，而进程在写 History 前崩溃。显式 Update/Delete 路径同样是先修改 Vector Store，再追加 UPDATE / DELETE History，最后清理或重建 Entity Link。这是调用方按 ID 发起的管理操作，不能与 infer=True 的 ADD-only 自动提取混为一谈。源码事实说明 Mem0 OSS 在这里偏向 best-effort availability；如果业务要求严格审计或 exactly-once，需要在外层补强，而不能把 history() 误当成数据库 WAL。

一个生产级封装可以增加：

1
operation_id + idempotency_key
2
Canonical Operation Log
3
Outbox / Inbox
4
Per-store apply status
5
Retryable Repair Worker
6
Read-time tombstone check
7
Periodic Reconciliation

1
class MemoryMutation(BaseModel):
2
    operation_id: str
3
    idempotency_key: str
4
    memory_id: str
5
    expected_version: int | None
6
    action: Literal["add", "update", "delete"]
7
    vector_applied: bool = False
8
    history_applied: bool = False
9
    entity_applied: bool = False

这里最重要的区分是：

1
Batch API
2
= 性能语义
3

4
Transaction / Idempotency / Reconciliation
5
= 正确性语义

两者不能互相替代。

1
flowchart LR
2
    A["Messages + recent context"] --> B["Read existing memories<br/>dedup / context / relation hint"]
3
    B --> C["Single-pass extraction<br/>ADD only"]
4
    C --> D["Batch embed + hash dedup"]
5
    D --> V["Vector Store"]
6
    V --> H["History: ADD"]
7
    H --> E["Entity Store"]
8
    E --> S["Session Messages"]
9

10
    V -. crash .-> X1["Vector exists<br/>History missing"]
11
    H -. partial item failure .-> X2["History may say ADD<br/>Vector item missing"]
12
    E -. warning only .-> X3["Entity projection incomplete"]

图 3：依据 Mem0 固定版本源码 [S7] 还原 V3 ADD-only 自动提取及顺序写入。Vector、History、Entity 与 Session 之间存在 Crash Window；operation_id、幂等、逐存储状态与 Reconciliation 是本文建议的生产化补强，不代表 Mem0 OSS 已提供跨存储事务。

7.19 Mem0 的边界#

Extraction Loss

1
Raw Event
2
↓
3
Extractor Miss
4
↓
5
Memory Never Exists

Recall 再强也救不回来。

Semantic Conflict

V3 刻意保留新旧事实而不在自动提取阶段覆盖历史，能够减少错误删除，却也会让 Memory 数量持续增长。Flat Memory Records 对时序冲突没有 Temporal Graph 天然；“旧偏好 + 新偏好”能否正确解析，依赖时间表达、候选召回与读时排序。需要控制体量时，应使用 Expiration、显式 Delete 或外部清理策略，而不是假定 Extractor 会自动合并。

Model Dependence

Memory Quality 受：

1
Extraction Prompt
2
LLM
3
Conversation Context

影响。

Retrieval Tuning

1
Semantic Weight
2
BM25 Weight
3
Entity Boost
4
Threshold
5
TopK
6
Reranker

都需要评估。

7.20 Mem0 论文结果如何正确理解#

Mem0 论文作者在 LoCoMo 实验中报告：

1
相对 OpenAI Memory baseline
2
LLM-as-a-Judge 指标相对提升约 26%
3

4
相对 full-context
5
p95 latency 降低约 91%
6
token cost 节省超过 90%

这些是 论文作者报告的实验结果，不能直接推导为“任何业务接入 Mem0 都获得同样提升”。

真实效果取决于：

1
Workload
2
Memory Distribution
3
Model
4
Evaluation Set
5
Retrieval Configuration

7.21 Mem0 的范式#

1
Messages
2
↓
3
Context Gathering
4
↓
5
Existing Memory Retrieval
6
↓
7
LLM Extraction
8
（Single-pass ADD-only）
9
↓
10
Batch Embedding
11
↓
12
Exact Dedup
13
↓
14
ADD Persistence + ADD History
15
↓
16
Entity Linking
17
↓
18
Hybrid Recall
19
↓
20
Rerank

显式 update() / delete() 位于这条自动流水线之外，是按 memory_id 触发的管理控制面。

Mem0 代表：

Memory as a Production Pipeline

8. Letta / MemGPT：Agent-Controlled Memory Hierarchy#

独立源码深挖：Letta / MemGPT Memory：Memory Block Prompt ABI、Shared State、Archival / Conversation Search 与 Context Paging。

8.1 Virtual Context Management#

MemGPT 的经典思想借鉴操作系统内存层级：

1
LLM Context Window
2
≈ RAM
3

4
External Memory
5
≈ Disk
6

7
Agent
8
≈ Memory Manager

真正的问题是：

当全部信息无法同时位于 Context 时，谁决定什么留在快层、什么进入慢层、什么时候重新加载？

这是：

1
Context Allocation Problem

8.2 Letta 把 Context Hierarchy 做成显式抽象#

Letta 当前官方 Context Hierarchy 包含：[S8]

1
Memory Blocks
2
Files
3
Archival Memory
4
External RAG

它们是四种不同的 Context Access Model。

Layer	是否常驻 Context	Agent 可编辑	典型访问
Memory Blocks	是	是	memory tools
Files	部分读取	通常只读	open / grep / semantic_search
Archival Memory	否	是	semantic search tools
External RAG	否	依实现	custom tools / MCP

原则：

1
Importance ↑
2
Scale ↓
3
→ Put closer to Context
4

5
Importance ↓
6
Scale ↑
7
→ Put farther from Context

8.3 Memory Block：Hot Memory#

Memory Block：

1
Persistent
2
In-context
3
Editable

例如：

1
/persona
2
/user_profile
3
/project_context
4
/current_strategy

优点：

1
Recall Miss = 0

因为不需要搜索。

缺点：

1
Context Tax every turn

所以：

Always-visible Memory 用 Context Cost 换 Retrieval Certainty。

8.4 Memory 正式进入 Agent Action Space#

Letta 公开源码：

1
letta/functions/function_sets/base.py

统一 Memory Management Tool 支持：

1
create
2
str_replace
3
insert
4
delete
5
rename

Agent 可以：

1
Reason
2
↓
3
发现 Preference 变化
4
↓
5
memory.str_replace(...)

因此：

Memory Management is an Agent Action.

8.5 `rethink_memory`：Whole-block Consolidation Primitive#

Letta 有 rethink_memory。

核心落点是：

1
agent_state.memory.update_block_value(
2
    label=target_block_label,
3
    value=new_memory,
4
)

源码：letta/functions/function_sets/base.py

函数语义要求：

1
保留所有仍有效信息
2
↓
3
移除 outdated / inconsistent 内容
4
↓
5
整合新信息
6
↓
7
形成 organized / readable / comprehensive block

这就是 Memory Consolidation。

Consolidation Unit 是：

1
One Memory Block

所以 Letta 的维护逻辑可以理解为：

Block-local Semantic Rewrite

8.6 为什么 Whole-block Rewrite 很重要#

旧 Block：

1
User is a Java developer.
2
User prefers Spring Boot.
3
User lives in Beijing.
4
User is learning Python.

新事件：

1
User moved to Shenzhen.
2
User now primarily works on Agent engineering.

简单 Append：

1
User lives in Beijing.
2
User moved to Shenzhen.

冲突。

Whole-block Rewrite：

1
Read whole block
2
↓
3
Integrate new facts
4
↓
5
Remove outdated / inconsistent info
6
↓
7
Rewrite canonical state

得到：

1
User primarily focuses on Agent engineering.
2
User has strong Java/Spring Boot experience and is learning Python.
3
User currently lives in Shenzhen.

这是 Canonical Memory State，而不是 Event Log。

8.7 Archival Memory：Cold Semantic Memory#

Archival Memory 不常驻 Context。

Agent 使用：

1
archival_memory_insert
2
archival_memory_search

适合：

1
self-contained facts
2
meeting summaries
3
project updates
4
past events

可以理解为：

1
Memory Block
2
=
3
Hot Canonical State
4

5
Archival Memory
6
=
7
Cold Searchable Memory

8.8 Conversation Search 和 Archival Search 不同#

Letta 还提供 Conversation Search。

它搜索：

1
prior conversation history

Archival Search 搜索：

1
agent explicitly stored long-term memory

所以：

1
Conversation History
2
=
3
What happened
4

5
Archival Memory
6
=
7
What agent chose to preserve

不要把“过去说过的话”自动视为“长期知识”。

8.9 Files：与 Claude Code 的交汇#

Letta Files 支持：

1
open
2
close
3
semantic_search
4
grep

与 Claude Code 有明显共通点。

区别：

1
Claude Code
2
=
3
Filesystem is the natural world of Coding Agent
4

5
Letta
6
=
7
Files are one tier in a generalized context hierarchy

8.10 如何选择 Memory Tier#

每轮都必须知道

1
User name
2
Critical persona
3
Current long-term goal
4
Core project constraint

→ Memory Block

偶尔召回

1
三个月前会议
2
历史讨论
3
某次任务总结

→ Archival Memory

大型资料

1
几百页文档
2
几十个文件

→ Files

百万级 Corpus

→ External RAG

可以抽象：

1
def route_memory(item):
2
    if must_always_be_visible(item):
3
        return MEMORY_BLOCK
4

5
    if is_large_document(item):
6
        return FILE
7

8
    if is_recallable_experience(item):
9
        return ARCHIVAL_MEMORY
10

11
    return EXTERNAL_RAG

8.11 Compaction 与 Memory Block 不同#

Long-running Agent：

1
Message 1
2
Message 2
3
...
4
Message 10000

需要：

1
Older Messages
2
↓
3
Compaction
4
↓
5
Compact History

但：

1
Compacted History
2
≠
3
Memory Block

Compaction 解决当前运行连续性。

Memory Block 保存明确持久化的高价值 Canonical Context。

8.12 Context Distance#

Memory Block：

1
Always visible
2
↓
3
No retrieval miss
4
↓
5
High context cost

Archival：

1
Out of context
2
↓
3
Low context cost
4
↓
5
May miss retrieval

可以定义一个概念：

Context Distance

越靠近模型：

1
Access Faster
2
Recall More Certain
3
Cost Higher
4
Capacity Smaller

越远：

1
Capacity Larger
2
Cost Lower
3
Need Retrieval
4
Recall Uncertain

Memory Hierarchy 的本质，是把不同重要度、规模、召回频率的信息放在不同 Context Distance。

8.13 Memory Block 是 Prompt ABI，不只是数据库字段#

固定版本的 Block schema/ORM 至少包含 label、description、value、limit、read_only、template 信息和 metadata。[S8] 这些字段并非都只是管理后台展示属性。letta/schemas/memory.py 编译 Context 时会把 Block 渲染为：

1
<memory_blocks>
2
  <human>
3
    <description>...</description>
4
    <metadata>
5
      - read_only=true
6
      - chars_current=820
7
      - chars_limit=2000
8
    </metadata>
9
    <value>...</value>
10
  </human>
11
</memory_blocks>

这意味着 Block Schema 实际上构成 Agent 可见的 Prompt ABI：

label 决定语义分区和工具寻址。
description 告诉模型该区应该保存什么。
limit 既是写入约束，也把容量压力显式暴露给模型。
read_only 是 Agent Action Space 的权限声明。
value 才是具体记忆内容。

BlockManager 还显式维护 PROMPT_AFFECTING_BLOCK_FIELDS = {description, label, limit, read_only, value}。更新时先检测 no-op；只要这些字段改变，就为所有连接该 Block 的 Agent 重建 system prompt。这揭示了一个常被忽略的一致性问题：

1
Database block updated
2
≠
3
Every active agent immediately observes the new prompt

共享 Block 会把一次写入扩散到多个 Agent，因此实现必须处理 Prompt Cache Invalidation、正在执行 Run 的 snapshot 边界，以及只读 Block 的授权校验。Letta 的编译与重建路径把这种扩散显式化了，而不是假设数据库更新自然等于模型 Context 更新。

检索工具也体现了分层契约。conversation_search 支持 role 与时间范围，并使用 text + semantic hybrid search；archival_memory_search 支持 tags、any/all 匹配、时间窗口和 TopK。两者看起来都是“搜过去”，但前者的检索单元是消息与会话顺序，后者的检索单元是 Agent 主动沉淀的长期对象。把它们合并成一个无类型向量集合，会丢失 role、时间和写入意图。

8.14 Letta / MemGPT 的范式#

1
                 Agent Context
2

3
           ┌───────────────┐
4
           │ Memory Blocks │
5
           │  Always-on    │
6
           └───────┬───────┘
7
                   │
8
                Files
9
         Partial Read / Search
10
                   │
11
            Archival Memory
12
            Semantic Recall
13
                   │
14
              External RAG
15
             Massive Corpus

Letta 代表：

Memory as an Agent-controlled Context Hierarchy

9. Graphiti：Temporal Context Graph 与动态事实记忆#

独立源码深挖：Graphiti Temporal Memory：Episode、Entity Resolution、Fact Invalidation、Saga 双 Watermark 与 Hybrid Graph Search。

9.1 Vector Memory 的真正弱点：世界会变化#

1
2024:
2
Alice works at Company A.
3

4
2025:
5
Alice joins Company B.
6

7
2026:
8
Alice becomes CTO of Company C.

Vector DB 保存：

1
M1: Alice works at A
2
M2: Alice joins B
3
M3: Alice is CTO of C

Query：

1
Where does Alice work?

Semantic Search 可能返回 M1、M2、M3。

但问题不是：

1
哪个文本更像 Query？

而是：

哪个 Fact 在当前时间有效？

这是 Temporal State Problem。

9.2 Graphiti 构建的是 Temporal World Model#

核心对象：

1
Episode
2
Entity
3
Entity Edge / Fact
4
Community

简化：

1
Episode
2
=
3
发生了什么
4

5
Entity
6
=
7
涉及谁 / 什么对象
8

9
Fact Edge
10
=
11
对象之间什么关系
12

13
Temporal Fields
14
=
15
事实何时有效 / 何时失效

例如：

1
Episode E1
2
2025-01-01
3
"Alice joined Company B."
4

5
Entity:
6
Alice
7
Company B
8

9
Fact:
10
Alice --WORKS_AT--> Company B
11

12
valid_at:
13
2025-01-01

后续：

1
Episode E2
2
2026-01-01
3
"Alice left B and joined C."

系统不应删除旧事实，而应形成：

1
Alice --WORKS_AT--> B
2
valid_at   = 2025-01-01
3
invalid_at = 2026-01-01
4

5
Alice --WORKS_AT--> C
6
valid_at   = 2026-01-01
7
invalid_at = null

这就是 Temporal Fact Evolution。

9.3 `created_at` 与 `valid_at`#

Graphiti Episode 同时维护：

1
created_at
2
valid_at

created_at#

系统什么时候摄取 Episode。

1
Ingestion / Processing Time

valid_at#

事件在真实世界的参考时间。

1
Event Time

今天是 2026-07-15，今天导入：

1
“2024-03-01，Alice 加入 Company A。”

则：

1
created_at = 2026-07-15
2
valid_at   = 2024-03-01

如果只有 created_at，系统可能误认为 Alice 2026 年才加入 A。

所以：

When system learned it 与 When the fact was true 必须分开。

9.4 `invalid_at`：失效不等于删除#

Graphiti 冲突处理源码有一个关键赋值：

1
edge.invalid_at = resolved_edge.valid_at

源码：graphiti_core/utils/maintenance/edge_operations.py

旧事实：

1
Alice works at A
2
valid_at = 2025-01

新事实：

1
Alice works at B
2
valid_at = 2026-03

旧 Edge 可变成：

1
valid_at   = 2025-01
2
invalid_at = 2026-03

含义：

1
Old Fact
2
不是“永远错误”
3

4
而是：
5
曾经为真
6
现在失效

对 CRM、订单状态、员工关系、组织结构、资产状态、项目状态非常关键。

9.5 `add_episode()` 的真实 Write Path#

源码入口：

1
graphiti_core/graphiti.py
2
Graphiti.add_episode(...)

流程：

1
Episode Input
2
      ↓
3
Retrieve Previous Episodes
4
      ↓
5
Create EpisodicNode
6
      ↓
7
Extract Nodes
8
      ↓
9
Resolve Nodes / Entity Resolution
10
      ↓
11
Extract Edges / Facts
12
      ↓
13
Resolve Edges
14
      ├── Duplicate
15
      ├── New
16
      └── Contradictory / Invalidated
17
      ↓
18
Extract Entity Attributes
19
      ↓
20
Build Episode Provenance Edges
21
      ↓
22
Persist Nodes + Edges + Episode
23
      ↓
24
Optional Community Update

这是完整的 Temporal Knowledge Ingestion Pipeline。

9.6 为什么 Write Path 先 Recall Previous Episodes#

当前 Episode：

1
She left the company last Friday.

没有历史：

1
She = ?
2
the company = ?
3
last Friday relative to what?

Previous Episodes 提供：

1
Entity Reference
2
Temporal Resolution
3
Fact Context

这说明：

Memory Write 也可能需要先读取旧 Memory。

9.7 Entity Resolution：Identity Canonicalization#

新 Episode：

1
Jupiter fixed the bug.

旧 Graph：

1
Wang Shuai
2
王帅
3
Jupiter

如果不做 Entity Resolution：

1
Node 1: Wang Shuai
2
Node 2: 王帅
3
Node 3: Jupiter

记忆碎片化。

Graph Memory 的质量高度依赖：

1
Entity Extraction
2
+
3
Entity Resolution

这不是简单 NER，而是：

Identity Canonicalization

9.8 Fact Edge 需要 Provenance 与 Time#

Graphiti Edge 可包含：

1
source entity
2
target entity
3
relation type
4
fact text
5
valid_at
6
invalid_at
7
episode attribution
8
reference_time

可以抽象成：

1
Fact {
2
    subject
3
    predicate
4
    object
5
    statement
6
    valid_time
7
    invalid_time
8
    source_episode
9
    reference_time
10
}

Episode Attribution 让系统能回答：

1
这个事实从哪里来的？

企业 Agent 不能只说：

1
“Memory里有。”

而应追溯到具体 Episode / Source。

9.9 Exact Dedup → Hybrid Candidate Search#

Graphiti 先对：

1
(source UUID, target UUID, normalized fact)

做 Exact Dedup。

然后：

1
Create Embeddings
2
↓
3
Get Existing Edges Between Nodes
4
↓
5
Hybrid Search Related Edges
6
↓
7
Hybrid Search Invalidation Candidates

又是：

1
Cheap deterministic processing
2
↓
3
Expensive semantic processing

9.10 Duplicate Candidate 与 Invalidation Candidate 分离#

新 Fact：

1
Alice works at Company B.

已有：

1
Alice is employed by Company B.

可能是 Duplicate。

另一个：

1
Alice works at Company A.

可能是 Contradiction / Temporal Replacement。

因此：

1
Related Edges
2
→ Duplicate Resolution
3

4
Broader Existing Edges
5
→ Invalidation Detection

Graphiti 甚至会去除两种候选集合中的重叠项，避免同一 Edge 进入两个决策路径。

9.11 冲突处理核心是时间窗口#

结构化逻辑：

1
For each old edge:
2

3
如果 Old invalid_at <= New valid_at
4
    时间不重叠
5
    skip
6

7
如果 New invalid_at <= Old valid_at
8
    时间不重叠
9
    skip
10

11
如果 Old valid_at < New valid_at
12
    Old invalid_at = New valid_at
13
    mark invalidated

因此：

1
A works at Company A
2
2019 → 2021
3

4
A works at Company B
5
2022 → now

虽然 Relation Type 相同，但并不冲突，因为时间区间不重叠。

9.12 `expired_at` 与 `invalid_at` 不应混淆#

概念上：

1
invalid_at
2
→ 事实在现实世界何时不再有效
3

4
expired_at
5
→ 系统何时将该记录标记为失效/过期状态

即：

1
World Time
2
vs
3
System Lifecycle Time

业务事实时间和存储生命周期时间是两个维度。

9.13 Saga 双 Watermark：非常高级的时序设计#

当前 summarize_saga 维护：

1
last_summarized_at
2
last_summarized_episode_valid_at

`last_summarized_at`#

Wall-clock / Ingestion Time。

作用：

1
下次找“新摄取”的 Episode

`last_summarized_episode_valid_at`#

Event Time。

作用：

1
摘要覆盖到真实世界哪个时间点

考虑 Backfill：

1
今天 2026-07-15
2
导入一条 2024-01-01 历史事件

Episode：

1
created_at = 2026-07-15
2
valid_at   = 2024-01-01

如果增量 Summary Filter 使用：

1
valid_at > last_valid_at

2024 的 Backfill 可能被漏掉。

所以增量处理应看 created_at，保证今天新摄取的数据进入下一轮。

但对外表达 Summary 覆盖到哪个事件时间，又应该看 valid_at。

因此：

1
Processing Watermark
2
+
3
Event-time Watermark

这已经是流处理系统中的经典问题。

Temporal Memory 开始接近事件流与时态数据库问题，而不是 Prompt 技巧。

Graphiti 中 Valid Time、Ingestion Time、迟到 Backfill 与双 Watermark 的关系

图 4：依据 Graphiti 固定版本的时间字段与 Saga 水位线 [S9] 绘制。旧事实的 invalid_at 表示业务有效区间结束，迟到 Episode 则说明 Processing Time 与 Event Time 必须分别推进。

9.14 Search：Graph Memory 不是 Traversal Only#

Graphiti Search 支持多个 Signal：

1
BM25 / Full-text
2
Cosine Similarity
3
BFS

Reranker 可包括：

1
RRF
2
MMR
3
Cross Encoder
4
Episode Mentions

源码根据 Search Config 动态构造 Search Tasks，并并发执行。一个关键并发语义可以从短句看出：

1
search_results = list(await semaphore_gather(*search_tasks))

源码：graphiti_core/search/search.py

固定版本的 SearchConfig 进一步把检索配置拆到四种结果类型：[S9]

Retrieval Unit	Candidate Method	可选 Reranker
Edge	BM25、Cosine、BFS	RRF、MMR、Cross Encoder、Node Distance、Episode Mentions
Node	BM25、Cosine、BFS	RRF、MMR、Cross Encoder、Node Distance、Episode Mentions
Episode	BM25	RRF、Cross Encoder
Community	BM25、Cosine	RRF、MMR、Cross Encoder

每种 config 还有自己的 sim_min_score、mmr_lambda、bfs_max_depth，顶层再用 limit 和 reranker_min_score 控制最终输出。官方 recipe 甚至分别提供 combined RRF、combined MMR 和 combined cross-encoder 方案，而不是宣称存在唯一最佳检索器。

Graphiti 的 RRF 源码实现为：

$\operatorname{score}_{\mathrm{RRF}}(u)=\sum_j\frac{1}{\operatorname{rank}_j(u)+c}$

它只依赖各通道排名，不要求 BM25、cosine 和 BFS 的分数处于同一量纲。MMR 则在相关性与候选间冗余之间权衡：

$\operatorname{MMR}(d)=\lambda\operatorname{sim}(q,d)-(1-\lambda)\max_{s\in S}\operatorname{sim}(d,s)$

这里的工程含义是：RRF 解决异构信号融合，MMR 解决有限 Context 中的结果多样性，Cross Encoder 解决高成本精排，Node Distance/Episode Mentions 则利用图结构与来源频次。它们解决的不是同一个问题，不能只用离线 Recall@K 选一个“总冠军”。

SearchFilters 同时支持 node labels、edge types、edge UUID、property filters，以及 valid_at / invalid_at / created_at / expired_at 的组合比较。时间过滤应尽量下推到 Candidate Generation，而不是先召回过期事实再让 LLM 猜哪条有效；后者既浪费 TopK，也容易让冲突内容同时进入 Context。

因此：

1
Multi-channel Candidate Generation
2
↓
3
Fusion / Reranking

Graph 只是结构和检索信号之一。

9.15 为什么同时 Search Edge、Node、Episode、Community#

不同 Query 的最佳 Retrieval Unit 不同。

1
“Alice现在在哪工作？”
2
→ Edge
3

4
“Alice是谁？”
5
→ Node
6

7
“上次项目事故发生了什么？”
8
→ Episode
9

10
“数据库迁移讨论的主要主题？”
11
→ Community

所以：

Memory Retrieval Unit 应与 Query Intent 对齐。

这比把所有信息统一切成 Chunk 更精细。

9.16 Graphiti 的成本和风险#

Entity Resolution Error

错误合并两个实体会污染整张图。

Entity Fragmentation

同一实体被拆成多个 Node，Recall 不完整。

Temporal Extraction Error

相对时间被解析错，会破坏状态演化。

Relation Ontology Drift

1
WORKS_AT
2
EMPLOYED_BY
3
MEMBER_OF

可能表示相近关系。

Infrastructure Cost

需要：

1
Graph DB
2
LLM Extraction
3
Embedding
4
Hybrid Search
5
Reranker

因此，不要因为 Graphiti 技术先进就给所有聊天机器人上 Temporal Graph。

它最适合：

1
事实持续变化
2
关系重要
3
历史需要保留
4
多跳关系查询
5
Temporal Reasoning

9.17 Zep / Graphiti 论文结果如何理解#

Zep 论文作者报告：

1
DMR:
2
94.8%
3
vs MemGPT 93.4%
4

5
LongMemEval:
6
部分评估准确率提升最高约 18.5%
7
相对基线降低约 90% 响应延迟

这是论文作者报告的实验结果。

它说明 Temporal Knowledge Graph 路线在动态企业 Memory 中有潜力，但不能脱离数据分布泛化到所有 Agent。

9.18 Graphiti 的范式#

1
Event / Episode
2
↓
3
Entity Extraction
4
↓
5
Entity Resolution
6
↓
7
Fact Extraction
8
↓
9
Temporal Annotation
10
↓
11
Duplicate Resolution
12
↓
13
Conflict / Invalidation
14
↓
15
Graph Persistence
16
↓
17
Hybrid Retrieval
18
↓
19
Temporal World State

Graphiti 代表：

Memory as an Evolving Temporal World Model

10. Mem0、Letta、Graphiti：三种框架路线比较#

维度	Mem0	Letta / MemGPT	Graphiti
核心问题	如何抽取和召回 Memory	Memory 放在哪一层	动态事实如何演化
核心抽象	Memory Record	Context Hierarchy	Temporal Context Graph
Write	Pipeline Extraction	Agent Memory Action	Episode Ingestion
Agent Control	中	高	通常较低
Hot Memory	依 Context Builder	Memory Blocks	查询后注入
Cold Memory	Vector Store	Archival / Files / RAG	Graph
Retrieval	Semantic + BM25 + Entity + Rerank	Always-on + File + Semantic	BM25 + Vector + BFS + Rerank
Conflict	ADD-only 保留历史，读时排序；显式 CRUD 独立	Block Rewrite	Temporal Invalidation
Temporal	Expiration	依内容设计	原生 valid/invalid time
Provenance	History / Metadata	依 Store	Episode Attribution
最强项	Production Pipeline	Agent-controlled Hierarchy	Dynamic World State
主要代价	Extraction/Retrieval 调优	Context Routing Complexity	Graph/Entity/Temporal Complexity

一句话：

1
Mem0
2
→ 什么值得抽成 Memory，如何高效找回？
3

4
Letta
5
→ Memory 应该离 Context 多远，由谁移动？
6

7
Graphiti
8
→ 世界变化后，如何保留历史又知道现在？

三者可以组合：

1
Mem0-like Extraction Pipeline
2
        ↓
3
Memory Router
4
        ├── Hot Important State → Letta-style Block
5
        ├── Episodic Memory → Vector / Archival
6
        └── Temporal Business Facts → Graphiti

Codex、Claude Code、Hermes、Mem0、Letta 与 Graphiti 六种记忆架构的机制对比

图 5：六个案例分别强调后台经验巩固、文件层级、受限自管理、工业化抽取、上下文分层与时态世界模型。横轴不是优劣排序，而是控制权与表示能力的变化。

Part IV：工业级架构设计、工程难题与场景选型#

11. 六个系统背后的五种 Memory 范式#

11.1 System-Managed Memory#

代表：

1
Codex
2
Mem0

控制流：

1
Event
2
↓
3
System Pipeline
4
↓
5
Extraction
6
↓
7
Evaluation
8
↓
9
Persistence

优势：

1
统一治理
2
可观测
3
容易执行安全策略
4
Agent不需要主动记

问题：

1
Extractor可能漏记
2
系统未必准确判断当前Agent主观上的Future Utility

适合：

1
Enterprise Agent
2
High-throughput Agent
3
Centralized Memory Platform

11.2 Memory as File#

代表：

1
Claude Code
2
Hermes
3
Letta Files

核心：

1
Memory
2
=
3
Human/Agent-readable artifacts

优势：

1
Readable
2
Editable
3
Auditable
4
Versionable
5
Tool-native
6
Hierarchical

边界：

1
Large-scale Fuzzy Recall
2
Semantic Conflict
3
Index Maintenance

适合：

1
Coding Agent
2
Research Agent
3
Local-first Agent

11.3 Agent-Controlled Memory#

代表：

1
Hermes
2
Letta

Memory 操作进入 Agent Action Space：

1
memory.add
2
memory.replace
3
memory.remove
4
memory.rethink
5
archival_memory_insert
6
archival_memory_search

优势：

1
Agent知道当前任务上下文
2
Agent能判断主观Future Utility
3
可主动整合

风险：

1
Agent乱写
2
过度记忆
3
Memory Tool Loop
4
Memory Poisoning
5
Wrong Forgetting

因此必须配：

1
Budget
2
Guardrail
3
Tool Limit
4
Validation
5
Audit

11.4 Hierarchical Memory#

代表：

1
Claude Code
2
Letta

核心：

1
不是所有Memory离Model一样近

可以抽象成：

1
L0
2
Always-on Core Memory
3

4
L1
5
Indexed / Topic Memory
6

7
L2
8
Semantic Archive
9

10
L3
11
External Massive Knowledge

需要两个 Router。

Memory Write Router

1
Information
2
↓
3
Which Level?

Memory Retrieval Router

1
Query
2
↓
3
Which Level to Search?

11.5 Temporal World Model#

代表：

1
Graphiti

核心：

1
Memory is not a bag of sentences.
2
Memory is an evolving state of entities and relations.

适合回答：

1
Who?
2
What?
3
Relationship?
4
When?
5
Changed From?
6
Changed To?
7
What is valid now?

它把 Memory 从 Retrieval Problem 升级成 State Evolution Problem。

11.6 真实生产系统通常是组合#

1
                    Agent Runtime
2
                          ↓
3
                  Memory Write Router
4
                          ↓
5
      ┌───────────────────┼───────────────────┐
6
      │                   │                   │
7
 User Profile         Experience          Business State
8
      │                   │                   │
9
 Mem0-like            Episodic /          Graphiti-like
10
 Pipeline              Procedural           Temporal Graph
11
      │                   │                   │
12
      └───────────────────┼───────────────────┘
13
                          ↓
14
                    Context Builder

所以不要问：

Mem0、Letta、Graphiti 哪个绝对最好？

正确问题是：

我的 Workload 中存在什么类型的 Memory Problem？

12. 一个完整工业级 Agent Memory Harness 应该长什么样#

综合六个系统，可以抽象出八个核心模块。

1
Event Sources
2
    ↓
3
Memory Capture
4
    ↓
5
Memory Extractor
6
    ↓
7
Memory Evaluator
8
    ↓
9
Memory Router
10
    ↓
11
Memory Stores
12
    ↓
13
Memory Retriever
14
    ↓
15
Context Builder
16
    ↓
17
Agent Runtime
18
    ↓
19
Execution / Feedback
20
    ↓
21
Memory Consolidator
22
    ↓
23
Memory Governance

生产级 Agent Memory 控制面中的 Canonical Memory、派生索引、策略门、审计、墓碑与修复任务

图 6：Canonical Memory 是权限、版本与来源的真相源；Vector、BM25、Graph 和 Summary 都是可修复的派生投影，删除由 Tombstone 向所有读路径传播。

12.1 Memory Capture#

职责：

1
统一接收 Agent 运行事件

建议 Event Schema：

1
from datetime import datetime
2
from typing import Any, Literal
3

4
from pydantic import BaseModel, Field
5

6

7
class AgentEvent(BaseModel):
8
    event_id: str
9
    trace_id: str
10
    session_id: str
11
    actor_id: str | None = None
12

13
    event_type: Literal[
14
        "user_message",
15
        "assistant_message",
16
        "tool_call",
17
        "tool_result",
18
        "state_transition",
19
        "error",
20
        "human_feedback",
21
        "task_result",
22
        "evaluation",
23
    ]
24

25
    payload: dict[str, Any]
26
    occurred_at: datetime
27

28
    sensitivity: Literal[
29
        "public",
30
        "internal",
31
        "confidential",
32
        "restricted",
33
    ] = "internal"
34

35
    metadata: dict[str, Any] = Field(default_factory=dict)

建议进一步增加：

1
ingested_at

使：

1
occurred_at
2
=
3
Event Time
4

5
ingested_at
6
=
7
Processing Time

这是从 Graphiti 双时间语义得到的直接工程启发。

交付语义：接受重复，不接受不可检测的丢失#

Memory Capture 通常跨越业务数据库、消息队列和后台 Worker。追求端到端 exactly-once 往往成本很高，更现实的契约是：

1
Producer: Transactional Outbox
2
Broker: at-least-once delivery
3
Consumer: idempotent apply
4
Store: unique(pipeline_version, event_id)

pipeline_version 必须进入幂等键，因为升级 Extractor 后可能需要对同一个源事件重新抽取。重放任务还要记录 from_watermark、to_watermark、配置版本与模型版本，使“线上写入”和“离线回填”不会互相覆盖。

建议补充三张控制表：

1
memory_capture_offset(consumer, partition, watermark)
2
memory_job(job_id, state, lease_owner, lease_until, retry_count)
3
memory_dead_letter(job_id, event_id, error_class, payload_ref)

监控不应只看 queue lag，还要看 oldest_unprocessed_event_age、重复消费率、dead-letter 增长和 watermark 停滞时间。队列长度为零不等于完整，有可能事件根本没有从业务事务发布出来。

12.2 Memory Extractor#

职责：

1
Event Stream
2
↓
3
Memory Candidate

建议输出：

1
from datetime import datetime
2
from typing import Literal
3

4
from pydantic import BaseModel, Field
5

6

7
class MemoryCandidate(BaseModel):
8
    content: str
9

10
    kind: Literal[
11
        "profile",
12
        "semantic",
13
        "episodic",
14
        "procedural",
15
        "temporal_fact",
16
    ]
17

18
    subject_ids: list[str] = Field(default_factory=list)
19
    source_event_ids: list[str]
20

21
    confidence: float
22
    importance: float
23
    reusability: float
24

25
    valid_at: datetime | None = None
26
    invalid_at: datetime | None = None
27
    expires_at: datetime | None = None
28

29
    sensitivity: str

Extractor 不应该直接写 Store。

推荐：

1
Extractor
2
↓
3
Candidate
4

5
Evaluator / Policy
6
↓
7
Write Decision

否则：

1
LLM一输出
2
↓
3
永久持久化

风险过高。

12.3 Memory Evaluator#

职责：

1
Should Write?

至少考虑：

1
Confidence
2
Importance
3
Reusability
4
Freshness
5
Sensitivity
6
Duplicate Probability
7
Conflict Probability

一个工程启发式示例：

1
def memory_utility(candidate: MemoryCandidate) -> float:
2
    benefit = (
3
        candidate.importance
4
        * candidate.reusability
5
        * candidate.confidence
6
    )
7

8
    risk_penalty = {
9
        "public": 0.0,
10
        "internal": 0.05,
11
        "confidential": 0.30,
12
        "restricted": 1.00,
13
    }.get(candidate.sensitivity, 0.20)
14

15
    return benefit - risk_penalty

再次强调：这是工程示例，不是学术标准公式。

高风险系统中：

1
Restricted Memory
2
↓
3
Never auto-write
4

5
Confidential Memory
6
↓
7
Policy / Encryption / Retention
8

9
Low-confidence Memory
10
↓
11
Episodic only
12
not canonical semantic state

12.4 Memory Router#

职责：

1
Candidate
2
↓
3
Which Store / Tier?

示例：

1
from enum import Enum
2

3

4
class MemoryTarget(str, Enum):
5
    CORE = "core"
6
    EPISODIC = "episodic"
7
    PROCEDURAL = "procedural"
8
    TEMPORAL_GRAPH = "temporal_graph"
9
    DROP = "drop"
10

11

12
def route_memory(candidate: MemoryCandidate) -> MemoryTarget:
13
    if candidate.confidence < 0.5:
14
        return MemoryTarget.DROP
15

16
    if candidate.kind == "temporal_fact":
17
        return MemoryTarget.TEMPORAL_GRAPH
18

19
    if candidate.kind == "procedural":
20
        return MemoryTarget.PROCEDURAL
21

22
    if (
23
        candidate.importance > 0.9
24
        and candidate.reusability > 0.8
25
    ):
26
        return MemoryTarget.CORE
27

28
    return MemoryTarget.EPISODIC

这里直接融合：

1
Claude / Letta Hierarchy
2
+
3
Mem0 Pipeline
4
+
5
Graphiti Temporal Store

12.5 Memory Store#

不要只定义：

1
save(text)
2
search(query)

更合理的统一协议：

1
from typing import Protocol
2

3

4
class MemoryStore(Protocol):
5
    async def add(self, candidate: MemoryCandidate):
6
        ...
7

8
    async def update(
9
        self,
10
        memory_id: str,
11
        candidate: MemoryCandidate,
12
    ):
13
        ...
14

15
    async def invalidate(
16
        self,
17
        memory_id: str,
18
        *,
19
        invalid_at,
20
        reason: str,
21
    ):
22
        ...
23

24
    async def search(self, query):
25
        ...
26

27
    async def history(self, memory_id: str):
28
        ...

不同 Store：

1
FileMemoryStore
2
VectorMemoryStore
3
BlockMemoryStore
4
TemporalGraphMemoryStore

Store Contract 必须表达版本和部分失败#

上面的协议还缺两个生产关键字段：expected_version 与 operation_id。没有前者，两个会话同时更新用户 Profile 时会 last-write-wins；没有后者，超时重试无法判断第一次写是否已经成功。

1
class MutationResult(BaseModel):
2
    operation_id: str
3
    memory_id: str
4
    previous_version: int | None
5
    committed_version: int
6
    canonical_applied: bool
7
    pending_projections: list[str]
8

9

10
class VersionConflict(Exception):
11
    current_version: int

推荐写序：

1
1. BEGIN canonical transaction
2
2. check expected_version / authorization
3
3. write canonical row or tombstone
4
4. append change_log + projection_outbox
5
5. COMMIT
6
6. async apply vector/BM25/graph/summary projections
7
7. acknowledge projection offsets

Read Path 不能盲信派生索引。检索命中 (memory_id=m1, version=7) 后，注入前批量回查 canonical store；如果当前是 version 9、invalid 或 deleted，就丢弃旧命中或重新取内容。这是对 eventual consistency 的显式闭环。

还需要 Reconciliation Job 定期比较：

1
canonical active IDs
2
vs vector IDs
3
vs lexical IDs
4
vs graph provenance IDs

它输出 missing projection、orphan projection、version drift 和 tombstone leak。Mem0 固定版本的 best-effort 多存储写入，正好说明这一层不能被 SDK 的成功返回值替代。[S7]

12.6 Memory Retriever#

Retriever 不应该只有：

1
semantic_search()

推荐：

1
Query
2
↓
3
Intent Analysis
4
↓
5
Retrieval Plan
6
        ├── Core Memory
7
        ├── BM25
8
        ├── Dense Vector
9
        ├── Entity Lookup
10
        ├── Temporal Graph
11
        └── File Search
12
↓
13
Candidate Fusion
14
↓
15
Rerank
16
↓
17
Context Selection

示例 Query Schema：

1
class MemoryQuery(BaseModel):
2
    text: str
3
    user_id: str | None = None
4
    agent_id: str | None = None
5
    run_id: str | None = None
6

7
    needs_temporal_reasoning: bool = False
8
    needs_procedural_memory: bool = False
9
    max_context_tokens: int = 2000

路由：

1
async def retrieve_memory(query: MemoryQuery):
2
    candidates = []
3

4
    candidates.extend(
5
        await core_store.get_always_visible(query)
6
    )
7

8
    if query.needs_procedural_memory:
9
        candidates.extend(
10
            await procedural_store.search(query.text)
11
        )
12

13
    if query.needs_temporal_reasoning:
14
        candidates.extend(
15
            await temporal_graph.search(query.text)
16
        )
17

18
    candidates.extend(
19
        await episodic_store.hybrid_search(query.text)
20
    )
21

22
    return rerank_and_budget(
23
        query=query,
24
        candidates=candidates,
25
    )

Retrieval 必须能解释“为什么这条被选中”#

每个候选建议保留分通道特征，而不是只返回一个无法解释的 score：

1
class RetrievalCandidate(BaseModel):
2
    memory_id: str
3
    version: int
4
    lexical_rank: int | None
5
    dense_rank: int | None
6
    graph_distance: int | None
7
    entity_overlap: float
8
    freshness: float
9
    confidence: float
10
    scope_match: float
11
    reranker_score: float | None
12
    selected: bool
13
    rejection_reason: str | None

这样才能区分三类问题：

1
Candidate miss      正确记忆没有进入候选集
2
Ranking miss        进入了候选集但排序太低
3
Packing miss        排名足够高但被 Context Budget 丢弃

三类问题的修复方向完全不同。只记录最终 TopK 会让调参变成猜测。

一个可审计的启发式排序可以写成：

$S(m,q)=w_rR+w_fF+w_cC+w_sS+w_tT-w_pP$

其中 $R$ 是检索相关性， $F$ 是 freshness， $C$ 是 confidence， $S$ 是 scope match， $T$ 是 task utility， $P$ 是风险或冲突惩罚。权重必须通过业务 Eval Set 与消融实验选择，而不是凭经验长期固定。

12.7 Context Builder#

Retriever 返回 20 条 Memory，不代表全部进入 Prompt。

Context Builder 应做：

1
Dedup
2
Conflict Marking
3
Freshness Check
4
Temporal Validity
5
Sensitivity Check
6
Token Budget
7
Diversity
8
Ordering
9
Compression

建议输出结构化 Context：

1
<user_profile>
2
...
3
</user_profile>
4

5
<current_project_memory>
6
...
7
</current_project_memory>
8

9
<relevant_experience>
10
...
11
</relevant_experience>
12

13
<temporal_facts as_of="2026-07-15">
14
...
15
</temporal_facts>

而不是：

1
Here are some memories:
2
- ...
3
- ...
4
- ...

Memory Context 需要 Semantic Segmentation。

Conflict Set 应作为一个整体进入 Builder#

如果两条 Memory 互相冲突，分别排序会把它们当成独立候选。更合理的是先形成 Conflict Set：

1
subject=user_42
2
predicate=works_at
3

4
M8: Acme, valid=[2024-01, 2025-03), source=user
5
M9: Beta, valid=[2025-03, +∞), source=user
6
M10: Acme, valid=unknown, source=old_web_page

对“现在在哪工作”只注入 M9，并保留“由 M8 演化而来”的 provenance；对“2024 年在哪工作”选择 M8；对“历史变化”同时注入 M8/M9，但标注有效区间。M10 不是简单按相似度竞争，而应因来源旧、时间未知被降权或隔离。

最终 Prompt 中每段 Memory 都应带稳定 ID、版本、来源类型、有效期和 trust label。模型答案再回传 used_memory_ids，才能计算真正的 Memory Attribution，而不是把所有已注入内容都算作“使用过”。

从并行检索、候选融合、重排、冲突集、权限过滤到 Token Packing 的 Memory 诊断漏斗

图 7：这是本文综合六个系统得到的生产检索路径，不对应某一个框架。Candidate Miss、Ranking Miss 与 Packing Miss 必须分别记录，否则“正确 Memory 没进入答案”只能得到一个无法行动的总失败率。

12.8 Memory Consolidator#

它对应：

1
Codex Phase 2
2
Hermes agent-driven consolidation
3
Letta rethink_memory

输入：

1
Existing Memory
2
+
3
New Candidates
4
+
5
Usage Statistics
6
+
7
Task Outcomes

输出：

1
Merge
2
Rewrite
3
Promote
4
Demote
5
Invalidate
6
Delete

建议决策 Schema：

1
class ConsolidationDecision(BaseModel):
2
    action: Literal[
3
        "keep",
4
        "merge",
5
        "rewrite",
6
        "promote",
7
        "demote",
8
        "invalidate",
9
        "delete",
10
    ]
11

12
    source_memory_ids: list[str]
13
    target_memory: MemoryCandidate | None = None
14
    reason: str

Consolidation 应拥有 Change Log：

1
M12 + M18 + M33
2
↓
3
MERGE
4
↓
5
M57
6

7
Reason:
8
three entries describe same Gradle test workflow

否则 Memory Debugging 会非常痛苦。

12.9 Memory Governance#

至少需要：

1
Namespace Isolation
2
Access Control
3
Encryption
4
PII Detection
5
Secret Redaction
6
Prompt Injection Scan
7
Retention
8
Expiration
9
Audit
10
User Delete
11
Data Export
12
Versioning

Memory 比普通日志更危险。

因为：

1
日志
2
→ 通常供人或系统查看
3

4
Memory
5
→ 会主动重新进入模型 Context
6
→ 改变未来行为

因此被污染的 Memory 具有：

1
Behavioral Persistence

这就是 Memory Poisoning 比普通脏数据更危险的原因。

Governance 是 Policy Decision Point，不是后台清理脚本#

每次 Write、Read、Export、Consolidate、Delete 都应经过相同的 Policy Decision Point：

1
principal + purpose + namespace + action + sensitivity + source_trust
2
                               ↓
3
                       allow / deny / review

用户删除流程需要生成 deletion job，而不是同步返回后即宣称完成：

1
REQUESTED → CANONICAL_TOMBSTONED → PROJECTIONS_PURGED
2
          → CACHES_PURGED → BACKUP_POLICY_RECORDED → VERIFIED

每一步记录证据和截止时间；读路径从 CANONICAL_TOMBSTONED 开始就必须 deny。对于由多条源记忆生成的 summary/skill，还需要 provenance DAG：删除一个源时，系统才能判断派生物应完全删除、重新生成还是仅移除对应陈述。

13. Agent Memory 真正困难的十个工程问题#

13.1 Write Problem：到底什么值得记#

Memory 最难的问题可能不是 Search，而是 Write Precision。

写太多：

1
Memory Pollution

写太少：

1
Memory Recall Ceiling

因为没写入的信息永远检索不到。

所以：

Memory System 的质量上限经常从 Write Path 开始决定。

13.2 Retrieval Problem：相关不等于有用#

Query：

1
如何修复支付模块测试？

Memory A：

1
支付模块去年重构。

语义相关。

Memory B：

1
支付模块集成测试必须先启动 Docker Compose。

真正有用。

所以 Ranking 不能只有 Semantic Relevance。

还应该考虑：

1
Task Utility
2
Procedural Applicability
3
Freshness
4
Confidence

13.3 Context Problem：召回多少才够#

TopK 太小：

1
Missing Evidence

TopK 太大：

1
Context Pollution

最终目标不是 Retrieval Recall 最大，而是：

在有限 Context Budget 内最大化 Downstream Task Utility。

13.4 Conflict Problem：新旧记忆冲突#

冲突类型：

1
Preference Change
2
dark → light
3

4
World State Change
5
works_at A → works_at B
6

7
Correction
8
Agent guessed X → User says wrong
9

10
Source Disagreement
11
Tool A says X → Tool B says Y

不同冲突需要：

1
Replace
2
Invalidate
3
Keep both with provenance
4
Lower confidence
5
Request verification

不能统一使用：

1
newest wins

13.5 Temporal Problem：哪个事实现在有效#

Temporal Memory 要回答：

1
What was true?
2
When?
3
Until when?
4
What is true now?
5
When did system learn it?

至少考虑：

1
Event Time
2
Ingestion Time
3
Validity Interval
4
System Expiration

一旦 Agent 面向真实业务状态，时间语义会迅速成为核心问题。

13.6 Consolidation Problem：100 条经验如何变成 5 条规律#

Agent 有：

1
30 次 Gradle 错误经验
2
20 次 Docker 测试经验
3
10 次 Migration 经验

直接存 60 条，Memory 不断膨胀。

理想结果：

1
Project Build Procedure
2
Integration Test Procedure
3
Migration Troubleshooting Procedure

即：

1
Episodes
2
↓
3
Pattern Discovery
4
↓
5
Procedure

真正强的 Memory 系统最终需要 Experience Distillation。

13.7 Forgetting Problem：Agent 必须学会遗忘#

应该遗忘：

1
Expired Temporary State
2
Low-value Noise
3
Superseded Preference
4
Duplicated Experience
5
Incorrect Memory
6
Security-sensitive Data

不会遗忘：

1
Memory Volume ↑
2
Context Noise ↑
3
Conflict ↑
4
Retrieval Cost ↑

所以：

Forgetting is a feature.

13.8 Poisoning Problem：攻击可以跨 Session 持久化#

1
Malicious Tool Result
2
↓
3
Memory Extractor
4
↓
5
Persistent Memory
6
↓
7
Future Session
8
↓
9
System Context Injection

攻击从 Single-turn Injection 升级为 Persistent Behavioral Injection。

防御需要：

1
Trust Boundary
2
Source Classification
3
Content Scan
4
Instruction-like Text Detection
5
Write Policy
6
Sanitized Injection
7
Human Audit

Hermes 的 Sanitized Snapshot 是很好的工程参考。

OWASP 已把 Memory Poisoning 明确为 Agentic Application 风险：持久 Memory 可被直接/间接 Prompt Injection、身份混淆和跨 Session 复用污染，其影响不在当前回答结束，而会持续改变未来行为。[S11]

完整威胁模型至少覆盖：

攻击面	示例	主要控制
Direct write	用户要求“以后忽略审批”	写策略、protected predicates、人工确认
Indirect write	网页/邮件把恶意指令伪装成事实	source trust、指令检测、隔离区
Scope escalation	项目事实被写成组织级规则	namespace authorization、scope ceiling
Cross-tenant collision	相同 entity name 合并两个租户	tenant-bound entity key、硬过滤
Consolidation poisoning	多条低可信 Episode 被总结成高可信规则	trust 不得因 merge 自动提升
Retrieval injection	Memory 内容命令模型调用危险工具	data/instruction 隔离、工具授权不继承
Deletion evasion	原始记录删了，summary/embedding 仍存在	lineage DAG、tombstone、purge verification

一个关键不变量是：

1
derived_trust <= max(source_trusts)

更保守的系统甚至采用最小来源信任级别。Consolidator 可以提高表达质量和复用度，但不能凭一次 LLM 总结把不可信网页内容“洗白”为系统规则。

防御应分四道门：

1
Capture: classify source + preserve raw evidence
2
Write: policy + schema + protected fields + quarantine
3
Read: authorization + freshness + sanitized serialization
4
Use: tool permissions and approvals remain independent of memory

最后一道尤其重要：即使 Memory 写着“允许部署生产”，执行工具仍必须根据当前 principal 和环境重新授权。Memory 只能提供上下文，不能签发 Capability。

运行层面还需要不可变 mutation log、周期快照、内容 hash、异常写入速率告警和一键 rollback。Hash 只能发现变化，不能判断变化是否恶意；因此它必须与来源、策略和行为 Eval 组合，而不是单独充当“防投毒”。

Agent Memory 写入投毒防线、顺序删除的部分失败窗口与可验证删除状态机

图 8：A 区依据 OWASP Agent Memory Guard [S11] 的检测与策略路径绘制；B 区对应 Mem0 [S7] 的顺序 best-effort 删除；C 区是本文提出的生产化补强。只有 Projection ACK、Reconciliation 与 DELETED_VERIFIED 完成后，才能证明派生索引和缓存不再可读。

13.9 Privacy Problem：能记不等于应该记#

个人 Agent 很容易接触：

1
Health
2
Financial
3
Credentials
4
Private Relationship
5
Precise Location
6
Internal Secrets

原则：

1
Can remember
2
≠
3
Should remember

Memory Write Policy 需要：

1
Data Minimization
2
Purpose Limitation
3
Retention
4
Deletion
5
User Control

Privacy 的难点是派生数据，而不只是原文#

一条敏感事实可能同时存在于：

1
Raw Event
2
Extracted Fact
3
Embedding
4
Entity / Edge
5
Rollout Summary
6
Consolidated Profile
7
Prompt Cache
8
Evaluation Trace
9
Backup

因此每个 Memory Record 需要 data_subject_ids、purpose、legal_basis/consent_ref、retention_class、source_event_ids 和 derived_from。没有 lineage，系统无法回答“删除 Alice 的资料会影响哪些 summary 和 graph edge”。

推荐把敏感字段分成三层：

1
Restricted raw value
2
  → encrypted field / tokenized reference
3

4
Prompt-safe projection
5
  → only the minimum fact needed for the task
6

7
Search feature
8
  → non-reversible or separately protected representation

Embedding 不是天然匿名化。它仍可能泄漏语义、被成员推断，且无法像结构化字段那样精确局部删除。对高敏内容，优先存受控引用或最小化 projection；删除时执行 canonical tombstone、索引 purge、缓存失效与密钥销毁，并对备份记录可验证的到期策略。

NIST AI RMF Generative AI Profile 强调全生命周期风险管理、数据治理、隐私、安全与可测量性。[S12] 对 Memory 系统而言，落地形式不是一段隐私声明，而是可查询的数据地图、保留规则、访问日志、删除 SLA 与定期恢复演练。

13.10 Evaluation Problem：怎么证明 Memory 真有用#

不要单独用：

1
Memory Count
2
Memory Hit Rate

评价系统。

最关键的是：

1
Downstream Task Improvement

推荐指标：

层级	指标
Write	Memory Write Precision
Write	Memory Write Recall
Write	Duplicate Write Rate
Write	Sensitive Memory Write Rate
Retrieval	Recall@K
Retrieval	Context Precision
Retrieval	Relevant Memory MRR
Conflict	Conflict Resolution Accuracy
Temporal	Temporal Accuracy
Freshness	Stale Memory Rate
Security	Memory Poisoning Success Rate
Context	Avg Memory Context Tokens
System	Memory Add Latency
System	Recall Latency
E2E	Task Success Rate
E2E	Repeated Task Improvement
E2E	Token Saving vs Full Context

评测必须拆开 Write、Retrieve、Read 与 E2E#

只看最终回答无法定位失败。推荐建立四层数据集：

1
Layer 1 - Write Set
2
  events → should_write / should_not_write / canonical target / scope
3

4
Layer 2 - Retrieval Set
5
  query + as_of_time → required memory IDs + forbidden stale IDs
6

7
Layer 3 - Context Set
8
  candidate pool + budget → expected evidence set / conflict handling
9

10
Layer 4 - Agent Task Set
11
  history + task → success, cost, latency, tool errors, human intervention

Layer 1 衡量抽取与写策略，Layer 2 衡量索引和排名，Layer 3 衡量 Context Builder，Layer 4 才衡量系统是否获得能力。每层都保存中间 artifact，才能把 E2E 失败归因到 not written、not retrieved、not packed 或 retrieved but ignored。

LongMemEval 将长期对话记忆拆成信息抽取、多 Session 推理、时序推理、知识更新和 abstention；2026 年的 LongMemEval-V2 又把 Web Agent 经验扩展为静态状态、动态状态、workflow、environment gotchas 与 premise awareness，并使用最长 500 条 trajectory、约 1.15 亿 Token 的历史。[S10] 这说明“能回答用户生日”不足以代表 Agent Experience Memory；还要评测操作流程、环境规律、失败条件和前提变化。

基线、消融与时间切分#

至少比较：

1
No Memory
2
Recent Window Only
3
Full History（可放入时）
4
BM25 Only
5
Dense Only
6
Hybrid Retrieval
7
Hybrid + Reranker
8
Full Memory System
9
Oracle Evidence

Oracle Evidence 给出该任务所需的正确 Memory，用来估计 Reader/Agent 上限；如果 Oracle 也失败，继续调 Retriever 没有意义。消融应逐项关闭 entity linking、temporal filter、consolidation、freshness、conflict resolution，测量每个模块的增益和成本。

数据集必须按时间切分：先让系统消费过去的 Run，再评测未来任务。随机把同一用户或同一仓库的近重复记录分到训练/测试，会产生严重泄漏。涉及 LLM Judge 时还要固定 Judge 版本、盲化系统名称、抽样人工复核，并报告多次运行的均值与置信区间。

在线实验要同时看收益与伤害#

Memory A/B 的 Guardrail 至少包括：

1
Task success / repeated-task improvement
2
P50/P95 first-action and total latency
3
Input tokens and retrieval cost
4
Wrong personalization / stale assertion rate
5
Sensitive write rate
6
Poisoning attack success rate
7
User correction and memory deletion rate

平均成功率上涨可能掩盖少量高影响错误。例如个人偏好召回提升 3%，但跨租户泄漏一次，系统仍不可上线。安全、隐私和越权指标应是 release gate，而不是与准确率加权后被抵消的普通分数。

Memory Write Precision

1
写入的 Memory 中
2
真正值得长期保留的比例

Memory Write Recall

1
应该被保留的信息中
2
实际写入多少

Context Precision

1
进入当前 Prompt 的 Memory 中
2
真正帮助当前任务的比例

Stale Memory Rate

1
被召回但已经失效的 Memory 比例

Repeated Task Improvement

这是最关键的 Agent 指标之一：

1
第一次执行任务
2
vs
3
拥有历史经验后再次执行类似任务

比较：

1
Task Success
2
Tool Calls
3
Retries
4
Latency
5
Token Cost
6
Human Intervention

如果 Memory 存了很多，但第二次任务没有更快、更准、少犯错，那么 Memory 没有产生能力价值。

14. 不同 Agent 场景如何选择 Memory 架构#

14.1 Coding Agent#

推荐：

1
File Memory
2
+
3
Procedural Experience
4
+
5
Background Consolidation

参考：

1
Claude Code
2
Codex
3
Hermes

架构：

1
Core:
2
project conventions
3
build commands
4

5
Topic Files:
6
debugging
7
architecture
8
tool quirks
9

10
Background:
11
task rollout extraction
12

13
Procedural:
14
verified workflows

14.2 Personal Assistant#

推荐：

1
User Profile
2
+
3
Semantic Memory
4
+
5
Temporal Facts

可组合：

1
Mem0-like pipeline
2
+
3
Graphiti-like temporal layer

原因是 Preference、Goal、Relationship、Location、Job 等都会变化。

不能只做 Vector TopK。

14.3 CRM / Customer Intelligence Agent#

推荐：

1
Temporal Graph

核心对象：

1
Customer
2
Company
3
Contact
4
Opportunity
5
Contract
6
Ticket
7
Product

关系：

1
works_at
2
owns
3
interested_in
4
negotiating
5
signed
6
cancelled
7
escalated

这些关系具有明显时间变化。

14.4 Long-running Autonomous Agent#

推荐：

1
Letta-like Hierarchy
2
+
3
Compaction
4
+
5
Procedural Memory

需要：

1
Hot Blocks
2
Cold Archive
3
Compacted History
4
External Knowledge

14.5 Customer Support Agent#

推荐：

1
Mem0-like User Memory Pipeline
2
+
3
Business State from Source of Truth
4
+
5
Optional Temporal Graph

特别强调：

订单状态、退款状态等业务事实不能只依赖 Agent Memory。

应该：

1
Authoritative Business Data
2
→ Tool / DB
3

4
Memory
5
→ User preference / interaction history / reusable context

即：

1
Source of Truth
2
≠
3
Memory

这与 Codex 的：

1
Policy
2
≠
3
Memory

是同一个工程思想。

14.6 Research Agent#

推荐：

1
File Memory
2
+
3
Episodic Memory
4
+
5
Provenance

需要记录：

1
Search Path
2
Sources Read
3
Hypotheses
4
Rejected Hypotheses
5
Interim Findings
6
Citation Evidence

不能只存最终 Summary。

14.7 Self-Evolving Agent#

推荐：

1
Experience Memory
2
↓
3
Outcome Evaluation
4
↓
5
Pattern Mining
6
↓
7
Procedural Memory
8
↓
9
Skill Lifecycle

可以借鉴：

1
Codex Phase 1/2
2
Hermes Learning Loop
3
Letta Agent-controlled Memory

关键原则：

失败轨迹不能直接变成 Procedure。

必须：

1
Experience
2
↓
3
Outcome / Verifier
4
↓
5
High-quality Experience
6
↓
7
Consolidation
8
↓
9
Procedure

否则 Agent 会把错误经验固化。

14.8 Multi-Agent System#

建议分：

1
Private Memory
2
Shared Memory
3
Role Memory
4
Task Memory

例如：

1
Coordinator
2
Private:
3
routing experience
4

5
Policy Agent
6
Private:
7
policy interpretation procedure
8

9
Shared:
10
case state
11
verified evidence
12
human decisions

Shared Memory 必须拥有：

1
Ownership
2
Schema
3
Write Permission
4
Conflict Policy

不能让所有 Agent 对同一个 Vector DB 随意 add()。

Part V：结论、工程速查与延伸阅读#

15. 结论：Memory 正从 Storage 走向 Cognitive Infrastructure#

回看六个系统：

1
Codex
2
→ Experience Extraction + Global Consolidation
3

4
Claude Code
5
→ Filesystem Memory + Progressive Disclosure
6

7
Hermes
8
→ Bounded Agent-controlled Curated Memory
9

10
Mem0
11
→ Production Memory Pipeline
12

13
Letta
14
→ Agent-controlled Context Hierarchy
15

16
Graphiti
17
→ Temporal World Model

它们共同指向一个趋势：

1
Memory
2
不再只是
3
“把过去存起来”
4

5
而是
6
“管理过去如何影响未来决策”

Agent Memory 的演进可以表示为：

1
Chat History
2
↓
3
Conversation Summary
4
↓
5
Vector Memory
6
↓
7
Memory Extraction Pipeline
8
↓
9
Hierarchical Memory
10
↓
11
Agent-controlled Memory
12
↓
13
Temporal Memory
14
↓
15
Experience Consolidation
16
↓
17
Procedural Memory
18
↓
19
Cognitive Infrastructure

未来真正优秀的 Memory System，需要同时回答五个问题。

What to Remember

1
什么值得记？

Where to Place It

1
Hot Context、File、Archive 还是 Temporal Graph？

When to Recall

1
什么时候主动 Push，什么时候让 Agent Pull？

How to Evolve

1
新事实如何更新、旧事实如何失效、经验如何巩固？

When to Forget

1
什么时候必须删除、过期或降级？

所以，Memory 的终点不是：

1
无限存储

而是：

把有限 Context 变成一个可持续更新的认知工作集。

真正强的 Agent，也不是“记得所有事情”。

而是：

知道什么值得记住，什么时候应该回忆，什么时候应该修正过去，什么时候应该遗忘，以及如何把一次执行转化成下一次任务的能力。

把全文进一步压缩成一个工程判断：

1
Memory Engineering
2
= Data Pipeline
3
+ Context Engineering
4
+ State Management
5
+ Information Retrieval
6
+ Temporal Modeling
7
+ Security
8
+ Agent Policy
9
+ Evaluation

当 Agent 从一次性 Demo 进入长期运行系统，Memory 就不再是“可选增强”或 Storage Engineering 的附属功能，而是：

Agent Cognitive Infrastructure。

附录 A：六个系统的统一 Memory Lifecycle 映射#

System	Capture	Extract	Evaluate	Write	Retrieve	Consolidate	Forget/Invalidate
Codex	Rollout	Phase 1 Agent	Eligibility	Background Job	Local Recall	Phase 2 Agent	Retention / prune
Claude Code	Session learning	Claude	Agent判断	Markdown	Index + file tools	File organization	Edit/delete
Hermes	Session observation	Agent	Agent + capacity	Memory Tool	Frozen Snapshot	Replace / Batch	Remove
Mem0	Messages	LLM	Extraction Pipeline	ADD-only Batch Store	Hybrid Search	无写时合并，读时排序	Expiration / explicit delete
Letta	Agent interaction	Agent	Agent	Block/Archive Tool	In-context + search	rethink_memory	Rewrite/delete
Graphiti	Episode	Node/Edge extraction	Resolution	Temporal Graph	Hybrid Graph Search	Saga summary	Fact invalidation

附录 B：工程选型速查表#

核心问题	优先研究
历史任务如何形成未来经验	Codex
Coding Agent 项目上下文如何组织	Claude Code
Agent 如何自己管理有限 Memory	Hermes
如何快速搭生产 Memory Pipeline	Mem0
Long-running Agent 如何管理多层 Context	Letta
动态事实、关系、时间状态怎么管理	Graphiti
需要长期事实 + 用户偏好	Mem0
需要当前状态与历史状态并存	Graphiti
需要 Always-on 核心记忆	Letta / Hermes
需要透明可审计的本地 Memory	Claude Code / Hermes
需要任务经验后台沉淀	Codex
需要 Experience → Procedure	Codex + Hermes + Letta 思想组合

附录 C：建议的源码阅读路线#

Codex#

1
codex-rs/memories/write/src/phase1.rs
2
↓
3
codex-rs/memories/write/templates/memories/stage_one_system.md
4
↓
5
codex-rs/memories/write/src/phase2.rs
6
↓
7
codex-rs/memories/write/templates/memories/consolidation.md
8
↓
9
codex-rs/state/src/runtime/memories.rs

阅读问题：

1
1. Rollout Eligibility 怎么判断？
2
2. 为什么需要 Lease？
3
3. Phase 1 为什么可以并行？
4
4. Raw Memory 与 Rollout Summary 分工是什么？
5
5. Phase 2 为什么全局串行？
6
6. Watermark 如何推进？
7
7. Git Workspace Diff 为什么适合 Memory Consolidation？
8
8. Consolidation Agent 权限如何限制？

Hermes#

1
tools/memory_tool.py
2
↓
3
tools/threat_patterns.py
4
↓
5
Prompt Assembly
6
↓
7
Skills / Curator

阅读问题：

1
1. Frozen Snapshot 和 Live State 如何分离？
2
2. 为什么 Sanitization 不直接删除磁盘原始内容？
3
3. Add 为什么可以弱化 Drift Guard？
4
4. Replace/Remove 为什么需要 Round-trip Check？
5
5. File Lock 如何保证并发安全？
6
6. Capacity Failure 如何反馈给 Agent？
7
7. 为什么限制每 Turn Consolidation Retry？
8
8. apply_batch 如何实现最终状态事务？

Mem0#

1
mem0/memory/main.py
2
↓
3
configs/prompts
4
↓
5
memory/storage
6
↓
7
utils/entity_extraction
8
↓
9
utils/scoring
10
↓
11
vector_stores

阅读问题：

1
1. infer=True/False 两条 Write Path 有什么区别？
2
2. Session Scope 为什么是必需约束？
3
3. Existing Memory 为什么在 ADD-only Extraction 前检索？
4
4. UUID → Integer 映射为什么必须沿 Payload 持久化路径验证？
5
5. LLM Failure 和 Empty Extraction 如何区分？
6
6. Batch Embed/Insert 如何降级？
7
7. Hash、BM25、Entity 各解决什么问题？
8
8. Candidate Pool 为什么 Over-fetch？

Letta#

1
letta/functions/function_sets/base.py
2
↓
3
letta/services/tool_executor/core_tool_executor.py
4
↓
5
letta/schemas/memory.py
6
↓
7
Agent State
8
↓
9
Prompt Assembly / Compaction

阅读问题：

1
1. Memory Block 为什么常驻 Context？
2
2. memory tool 如何进入 Tool Executor？
3
3. rethink_memory 与普通 replace 有什么区别？
4
4. Conversation Search 和 Archival Search 的数据语义有何不同？
5
5. Memory Hierarchy 如何影响 Context Cost？
6
6. Agent 何时应该主动移动信息层级？

Graphiti#

1
graphiti_core/graphiti.py
2
↓
3
utils/maintenance/node_operations.py
4
↓
5
utils/maintenance/edge_operations.py
6
↓
7
edges.py / nodes.py
8
↓
9
search/search.py
10
↓
11
search/search_config_recipes.py

阅读问题：

1
1. Episode、Entity、Fact 的边界是什么？
2
2. created_at 与 valid_at 为什么必须分离？
3
3. Entity Resolution 如何避免碎片？
4
4. Duplicate Candidate 与 Invalidation Candidate 为什么分开？
5
5. Temporal Contradiction 如何判断？
6
6. invalid_at 与 expired_at 的语义区别？
7
7. Saga 为什么需要双 Watermark？
8
8. BM25、Vector、BFS 如何并行融合？

参考资料与源码#

以下资料均在 2026-07-15 联网核对。源码链接固定到本文开头记录的 Commit，避免 main 分支后续变化导致分析无法复现。

官方产品文档#

[S1] OpenAI Codex Memories#

Memories
核对内容：本地 Codex Memory 与 ChatGPT Memory 的边界、后台生成、idle eligibility、secret redaction、~/.codex/memories/、任务级控制、Memory 与 AGENTS.md 的职责边界。

[S2] OpenAI Cookbook：Building Reliable Agents with Memory and Compaction#

Building Reliable Agents with Memory and Compaction
核对内容：Compaction 服务当前长 Run 的连续执行；Memory 服务未来 Run 对历史 Workflow Lessons 的复用。

[S3] Anthropic Claude Code Memory#

How Claude remembers your project
核对内容：CLAUDE.md、Auto Memory、MEMORY.md、Topic Files、On-demand File Read、层级发现与导入规则。

[S4] Nous Research Hermes Agent Persistent Memory#

Persistent Memory
核对内容：bounded curated memory、MEMORY.md、USER.md、2,200 / 1,375 字符预算、Frozen Snapshot、add/replace/remove 与容量满时的显式错误。

固定版本源码#

[S5] OpenAI Codex Source#

Repository：openai/codex，Commit 8604689ec5e3437eb79802d8d72249b7722fbf5b。
Write Path：phase1.rs、phase2.rs、runtime/memories.rs。
Read Path：read_path.md、backend.rs、local.rs、search.rs、citations.rs。

[S6] Hermes Agent Source#

Repository：NousResearch/hermes-agent，Commit 77d5b2d573f82fc514fbef02f0b6303c44149805。
Key file：tools/memory_tool.py。

框架、论文与官方实现说明#

[S7] Mem0#

论文：Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory，Prateek Chhikara et al., 2025。
官方资料：Memory Evaluation、Migrating to the New Memory Algorithm、迁移文档 Markdown 原文。迁移文档明确区分旧算法的 ADD / UPDATE / DELETE 与 V3 的 Single-pass ADD-only。
Repository：mem0ai/mem0，Commit ccbe5861a138c7583e01bb3a3aa6168e52526a23。
Key paths：V3 _add_to_vector_store、显式 Update/Delete、ADDITIVE_EXTRACTION_PROMPT、storage.py。旧 DEFAULT_UPDATE_MEMORY_PROMPT 仍在同一文件中，但固定版本 V3 主路径没有调用它。

[S8] Letta / MemGPT#

论文：MemGPT: Towards LLMs as Operating Systems，Charles Packer et al., 2023。
官方资料：Context hierarchy。
Repository：letta-ai/letta，Commit b76da9092518cbaa2d09042e52fdcbde69243e18。
Key files：base.py、block.py、memory.py、block_manager.py。

[S9] Zep / Graphiti#

论文：Zep: A Temporal Knowledge Graph Architecture for Agent Memory，Preston Rasmussen et al., 2025。
官方资料：Adding Episodes。
Repository：getzep/graphiti，Commit 526dcad7a300f3c5c506ff96a68bcdc7ca9f97ed。
Key files：graphiti.py、edge_operations.py、search_config.py、search_utils.py、search_filters.py。

评测、安全与交叉验证#

[S10] LongMemEval#

[S11] OWASP Agent Memory Security#

OWASP Agent Memory Guard。
AI Agent Security Cheat Sheet。
核对内容：Memory Poisoning、持久化 Prompt Injection、完整性基线、策略校验、快照、审计与回滚。

[S12] NIST AI RMF Generative AI Profile#

Artificial Intelligence Risk Management Framework: Generative Artificial Intelligence Profile，NIST AI 600-1，DOI 10.6028/NIST.AI.600-1。

[S13] LangGraph Memory#

Memory overview。
Add and manage memory。
Persistence。
核对内容：thread-scoped state/checkpointer、cross-thread namespace/store、semantic/episodic/procedural memory、Profile vs Collection、hot-path vs background write。

Agent 记忆系统架构总览：Codex、Claude Code、Hermes、Mem0、Letta 与 Graphiti

0. 阅读说明与研究边界#

0.1 引用方法与事实边界#

0.2 源码版本与复现基线#

Part I：问题模型与统一生命周期#

1. Agent Memory 真正解决什么问题#

1.1 Context Window 不等于 Memory#

1.2 从 Stateless LLM 到 Stateful Agent#

1.3 为什么 Full History 是糟糕的默认方案#

Context Pollution#

Historical Conflict#

History 不是 Knowledge#

1.4 Memory 和 RAG 的根本区别#

2. 用统一生命周期理解 Agent Memory#

2.1 Capture：捕获什么事件#

Capture 不是“把聊天存下来”，而是建立可重放的事实日志#

2.2 Extract：从事件中抽取什么#

Candidate 不是 Canonical Fact#

2.3 Evaluate：不是所有信息都值得记#

2.4 Write：Memory Control Plane 在哪里#

Write Path 需要显式状态机#

2.5 Organize：Memory 不只是 Text Chunk#

Canonical Record 与派生索引必须分层#

2.6 Retrieve：召回不是只有 Vector TopK#

2.7 Inject：检索到不等于全部塞进 Prompt#

Context Packing 是有约束的组合优化#

2.8 Maintenance：Memory 必须会变化#

2.9 统一分析维度#

Part II：产品级 Agent 的记忆实践#

3. Codex：后台记忆抽取与任务经验沉淀#

3.1 Coding Agent 的 Memory Workload#

3.2 官方公开的 Memory 边界#

3.3 两阶段后台流水线#

3.4 Phase 1：Rollout Extraction#

3.5 Eligibility：Memory Write 之前先决定“这次任务能不能写”#

3.6 为什么 Phase 1 可以并行#

3.7 Structured Output：Memory Extraction 是 Semantic ETL#

3.8 Secret Redaction：Memory Write Path 是 Security Boundary#

3.9 Phase 2：Global Consolidation#

3.10 为什么 Phase 2 需要 Global Lock#

3.11 Git-backed Memory Workspace#

3.12 为什么 Spawn 独立 Consolidation Agent#

3.13 Memory 和 Compaction 必须分开#

3.14 Read Path：Summary → Registry → Evidence / Skill#

3.15 MemoriesBackend：把存储能力与 Agent 工具协议分离#

3.16 Local Backend 的 Path Sandbox#

3.17 Job State Machine：Watermark、租约与“无输出成功”#

3.18 Provenance、Drift 与受控更新#

3.19 Codex 的工程范式#

4. Claude Code：Memory as File 与 Progressive Disclosure#

4.1 为什么先进 Coding Agent 仍大量使用 Markdown#

4.2 CLAUDE.md：Hierarchical Persistent Instruction#

4.3 Auto Memory：MEMORY.md 不是“大型记忆数据库”#

4.4 这其实是一种 Context Cache Hierarchy#

4.5 Recall Path：Agentic Retrieval#

4.6 如何严谨地“还原” Claude Code 的 Memory 实现#

4.7 为什么文件系统在 Coding Agent 中可能优于 Vector DB#

项目本身已经是 Filesystem World#

人类可读、可编辑#

天然 Hierarchy#

确定性更强#

Git Friendly#

4.8 File Memory 的边界#

4.9 200 行 / 25 KB：Always-on Memory 必须有预算#

4.10 Claude Code 的范式#

5. Hermes：Agent 自主管理 Memory 与 Learning Loop#

5.1 Hermes 为什么特别值得研究#

5.2 USER.md 与 MEMORY.md：User Model 和 Agent Experience 分离#

5.3 MemoryStore 的双状态模型#

5.4 为什么 Frozen Snapshot 不立即更新 Context#

5.5 Session-level Snapshot Isolation#

5.6 为什么用字符预算而不是 Token 预算#

5.7 Bounded Memory：容量满了故意不自动压缩#

5.8 Capacity Pressure 是一种认知压力#

5.9 Memory Poisoning 防御：Sanitized Snapshot#

5.10 File Lock：Memory 同样有并发一致性问题#

5.11 Drift Detection：防止 Tool 覆盖外部修改#

5.12 为什么 Add 可以弱化 Drift Guard#

5.13 Memory Side Effect 不能阻塞用户主任务#

5.14 apply_batch：Memory Mutation 需要事务语义#

5.14 `apply_batch`：Memory Mutation 需要事务语义#

7.3 `infer=False`：Raw Persistence Path#

7.4 `infer=True`：V3 Phased Batch Pipeline#

7.12 `text_lemmatized`：Memory Retrieval 不应该押注 Vector Only#

8.5 `rethink_memory`：Whole-block Consolidation Primitive#

9.3 `created_at` 与 `valid_at`#

9.4 `invalid_at`：失效不等于删除#

9.5 `add_episode()` 的真实 Write Path#

9.12 `expired_at` 与 `invalid_at` 不应混淆#

`last_summarized_at`#

`last_summarized_episode_valid_at`#