memind/docs/architecture/temporal-recall-v0.1.md

# RFC: Temporal Recall & Context Planner v0.1

| 字段 | 值 |
|------|-----|
| 状态 | **Frozen（V0.1）** |
| 日期 | 2026-09-03 |
| 关联 Schema | `schemas/timeline-item.schema.json`, `schemas/context-plan.schema.json` |
| 关联 API | `docs/api/temporal-recall-v1.md`, `docs/api/context-planner-v1.md` |
| 前置 RFC | `docs/rfc/user-model-v0.1.md` |

---

## 1. 摘要

MeMind 需要一套独立于 User Model 与 Memory V2 的 **Temporal Recall** 能力，回答：

> **某个时间范围内，发生了什么？**

这与 User Model（「你是谁 / 你现在关注什么」）正交，是第四条一级能力域。

**V0.1 目标：** 跑通 `User Query → Context Planner → Multi-source Retrieval → Timeline → Rank → Answer`，数据源仅 **MeInput + Chat**；Calendar / Memory V2 作为可选低权重源或 v0.2 接入。

**核心架构转变（Frozen）：**

```
Intent Classification（单选 intent）  →  不再是 Temporal 问题的核心
Context Planning（多源 Query Plan）    →  新核心
Retrieval Robustness（宽召回 + Rank）  →  优于 Intent Precision
```

---

## 2. 四个能力域（Frozen）

| 域 | 回答 | 典型问题 |
|----|------|----------|
| **User Model** | 我是谁、我现在关注什么 | 「帮我写代码时用什么风格？」 |
| **Memory V2** | 我过去明确发生过 / 决定过什么 | 「我们上次定的架构是什么？」 |
| **Temporal Recall** | 某个时间范围内发生了什么 | 「我这周有什么重要的事？」 |
| **Runtime Context** | 当前这一轮要用哪些上下文 | Session 内 tool / page / task 状态 |

```
                    User Query
                        │
                        ▼
                 Context Planner
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
      User Model   Temporal Recall   Memory V2
      「你是谁」    「发生了什么」    「曾经记住什么」
          │             │             │
          └─────────────┼─────────────┘
                        ▼
                   Agent Runtime
```

### 2.1 组合策略（Frozen）

| 问题类型 | User Model | Temporal Recall | Memory V2 |
|----------|------------|-----------------|-----------|
| 普通聊天 | REQUIRED | SKIP | SKIP |
| 时间范围问题 | OPTIONAL | REQUIRED | OPTIONAL |
| 历史决策 | OPTIONAL | OPTIONAL | REQUIRED |
| 复杂综合 | OPTIONAL | REQUIRED | REQUIRED |

每项取值：`REQUIRED | OPTIONAL | SKIP`。

---

## 3. 架构铁律（Frozen）

1. **Temporal 问题不做单选 intent 分类。** 输出 Query Plan，允许多源并行检索。
2. **时间词用确定性 parser，不交给 LLM 猜。**（今天 / 昨天 / 这周 / 最近三天 …）
3. **强约束词给 source 加权，不硬路由。**（行程→Calendar 高权重；原话→MeInput 高权重）
4. **模糊语义才走 LLM semantic expansion。**（「重要的事」「需要注意的」）
5. **Timeline Item 必须区分 `event_time` 与 `observed_time`。**
6. **宽召回优于窄 intent。** 误解 20% 仍应能召回正确证据。
7. **Temporal Recall 不写入 User Model Graph。** 它是检索视图，不是画像。
8. **Temporal Recall 不默认写入 Memory V2。** 长期记忆仍走 UMS → Candidate → Memory 链。
9. **Answer 必须基于 ranked timeline items，禁止 LLM 无证据自由发挥。**
10. **Dedupe 跨源合并同一事件**（Calendar + MeInput + Chat 三条 → 一条）。

---

## 4. 核心组件

### 4.1 Context Planner（Personal Query Planner）

**职责：** 决定「这句话需要哪些上下文」，而非「这句话属于哪个 intent」。

**双通道解析（Frozen）：**

```
               User Query
                    │
          ┌─────────┴──────────┐
          ▼                    ▼
 deterministic parser      semantic parser
 (rule / small model)       (LLM, 仅复杂 query)
          │                    │
 time / keywords /        targets / ambiguity /
 explicit entities         implied meaning
          │                    │
          └─────────┬──────────┘
                    ▼
              Context Plan Merge
                    ▼
               ContextPlan AST
```

**Level 1 — Cheap Router（~80% 问题）：** 无 LLM 或小模型；检测时间范围、明显 Calendar 词、明显原文请求、是否历史问题。

