# Agent 记忆系统对比：天工平台 vs Claude Code

> 最后更新：2026-06-14

---

## 一、天工平台记忆架构

### 1.1 概览

```
┌─────────────────────────────────────────────────────────┐
│                    天工 Agent 记忆栈                      │
├─────────────────────────────────────────────────────────┤
│  三层记忆                                                 │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │  压缩记忆    │  │  向量语义记忆 │  │  自主学习模式   │  │
│  │ (Compaction) │  │ (Vector Mem) │  │ (Learning)     │  │
│  └──────┬──────┘  └──────┬───────┘  └───────┬────────┘  │
│         │                │                   │           │
│   LLM 摘要压缩      BGE-M3 Embedding    LLM 模式提取     │
│   三级策略触发      余弦相似度检索      工具调用学习      │
│         │                │                   │           │
│  ┌──────┴──────┐  ┌─────┴──────┐  ┌───────┴────────┐  │
│  │ persistent  │  │ AgentVector │  │ learning       │  │
│  │ _memory     │  │ Memory 表   │  │ _patterns 表   │  │
│  │ (JSON blob) │  │ (向量+元数据)│  │ (模式+频率)    │  │
│  └─────────────┘  └────────────┘  └────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

### 1.2 三层记忆详解

#### 压缩记忆 (Compaction Memory)

| 级别 | 触发条件 | 机制 | 效果 |
|------|---------|------|------|
| MicroCompact | 窗口 70% | 旧工具结果替换为桩标记 | 回收 30-50% token |
| FullCompact | 窗口 85% | LLM 摘要替换旧对话片段 | 进一步压缩 |
| ReactiveCompact | 窗口 95% | API 报错后被动触发 | 最终兜底 |

- 熔断保护：连续压缩失败 3 次自动停止
- 受保护工具（14 个）：`file_write`, `send_email`, `deploy_push` 等绝不压缩
- 配置：`CompactionConfig` 可单独设定各阈值

#### 向量语义记忆 (Vector Semantic Memory)

- **Embedding 模型**: `BAAI/bge-m3` (1024 维, 8192 token)
- **后端**: SiliconFlow (国内直连)
- **存储**: MySQL `agent_vector_memory` 表
- **检索**: 余弦相似度 + LLM Rerank（可选）
- **类型分类**: user / feedback / project / reference
- **配置**: `vector_memory_enabled`, `vector_memory_top_k`, `vector_memory_rerank`

最近 50 条记忆参与相似度计算，语义检索 top-5 注入 system prompt。

#### 自主学习模式 (Learning Patterns)

- 从工具调用序列中提取使用模式
- 记录调用成功率和参数偏好
- 存储到 `learning_patterns` 表
- 后续类似任务时注入匹配模式

### 1.3 记忆生命周期

```
用户发消息
  │
  ├─→ AgentMemory.initialize(query)
  │     ├─ 加载 persistent_memory (JSON blob: 用户画像+上下文+历史摘要)
  │     ├─ 向量检索 AgentVectorMemory (按 query 语义相似度)
  │     └─ 全局知识库检索 GlobalKnowledge
  │
  ├─→ Agent 执行对话...
  │
  └─→ AgentMemory.save_context()
        ├─ _compress_and_summarize() (LLM 提取 user_profile/key_facts/summary/topics)
        ├─ save_persistent_memory() (写入 MySQL persistent_memory 表)
        ├─ _save_vector_memory() (embedding → agent_vector_memory 表)
        └─ _save_compressed_memories() (摘要向量化写入，P1 新增)
