Document Experience schema and JKRiver read-only references.

Map Mi-Memory Structure/Expansion into h5_experience V1 fields and record JKRiver Sleep design lessons under AGPL constraints, plus post-fix MemFuseBench numbers.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/architecture/experience-schema-v1.md

@@ -0,0 +1,201 @@
+# Experience Schema V1（Mi-Memory Structure / Expansion 映射）
+
+日期: 2026-09-02
+
+状态: 设计草案。依据 Mi-Memory 论文（arXiv:2607.18975）**Structure + Expansion** 段与 Memind 现有 `h5_experience` / Agent Memory 定位。**不含 Evolution / Deployment 实现**——那些需等 MemFuseBench 基线与 `memory-v2-product-events` 指标就绪后再做。
+
+## 0. 定位
+
+Mi-Memory 把 Memory 分成四层角色（Structure / Expansion / Evolution / Deployment），用统一 **Audit Contract** 连接。Memind 上一轮架构判断里，**Personal Memory**（`h5_user_memory_items`）与 **Agent Memory**（`h5_experience`）生命周期不同；Experience Schema V1 只服务后者。
+
+| Mi-Memory 概念 | Memind 落点 | V1 范围 |
+|---|---|---|
+| MemStack L0 Facts | `h5_user_memory_items` | 已有，不在本文 |
+| MemStack L1 Summaries | `conversation-memory` / episodic | 已有，不在本文 |
+| MemStack L2 Profile | `user-memory-profile` | 已有，不在本文 |
+| **MemStack Skills / 可复用行为** | **`h5_experience` 扩展** | **本文** |
+| MemSense / MemFuse 来源标注 | Experience 的 `evidence_json` | **本文** |
+| D²ACCI / E²MEND Gate | `memory-v2-product-events` + 未来 gate 表 | 后置 |
+| LiteMem 部署变体 | 不在 V1 | 后置 |
+
+论文核心句（§3.1）：**memory item ≠ evidence ≠ strategy**。存对了 memory 不够——检索、过滤、打包仍可能丢 evidence。Experience V1 因此必须同时存 **结构化 memory item** 和 **可追溯 evidence 链**，而不是一行 `title + body` 摘要。
+
+## 1. 动机：现有 `h5_experience` 缺什么
+
+当前 schema（`schema.sql`）：
+
+```sql
+h5_experience (
+  id, scope, kind, title, body, tags_json,
+  source_session_id, source_user_id, use_count,
+  embedding, created_at, updated_at
+)
+```
+
+写入点（`mindspace-agent-runner.mjs`）只填 `kind: 'task_outcome'` + `title` + `body` 一行摘要。`reflect()` 在 `experience-service.mjs` 仍为 `not_implemented`。
+
+这无法支撑用户描述的 SSE 场景：
+
+```
+problem: SSE connection instability
+environment: goosed + Docker + PG
+hypothesis: connection lifecycle issue
+action: modified server.rs
+result: success
+confidence: 0.86
+```
+
+也无法对接 Mi-Memory 的 **Typed Evidence Payload**（source id / time / device / confidence / provenance）。
+
+## 2. V1 字段定义
+
+### 2.1 表级：`h5_experience` 扩展列
+
+在现有列上**加列**，不新建表。保持 `record()` / `search()` 契约向后兼容：旧行新列为 NULL，读路径用 fallback。
+
+| 列 | 类型 | 必填 | 来源 / 含义 |
+|---|---|---|---|
+| `problem` | `VARCHAR(512)` | 否 | 触发本次执行的问题陈述（Mi-Memory: 诊断起点） |
+| `environment_json` | `JSON` | 否 | 运行环境：`{ runtime, components[], version?, region? }` |
+| `hypothesis` | `VARCHAR(512)` | 否 | 执行前的假设（**可空**；见 JKRiver 反面经验） |
+| `action_json` | `JSON` | 否 | `{ executor, steps[], artifacts[], diff_ref? }` |
+| `result` | `ENUM('success','partial','failure','unknown')` | 否 | 终态 |
+| `confidence` | `DECIMAL(4,3)` | 否 | 0–1，写入时对 result 的确信度 |
+| `evidence_json` | `JSON` | 否 | **Mi-Memory Typed Evidence**（见 §2.2） |
+| `parent_experience_id` | `CHAR(36)` NULL | 否 | 同类问题复发时的链接 |
+| `supersedes_id` | `CHAR(36)` NULL | 否 | 新经验取代旧经验 |
+| `status` | `ENUM('active','archived','deleted')` | 是 | 默认 `active` |
+
+保留现有 `title` / `body`：`title` = 短标题（列表 / 注入），`body` = 人类可读摘要（LLM 注入块）。结构化字段供检索、reflect、skill 晋升，不替代 `body`。
+
+### 2.2 `evidence_json`：Mi-Memory Typed Evidence 最小契约
+
+对应论文 Table 3 **Typed evidence payload**（source id, time, device, confidence, provenance）。
+
+```json
+{
+  "sources": [
+    {
+      "source_id": "run:abc123",
+      "source_type": "agent_run",
+      "actor": "goose",
+      "device": null,
+      "timestamp_ms": 1756780800000,
+      "modality": "tool_result",
+      "snippet_ref": "event:tool_sse_error_1",
+      "confidence": 0.86
+    }
+  ],
+  "provenance": {
+    "run_id": "abc123",
+    "session_id": "sess-xyz",
+    "user_id": "user-1",
+    "causal_event_ids": ["evt-1", "evt-2"]
+  },
+  "checklist": [
+    { "point": "SSE error in goosed logs", "source_ids": ["evt-1"] }
+  ]
+}
+```
+
+与 MemFuseBench 对齐：`checklist` + `source_ids` 可直接对接 `memory-v2-memfuse-bench.mjs` 的 `checklistCoverage` 指标，作为 Experience 召回质量的离线代理。
+
+**V1 不存原始 Event Stream**——只存引用（`run_id` / `causal_event_ids`）。原始事件留在 `h5_agent_run_events`；Experience 是 **derived memory item**，不是 Event Kernel 本身。
+
+### 2.3 `kind` 枚举扩展
+
+| `kind` | Mi-Memory 对应 | 用途 |
+|---|---|---|
+| `lesson` | L0 fact / 教训 | 默认，兼容现有 |
+| `task_outcome` | L1 summary | 现有 mindspace-agent-runner |
+| `execution_pattern` | procedural hook | 可复用执行模式 |
+| `skill_candidate` | Skill 候选 | `reflect()` 晋升前 |
+
+V1 写入仍用 `task_outcome`；`reflect()` 实现后再产出 `skill_candidate`。
+
+### 2.4 `environment_json` 示例
+
+```json
+{
+  "runtime": "goosed",
+  "components": ["docker", "postgres-session", "portal-proxy"],
+  "versions": { "goosed": "1.4.1", "portal": "61eebb44" },
+  "region": "103-canary"
+}
+```
+
+## 3. 写入契约（Expansion 段）
+
+执行器**不直接写 Experience 表**。对齐 Event Kernel 方向（论文 §5 + Memind 架构共识）：
+
+```
+Goose / OpenHands / Aider / Browser
+        │
+        ▼
+  h5_agent_run_events  （已有）
+        │
+        ▼
+  Experience Extractor   （V1 新增：agent-run 完成钩子）
+        │
+        ▼
+  h5_experience
+```
+
+V1 Extractor 触发点（按优先级）：
+
+1. `agent-run-gateway.mjs` — run 终态 `completed` / `failed`
+2. `mindspace-agent-runner.mjs` — 已有 `recordExperience()`，扩字段
+3. OpenHands / Aider — 仅当 `tool-gateway` 返回结构化 outcome 时
+
+Extractor 必填：`problem`（从 user_message + run 摘要）、`result`、`evidence_json.provenance.run_id`。其余可 best-effort。
+
+## 4. 读取契约（Structure 段）
+
+`experience-service.search()` V1 不改签名；排序层后续可叠加：
+
+1. 关键词（现有）
+2. `environment_json` 组件匹配（如 query 含 "goose" / "sse"）
+3. `problem` 向量相似度（接 pgvector 后）
+
+注入格式（`retrieveExperience()`）V1 扩展为：
+
+```
+# 相关经验（供参考，来自历史任务）
+- [2026-09] SSE 连接不稳定 (success, conf=0.86)
+  环境: goosed + Docker + PG
+  处理: 修改 server.rs 连接生命周期
+  摘要: ...
+```
+
+## 5. 与 Personal Memory 的边界
+
+| 维度 | Personal (`h5_user_memory_items`) | Agent (`h5_experience`) |
+|---|---|---|
+| 关于 | 这个人是谁 | 怎么做事 |
+| 典型字段 | preference, goal, relationship | problem, action, result |
+| 生命周期 | JKRiver 式 consolidation（**仅参考，不移植代码**） | 执行 → reflect → skill |
+| Mi-Memory 段 | Structure + Expansion（用户态） | Structure（Skills）+ Expansion（tool/run evidence） |
+
+**禁止**把 `hypothesis` 做成一级必填字段。JKRiver `008_drop_hypotheses.sql` 记录：独立 hypotheses 表建后废弃，改由 `user_profile.layer ∈ {suspected, confirmed}` + `supersedes` 表达。Experience 里 `hypothesis` 保持可空；不确定时用 `confidence < 0.5` + `result: 'unknown'`。
+
+## 6. V1 实施顺序
+
+1. **Migration**：`h5_experience` 加列（上表），默认值 NULL
+2. **Extractor**：扩 `recordExperience()` + agent-run 完成路径
+3. **`reflect()` 最小实现**：把 N 条 `task_outcome` 聚合为 1 条 `execution_pattern`（规则版，无 LLM）
+4. **指标**：复用 `memory-v2-product-events` 增 `experience_saved` / `experience_recalled`
+5. **MemFuseBench 对照**：Experience 召回不参与 MemFuse（语料不同），但 `checklistCoverage` 格式保持一致以便将来统一 audit
+
+## 7. 明确不做（V1）
+
+- E²MEND 自动策略搜索
+- Gate / Rollback 表（Evolution 段）
+- LiteMem 文件-native 部署
+- 把 Experience 写进 goosed 会话内
+- JKRiver Sleep Pipeline 代码移植（AGPL-3.0，见 `jkriver-sleep-reference.md`）
+
+## 8. 参考
+
+- Mi-Memory 论文: https://arxiv.org/abs/2607.18975
+- MemFuseBench 基线: `docs/architecture/memfuse-bench-baseline.md`
+- 现有实现: `experience-service.mjs`, `schema.sql` `h5_experience`

