life-echo/docs/plans/memory-capability-gap.md

Memory 能力差距文档

面向回忆录生产的素材检索与事实组织系统 — 当前实现状态与待完成项。

---

一、定位与目标（来自架构计划）

本项目中的 memory 定义为：

• 面向回忆录生产的可检索素材资产
• 可持续抽取、修正、确认的结构化事实层
• 为章节生成和追问生成提供 grounding 的 RAG 基础设施

明确不做：

• 通用「记住这个」的终端用户指令式记忆
• 聊天助手式 persona memory
• 面向终端用户的自然语言 forget that

---

二、当前已就绪部分

2.1 数据模型（features/memory/models.py）

表	状态	说明
memory_sources	✅	原始素材主记录，含 source_type、raw_text、conversation_id、speaker、captured_at
memory_chunks	✅	检索单元，含 content、embedding（pgvector）、content_tsv（FTS）、chunk_index、is_excluded
memory_summaries	✅	会话/滚动/主题摘要，含 source_chunk_ids 追溯
memory_facts	✅	候选/已确认事实，含 fact_type、subject、predicate、source_chunk_id
timeline_events	✅	时间线事件，含 event_year、source_fact_ids
memory_curation_actions	✅	操作轨迹（exclude/restore/correct/confirm/reject）

2.2 接口与依赖

组件	状态	说明
MemoryService 类	✅	门面已定义，ingest_transcript、retrieve 签名就绪
MemoirService.get_evidence()	✅	通过注入 MemoryService 调用 retrieve
MemoirService 注入 MemoryService	✅	deps.py 已配置
EmbeddingProvider port	✅	OpenAI adapter 已实现
get_embedding_provider()	✅	core/dependencies.py 已注册

2.3 骨架文件

文件	状态	说明
chunker.py	骨架	chunk_transcript() 未实现
repo.py	骨架	无具体 CRUD
retriever.py	骨架	HybridRetriever.retrieve() 未实现
extractor.py	骨架	extract_facts() 未实现
summarizer.py	骨架	generate_session_summary、generate_rolling_summary 未实现
timeline.py	骨架	无具体逻辑
curation.py	骨架	无具体逻辑

---

三、待完成能力（按优先级）

3.1 写入路径（Ingest）

目标：对话结束后，将 transcript 沉淀为 memory 资产，并异步补齐 embedding、summary、fact。

步骤	当前状态	待实现
1. MemoryService.ingest_transcript()	raise NotImplementedError	写入 memory_sources、切块写入 memory_chunks、提交主事务
2. 触发异步任务	无	Celery 任务：embedding 生成、summary 生成、fact 提取、timeline 构建
3. chunker.chunk_transcript()	raise NotImplementedError	按 max_tokens/overlap 切分，支持 speaker 边界
4. memory/repo.py	空	create_source()、create_chunks()、update_chunk_embedding() 等
5. memory_tasks.py	无	新增 enrich_memory_source 等 Celery 任务

接入点：conversation/ws/router.py 中 END_CONVERSATION 分支，在 process_conversation_segments 之后调用 MemoryService.ingest_transcript()。需从 segments 聚合 transcript 文本。

3.2 读取路径（Retrieve）

目标：混合检索（metadata + FTS + vector）生成 evidence bundle，供 memoir 章节生成使用。

步骤	当前状态	待实现
1. HybridRetriever.retrieve()	raise NotImplementedError	metadata filter → FTS 查询 → 向量检索 → score fusion
2. MemoryService.retrieve()	返回空 dict	调用 HybridRetriever，按 token budget 组装 evidence bundle
3. memory/repo.py	空	search_chunks_fts()、search_chunks_vector()、get_summaries()、get_facts()
4. memory_chunks.content_tsv	模型有列	需 Alembic 迁移：generated tsvector 列 + GIN index
5. memory_chunks.embedding	模型有列	需异步任务写入，pgvector 索引已由 pgvector 扩展支持

Evidence Bundle 结构（已定义于 memory/schemas.py）：

{
    "relevant_chunks": [...],
    "relevant_summaries": [...],
    "relevant_facts": [...],
    "timeline_hints": [...],
}

3.3 消费端接入

目标：章节生成必须优先使用 evidence bundle（规则 26）。

消费端	当前状态	待实现
process_conversation_segments	未调用 ingest	无（ingest 在 END_CONVERSATION 时由 router 触发）
process_memoir_segments（Celery）	未使用 evidence	在生成章节前调用 MemoryService.retrieve() 或通过 MemoirService 传入
generate_chapter_content（Celery）	未使用 evidence	同上
MemoirGenerator.generate_narrative	仅用 slots + content	增加 evidence 参数，拼入 prompt
get_narrative_prompt	无 evidence 参数	增加 evidence_bundle: dict 参数，格式化后注入 prompt

注意：Celery 任务为同步，需通过 get_sync_db() 获取 session，并调用 MemoryService 的同步版本或封装。当前 MemoryService 为 async，需考虑：

• 方案 A：在 Celery 中 asyncio.run(memory_service.retrieve(...))
• 方案 B：定义 MemoryServiceSync 或 retrieve_sync 供 Celery 使用

3.4 辅助能力（二期可延后）

能力	文件	说明
fact extraction	extractor.py	LLM 抽取结构化事实
session summary	summarizer.py	会话摘要、滚动摘要
timeline build	timeline.py	按 event_year 组织时间线
curation	curation.py	exclude/restore/correct 操作
reranker	ports/reranker.py	可选 cross-encoder 重排

---

四、实现顺序建议

1. Phase 1：写入路径

   • 实现 chunk_transcript()
   • 实现 memory/repo.py 的 create_source、create_chunks
   • 实现 MemoryService.ingest_transcript()
   • 在 END_CONVERSATION 时调用 ingest（需聚合 segments 的 transcript）

2. Phase 2：异步补齐

   • 新增 memory_tasks.py，Celery 任务：embedding 生成、写入 memory_chunks.embedding
   • 可选：summary、fact 提取（可后续迭代）

3. Phase 3：读取路径

   • 实现 repo.search_chunks_fts()、search_chunks_vector()（需 FTS 迁移）
   • 实现 HybridRetriever.retrieve()（metadata + FTS + vector + 融合）
   • 实现 MemoryService.retrieve() 调用 HybridRetriever

4. Phase 4：消费端接入

   • 修改 get_narrative_prompt 增加 evidence 参数
   • 修改 MemoirGenerator.generate_narrative 接收 evidence
   • 修改 process_memoir_segments、generate_chapter_content 在生成前获取 evidence 并传入

---

五、Alembic 迁移待办

迁移	说明
memory_chunks FTS	需 content_tsv 使用 tsvector generated column + GIN index，或应用层维护
若已有 create_all 建表	需 alembic revision --autogenerate 生成与当前 models 一致的迁移，或手写等效 DDL

---

六、依赖规则

• conversation / memoir 不得直接读写 memory 表，只能调用 MemoryService
• agents/ 不得直接读写 memory 表，只能消费 evidence bundle
• memory 不得直接 import adapters，只依赖 EmbeddingProvider port

---

七、预估工作量

阶段	预估	说明
Phase 1 写入路径	1–1.5 天	chunker、repo、ingest、END_CONVERSATION 接入
Phase 2 异步补齐	0.5–1 天	Celery 任务、embedding 写入
Phase 3 读取路径	1–1.5 天	FTS、vector、HybridRetriever、MemoryService.retrieve
Phase 4 消费端接入	1 天	prompt、MemoirGenerator、Celery 任务
合计	约 3.5–5 人天	视测试与联调深度而定