---
title: 记忆管道
updated: 2026-04-14
status: active
tags: [module, memory, growth]
---

# 记忆管道 (Memory Pipeline)

> 从 [[index]] 导航。关联模块: [[chat]] [[middleware]]

## 设计思想

**核心问题: LLM 无状态，每次对话都从零开始。需要从历史对话中积累知识。**

设计决策:
1. **闭环架构** — 对话 → 提取 → 索引 → 检索 → 注入，形成正向循环
2. **FTS5 + TF-IDF** — 轻量级语义搜索，不依赖外部 embedding 服务
3. **Token 预算控制** — 注入 system prompt 时有 token 上限，防止溢出
4. **EmbeddingClient trait 已预留** — 接口已写，激活即可升级到向量搜索

## 代码逻辑

### 闭环数据流

```
[提取] 对话发生
  → MemoryExtractor (crates/zclaw-growth/src/extractor.rs)
    → LLM 提取: 偏好 (Preference) / 知识 (Knowledge) / 经验 (Experience)
    → MemoryEntry { agent_id, memory_type, content, keywords, importance }

[索引] 存储
  → SqliteStorage.store() (crates/zclaw-growth/src/storage/sqlite.rs)
    → SQLite + FTS5 全文索引
    → TF-IDF 权重计算
    → (可选) EmbeddingClient.embed() → 向量存储 [未激活]

[检索] 查询时
  → MemoryRetriever.retrieve(query, agent_id) (crates/zclaw-growth/src/retriever.rs)
    → QueryAnalyzer: 意图分类 (Preference/Knowledge/Experience/Code/General)
    → 中文+英文关键词提取 + CJK 支持 + 同义词扩展
    → SemanticScorer: TF-IDF 匹配 (70% embedding / 30% TF-IDF, embedding 未激活)
    → 返回 top-k 相关记忆

[注入] 给 LLM
  → PromptInjector.inject(system_prompt, memories) (crates/zclaw-growth/src/injector.rs)
    → token 预算控制
    → 格式化为结构化上下文块
    → 插入到 system prompt 中
```

### 经验存储 (ExperienceStore)

Hermes 管线 Chunk1 新增:

```
ExperienceStore (crates/zclaw-growth/src/experience_store.rs)
  → CRUD 封装: pain → solution → outcome 结构化经验
  → 底层使用 VikingAdapter
  → URI scheme: agent://{agent_id}/experience/...
```

### Hermes 管线 (4 Chunk)

| Chunk | 模块 | 文件 | 测试 |
|-------|------|------|------|
| 1 | ExperienceStore + Extractor | experience_store.rs | 10 |
| 2 | UserProfileStore + Profiler | user_profile.rs | 14 |
| 3 | NlScheduleParser | nl_schedule.rs | 16 |
| 4 | TrajectoryRecorder + Compressor | middleware/trajectory_recorder.rs | 18 |

Hermes 相关测试分布:
- `nl_schedule.rs`: 16 tests (中文时间→cron 解析)
- `types.rs`: 9 tests (记忆类型)
- `injector.rs`: 9 tests (prompt 注入)

### 查询意图分类

`QueryAnalyzer` 支持 5 种意图:

| 意图 | 说明 | 检索策略 |
|------|------|----------|
| Preference | 用户偏好 | 精确匹配 preference 类型记忆 |
| Knowledge | 知识查询 | 语义搜索 knowledge 类型 |
| Experience | 经验检索 | 时间+相关性排序 |
| Code | 代码相关 | 关键词优先 |
| General | 通用 | 混合策略 |

### Embedding 基础设施 (已写未激活)

```
EmbeddingClient trait (crates/zclaw-growth/src/retrieval/semantic.rs)
  → async embed(&str) -> Vec<f32>
  → is_available() -> bool
  → 当前实现: NoOpEmbeddingClient (始终返回空)

SaaS 侧:
  → pgvector HNSW 索引就绪 (knowledge_chunks 表, vector(1536))
  → generate_embedding Worker: 内容分块 + 中文关键词提取 (Phase 2 embedding deferred)
```

### 前端 Tauri 命令

Memory 相关命令 (13 个，来自 `memory_commands.rs` + `memory/`):
`memory_init, memory_store, memory_get, memory_search, memory_delete, memory_delete_all, memory_stats, memory_export, memory_import, memory_db_path, memory_configure_embedding, memory_is_embedding_configured, memory_build_context`

加上 `memory/extractor.rs` 的 2 个: `extract_session_memories, extract_and_store_memories`
和 `memory/context_builder.rs` 的 1 个: `estimate_content_tokens`

总计 16 个 memory 相关 Tauri 命令。

## 关联模块

- [[chat]] — 对话是记忆的输入源
- [[butler]] — 管家模式可能利用记忆提供个性化响应
- [[middleware]] — Memory 中间件自动提取 + SkillIndex 注入

## 关键文件

| 文件 | 职责 |
|------|------|
| `crates/zclaw-growth/src/extractor.rs` | LLM 记忆提取 |
| `crates/zclaw-growth/src/retriever.rs` | 语义检索 |
| `crates/zclaw-growth/src/injector.rs` | Prompt 注入 (token 预算) |
| `crates/zclaw-growth/src/experience_store.rs` | 经验 CRUD |
| `crates/zclaw-growth/src/storage/sqlite.rs` | FTS5 + TF-IDF 核心 |
| `crates/zclaw-growth/src/retrieval/semantic.rs` | EmbeddingClient trait |
| `crates/zclaw-growth/src/retrieval/query.rs` | 意图分类 + CJK 关键词 |
| `crates/zclaw-growth/src/nl_schedule.rs` | 中文时间→cron 解析 (16 tests) |
| `crates/zclaw-runtime/src/middleware/memory.rs` | 记忆中间件 |
| `crates/zclaw-runtime/src/middleware/trajectory_recorder.rs` | 轨迹记录中间件 |
| `desktop/src/store/memoryGraphStore.ts` | 前端记忆 UI |
| `desktop/src-tauri/src/memory/` | Tauri 记忆命令桥接 |
| `desktop/src-tauri/src/memory_commands.rs` | 13 个 memory CRUD 命令 |