docs/architecture/jkriver-sleep-reference.md

@@ -0,0 +1,164 @@
+# 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` 核心模式：
+
+```python
+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 行）
+
+```python
+_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`
+
+```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. 本地材料
+
+```bash
+# 已 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` — 反面教训

docs/architecture/memfuse-bench-baseline.md

@@ -25,6 +25,19 @@
 
 按维度看，`multi_source_conflict_arbitration` 明显最好（候选 71.5% / 召回 39.4%），`cross_device_information_fusion` 最差（26.5% / 6.1%）。
 
+### keyword 路径修复后（commit `2c0d903e`，k=20）
+
+只改 `fetchKeywordCandidates`：去掉 `ORDER BY updated_at DESC`，扩大 fetch cap 后按 `lexicalQueryCoverage` 排序；keyword 行携带 lexical 分。`rankHybridCandidates` 未改。
+
+| 指标 | 修复前 | 修复后 | Δ |
+|---|---|---|---|
+| candidateRecall | 36.6% | **72.8%** | +36.2pp |
+| recall@k | 13.5% | 13.3% | ≈0 |
+| hitAny@k | 41.7% | **43.1%** | +1.4pp |
+| checklistCoverage | 16.8% | 16.4% | ≈0 |
+
+候选池扩大后 rankingLoss 相对值上升（59.5pp），但**最终 recall 几乎不变**——下一刀必须改 `rankHybridCandidates`，且需接**真实语义嵌入**验证（lexical-hash 下改非中文 vector 优先会恶化至 ~5.7% recall）。
+
 ## 1. 两个已定位的机制
 
 ### 机制一：`lexicalQueryCoverage` 是主排序键，但判别力接近随机
@@ -129,4 +142,5 @@ npm run verify:memory-v2-memfuse-bench
 - `memory-v2-memfuse-bench.test.mjs` — 内联 fixture，19 个用例，不依赖外部数据集
 - `scripts/run-memory-v2-memfuse-bench.mjs` — CLI
 - `memory-v2-pgvector.mjs` — 被测的生产排序路径（`rankHybridCandidates` / `fetchKeywordCandidates` / `extractKeywordTerms`）
-- `memory-v2-recall-benchmark.mjs` — 既有的 4 例中文手写基线，与本文互补
+- `docs/architecture/jkriver-sleep-reference.md` — JKRiver 只读参考（AGPL 边界）
+- `docs/architecture/experience-schema-v1.md` — Mi-Memory Structure/Expansion 映射