group_fqcd_jr/docs/32-记忆投影链路实现说明.md

记忆投影链路（Outbox → Milvus 长期记忆 / Neo4j）实现说明

适用分支：NL_develop（用户端线）｜日期：2026-09-12｜状态：已实现并通过真机验证

---

1. 这条链路是干什么的

记忆（对话里被抽取出来的长期事实）要能被后续召回，必须从 MySQL 同步到两处外部存储：

对话消息
  └─→ memory.extraction_requested（domain_event_outbox）
        └─→ MemoryExtractionWorker → MemoryService.upsert() → memory_unit（MySQL，唯一真相）
              └─→ profile.rebuild_requested（domain_event_outbox）
                    ├─→ ProfileAssemblyService.rebuild()        → profile_snapshots
                    ├─→ ProfileGraphProjectionService          → Neo4j（图）
                    └─→ ProfileGenerationService.generate()    → memory_sync_outbox
                          ├─ milvus → MilvusProfileProjection   → Milvus 长期记忆向量
                          └─ neo4j  → ProfileGraphProjectionService（幂等复投）

memory_sync_outbox 是"画像版本 → 外部存储"的投递队列，唯一键 uk_memory_sync_event (event_uuid, target_store)：同一 event_uuid 对两个目标库各写一条。

---

2. ⚠️ 最容易踩的坑：枚举取值必须全仓统一（小写 + 英文）

这条链曾完全失效但不报错，根因就是取值口径不统一。

唯一正确口径

字段	取值	大小写
target_store	milvus / neo4j	小写
operation	upsert / archive / delete	小写
status	pending / failed / processed / dead	小写英文

（aggregate_type 用 memory / profile / relationship / deletion。）

为什么照 docs/00 §6.4.6 写会坏

docs/00 §6.4.6 那一栏曾写作大写 MILVUS/NEO4J、UPSERT 与中文 待处理， 与全仓实现从未对齐。按那份文档写会造成：

1. MemorySyncOutboxWorker 按 handlers.get(event.target_store) 分派 handler —— 大写值找不到 handler；
2. 领取条件是 status.in_({"pending","failed"}) —— 中文 待处理 不满足。

⇒ 两个条件都不满足，事件任何消费者都领不到，永久滞留且不报错。 唯一键 (event_uuid, target_store) 对大小写没有约束，MySQL 也不会报错，所以是静默失效。

判断依据应以主干既有读取方为准，不是文档： projection_reconciliation_service.py:20（{"pending","failed"}）、 graph_projection_worker.py（pending/processed/dead）。

现状

• 生产端取值集中在 app/service/profile_generation_service.py 的常量 （TARGET_MILVUS/TARGET_NEO4J/SYNC_OPERATION_UPSERT/SYNC_STATUS_PENDING）；
• 测试不再硬编码字面量，并断言 SYNC_STATUS_PENDING == "pending"、 set(SYNC_TARGETS) == {"milvus","neo4j"} （硬编码正是当初跑偏的直接原因）；
• tests/unit/worker/test_memory_sync_outbox_worker.py 有一条契约回归测试， 断言大写 MILVUS 分派不到 handler、会进死信 —— 谁改回大写，测试立刻红；
• 历史 2 行已就地把取值改齐（只改值，主键/唯一键/payload 未动）， 正式订正工具 tools/normalize_memory_sync_outbox.py （默认 dry-run，加 --apply 才写库，幂等可复跑；换环境若也有同批旧值可直接用）。

---

3. Milvus 长期记忆向量集合

项	值
集合名	user_long_term_memory_v1
主键	memory_uuid（VARCHAR 64，UUID 字符串，按 UUID 幂等 upsert）
向量	embedding，FLOAT_VECTOR dim 1024，索引 AUTOINDEX + COSINE
其他字段	customer_id(INT64) / version(INT64,可空) / valid_until_ts(INT64,可空) / updated_at_ts(INT64,可空) / confidence(DOUBLE) / content(VARCHAR 2048) / memory_type(VARCHAR 32) / memory_key(VARCHAR 64) / status(VARCHAR 16)

建集合：python tools/setup_milvus_profile_collection.py ——幂等，集合已存在时只做结构比对报告、不覆盖不删重建（共享 Milvus 实例里还有别的项目的集合）。

memory_sources 契约（适配器的输入）

{
  "customer_id": 9102,
  "profile_version": 2,
  "memory_sources": [{
    "memory_uuid": "uuid 字符串",
    "memory_key": "preference:risk_level",
    "content": "正文",
    "memory_type": "preference",
    "confidence": 0.9,
    "version": 1,
    "valid_until": null
  }]
}

数据源：memory_unit 中 status='active' 的行 （ProfileRepository.active_memories()）。由生产端组装而不是消费端回查： 消费端到时记忆可能已改版本，事件里带确定快照才能与 aggregate_version 语义一致。

为什么用 memory_unit 而不是 user_facts：两者用途不同 —— user_facts 是 已确认的结构化事实（喂画像与图投影），memory_unit 是长期记忆条目 （正是长期记忆向量集合要存的东西）。这不与"图投影只读 user_facts"的不变式冲突。

---

4. 移植自 ZSY_develop 的改动（含两处契约放宽）

来源：同事 ZSY_develop 分支。整文件移植、骨架未改的部分： app/core/conversation_privacy.py、app/worker/memory_sync_outbox_worker.py （领取/skip_locked/指数退避/5 次转死信的可靠性骨架原样保留）、 app/infrastructure/milvus_profile_projection.py。

对适配器做了两处契约放宽，都是"避免整批失败"，不改变写入语义：

