life-echo/.cursor/plans/memory_compaction_pipeline.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
			false

Memory 整理（Compaction）管线计划（修订版）

目标与约束

• 事件触发 + 防抖、增量范围（非每次全库）、软操作优先（合并/标记 exclude，硬删极少且高置信）、全量大扫除低频。
• 不修改 User 档案字段（出生年、职业等）；仅操作 memory 相关表。

---

必须满足（MVP 硬约束）

约束	说明
幂等	同一批次重复执行，结果不应放大（重复 exclude、重复 curation_action 应被跳过或 no-op）。
用户级互斥	同一用户同一时刻只允许一个 compaction 在跑（见下「用户级短锁」）。
单次上限	扫描 chunk 数、写入 exclude 数、候选对数均有限流与上限。
只做软操作	set_chunk_excluded + MemoryCurationAction；不物理删 memory_sources/memory_chunks（MVP）。
可追踪	每次 exclude 记录原因、对比对象 chunk id、触发上下文（见 context）。

---

1) 调度层：防抖主路径（收紧）

不再把「revoke 旧 Celery task + 重新 apply_async」作为主路径，原因：Celery revoke 对 已 prefetch / 已执行 的任务 强保证不足；多 worker、网络抖动下 task_id 链路易碎。

主路径（推荐）

• Redis 键例如：debounce_until:{user_id} 或 pending:{user_id}（值可为 Unix 秒或 ISO 时间），表示「最早允许执行 compaction 的时间」。
• 每次触发（memoir / recompose / manual / beat）只做：把 debounce 窗口往后推（或 SET + TTL），尽量少发 Celery 任务。
• 任务 memory_compaction_run 设计为 幂等；worker 执行开头校验：
  • 当前时间是否 仍落在 debounce 窗口内（若设计为「到点再跑」，则相反：未到点则短 retry 或 return）；
  • 是否已取得用户级锁（见 §2）；
  • 可选：是否有 更新的 trigger 覆盖了本次 run（例如比较 pending_version / last_trigger_seq）。

增强项（可选）

• revoke + task_id 可作为 补充，不作为依赖正确性的主路径。

分层原则

• 调度层：尽量少发任务。
• 执行层：即使多发、retry、重叠调度，也 安全（幂等 + 锁 + 上限）。

---

2) 用户级短锁（MVP 标配，非可选）

在 memory_compaction_run(user_id) 开头：

• 键：lock:memory_compaction:{user_id}
• TTL：5–15 分钟（可配置，略大于单次任务 P99）。
• 获取失败：直接 skip，结构化日志 lock_contention / skipped_reason=lock_not_acquired。

覆盖场景：process_memoir_segments 与 recompose_chapters_for_story 双触发、worker 重试、beat/手动全量与增量重叠。

---

3) 增量范围（明确规则：以 chunk 为索引）

MVP 定义：增量对象 = 新进入对比池的 chunks，不以 memory_sources.created_at 单独作为主粒度。

原因

• 一个 source 下多 chunk，source 时间粒度太粗；
• source 更新不一定等于 chunk 语义变化。

推荐规则

• 维护 per-user cursor：last_compaction_cursor（Redis 或 DB；MVP 可用 Redis compaction:chunk_cursor:{user_id} 存 max(processed_chunk_updated_at) 或单调序号）。
• 取 **memory_chunks.updated_at（或 created_at）> cursor** 的 chunk 作为 增量 chunk 集合（分页 + 上限）。
• 对比范围：增量 chunk 仅与 同 user、未 excluded 的 历史 chunk 做近重复检测（可再限：同 source 优先、或时间窗内）。

可选收窄：若 context 带 candidate_chunk_ids / candidate_source_ids，与上述集合 求交 或 并集取优（实现时二选一并写死文档）。

---

4) 近重复判定：多层保护（不只全局 embedding 阈值）

配置项 memory_compaction_chunk_similarity_threshold 保留，但 自动 exclude 条件 至少需 多层组合（建议 三项中满足 ≥2 项 才自动 exclude，可配置）：

