memind/docs/architecture/jkriver-sleep-reference.md

JKRiver Sleep Pipeline 只读参考

日期: 2026-09-02

状态: 架构级参考文档。JKRiver（Riverse）源码位于 ~/Project/jkriver，AGPL-3.0 / 商业双授权，禁止将其实现移植进 Memind 商业 SaaS。本文只记录可安全采用的设计决策与反面教训，供 memory-v2-lifecycle.mjs 未来填槽时对照。

0. 授权边界（必读）

JKRiver LICENSE 为 Dual License：

• 开源：AGPL-3.0（网络服务需开源修改版）
• 商业：需联系 mailwangjk@gmail.com

Memind 103 生产为商业 SaaS → 不得复制 agent/sleep/*.py 或 agent/storage/*.py 的实现。允许：

• 读源码理解事务边界、幂等策略、数据模型取舍
• 在 Memind 内独立设计语义等价的 JS 逻辑
• 引用公开概念（Sleep Consolidation、supersede、evidence linking）

禁止：

• 逐行翻译 Python → JavaScript
• 嵌入 JKRiver 代码片段
• 在未取得商业授权前声称「基于 JKRiver 移植」

Mi-Memory（MIT）无此限制；JKRiver 有。

1. 忽略清单（与 Memind 重叠）

JKRiver 下列模块不建议研究或集成——Memind 已有等价或更完整实现：

JKRiver 模块	原因
Agent / Web Chat / Telegram	重叠 wechat-mp, Portal chat
Skills / Task Agent	重叠 skills-registry, chat-skills
MCP 集成	重叠 Goose MCP extension
Proactive messaging	重叠 schedule-reminder-worker, notification-dispatcher
Finance / Health 领域 storage	领域耦合，与 h5_user_memory_items 模型不兼容

2. 值得读的核心：agent/sleep/（2324 行）

2.1 14 步流水线（orchestration.py）

load_initial → extract_sessions → analyze_behavior → classify_and_integrate
→ cross_verify → resolve_disputes → extract_edges → expire_facts
→ maturity_decay → user_model → trajectory → consolidate → snapshot → finalize

与 Memind 此前画的 Sleep 图相比，JKRiver 多五步：

步骤	作用	Memind 对应空槽
cross_verify	交叉验证新 fact	无
resolve_disputes	争议 fact 仲裁（disputes.py 231 行）	无
user_model	用户模型更新	user-memory-profile 部分覆盖
trajectory	长期轨迹 / key_anchors	无
consolidate + snapshot	预编译快照	memory-v2-lifecycle.compact() 占位

Memind V1 只需关注后四个 maintenance 步映射到 lifecycle：

JKRiver 步骤	memory-v2-lifecycle.mjs	现状
expire_facts	expire()	flag 关，逻辑有
maturity_decay	decay（无独立函数）	未实现
promote（classify 隐含）	promote()	candidate→item INSERT IGNORE
consolidate	compact()	mode: 'candidate-only'
reflect（trajectory 隐含）	reflect()	mode: 'observation-only'

2.2 事务与幂等（可安全采用的设计）

orchestration.py 核心模式：

with transaction():
    _run_sleep_pipeline_inner(...)

# finalize 步才 mark_processed()
# 崩溃 → 整批回滚 → 下次重跑（at-least-once）
# embedding / clustering 在事务外，失败只 warning

Memind 现状：expire / compact / promote / reflect 各自独立调用，无共同事务边界，无 processed 水位。

可独立采用的设计决策（不是代码）：

1. Consolidation 批次必须在单 DB 事务内
2. mark_processed / 水位标记必须在流水线最后一步
3. 非关键后处理（embedding、聚类）放在事务外
4. LLMPipelineError 单独处理：LLM 不可用则 abort 整批，不部分提交

2.3 Maturity Decay 语义（_maturity.py，17 行）

_MATURITY_TIERS = [(730, 10, 730), (365, 6, 365), (90, 3, 180)]
# if new_decay > current_decay: update  （只增不减）

这是 保留期延长，不是置信度衰减：

• 跨度 ≥730 天且 evidence ≥10 → decay_days 延到 730
• 命中 key_anchors 时门槛 ×0.6

与 Memind experience-service.mjs 的 30 天半衰期指数衰减相反。若 Personal Memory 填 decay 槽，必须先做语义选择，不能混用。

2.4 Fact 模型（与 Memind 差距）

JKRiver fact：category, subject, value, start_time, supersedes, superseded_by, decay_days, evidence[]

Memind h5_user_memory_items：label, memory_text, confidence, status, evidence_message_id

这是换模型，不是加字段。JKRiver consolidation 算法 tied to 前者，不能直映射。

3. 反面教训：008_drop_hypotheses.sql

-- hypotheses 表一直是 0 行，无生产读写
-- 被 user_profile (layer 'suspected'/'confirmed' + supersedes) 完全取代
DROP TABLE IF EXISTS hypotheses CASCADE;

对 Memind 的含义：

1. 不要把 hypothesis 做成独立表或必填字段（Experience schema 已采纳：hypothesis 可空）
2. 未验证的推断应表达为 layer=suspected + supersedes 链，而不是平行 hypotheses 存储
3. 建表前先证明有读写路径，否则 0 行表最终被删

4. Memind 填槽优先级（JKRiver 启发，自行实现）

在 memory-v2-lifecycle flag 打开 + MemFuseBench 基线稳定后：

优先级	函数	JKRiver 启发	自行实现要点
P0	事务边界 + 水位	orchestration.transaction()	MySQL 事务包裹 promote+expire
P1	promote() supersede	classify_and_integrate	candidate 冲突时 supersede 而非 INSERT IGNORE
P2	expire() + verify	expire_facts + verify strategy	过期写 verify 候选，不静默删
P3	decay 延长	maturity_decay	按 evidence 计数延长 retention，非指数衰减
P4	compact()	consolidate + snapshot	保守：只报告 eligible，不覆盖源
P5	reflect()	trajectory + disputes	需 Experience 结构化数据先就绪

5. 何时启动 JKRiver 填槽

三门（与 memfuse-bench-baseline.md 一致）：

1. h5_memory_v2_candidates 有真实流量
2. lifecycle rolloutMode 至少 canary
3. MemFuseBench / recall benchmark 有可对比的前后基线

当前（2026-09-02）：仅第 3 项部分满足（MemFuseBench 已可跑）。lifecycle 仍 off → 不启动填槽实现。

6. 本地材料

# 已 clone，不在 Memind 仓库内
~/Project/jkriver
~/Project/mi-memory   # MIT，含 MemFuseBench 数据集

关键路径：

• agent/sleep/orchestration.py — 流水线入口
• agent/sleep/steps_maintain.py — expire / maturity
• agent/sleep/disputes.py — 争议解决
• migrations/008_drop_hypotheses.sql — 反面教训