zclaw_openfang/wiki/memory.md

title, updated, status, tags

title	updated	status	tags
记忆管道	2026-04-14	active	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 命令