docs(memory): add document for memory

doc/memory/memory-retrieval.md

@@ -0,0 +1,113 @@
+# 记忆检索
+
+本文说明 Partner 记忆系统的组织层。存储层只保存稳定的 `MemoryUnit` 与 `MemorySlice`，检索层在这些数据之上建立可替换的召回结构。
+
+当前默认实现是 `MemoryRuntime`：它维护主题路径索引和日期索引，并把索引结果重新解析为可注入上下文的 `ActivatedMemorySlice`。
+
+| 索引                        | 作用                                       |
+|---------------------------|------------------------------------------|
+| `TopicMemoryIndex`        | 按主题路径组织 `MemorySlice`，支持主主题、父主题和相关主题扩散召回 |
+| `DateMemoryIndex`         | 按日期记录 `MemorySlice` 引用，支持按日期直接召回         |
+| `MemoryRuntimeStateCodec` | 负责主题索引和日期索引的持久化与恢复                       |
+
+## 索引建立
+
+`MemoryRuntime` 不直接生成原始记忆。原始记忆由 `DialogRolling` 写入 `MemoryUnit` 后，`AfterRolling` consumer 会消费
+`RollingResult`，为新产生的 `MemorySlice` 提取主题路径、相关主题和激活参数，再调用 `MemoryRuntime.recordMemory(...)` 建立索引。
+
+```mermaid
+flowchart TD
+    A["DialogRolling"] --> B["RollingResult"]
+    B --> C["AfterRollingRegistry"]
+    C --> D["MemoryRecallProfileExtractor"]
+    D --> E["topicPath<br/>主主题路径"]
+    D --> F["relatedTopicPaths<br/>相关主题路径"]
+    D --> G["ActivationProfile<br/>激活 / 扩散 / 上下文独立权重"]
+    B --> H["MemoryUnit"]
+    B --> I["MemorySlice"]
+    H --> J["SliceRef<br/>unitId + sliceId"]
+    I --> J
+    I --> K["LocalDate<br/>由 slice timestamp 转换"]
+    J --> L["MemoryRuntime.recordMemory"]
+    E --> L
+    F --> L
+    G --> L
+    K --> L
+    L --> M["DateMemoryIndex.record"]
+    L --> N["TopicMemoryIndex.recordBinding"]
+    L --> O["TopicMemoryIndex.ensureTopicPaths"]
+    M --> P["date -> SliceRef[]"]
+    N --> Q["topicPath -> TopicBinding[]"]
+    O --> R["related topic path nodes"]
+```
+
+`TopicMemoryIndex` 的绑定对象不是完整记忆内容，而是 `SliceRef`。它只记录 `unitId`、`sliceId`、时间戳、相关主题路径和
+`ActivationProfile`。真正需要展示原始消息时，`MemoryRuntime` 会再回到 `MemoryCapability` 读取对应 `MemoryUnit` 和
+`MemorySlice`。
+
+主题路径使用 `->` 表示层级，例如：
+
+```text
+project->partner->memory
+```
+
+`TopicMemoryIndex` 会按路径建立树节点；绑定到某个节点的 slice 表示该记忆切片属于这个主题。相关主题路径不会直接复制
+slice，而是作为扩散召回的候选入口参与后续评分。
+
+## 使用检索: 主题路径和日期索引
+
+运行时召回由 `MemorySelector` 触发。它会收集输入，使用当前主题树和输入内容提取召回线索，再按线索类型分别查询主题索引或日期索引。
+
+```mermaid
+flowchart TD
+    subgraph Input["输入收集"]
+        A["PartnerRunningFlowContext"] --> B["MemorySelector.collectInputs"]
+        B --> C["collectedInputs"]
+        C --> D["drainMemoryRecall"]
+    end
+
+    subgraph Cue["召回线索抽取"]
+        D --> E["MemoryRuntime.getTopicTree"]
+        D --> F["MemoryRecallCueExtractor"]
+        E --> F
+        F --> G["ExtractorResult.matches"]
+    end
+
+    subgraph Lookup["索引查询"]
+        G --> H{"match.type"}
+        H -- " TOPIC " --> I["MemoryRuntime.queryActivatedMemoryByTopicPath"]
+        H -- " DATE " --> J["MemoryRuntime.queryActivatedMemoryByDate"]
+        I --> K["TopicRecallCollector.collect"]
+        J --> L["DateMemoryIndex.find"]
+        K --> M["SliceRef[]"]
+        L --> M
+    end
+
+    subgraph Materialize["切片还原"]
+        M --> N["MemoryCapability.getMemoryUnit"]
+        M --> O["MemoryCapability.getMemorySlice"]
+        N --> P["sliceMessages"]
+        O --> P
+        P --> Q["ActivatedMemorySlice"]
+    end
+
+    subgraph Evaluate["评估与上下文注入"]
+        Q --> R["MemoryRecallEvaluator"]
+        R --> S["activated_memory_slices ContextBlock"]
+        S --> T["ContextWorkspace"]
+    end
+```
+
+按主题召回时，`TopicRecallCollector` 会从三个来源收集候选：
+
+| 来源        | 含义                    |
+|-----------|-----------------------|
+| `PRIMARY` | 当前主题节点直接绑定的 slice     |
+| `PARENT`  | 父主题节点的近期候选，用于保留上层语境   |
+| `RELATED` | 由当前主题绑定声明的相关主题，用于扩散召回 |
+
+候选会经过 `TopicRecallScorer` 打分。分数综合来源类型、时间新近性、激活权重、上下文独立权重和扩散权重。最终结果会限制数量，并转换成
+`ActivatedMemorySlice`。
+
+`ActivatedMemorySlice` 包含 slice 摘要、日期、时间戳以及对应原始消息片段。`MemorySelector` 会基于这些结果构造
+`activated_memory_slices` 上下文块，使后续 communication、cognition 或 action 模块能够读取被激活的记忆。