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

package/docs/3.memory-skill-prompt-design.md

@@ -0,0 +1,430 @@
+# Memory Skill Prompt 设计文档
+
+> 本文档描述如何设计一个 Prompt，让 Agent 从"金鱼脑的临时工"升级为"带档案的老法师"。它建立在 Memory MCP 的工具层之上，解决的不是"记性好不好"，而是"行为一致性（Consistency）"的问题。
+
+---
+
+## TL;DR
+
+Memory Skill 的核心任务只有三个：
+
+1. **该记的时候记** —— 把决策、规则、知识沉淀到 `memory/`
+2. **该查的时候查** —— 做决策前先翻档案
+3. **该整理的时候整理** —— 把 `memory/` 蒸馏成 `essence.md`
+
+所有规则围绕一个目标：让 Agent 的行为依赖于历史沉淀，而不是当前上下文的运气。
+
+---
+
+## 一、设计哲学
+
+### 1.1 为什么是"一致性"而不是"记性"
+
+没有记忆系统时，Agent 的决策是"无根的"：
+
+- 上一轮刚定好的架构，新开 Session 可能因为 prompt 变化而选相反的路
+- 长周期项目里，周一做 Auth，周三做性能，周五回来 Auth 的上下文已经丢失
+- 上下文窗口溢出后，Agent 会"突然失智"
+
+有了记忆系统后：
+
+- 决策有锚点：`memory/decisions/` 保存"我们为什么这样决定"
+- 任务有主题：`themes/` 把散落在多周的 Auth 讨论连成一条线
+- 不会失智：`essence.md` 作为 ≤15KB 的"工作宪法"，无论当前对话多乱都能回到核心规则
+
+### 1.2 三层记忆模型
+
+```text
+┌─────────────────────────────────────────────┐
+│  Layer 1: 工作宪法                           │
+│  essence/essence.md (≤15KB)                  │
+│  当前什么最重要                               │
+└───────────────────┬─────────────────────────┘
+                    │ 由 organize_memories 提炼
+                    ▼
+┌─────────────────────────────────────────────┐
+│  Layer 2: 结构化长期记忆                      │
+│  memory/                                     │
+│  ├── decisions/   关键决策                    │
+│  ├── rules/       协作规则与编码红线          │
+│  └── knowledge/   项目知识与技术方案          │
+└───────────────────┬─────────────────────────┘
+                    │ 由 remember / recall / search 操作
+                    ▼
+┌─────────────────────────────────────────────┐
+│  Layer 3: 对话追溯与主题提炼                  │
+│  wire.jsonl  →  refined/  →  themes/        │
+│  原始记录      每轮摘要      主题视图         │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 二、启动协议（Boot Protocol）
+
+每次新会话开始后、回答用户第一个问题之前，Agent 必须执行：
+
+```text
+Session Start
+    │
+    ▼
+bootstrap_workspace()
+    │
+    ├──► 读取 essence.md        → 知道"现在什么重要"
+    │
+    ├──► 读取 memoryIndexTree   → 知道"我知道什么"，关注 [new]
+    │
+    ├──► 读取 recentContext     → 知道"刚才聊到哪了"
+    │
+    └──► 读取 notesRefs         → 知道"有没有待处理速记"
+         │
+         ▼
+    回答用户问题
+```
+
+**纪律**：完成以上步骤前，不要执行任何会改变项目状态的操作（写文件、运行命令等）。
+
+---
+
+## 三、记录规则
+
+### 3.1 什么时候必须 `remember`
+
+出现以下任一信号，立即写入 `memory/`：
+
+| 信号 | 用户说法示例 | folder | tag |
+|------|-------------|--------|-----|
+| 决策 | "我们决定用方案 A"、"拍板了" | `memory/decisions/` | `decision` |
+| 规则 | "这里必须…"、"红线是…" | `memory/rules/` | `rule` |
+| 知识 | 首次解释技术选型、接口约定、业务术语 | `memory/knowledge/` | `knowledge` |
+| 修复 | 定位到 bug 根因和修复方案 | `memory/decisions/` 或 `memory/knowledge/` | `fix` |
+| 约定 | 编码风格、目录结构、命名规范 | `memory/rules/` | `convention` |
+
+### 3.2 few-shot 示例
+
+**场景：决策**
+
+```text
+用户：我们决定用 Tauri 的 command 模式做 IPC，不直接暴露 fs。
+
+→ Agent 调用：
+   remember(
+     key: "ipc-use-command-pattern",
+     folder: "memory/decisions",
+     tags: ["decision", "ipc", "tauri"],
+     content: |
+       IPC 采用 Tauri command 模式，前端通过 invoke 调用 Rust 命令。
+
+       原因：避免直接暴露 Node/fs API，减少攻击面。
+
+       影响范围：所有前端 ↔ Rust 的通信接口。
+
+       相关文件：src/ipc/、src-tauri/src/commands/
+   )
+
+→ Agent 回复：
+   "已记录到 memory/decisions/ipc-use-command-pattern。"
+```
+
+### 3.3 什么时候不要 `remember`
+
+防止记忆库变成垃圾堆：
+
+- 临时调试命令或探索性代码
+- 用户未确认的推测
+- 一次性报错（没有形成通用结论）
+- 当前会话的临时上下文（由 `wire.jsonl` 自动捕获）
+- 已经在 `memory/` 中存在的知识
+
+**判断口诀**：
+
+> 如果这条信息三天后回头看仍然有价值，才写入 `memory/`；否则让它留在 `wire.jsonl` 里。
+
+---
+
+## 四、查询规则
+
+### 4.1 什么时候该"翻旧账"
+
+Agent 应在以下节点主动查询记忆：
+
+1. **启动后首次处理该工作区** → `bootstrap_workspace`（已自动执行）
+2. **要做架构/接口/流程决策前** → `search` 相关 `decision` 和 `rule`
+3. **用户提到"之前"、"上次"、"我们之前定过"** → `recall` 具体 key 或 `search` 关键词
+4. **要修改某个已有功能前** → `search` 该功能相关的决策和知识
+5. **出现与之前结论矛盾的倾向时** → 立即 `search` 验证历史决策
+6. **主题追溯请求** → 按"主题追溯冷启动规则"执行
+
+### 4.2 few-shot 示例
+
+**场景：用户提到历史**
+
+```text
+用户：我们之前是不是说过不要在前端直接调用 fs？
+
+→ Agent 调用：
+   search(query: "前端 fs", folder: "memory")
+
+→ 命中 memory/decisions/frontend-no-direct-fs 后调用：
+   recall(key: "frontend-no-direct-fs", folder: "memory/decisions")
+
+→ Agent 回复：
+   "是的，根据 memory/decisions/frontend-no-direct-fs，我们决定通过 Tauri command
+    模式暴露文件操作，避免前端直接调用 fs。"
+```
+
+---
+
+## 五、主题追溯冷启动规则
+
+当用户要求追溯某个主题时，**禁止直接全量提炼所有历史对话**。
+
+### 5.1 标准流程
+
+```text
+用户："Auth 流怎么发展到现在的？"
+    │
+    ▼
+确认主题范围
+"你指的是登录、注册、Token 刷新还是权限校验？"
+    │
+    ▼
+索要关键词种子（1-3 个）
+"比如 auth、token、jwt、refresh"
+    │
+    ▼
+search_context 粗筛候选 turns
+    │
+    ▼
+用户确认 / 补充候选
+    │
+    ▼
+refine_session_turns 提炼缺失 turns
+    │
+    ▼
+tag_theme 生成 themes/<theme>.json
+    │
+    ▼
+trace_theme 输出主题时间线
+```
+
+### 5.2 禁止行为
+
+- 没有关键词种子就全量提炼
+- 把粗筛候选直接当成最终结果，不经过用户确认或至少明示"基于这些候选"
+
+### 5.3 为什么必须冷启动
+
+提炼是按需计算的昂贵操作；用户种子决定召回率，是避免遗漏关键 turns 的前提。同时，盲目提炼会把无关内容混入主题，降低主题视图质量。
+
+---
+
+## 六、整理规则
+
+### 6.1 什么时候整理 `essence.md`
+
+- `memory/` 下新增 3-5 条关键决策/规则后
+- 用户说"整理一下记忆"、"更新精要"
+- `essence.md` 接近或超过 15KB
+- 项目完成重要里程碑（版本发布、架构重构完成）
+
+### 6.2 整理流程
+
+```text
+触发条件满足
+    │
+    ▼
+organize_memories() 空参调用
+    │
+    ▼
+返回 essence.md + memory/ 原材料 + 规则
+    │
+    ▼
+Agent 生成新的精要 content（≤15KB）
+    │
+    ▼
+organize_memories(content) 存储
+```
+
+### 6.3 整理纪律
+
+- 关键结论必须 inline 标注来源：`> 来源：memory/decisions/ipc-use-command-pattern`
+- 不删除任何 `memory/` 源文件
+- 超过 15KB 时工具会警告，但允许写入；下次整理时应进一步压缩
+- `notes/` 不参与整理
+
+---
+
+## 七、引用来源的纪律
+
+所有从 `memory/` 召回的关键结论，在回复中必须标注来源：
+
+- ✅ "根据 `memory/decisions/ipc-use-command-pattern`，我们决定…"
+- ✅ "如 `essence.md` 中总结的…"
+- ❌ "我们之前决定…"（无来源）
+
+如果记忆与当前情况冲突，不要自动覆盖记忆，而是向用户提出澄清：
+
+> "当前方案与 `memory/decisions/xxx` 中记录的决策冲突，是否需要更新该决策？"
+
+---
+
+## 八、记忆卫生检查清单
+
+### 8.1 每次调用 `remember` 前
+
+- [ ] 这条信息三天后还有价值吗？
+- [ ] 它属于 `decision` / `rule` / `knowledge` / `fix` / `convention` 之一吗？
+- [ ] 是否已经有重复的记忆？（先 `search`）
+- [ ] `folder` 选对了吗？项目相关不进 `notes/`
+- [ ] `tags` 是否包含最贴切的分类标签？
+- [ ] 正文是否包含决策原因/影响范围/相关文件？
+
+### 8.2 每次做决策前
+
+- [ ] 是否已 `search` 相关历史决策？
+- [ ] 是否已检查 `essence.md` 中的核心约束？
+- [ ] 如果与历史记忆冲突，是否已向用户澄清？
+
+---
+
+## 九、决策守卫（Decision Guard）
+
+在你准备执行任何可能改变项目状态的操作之前（写文件、改结构、做选择、引入依赖），必须执行一次决策守卫。
+
+### 9.1 触发条件
+
+满足以下任一条件，必须暂停并主动检索记忆：
+
+**决策型触发**：
+- 你要做出架构/接口/数据模型选择
+- 你要引入、删除或替换依赖
+- 你要修改目录结构或移动核心文件
+- 你要删除或重写已有功能
+- 你的方案可能影响多个模块的协作方式
+
+**推理性触发（无根盲推）**：
+- 你使用了"我觉得"、"我认为"、"也许"、"暂定"、"先这样"等不确定表达
+- 你引入了新方案但没有引用任何历史决策
+- 你的方案与 `essence.md` 或 `memory/` 中的规则可能矛盾
+- 你使用了新的命名/结构风格，与项目约定不一致
+- 你解释了"为什么这样做"但没有给出具体来源
+
+### 9.2 检索流程
+
+```text
+准备执行关键动作
+    │
+    ▼
+提取关键词（技术实体 + 动作）
+    │
+    ▼
+并行查询：
+  ├── search(query, folder="memory")     → 查决策/规则/知识
+  ├── search_context(query)              → 查历史对话
+  └── 关键词像主题 → trace_theme(theme)  → 查主题发展
+    │
+    ▼
+评估检索结果
+    │
+    ├── 命中且一致 → 引用来源后继续执行
+    ├── 命中但矛盾 → 向用户报告冲突，请求澄清
+    ├── 未命中但重要 → 询问用户"这是一个新决策，是否记录？"
+    └── 未命中且影响小 → 继续执行，但标记为待观察
+```
+
+### 9.3 关键词提取
+
+从你的当前方案中提取：
+- 技术实体：Tauri、command、IPC、PlayerState、zustand
+- 动作实体：引入、删除、修改、选择、替代
+- 领域实体：frontend、backend、database
+
+生成 2-3 个查询变体，分别投向 `search()` 和 `search_context()`。
+
+### 9.4 最小自检
+
+如果你没时间走完整流程，至少问自己：
+
+1. 这个决定会影响架构、接口或数据模型吗？
+2. `memory/` 里是否已经有相关决策或规则？
+3. `essence.md` 里是否有相关约束？
+
+如果任一答案为"是"，必须先 `search()` 再执行。
+
+### 9.5 为什么需要决策守卫
+
+没有守卫时，Agent 容易：
+- 新开 Session 就推翻昨天刚定的架构
+- 在长周期项目里反复重新解释"为什么这样设计"
+- 上下文窗口溢出后"突然失智"
+
+决策守卫让 Agent 在**动作之前**就把当前方案与历史沉淀对齐，把一致性从"希望"变成"机制"。
+
+---
+
+## 十、与 MCP 工具的映射
+
+| Skill 规则 | MCP 工具 | 作用 |
+|------------|----------|------|
+| 启动协议 | `bootstrap_workspace` | 加载精要、目录树、上下文、速记 |
+| 写入决策/规则/知识 | `remember` | 写入 `memory/` |
+| 精确读取 | `recall` | 按 key+folder 读取 |
+| 关键词搜索 | `search` | 在记忆标题/内容中搜索 |
+| 最近记忆 | `recall_recent` | 读取最近更新的记忆 |
+| 查询历史 | `search_context` | 跨 session 搜索对话 |
+| 加载指定轮次 | `load_turn_context` | 读取具体 turn 的完整内容 |
+| 主题追溯 | `tag_theme` / `trace_theme` / `refine_session_turns` | 主题关联与演化 |
+| 整理精要 | `organize_memories` | 生成/更新 `essence.md` |
+| 同步索引 | `sync_workspace_index` | 重建 `index.json` / 设置 folder 备注 |
+
+---
+
+## 十一、常见误区
+
+### 误区 1：什么都记
+
+记忆库不是垃圾桶。什么都记会导致：
+- `search` 召回噪音大
+- `essence.md` 难以聚焦
+- Agent 被过时信息干扰
+
+**解法**：严格执行"三天后是否有价值"判断。
+
+### 误区 2：从不翻旧账
+
+只记不查，记忆系统就失去意义。
+
+**解法**：在做任何可能影响架构、接口、流程的决策前，先 `search` 相关历史。
+
+### 误区 3：主题追溯盲跑
+
+没有关键词种子就全量提炼，会：
+- 浪费计算
+- 混入无关 turns
+- 让用户感到 Agent 在"瞎猜"
+
+**解法**：坚持冷启动流程，先确认范围再索要关键词。
+
+### 误区 4：记忆与现状冲突时自动覆盖
+
+历史记忆可能是正确的约束，当前用户的临时需求可能是例外。
+
+**解法**：标注冲突，向用户澄清，由用户决定是否更新记忆。
+
+---
+
+## 十二、设计口诀
+
+> **AGENTS.md 定义你是谁。essence.md 定义现在什么重要。memory/ 定义你知道什么。themes/ 定义知识如何连接。refined/ 定义你实际做了什么。**
+>
+> **memory/ 是自由生长的花园，essence.md 是剪出来的盆景，index.json 是花园的导览图，memoryIndexTree 是导览图上高亮最近改动的批注。**
+>
+> **wire.jsonl 是录音，refined/ 是翻译稿，themes/ 是索引，memory/ 是正典。**
+>
+> **该记则记，该查则查，该整理则整理。不要当金鱼，也不要当囤积狂。**
+
+---
+
+*文档生成时间：2026-06-23*  
+*描述对象：Memory Skill Prompt 设计*