**Level 2 — Semantic Planner：** 仅复杂 query 启用 LLM（多时间引用、未完成承诺追踪、跨源条件过滤）。

### 4.2 Temporal Recall Service

**职责：** 按 Context Plan 并行检索各 Source Adapter，归一化为 Timeline Item，Dedupe + Rank，返回 Recall Bundle。

```
             Context Plan
                 │
    ┌────────────┼─────────────┐
    ▼            ▼             ▼
 Calendar      Chat           MeInput
 (v0.2+)    (v0.1)            (v0.1)
    │            │             │
    └────────────┼─────────────┘
                 ▼
          Timeline Normalizer
                 ▼
              Dedupe
                 ▼
         Recall Ranker
                 ▼
          Recall Bundle
```

### 4.3 Source Adapter 边界

每个 Source **只暴露 Timeline Item 或 Evidence Envelope**，Temporal Recall **不得** JOIN Source 内部表（与 UMS 铁律一致）。

| Source | V0.1 | Adapter 入口 |
|--------|------|--------------|
| MeInput | ✅ | `GET /v1/evidence/export`（expression_segment） |
| Chat | ✅ | Portal session messages / agent runs |
| Memory V2 | 低权重可选 | `memory-v2` time-bounded search |
| Calendar | ❌ v0.2 | 待定 |

---

## 5. ContextPlan AST（Frozen）

见 `schemas/context-plan.schema.json`。核心字段：

```json
{
  "query_type": "personal_temporal_recall",
  "time": {
    "mention_range": { "start": "...", "end": "..." },
    "event_range": null
  },
  "temporal_mode": "OCCURRED_IN | MENTIONED_IN | PLANNED_IN | CREATED_IN | DUE_IN | AMBIGUOUS",
  "targets": [
    { "type": "calendar_event", "weight": 0.8 },
    { "type": "commitment", "weight": 1.0 },
    { "type": "todo", "weight": 0.9 }
  ],
  "sources": {
    "calendar": 0.85,
    "chat": 0.80,
    "meinput": 0.75,
    "memory_v2": 0.45
  },
  "retrievals": [
    {
      "source": "meinput",
      "query_type": "important_mentions",
      "expanded_queries": ["会议", "安排", "明天", "截止"],
      "weight": 0.75
    }
  ],
  "filters": {
    "importance_min": 0.6,
    "status": "unresolved"
  },
  "output": {
    "group_by": "importance",
    "dedupe": true,
    "timeline": true,
    "wide_recall": true
  },
  "context_needs": {
    "user_snapshot": "OPTIONAL",
    "temporal_recall": "REQUIRED",
    "memory_retrieval": "OPTIONAL"
  }
}
```

### 5.1 六个解析槽位

| 槽位 | 含义 | 示例 |
|------|------|------|
| `time_scope` | 绝对时间范围 | yesterday → `[start, end)` |
| `target` | 要找什么类型 | event, schedule, todo, commitment |
| `operation` | 检索后操作 | retrieve / retrieve_and_summarize |
| `importance` | 重要性过滤 | important / any |
| `sources` | 多源权重（非单选） | calendar:0.85, chat:0.80 |
| `temporal_semantics` | 时间语义 | occurred_or_planned / ambiguous |

### 5.2 Temporal Mode（Frozen）

| Mode | 语义 | 示例问题 |
|------|------|----------|
| `OCCURRED_IN` | 事件发生在该范围 | 「我昨天做了什么？」 |
| `MENTIONED_IN` | 在该范围内被提到 | 「我昨天说过要做什么？」 |
| `PLANNED_IN` | 计划在该范围发生 | 「我今天有什么安排？」 |
| `CREATED_IN` | 在该范围内创建/记录 | 「我上周定了哪些事？」 |
| `DUE_IN` | 截止 / 应完成在该范围 | 「这周五之前要交什么？」 |
| `AMBIGUOUS` | 宽召回两种语义 | 「我昨天有什么重要的事？」 |

`AMBIGUOUS` 时 **禁止追问为默认行为**；并行查 occurred + mentioned，分组回答。

---

## 6. Timeline Item 统一模型（Frozen）

见 `schemas/timeline-item.schema.json`。

```json
{
  "timeline_item_id": "uuid",
  "user_id": "uuid",
  "source": "calendar | chat | meinput | memory_v2",
  "type": "event | todo | decision | mention | commitment",
  "event_time": "2026-09-03T15:00:00+08:00",
  "observed_time": "2026-09-02T20:30:00+08:00",
  "title": "与张总签合同",
  "content": "明天下午三点去签合同",
  "importance": 0.82,
  "confidence": 0.91,
  "recall_score": 0.76,
  "source_ref": "meinput:segment:...",
  "participants": ["张总"],
  "status": "planned | completed | mentioned | unknown",
  "merged_from": ["calendar:...", "chat:...", "meinput:..."]
}
```