层	说明
Embedding	同 user_id、余弦相似度 ≥ 阈值
文本规则	归一化（空白/标点）后高 overlap、containment、或长度比例接近
元数据邻近	时间相近；或 source / story / chapter 关联接近（若有）

必须：embedding 高相似 不等于 重复（主题/情绪相近的不同场景）。

---

5) 保留哪条 chunk：canonical 选择策略（非「一律排除较晚」）

不采用简单「排除较晚一条」。

MVP 打分函数（示例因子，可加权）

• referenced_count / 被引用次数（若有）
• metadata 完整度
• 文本长度（信息更全）
• canonical 来源加成：来自 story/chapter 流水线、或 source_type / 标记为 canonical 的来源

结果：保留 分高者，exclude 分低者；同分再 tie-break（如更早的 ingest、或更长的文本）。

---

6) Context：触发批次信息（收紧）

除 story_ids / chapter_ids / story_dispatch_ids / chapters_to_enqueue 外，显式传入：

字段	说明
trigger_source	memoir_segments / chapter_recompose / manual / beat
trigger_time	ISO8601 或 monotonic
candidate_chunk_ids / candidate_source_ids	直接候选（可选）
pipeline_run_id / request_id	与 memoir task / HTTP 对齐，便于追溯

写入日志与（可选）MemoryCurationAction.details。

---

7) 可观测性：指标 + 日志

日志（保留）：结构化，user_id、耗时、跳过原因、exclude 对。

指标（建议 Prometheus 或现有 metrics 体系）

• memory_compaction_runs_total
• memory_compaction_skipped_total（含 lock、debounce、空增量）
• memory_compaction_chunks_scanned_total
• memory_compaction_chunks_excluded_total
• memory_compaction_candidates_total
• memory_compaction_duration_ms
• memory_compaction_lock_contention_total

派生关注

• exclude rate；
• duplicate detection 人工抽检 precision（流程外记录，非自动指标）。

原因：compaction 最常见问题是 悄悄做错，而非 crash。

---

架构示意（修订）

flowchart LR
  subgraph triggers [Triggers]
    MS[memoir_segments]
    RC[chapter_recompose]
    M[manual]
    B[beat]
  end
  subgraph redis [Redis]
    DEB[debounce_until_or_pending]
    LOCK[lock memory_compaction user]
    CUR[last_compaction_cursor]
  end
  subgraph worker [Worker]
    T[memory_compaction_run idempotent]
  end
  triggers --> DEB
  DEB --> T
  T --> LOCK
  T --> CUR

---

代码锚点（不变）

• 调度挂钩：[process_memoir_segments](api/app/tasks/memoir_tasks.py) 成功路径；可选 [recompose_chapters_for_story](api/app/tasks/chapter_compose_tasks.py)（双触发由锁 + 幂等吸收）。
• 业务逻辑：新 features/memory/compaction_service.py；任务：tasks/memory_compaction_tasks.py；配置：core/config.py。

---

阶段切分（不变，与修订对齐）

• MVP：Redis 防抖主路径 + 用户锁 + chunk 增量 + 多层近重复 + 打分保留 + context + 日志 + 指标。
• 阶段二：pending 建议表 / LLM 仲裁。
• 阶段三：低频全量 + 分片。

---

Implementation todos（修订）

1. Config：memory_compaction_*（含 debounce 秒、锁 TTL、chunk 上限、相似度与「至少 K 层满足」）。
2. Redis：debounce_until / pending 主路径；lock:memory_compaction:{user_id}；last_compaction_cursor（或等价）。
3. Service：幂等 compaction；chunk 索引增量；多层判定 + 打分 exclude；curation_action details 含对比 id 与 context。
4. Celery：memory_compaction_run 入口锁与 debounce 校验；注册 task。
5. Hooks：memoir_tasks / 可选 chapter_compose_tasks 传完整 context。
6. Metrics + logs + .env.example 文档。