kimi-code-memory-mcp-server 0.1.0 → 0.1.2

package/docs/5.decision-guard-design-notes.md

@@ -0,0 +1,500 @@
+> 本文性质：设计思考 / 讨论稿，记录对决策守卫机制的深入探讨。
+> 与具体项目无关。
+
+---
+
+# 决策守卫机制设计笔记
+
+## 一、问题背景
+
+在多轮、长周期的 coding agent 项目中，历史决策的漂移和矛盾是一个常见问题：
+
+- agent 在新 session 中推翻昨天刚定的架构
+- 长会话中逐渐偏离早期结论
+- 同一个问题在不同 session 被反复争论
+- 决策更新后，相关历史讨论没有被自动关联
+
+决策守卫（Decision Guard）就是为了解决这个问题而提出的机制。
+
+---
+
+## 二、一个常见的误解：决策守卫是外部控制
+
+最初容易把决策守卫理解为一种**外部强制机制**：
+
+- 在 agent 执行 Write/Edit/Bash 之前拦截
+- 监听 agent 的 thinking 流
+- 替 agent 判断某个动作是否违反历史决策
+
+但这种思路有一个根本问题：**它入侵了 agent 的行为层和思想层**。
+
+agent 架构的核心原则是：LLM 是决策者，外部系统只提供信息和工具。如果外部系统强制控制 LLM 能做什么、不能做什么，就违背了这个原则，也会带来高昂的实现成本和误判风险。
+
+---
+
+## 三、核心洞察：决策守卫是认知问题，不是控制问题
+
+**决策守卫本质上只能发生在 LLM 的意识层。**
+
+如果 LLM 自己不知道、不理解、不重视历史决策，任何外部强制都是：
+- 入侵行为层（拦截工具调用）
+- 入侵思想层（监听 thinking 流）
+- 架空 LLM（替它做决定）
+
+因此，真正的问题不是"如何阻止 LLM 做错误的事"，而是：
+
+> **如何让 LLM 在需要时，主动、自然、低成本地想起并检查相关历史决策？**
+
+决策守卫的边界应该在 LLM 意识层：系统负责把正确的决策在合适的时机送到 LLM 面前，LLM 负责基于这些决策做判断。
+
+---
+
+## 四、从软约束到硬机制的光谱
+
+决策守卫不是单一机制，而是一个从软到硬的连续谱。
+
+### 4.1 Prompt 软约束：意义层（必要但不足够）
+
+把决策守卫写在 Prompt 里，要求 agent 在执行状态改变动作前主动检索 memory/、search_context、trace_theme。
+
+**Prompt 软约束是必须的**，因为它是让 agent **理解决策守卫意义**的关键。agent 需要知道：
+- 历史决策为什么重要
+- 什么时候应该检查
+- 检查到什么结果该怎么处理
+- 冲突时应该向用户报告而不是 silently 绕过
+
+没有这一层，任何工具或机制都会变成无意义的仪式。agent 可能机械地调用 `decision_guard`，但不理解为什么要重视返回结果。
+
+**但 Prompt 软约束本身不够**：
+- 长会话中 agent 会"忘记"
+- 检索质量不稳定
+- 发现冲突也只是文本提醒，agent 仍可能继续执行
+
+所以 Prompt 是**意义层**，负责解释"为什么"；还需要一个**机制层**，负责提醒"什么时候做"。
+
+### 4.2 提供专用检查工具（低侵入，中等可靠性）
+
+提供一个 `decision_guard(query)` 工具，让 LLM 用一步调用就能查到相关决策。
+
+```text
+LLM: 我要把 refresh token 存到 localStorage
+    │
+    ▼
+decision_guard("refresh token localStorage")
+    │
+    ▼
+返回：memory/decisions/auth-flow.md
+       "refresh token 不得存储在前端"
+```
+
+这比让 LLM 自己组织检索要容易，但仍然依赖自觉。
+
+### 4.3 任务层上下文注入（中等侵入，中等可靠性）
+
+当用户给出一个任务时，系统根据任务描述匹配相关 themes，把 decision clusters 注入到 LLM 初始上下文中。
+
+```text
+User: "帮我改一下 Auth 模块的 token 刷新逻辑"
+    │
+    ▼
+Orchestrator: 这个任务与 auth-flow 主题相关
+    │
+    ▼
+在 LLM 初始上下文中追加：
+"[相关决策] Auth 模块采用 JWT + httpOnly cookie 方案，
+ refresh token 不得存储在前端。"
+```
+
+这相当于"会议开场时把背景资料摆在桌上"，不需要监听 LLM 的 thinking。
+
+**局限**：只能覆盖用户明确提到的任务，无法处理会话中自发偏离。
+
+### 4.4 响应/计划层上下文注入（较高侵入）
+
+系统观察 LLM 的输出或计划，当检测到与某主题相关时，动态注入决策上下文。
+
+这需要某种形式的观察，侵入性比任务层更高。
+
+### 4.5 工具调用层 checkpoint（高侵入，高可靠性）
+
+在状态改变类工具调用执行前，系统暂停并要求 LLM 完成决策检索。
+
+```text
+LLM: 我要写 src/auth/token.ts
+    │
+    ▼
+Orchestrator: 这个文件与 auth-flow 主题相关，请先检查历史决策
+    │
+    ▼
+LLM 完成检索后，Orchestrator 决定是否放行
+```
+
+**问题**：
+- 侵入 orchestrator 核心流程
+- 每次 Write/Edit 都可能触发，增加延迟
+- 误判成本高，容易打断开发流
+- 只看工具调用参数，可能判断不出真实意图
+
+### 4.6 事后漂移检测（低侵入，滞后）
+
+不在执行前拦截，而是在 session 结束或 compaction 时，native 语义分析检查本次会话是否有与历史决策冲突的操作，生成报告。
+
+```text
+Session 结束
+    │
+    ▼
+native 分析本次 turns 和动作
+    │
+    ▼
+发现：本次提议"前端存储 refresh token"与 auth-flow 决策冲突
+    │
+    ▼
+生成 drift report，供用户 review
+```
+
+这是"发现后提醒"，不是"执行前阻止"。
+
+---
+
+## 五、关键张力：不存在完美方案
+
+决策守卫面临一个根本张力：
+
+| 方案 | 侵入性 | 可靠性 |
+|------|--------|--------|
+| 纯 LLM 自觉 | 零 | 低 |
+| 提供检查工具 | 低 | 中低 |
+| 任务层注入 | 中 | 中 |
+| 响应层注入 | 中高 | 中高 |
+| 工具调用 checkpoint | 高 | 高 |
+| 事后漂移检测 | 低 | 滞后 |
+
+**不存在一个既零侵入又高度可靠的方案。**
+
+任何系统侧的主动行为都需要某种形式的观察：
+- 要知道 LLM 在讨论什么主题
+- 要知道 LLM 准备改哪个文件
+- 要知道 LLM 当前的任务范围
+
+这些信息的获取本质上都需要读取 LLM 的输出、计划或工具调用意图。
+
+---
+
+## 六、推荐形态：TodoList 第零项
+
+在所有可选方案中，把 `decision_guard` 集成到 TodoList 内部作为**第零项**，是目前看起来最干净、最尊重 agent 自主性的形态。
+
+### 6.1 基本设计
+
+当 agent 创建一个较长的 coding todo list 时，系统自动在第零项插入 guard 任务：
+
+```text
+[TodoList]
+0. 🔍 decision_guard: 检查与本计划相关的历史决策
+1. 设计 JWT 认证流程
+2. 实现 refresh token 存储
+3. 添加登录页面
+```
+
+第零项意味着：
+- 它在所有实际工作之前
+- 它是一个显式的前置检查点
+- 它不参与后续编号竞争
+- 它是可选的，但足够显眼
+
+### 6.2 触发条件
+
+不是每个 todo list 都需要 guard。触发条件：
+
+- todo 项数量超过 N（如 3 或 4）
+- native 语义分析判断该 list 的 coding 强度超过阈值
+- 涉及架构、接口、依赖、数据模型等决策敏感领域
+
+```text
+coding_score > 0.6 且 项数 > 3  →  自动插入第零项
+coding_score < 0.6              →  不插入
+纯研究/讨论类 list               →  不插入
+```
+
+### 6.3 为什么放在第零项而不是自动调用
+
+| 方式 | 问题 | 第零项方式 |
+|------|------|-----------|
+| 系统自动静默调用 | agent 不知道发生了什么 | agent 在自己的计划里看到 guard 任务 |
+| 纯 Prompt 软约束 | agent 可能忘记 | todo 项是显式的，无法忽视 |
+| 工具调用拦截 | 高侵入 | 不拦截任何动作 |
+| 任务层自动注入 | 系统替 agent 决定 | agent 自己执行 guard |
+
+注意：第零项不是替代 Prompt，而是**承载 Prompt**。Prompt 解释意义，第零项提供时机。
+
+第零项的关键优势：**它既提供了强提醒，又保留了 agent 的跳过权利**。
+
+### 6.4 信任 agent 的正常性
+
+如果 agent 直接划掉第零项不执行，这本身是一个有效信号：
+
+- 这个计划可能不够严肃，只是脑暴或试探
+- 或者确实不需要决策守卫
+- 或者 agent 自己已经判断没有相关决策
+
+**不应该假设 agent 恶意**。设计的正确假设是：
+
+```text
+错误假设：agent 会故意违反决策 → 需要强制拦截
+正确假设：agent 会遗忘或没意识到 → 给它一个无法遗忘的提醒
+```
+
+第零项就是那个"无法遗忘的提醒"。
+
+### 6.5 执行与上下文增强
+
+agent 执行第零项时调用 `decision_guard(query)`：
+
+```text
+LLM: 执行第零项
+    │
+    ▼
+decision_guard("auth token frontend-state")
+    │
+    ▼
+返回相关 decision clusters
+    │
+    ▼
+系统把决策追加到当前上下文顶部
+```
+
+这样即使 agent 只是"完成"了 guard 项，上下文已经被增强，后续 todo 执行时会自然看到这些决策。
+
+### 6.6 被跳过的处理
+
+如果 agent 跳过第零项，系统记录：
+
+```text
+guard_item_0: skipped_by_agent
+inferred_reason: agent_judged_unnecessary
+```
+
+这个记录不用于惩罚或拦截，只用于：
+- 事后复盘时参考
+- 帮助优化触发条件
+- 发现 agent 是否系统性忽略 guard
+
+### 6.7 Prompt 软约束与第零项的关系
+
+第零项是**机制层**，负责在正确时机提醒 agent 执行 guard。但它不能替代 **Prompt 软约束（意义层）**。
+
+完整的工作方式是：
+
+```text
+系统 Prompt 中：
+"在改变项目状态前，你应该检查相关历史决策。
+ 当 todo list 出现第零项 decision_guard 时，请优先执行它。
+ 如果发现冲突，向用户报告并请求澄清，不要 silently 绕过。"
+
+实际运行时：
+[TodoList]
+0. 🔍 decision_guard: 检查与本计划相关的历史决策
+1. 设计 JWT 认证流程
+```
+
+Prompt 回答"为什么"和"怎么处理"，第零项回答"什么时候做"。两者结合：
+- Prompt 让 agent 理解决策守卫的意义
+- 第零项让 agent 无法忘记执行
+
+没有 Prompt，第零项只是一个无意义的仪式；没有第零项，Prompt 只是容易被遗忘的嘱咐。
+
+---
+
+## 七、`decision_guard` 工具设计
+
+### 7.1 基础设施 2 之后的成本结构
+
+在主题检索基础设施化之前，`decision_guard` 的成本很高：
+
+```text
+当前：
+search(memory/) + search_context() + trace_theme()
+    │
+    ▼
+LLM 从大量原始文本中找决策、判断是否冲突
+```
+
+每一步都有 token 开销：检索需要 LLM 理解上下文，分析需要 LLM 从结果中提炼决策。
+
+基础设施 2 之后：
+
+```text
+未来：
+nativeQuery(memory/)  → 命中决策条目（无 token）
+nativeQuery(turns/)   → 命中相关 clusters（无 token）
+    │
+    ▼
+LLM 只读少量已命中的 memory + turns，判断是否有决策冲突
+```
+
+**关键变化**：
+- 检索本身没有 token 开销
+- 返回结果是已经被语义化提炼过的 clusters
+- LLM 只需要做最后的判断
+- 决策守卫的性价比因此变高
+
+### 7.2 工具只做召回，不做判断
+
+`decision_guard` 的定位是**材料准备工具**，不是**冲突判断工具**。
+
+**冲突判断必须由 LLM 自己完成**，因为：
+- 冲突往往是语境化的
+- "冲突"可能只是合法的决策演进
+- 决策有优先级和边界，需要权衡
+- 只有 LLM 理解当前动作的真实意图
+
+所以工具内部不应该输出"冲突/不冲突"的结论，只输出"相关材料"。
+
+### 7.3 输入
+
+```json
+{
+  "query": "auth token refresh localStorage"
+}
+```
+
+`query` 描述当前计划或动作。context 不是必须的，因为 native query 会根据语义自动召回。
+
+### 7.4 内部实现
+
+```text
+decision_guard(query)
+    │
+    ├── nativeQuery(memory/, query)
+    │     └── 命中决策、规则、知识条目
+    │
+    └── nativeQuery(turns/clusters/, query)
+          └── 命中历史讨论 clusters
+                │
+                ▼
+        返回给 LLM：
+          - 相关 memory 条目
+          - 相关 turns/clusters 摘要
+                │
+                ▼
+        LLM 判断是否存在冲突
+```
+
+为什么只需要 memory 和 turns：
+- **memory** 保存决策结论
+- **turns/clusters** 保存决策形成过程的上下文
+- 单独的 context 查询不再必要，因为 context 已经在 turns 里
+
+### 7.5 返回值
+
+```json
+{
+  "status": "ok",
+  "query": "auth token refresh localStorage",
+  "hits": {
+    "memory": [
+      {
+        "source": "memory/decisions/auth-flow.md",
+        "title": "JWT + httpOnly cookie 方案",
+        "content": "refresh token 不得存储在前端",
+        "relevance_score": 0.94
+      }
+    ],
+    "turns": [
+      {
+        "cluster_id": "cluster-3",
+        "theme": "auth-flow",
+        "summary": "确定 JWT + httpOnly cookie 的 Auth 方案",
+        "decision": true,
+        "relevance_score": 0.91
+      }
+    ]
+  },
+  "llm_judgment_required": true,
+  "summary": "找到 auth-flow 相关决策和讨论，请 LLM 判断是否冲突"
+}
+```
+
+注意：返回值中没有 `conflict` 或 `recommendation` 字段。工具不替 LLM 判断，只负责把相关材料摆在它面前。
+
+### 7.6 LLM 的判断 prompt
+
+工具返回后，LLM 应该收到类似这样的提示：
+
+```text
+你计划执行：把 refresh token 存储在 localStorage
+
+相关历史决策：
+- memory/decisions/auth-flow.md: "refresh token 不得存储在前端" (relevance: 0.94)
+
+相关历史讨论：
+- cluster-3 (auth-flow): "确定 JWT + httpOnly cookie 的 Auth 方案" (relevance: 0.91)
+
+请判断：
+1. 这些材料中是否有与你当前计划冲突的决策？
+2. 如果有，请引用来源并说明冲突点。
+3. 如果没有，请说明可以继续执行。
+4. 如果旧决策的前提已经变化，请说明原因并建议更新决策。
+```
+
+---
+
+## 九、更诚实的定位
+
+决策守卫不应该被描述为一个已经确定的原生强制机制，而应该被理解为：
+
+> **一组按侵入性排序的可选机制，用于帮助 LLM 在意识层记起历史决策。**
+
+最理想的形态是 LLM 自发地、习惯性地检查历史决策。当自觉性不足时，系统可以在任务层面预加载决策。对于核心架构决策，才考虑更高侵入性的执行前检查。
+
+**核心原则**：
+- 决策守卫的目标不是禁止变化
+- 而是确保**变化被看见、被评估、被记录**
+- 系统负责把决策送到 LLM 面前
+- LLM 负责基于决策做判断
+
+---
+
+## 十、与主题检索基础设施的关系
+
+主题检索基础设施化让决策守卫变得更可行，因为它提供了：
+
+- **结构化的决策单元**：theme 中的 `decision: true` clusters
+- **低成本的语义匹配**：native semantic analysis 可以快速判断当前讨论/动作与哪些决策相关
+- **决策演进的时间线**：每个决策 cluster 都有关联 turns 和历史上下文
+
+但主题基础设施解决的是"决策如何被存储和检索"，不是"如何强制 LLM 遵守决策"。后者仍然是一个开放的认知问题。
+
+---
+
+## 十一、设计建议
+
+1. **首选 TodoList 第零项**：对于 coding todo list，当长度和复杂度超过阈值时，自动插入 `decision_guard` 作为第零项。这是目前最干净、最不侵入的形态。
+2. **信任 agent 的正常性**：如果 agent 跳过第零项，不强制拦截。agent 直接划掉 guard 本身说明该计划可能不需要守卫。
+3. **从软到硬逐步引入**：先提供工具和任务层注入，再探索更强机制
+4. **可配置性优先**：不同 theme、不同动作类型可以配置不同的守卫强度
+5. **避免误杀**：实验目录、prototype、spike 应该默认低强度
+6. **演进通道**：不是简单阻断，而是提供"更新决策"的路径
+7. **反馈循环**：当 LLM 违反决策时，把冲突信息返回给 LLM，帮助其形成检查习惯
+
+---
+
+## 十二、结论
+
+决策守卫是一个重要但棘手的问题。
+
+它不是靠一个"原生强制 checkpoint"就能干净解决的。真正的解决方案更可能是：**让检查历史决策成为 LLM 最自然、成本最低的行为选择**，而不是靠外部系统强制控制。
+
+当前最推荐的形态是 **TodoList 第零项**：当 agent 创建较长的 coding todo list 时，系统自动插入 `decision_guard` 作为第零项。agent 可以选择执行或跳过，这种设计既提供了强提醒，又尊重了 agent 的自主性。
+
+主题检索基础设施化是必要条件，但不是充分条件。充分的解决方案需要：
+- 更好的上下文设计
+- 更好用的检查工具
+- 更自然的反馈循环
+- 以及承认有些场景下只能依赖 LLM 自觉
+
+---
+
+*文档性质：设计思考 / 讨论稿*  
+*生成时间：2026-06-23*  
+*与任何具体项目无关*

