全局证据页

# `repos/` Agent Context / Memory 源码分析总览

## 1. 分析范围

本目录覆盖 `E:\Agents\agent-memory\repos` 下 6 个仓库：

- `claude code`

- `codex`

- `hermes-agent`

- `langmem`

- `letta`

- `mem0`

目标不是复述项目说明，而是基于源码、测试、配置、migration、运行时路径解析逻辑，分析这些项目的：

- `context` 组装方式

- `summary / compaction` 机制

- `history` 与 `session/thread` 持久化

- `short-term memory` 与 `long-term memory`

- `检索路径`

- `state` / 存储后端

- 多 agent / 多线程 / 多 session 关系

## 2. 阅读方法

### 2.1 术语约定

- `context`：某一轮真正送进模型、或即将送进模型的可见上下文。

- `history`：消息历史、turn 历史、命令历史、thread transcript 等历史记录容器。

- `summary / compaction`：为缩短上下文窗口而进行的摘要、裁剪、压缩、窗口重写。

- `short-term memory`：面向当前 session/thread 的近程记忆，例如运行中缓存、当前会话摘要、最近消息窗口。

- `long-term memory`：跨 session/thread 持续存在、可被重新召回的记忆。

- `state`：除消息正文外的持久化运行时状态，例如 SQLite 元数据、线程表、job 表、路径布局、memory root。

### 2.2 证据原则

- 结论只以源码和测试为准。

- 如果某个行为主要由测试揭示，文档中会明确标成“测试验证到的行为”。

- 每份专题文档的每一节末尾都附有 `源码锚点`，用于回到实现位置核对。

## 3. 仓库分类

### 3.1 终端型 / 交互式 Agent Runtime

- [claude code](./claude%20code.md)

- [codex](./codex.md)

- [hermes-agent](./hermes-agent.md)

这三类项目都不是单一 memory 库，而是完整 agent runtime。阅读时要优先区分：

- 模型可见 `context`

- `history` / transcript

- 运行时 `state`

- 可跨会话复用的 memory

### 3.2 Memory / Context 工具库

- [langmem](./langmem.md)

- [mem0](./mem0.md)

这两类项目更像“可嵌入的 memory 能力层”：

- `langmem` 偏 `LangGraph/BaseStore` 场景，关注摘要节点、memory 抽取器、工具封装、命名空间与后台反射。

- `mem0` 偏“抽取式长期记忆”，关注向量库、SQLite 历史、实体链接、混合检索与 procedural memory。

### 3.3 Agent 平台 / 服务器型系统

- [letta](./letta.md)

`letta` 同时包含：

- block/core memory

- 会话与消息 ORM

- archive/passage 长期记忆

- 可选 git-backed memory

因此它既有 runtime，又有平台化持久层。

## 4. 文档树

```text

docs/

├─ 00-总览.md

├─ 01-横向对照.md

├─ claude code.md

├─ claude code/

│ ├─ 01-架构与范围.md

│ ├─ 02-context管理.md

│ ├─ 03-memory实现.md

│ ├─ 04-存储与状态.md

│ └─ 05-调用链、压缩与边界.md

├─ codex.md

├─ codex/

│ ├─ 01-架构与范围.md

│ ├─ 02-context管理.md

│ ├─ 03-memory实现.md

│ ├─ 04-存储与状态.md

│ └─ 05-调用链、压缩与边界.md

├─ hermes-agent.md

├─ hermes-agent/

│ ├─ 01-架构与范围.md

│ ├─ 02-context管理.md

│ ├─ 03-memory实现.md

│ ├─ 04-存储与状态.md

│ └─ 05-调用链、压缩与边界.md

├─ langmem.md

├─ langmem/

│ ├─ 01-架构与范围.md

│ ├─ 02-context管理.md

│ ├─ 03-memory实现.md

│ ├─ 04-存储与状态.md

│ └─ 05-调用链、压缩与边界.md

├─ letta.md

├─ letta/

│ ├─ 01-架构与范围.md

│ ├─ 02-context管理.md

│ ├─ 03-memory实现.md

│ ├─ 04-存储与状态.md

│ └─ 05-调用链、压缩与边界.md

├─ mem0.md

└─ mem0/

├─ 01-架构与范围.md

├─ 02-context管理.md

├─ 03-memory实现.md

├─ 04-存储与状态.md

└─ 05-调用链、压缩与边界.md

```