```

### 1.4 记忆配置 (AgentMemoryConfig)

| 配置项 | 默认值 | 说明 |
|--------|------|------|
| max_history_messages | 20 | 注入 LLM 上下文的最大消息数 |
| persist_to_db | true | 会话记忆写入 MySQL |
| vector_memory_enabled | true | 向量语义检索 |
| vector_memory_top_k | 5 | 每次检索返回 top 5 |
| vector_memory_rerank | false | LLM Rerank 精选 |
| memory_type_filter | null | 按类型过滤 (如 `["user","project"]`) |
| learning_enabled | true | 自主学习模式 |
| compaction | null | CompactionConfig 配置 |

---

## 二、Claude Code 记忆架构

### 2.1 概览

```
┌──────────────────────────────────────────────────────────┐
│                  Claude Code 记忆栈                        │
├──────────────────────────────────────────────────────────┤
│  五层文件记忆 + 三个后台进程                                │
│                                                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
│  │CLAUDE.md │  │   Auto   │  │  Team    │  │  Agent   │ │
│  │ 项目指令  │  │  Memory  │  │  Memory  │  │  Memory  │ │
│  └──────────┘  └────┬─────┘  └────┬─────┘  └──────────┘ │
│                      │             │                      │
│               MEMORY.md       memory/team/                │
│               + topic/*.md    push/pull sync              │
│                      │                                   │
│  ┌───────────────────┴──────────────────────────────┐   │
│  │           Session Memory (当前会话笔记)             │   │
│  └──────────────────────────────────────────────────┘   │
│                                                           │
│  后台进程：                                                │
│  ┌────────────────┐  ┌──────────────┐  ┌─────────────┐  │
│  │ Extract        │  │  Auto Dream  │  │ Kairos Daily│  │
│  │ Memories       │  │  夜间整合    │  │  Log Mode   │  │
│  │ (每轮对话后)    │  │ (24h+5会话)  │  │ (append日记) │  │
│  └────────────────┘  └──────────────┘  └─────────────┘  │
└──────────────────────────────────────────────────────────┘
```

### 2.2 五层文件记忆

#### Layer 1: CLAUDE.md 项目指令

- 启动时加载，四层优先级：Managed → User → Project → Local
- 支持 `@include` 指令组合文件
- 支持 glob 条件规则 (`paths:` 在 YAML frontmatter)
- 最大 40,000 字符/文件

#### Layer 2: Auto Memory (自动化持久记忆)

- 存储位置：`~/.claude/projects/<project>/memory/`
- 四类记忆：**user** / **feedback** / **project** / **reference**
- 两步保存：(1) 写 `.md` 文件 (含 frontmatter) → (2) 追加索引到 `MEMORY.md`
- `MEMORY.md` 上限 200 行 / 25KB

#### Layer 3: Team Memory (团队共享)

- `memory/team/` 子目录，独立 `MEMORY.md` 索引
- push/pull 同步机制：watcher 监听文件变化 → debounce → push 到服务器
- 路径遍历防护：symlink 解析、realpath 容器检查

#### Layer 4: Agent Memory (Agent 专属)

- 用户/项目/本地三种 scope
- Agent 创建向导中配置

#### Layer 5: Session Memory (会话笔记)

- 当前对话的运行中笔记
- token 计数阈值 + 工具调用阈值触发更新
- GrowthBook 特性开关控制

### 2.3 三个后台进程

#### Extract Memories（每轮对话后）

- 对话结束后 fork 子 Agent，共享父级 prompt cache（零成本上下文）
- 只读搜索 + 仅可写 memory 目录（沙箱隔离）
- 上限 5 轮防止无限循环

#### Auto Dream（夜间整合）

- 触发条件：(1) ≥ 24h 距上次整合 (2) ≥ 5 次新会话 (3) 获取锁
- 回顾会话 transcript，提炼为 topic 文件 + 更新 MEMORY.md

#### Kairos Daily Log Mode（日记模式）

- 长运行 Assistant 会话：append-only 日期日志
- 夜间 `/dream` 技能提炼日志为结构化记忆

### 2.4 记忆检索：LLM 分类器（非向量搜索）

```
用户提问
  │
  ├─→ 扫描所有记忆文件的 frontmatter (name + description)
  ├─→ 格式化 manifest → 发送给 Sonnet 模型
  ├─→ Sonnet 选最相关 5 个文件
  └─→ 选中文件内容注入上下文

没有 Embedding, 没有向量数据库，纯 LLM 判断 + 文件系统。
```

---

## 三、核心差异对比

### 3.1 架构理念

| 维度 | 天工平台 | Claude Code |
|------|---------|-------------|
| 设计哲学 | 传统 RAG + Agent | 文件系统 + LLM 原生 |
| 记忆存储 | MySQL 数据库 | Markdown 文件 |
| 检索方式 | 向量相似度 + LLM Rerank | LLM 读 frontmatter 选文件 |
| 记忆写入 | 对话中同步，结构化 | 后台子 Agent 异步，自由文本 |
| 分类体系 | 关键词推断 4 类 | 4 类显式标注 |
| 记忆整合 | 无（实时覆盖） | Auto Dream 夜间去重合并 |
| 外部依赖 | Embedding API (SiliconFlow) | **零** |
| 离线可用 | 否 | 是 |

### 3.2 能力矩阵

| 能力 | 天工 | Claude Code | 说明 |
|------|:--:|:--:|------|
| 对话压缩 | ✅ | ✅ | 天工三级策略更细粒度 |
| 向量语义检索 | ✅ | ❌ | 天工专属优势 |
| LLM Rerank 检索 | ✅ | ✅ | 天工可选，Claude Code 必选 |
| 自动记忆提取 | ✅ | ✅ | Claude Code 子 Agent 更智能 |
| 夜间记忆整合 | ✅ | ✅ | 天工 Auto Dream 已实现 |
| 记忆类型分类 | ✅ | ✅ | 均支持 4 类 |
| 后台异步提取 | ✅ | ✅ | 天工已改为 fire-and-forget |
| 团队共享记忆 | ❌ | ✅ | Claude Code 独有 |
| 记忆去重 | ✅ | ❌ | 天工 GlobalKnowledge 去重 |
| 全局知识池 | ✅ | ❌ | 天工独有 |
| 自主学习模式 | ✅ | ❌ | 天工独有 |
| 记忆规模上限 | 百万级 | ~200 条 | 天工向量搜索更具扩展性 |
| 单次检索成本 | 几乎免费 | 1 次 LLM 调用 | 天工更经济 |

### 3.3 优缺点对比

#### 天工平台

| 优点 | 缺点 |
|------|------|
| 向量搜索毫秒级响应，可扩展百万级记忆 | 离线关键词匹配精度弱于语义搜索 |
| LLM Rerank + 向量混合检索，精度高 | — |
| 全局知识池跨 Agent 共享 + 去重 | — |
| 后台异步压缩 + Auto Dream 每日整合 | — |
| 文件式记忆 (MEMORY.md) 离线兜底 | — |
| 自主学习从工具调用中提取模式 | — |
| 三级对话压缩 + 熔断保护 | — |
| 4 类记忆分类 + 关键词自动推断 | — |
| 团队共享记忆 + 跨 Agent 知识池 | — |

#### Claude Code

| 优点 | 缺点 |
|------|------|
| 零外部依赖，完全离线可用 | 检索每次调 LLM，成本高速度慢 |
| 子 Agent 后台提取记忆，不影响主对话 | 记忆上限受 manifest 长度限制 (~200 条) |
| 夜间自动整合去重，记忆质量持续提升 | 无向量搜索，长尾记忆可能漏 |
| 团队共享记忆，多用户协同 | 无全局知识池，跨项目知识难复用 |
| 自由文本格式，记忆表达灵活 | 文件管理无结构化查询能力 |

---

## 四、天工借鉴 Claude Code 已实施改进

| 优先级 | 改进 | 状态 | 说明 |
|--------|------|:--:|------|
| P0 | 记忆分类体系 | ✅ | user/feedback/project/reference 4 类 + 关键词推断 |
| P1 | 压缩摘要向量化 | ✅ | `_save_compressed_memories()`，压缩结果注入向量索引 |
| P2 | LLM Rerank 混合检索 | ✅ | 向量粗筛 top-20 → LLM 精选 top-K，可选开关 |
| P3 | 后台异步记忆提取 | ✅ | `_background_compress_and_save()` fire-and-forget，不阻塞对话 |
| P4 | Auto Dream 每日整合 | ✅ | 凌晨 3:00 触发，合并相似记忆 + 生成每日摘要 |
| P5 | 离线鲁棒性 | ✅ | 关键词分词器 + 离线搜索降级，Embedding API 不可用时自动兜底 |
| P6 | 团队共享记忆 | ✅ | team_id 机制，记忆自动发布到团队池 + 跨 Agent 检索 |
| P7 | 文件式记忆 MEMORY.md | ✅ | 本地 markdown 存储，YAML frontmatter，数据库不可用时可独立运行 |

### 后续可借鉴

- **push/pull 同步**：团队记忆的跨服务器同步（目前本地共享）
- **子 Agent 记忆提取**：fork 独立 Agent 做更深度的记忆分析和关联

---

## 五、相关文件

| 文件 | 说明 |
|------|------|
| `backend/app/agent_runtime/memory.py` | 天工记忆管理核心（~720 行） |
| `backend/app/agent_runtime/schemas.py` | 记忆配置模型 |
| `backend/app/services/embedding_service.py` | Embedding 生成 + 离线关键词兜底 |
| `backend/app/services/auto_dream_service.py` | Auto Dream 每日记忆整合（新增） |
| `backend/app/core/compaction.py` | 三级对话压缩引擎 |
| `D:\cd\claude-code\src\memdir\memdir.ts` | Claude Code 记忆目录管理 |
| `D:\cd\claude-code\src\services\extractMemories\` | Claude Code 后台记忆提取 |
| `D:\cd\claude-code\src\services\autoDream\` | Claude Code 夜间记忆整合 |