package/docs/ARCHITECTURE.md

@@ -67,7 +67,7 @@ This document explains how Kimi Code Memory MCP Server is structured, how data f
 | `src/server.ts` | MCP server entry, registers tools, starts stdio transport. |
 | `src/config.ts` | Default paths, environment variable handling (`MEMORY_STORE_ROOT`, `MEMORY_SESSIONS_ROOT`, `KIMI_CODE_HOME`). |
 | `src/tools/index.ts` | Tool schemas, validation, and dispatch. |
-| `src/tools/memory-tools.ts` | `remember`, `recall`, `recall_recent`, `search`, `list`, `list_tags`, `delete`, `move`. |
+| `src/tools/memory-tools.ts` | `remember`, `recall`, `search`, `list`, `list_tags`, `delete`, `move`. |
 | `src/tools/context-tools.ts` | `load_workspace_context`, `load_more_context`, `search_context`, `load_turn_context`. |
 | `src/tools/theme-tools.ts` | `tag_theme`, `trace_theme`, `list_themes`, `refine_session_turns`. |
 | `src/tools/system-tools.ts` | `organize_memories`, `sync_workspace_index`, `bootstrap_workspace`, `get_current_workspace`. |
@@ -115,7 +115,7 @@ This document explains how Kimi Code Memory MCP Server is structured, how data f
 
 1. **Capture** — Agent writes a memory via `remember`.
 2. **Index** — `IndexDao` updates `index.json` and writes the `.md` file.
-3. **Recall** — Agent uses `search`, `recall`, or `recall_recent` to retrieve memories.
+3. **Recall** — Agent uses `search`, `recall`, or `list` to retrieve memories.
 4. **Distill** — `organize_memories` condenses `memory/` into `essence/essence.md` (≤15 KB).
 5. **Trace** — `tag_theme` and `trace_theme` connect memories and conversation turns into evolving themes.
 6. **Archive/Move** — `move` renames or relocates a memory; `delete` removes it.