## 5. 推荐阅读顺序

### 5.1 先看横向共性

先读 [01-横向对照.md](./01-横向对照.md)，建立下面几个问题的统一框架：

- 谁在组装模型可见 context

- 谁在维护历史

- 谁在做 compaction / summary

- 谁在保存 long-term memory

- 谁负责检索和召回

- 数据到底落在哪

### 5.2 再按类型深入

如果想看完整 agent runtime：

1. [claude code](./claude%20code.md)

2. [codex](./codex.md)

3. [hermes-agent](./hermes-agent.md)

如果想看 memory 能力库：

1. [langmem](./langmem.md)

2. [mem0](./mem0.md)

如果想看平台型实现：

1. [letta](./letta.md)

## 6. 快速索引

- `claude code`：`context.ts`、`utils/claudemd.ts`、`memdir/*`、`services/SessionMemory/*`

- `codex`：`codex-rs/core/src/codex.rs`、`context_manager/*`、`memories/*`、`state/*`

- `hermes-agent`：`run_agent.py`、`agent/*`、`plugins/memory/*`、`hermes_state.py`

- `langmem`：`short_term/summarization.py`、`knowledge/extraction.py`、`knowledge/tools.py`、`reflection.py`

- `letta`：`schemas/*`、`prompt_generator.py`、`services/*manager.py`、`context_window_calculator/*`

- `mem0`：`mem0/memory/main.py`、`storage.py`、`utils.py`、`configs/prompts.py`

## 7. 交叉阅读提示

- `claude code` 与 `codex` 都同时存在 `context`、`history`、`compaction` 和单独的 memory 管线，但设计边界不同。

- `hermes-agent` 与 `letta` 都有“多条并行 memory 路径”，前者偏插件 provider，后者偏平台内建模型。

- `langmem` 与 `mem0` 都是 memory 能力层，但 `langmem` 偏工作流节点与 store namespace，`mem0` 偏抽取、去重、检索与存储。

# 6 个仓库的横向对照

## 1. 对照维度

本文统一按以下维度对照：

- `context 组装`

- `压缩 / 摘要`

- `短期历史`

- `长期 memory`

- `检索路径`

- `存储后端`

- `多 agent / 线程关系`

详细证据与源码锚点都下沉在各仓库专题文档中，这里只给结论级对照。

## 2. 总表

| 仓库 | context 组装 | 压缩 / 摘要 | 短期历史 | 长期 memory | 检索路径 | 存储后端 | 多 agent / 线程关系 |

| --- | --- | --- | --- | --- | --- | --- | --- |

| `claude code` | `context.ts` + dynamic system prompt sections + memory files 注入 | `/compact`、`microcompact`、`SessionMemory` 摘要与 compaction | transcript、命令 history、compact boundary 后消息视图 | `memdir` 文件型 memory + `SessionMemory/summary.md` | `/context` 分析视图、memory files 加载、远端 session history | 项目目录 transcript、`~/.claude/projects/.../memory/`、session-memory 目录 | 存在 subagents 目录与远端 session history，但 memory 主要按 session/project 组织 |

| `codex` | `build_initial_context()` + `build_settings_update_items()` + `ContextManager` | auto-compact、remote compact、window generation 重建 | `ContextManager` 历史、`history.jsonl`、thread rollout truncation | `core/memories` phase1/phase2 pipeline + `memory_summary.md` | startup memory jobs、phase2 selection、memory tool 读 summary | SQLite `state_5.sqlite` / `logs_2.sqlite` + `codex_home/memories/` + `history.jsonl` | thread、subagent、spawn edges 都进 state DB，memory 以 thread 为候选单位 |

| `hermes-agent` | `prompt_builder.py` + `run_agent.py` + provider system block | `ContextCompressor` + tool output slimming + summary fallback | `state.db` transcript、gateway JSONL/SQLite 双写 | 内建 `MEMORY.md/USER.md` + 外部 provider 插件 | `session_search`、provider prefetch、provider recall/search | SQLite `state.db`、本地 memory 文件、各 provider 自有后端/配置文件 | session、gateway、provider、subagent 路径并存，但以 session 为主轴 |