1. customer_id 接受 int 或数字字符串 原实现要求 isinstance(customer_id, int)，而本仓所有生产者写的都是 str(customer_id)。不放宽则每个事件必然失败、重试 5 次后进死信。 放宽仅限纯数字串，非数字（如 uuid）仍拒绝。
2. 不可投影的 memory_key 跳过而非整批报错 受控词表 app/service/memory_taxonomy.py 共 13 个键，其中 constraint:*（3 个）与 profile:*（4 个）不以 preference:/goal: 开头。原实现对第一个不合规的键直接 raise —— 一条 constraint: 记忆就会毒死该客户整批同步。现改为跳过并留痕。

收窄而非扩容的理由：preference:*/goal:* 是偏好与目标，适合语义召回； constraint:*/profile:* 是结构化约束与属性，应由结构化通道查询（user_facts → 图）， 放进向量集合只会造成召回噪声。若日后要给它们做语义召回，应扩容而非靠现在的跳过。

---

5. Neo4j 分支：方案 A（不引入第二套投影）

同事分支另有一套 neo4j_profile_projection.py（按客户各建私有 Preference/Goal 节点、数据源 memory_unit）。未采用，理由：

主干 ProfileGraphProjectionService 已由 profile.rebuild_requested 驱动同一条链， 其数据源是 user_facts（已确认事实）、MERGE 共享 tag 节点，且文件头写明不变式：

"只投影'已确认'的事实……保证图里的偏好标签与画像口径一致； 否则同一件事在画像和图里会有两种说法。"

两套并存 = 同一事实在图中两种表示，正好违反这条不变式。 因此 memory_sync_outbox 的 neo4j 分支复用主干服务： 图投影是 MERGE 幂等的，再投一次不产生重复节点/关系，只用于收敛 outbox 的投递状态。

---

6. 消费端装配

WorkerRuntime.consume_profile_projections()（app/worker/runtime.py），在 run_once() 每轮执行，按条提交、单条失败不冒泡。

• milvus handler → MilvusProfileProjection（注入 MilvusProfileVectorClient + 向量化）；
• neo4j handler → ProfileGraphProjectionService；其 degraded 会如实抛错 走失败/退避，不记成已投递；
• milvus_uri 未配置时显式降级：不消费、事件留 pending（可观测、可重放）， 启动路径留一条 warning，绝不伪造同步成功（与 knowledge_writer 同一取向）；
• 目标存储没有对应 handler 时判死信并记 target_handler_not_configured —— 这正是当初大写值事件的下场（有回归测试守着）。

向量化复用与知识向量同一套已批准端点解析（agent_type="memory_recall", task_type="embedding"）。

---

7. 真机验证证据（2026-09-12）

验证项	结果
集合创建幂等	首次 created，复跑 exists
真实 embedding 维度	1024（与集合定义一致）
真实写入 + 回读	2 条可投影键写入成功并可回读（内容/版本正确）
不可投影键	constraint:liquidity 未写入（跳过生效，未毒死整批）
测试数据清理	已按 customer_id=999999 删除，集合残留 0 条
单元测试	新增 17 个（适配器 10 + worker 5 + 生产端 2），全过
全量回归	2 failed, 1307 passed, 2 skipped —— 与基线一致，无新增失败
mypy	Success: no issues found in 227 source files

全量的 2 个失败是既有环境相关项（test_offsite_document_recognition_adapter.py 断言请求体里的中文原文，而 httpx 序列化成 \uXXXX），与本次改动无关。

真机注意：Milvus 写入后短时间内可能查不到（索引尚未可见）， 验证脚本按重试处理；同理删除后立即查询可能仍返回旧行，需重查确认。

---

8. 尚未完成 / 依赖他人

1. 常驻 Worker 未运行：核对时数据库里 memory_sync_outbox 2 行、 domain_event_outbox 积压 （agent.run_requested 428、profile.rebuild_requested 216、 agent.run_completed 61、memory.extraction_requested 58）。 memory_unit 与 user_facts 目前都是 0 行 —— 代码链路是通的， 但没有 Worker 在跑，所以记忆永远不会被抽取出来。起 python -m app.worker --once（或常驻）即会开始消费。
2. 投顾线两处生产者的取值：profile_governance_service.py 与 risk_questionnaire_service.py 已写小写 milvus/neo4j + pending（与本文口径一致）， 但它们的 payload 是 {customer_id, profile_uuid, version, profile}， 没有 memory_sources → 投影时会因 memory_sources is invalid 失败重试至死信。 需投顾线补 memory_sources 或明确这两个来源是否也要投影长期记忆。 （属架构师线的改动，本线未动。）
3. docs/00 §6.4.6 的取值栏与实现不一致：按评审要求未改基线文档， 实际口径以本文第 2 节为准。

---

9. 相关文件

新增

• app/core/conversation_privacy.py（移植）
• app/infrastructure/milvus_profile_projection.py（移植 + 2 处放宽）
• app/infrastructure/milvus_profile_vector_client.py
• app/worker/memory_sync_outbox_worker.py（移植）
• tools/setup_milvus_profile_collection.py
• tests/unit/infrastructure/test_milvus_profile_projection.py
• tests/unit/worker/test_memory_sync_outbox_worker.py

修改

• app/service/profile_generation_service.py（取值改小写、payload 加 memory_sources 与 profile_version）
• app/repository/profile_repository.py（active_memories()）
• app/service/agent/bootstrap.py（get_milvus_profile_vector_client()）
• app/worker/runtime.py（consume_profile_projections() + run_once 接线）
• tests/unit/service/test_profile_generation_service.py（+2 用例、断言改引用常量）