**关键区分：**

- `event_time` — 事情何时发生 / 计划发生
- `observed_time` — 何时被记录 / 输入 / 提到

例：9 月 2 日输入「明天下午三点签合同」→ `observed_time=9/2`, `event_time=9/3 15:00`。

---

## 7. Recall Score（Frozen）

```
recall_score =
  source_quality
× temporal_match
× semantic_match
× importance
× extraction_confidence
```

| 分数区间 | 展示策略 |
|----------|----------|
| ≥ 0.75 | 主答案直接展示 |
| 0.50 ~ 0.75 | 次要信息 / 「可能相关」 |
| < 0.50 | 默认不展示 |

---

## 8. Query Expansion（Frozen）

**禁止**用用户原句单一 embedding 搜所有库。

Planner 为每个 source 生成 **expanded_queries**：

| Source | 扩展策略 |
|--------|----------|
| Calendar | 时间 filter 为主，keyword 为辅 |
| Chat | 约 / 安排 / 明天 / 会议 / 确认 / 跟进 / 截止 |
| MeInput | 任务词 / 时间表达 / action verbs |
| Memory V2 | commitment / task / decision |

---

## 9. Dedupe 规则（V0.1 简化）

同一 `event_time` ±15min + 语义相似（title/content embedding 或 keyword overlap > 0.7）→ merge。

Merge 后保留最高 `source_quality`，`merged_from` 记录各源。

---

## 10. 与 User Model 的关系

| | User Model | Temporal Recall |
|--|------------|-----------------|
| 时间性 | 慢变 / 半静态 | 强时间索引 |
| 问题 | 「我是谁」 | 「那时发生了什么」 |
| 存储 | Graph + Snapshot | 检索视图（不持久化画像） |
| 写入 | Evidence → Signal → Candidate | 只读各 Source |
| Session 加载 | 默认 REQUIRED | 按 Planner 按需 |

Planner 可将 User Snapshot 作为 **ranking prior**（例如已知 active_projects 加权相关 timeline items），但 Temporal Recall 不反向写 Graph。

---

## 11. V0.1 范围

### 做

- [ ] ContextPlan JSON Schema + Timeline Item Schema
- [ ] Deterministic time parser（zh-CN 相对时间）
- [ ] Rule-based source weight（强约束词表）
- [ ] Cheap Router（Level 1）
- [ ] MeInput Source Adapter（evidence export）
- [ ] Chat Source Adapter（session messages）
- [ ] Timeline Normalizer + Dedupe + Rank
- [ ] `POST /v1/temporal-recall/query` API
- [ ] Agent Runtime hook：`context_needs.temporal_recall = REQUIRED` 时注入 Recall Bundle

### 不做（V0.1）

- Calendar / Email / Browser / Git / Location
- LLM Semantic Planner（Level 2）— 仅预留接口
- Memory V2 深度集成（可选低权重 stub）
- 用户追问 clarification UI（默认宽召回 + 分组）
- Timeline 持久化索引库（V0.1 实时检索；V0.2 考虑 `memind_timeline` 物化）

---

## 12. 开发顺序（建议）

1. Schema + API 契约冻结（本文档）
2. Deterministic time parser + rule keyword weights
3. MeInput adapter（复用 evidence export）
4. Chat adapter
5. Normalizer + Ranker + Dedupe
6. Cheap Router → ContextPlan
7. Temporal Recall API
8. Runtime Context Planner hook
9. v0.2：Calendar adapter + Semantic Planner + 物化 timeline index

---

## 13. 命名约定（Frozen）

| 避免 | 使用 |
|------|------|
| Intent Layer（用于 Temporal） | **Context Planner** |
| `intent: query_schedule` | `ContextPlan.sources` 多源权重 |
| 「猜测用户唯一意图」 | 「宽召回 + Rank」 |
| Personal Intent Classification | **Personal Temporal Recall** |

Task Execution Intent（聊天→Agent 升级）仍走现有 `chat-intent-router`；**不与 Context Planner 混用**。

---

## 14. 验收标准（V0.1）

1. 「我昨天有什么重要的事？」→ 返回 grouped timeline（occurred + mentioned），不全为空
2. 「我这周输入过什么关于 MeInput 的？」→ MeInput source 高权重命中
3. 同一事件在 Chat + MeInput 重复出现 → Dedupe 为一条
4. `event_time` / `observed_time` 过滤行为符合 Temporal Mode
5. 无 ContextPlan 时 Agent 不调用 Temporal Recall（不误触发）