| `langmem` | `summarize_messages` / `SummarizationNode` + runtime namespace | 短期摘要节点，把旧消息压成 running summary | 运行中 messages + `RunningSummary` 状态 | `MemoryManager` / `MemoryStoreManager` 写 `BaseStore` | `create_memory_searcher()`、`search_memory` 工具、dilated windows | 注入式 `BaseStore`，namespace 由 runtime config 决定 | 不是完整 agent，更多是 graph/store 级 workflow 组合 |

| `letta` | `PromptGenerator` 用 `Memory.compile()` + metadata 组 system prompt | `Summarizer` 的静态缓冲和部分驱逐摘要 | `MessageManager` + `ConversationManager` + `conversation_messages` 顺序表 | core blocks memory + archive/passage + 可选 git-backed memory | message search、archival memory search、archive/passage 检索 | SQL ORM、可选 TPUF、可选 memfs/git repo + Postgres cache | conversation、group、multi-agent、git-backed memory 路径并存 |

| `mem0` | 抽取 prompt 只拼最近消息窗口 + 已有 memories | 无通用 conversation compaction；procedural memory 走摘要式生成 | SQLite 最近消息窗口、history 表 | 向量库存 memory、本地/远端 embedder、entity store、procedural memory | 语义检索 + keyword + BM25 + entity boost + rerank | 向量库 + SQLite `history/messages` + entity collection | 主要按 `user_id/agent_id/run_id -> session_scope` 组织，不是 thread runtime |

## 3. 按维度看差异

### 3.1 `context` 谁来组装

- `claude code`：更偏“会话级缓存 + 文件注入”，`memdir` 与 `claudemd` 进入 prompt。

- `codex`：更偏“turn 级差分注入”，首次全量、之后增量。

- `hermes-agent`：更偏“prompt builder + provider hook”。

- `langmem`：更偏“工作流节点”，上下文本身就是 graph state。

- `letta`：更偏“Memory.compile() -> PromptGenerator -> ContextWindowCalculator”。

- `mem0`：更偏“为 memory 抽取服务的 prompt 上下文”，不是完整对话 runtime。

### 3.2 `summary / compaction` 谁负责

- `claude code`：压缩同时影响用户上下文缓存、session memory、消息视图。

- `codex`：压缩直接重写历史和 window generation。

- `hermes-agent`：压缩是核心能力，带 tool output 瘦身和 summary fallback。

- `langmem`：摘要就是产品能力本身。

- `letta`：摘要器负责驱逐旧消息时生成 summary message。

- `mem0`：没有统一的对话压缩主线，重点在抽取式记忆生成。

### 3.3 `history` 和 `memory` 是否分离

- 明显分离：`claude code`、`codex`、`hermes-agent`

- 半分离但同平台管理：`letta`

- 以 store 为主、history 不是第一对象：`langmem`

- SQLite history 主要服务抽取，不等于 long-term memory：`mem0`

### 3.4 `long-term memory` 的落点

- 文件目录：`claude code`

- SQLite state + 文件同步：`codex`

- 本地文件 + provider backend：`hermes-agent`

- `BaseStore` namespace：`langmem`

- blocks/archive/git repo：`letta`

- 向量库 + entity store：`mem0`

### 3.5 多 agent / 多线程关系

- `codex` 与 `letta` 的线程/会话/子 agent 关系最结构化。

- `claude code` 与 `hermes-agent` 有多 agent 能力，但 memory 仍主要围绕 session/project。

- `langmem` 和 `mem0` 更像被别的 agent runtime 调用的能力层。

## 4. 阅读建议

- 如果你关心“终端 agent 怎样做 context 差分和压缩”，优先看 `codex` 与 `claude code`。

- 如果你关心“插件式外接 memory provider”，优先看 `hermes-agent`。

- 如果你关心“平台如何统一消息、block memory、archive 与 git-backed memory”，优先看 `letta`。

- 如果你关心“怎么把 memory 能力嵌到自己的 agent/workflow 里”，优先看 `langmem` 与 `mem0`。

## 5. 对照入口

- [claude code](./claude%20code.md)

- [codex](./codex.md)

- [hermes-agent](./hermes-agent.md)

- [langmem](./langmem.md)

- [letta](./letta.md)

- [mem0](./mem0.md)