kimi-code-memory-mcp-server 0.1.1 → 0.2.0

package/docs/1.memory-system-proposal-for-kimi-code.md

@@ -0,0 +1,688 @@
+# 建议 kimi-code 采用的记忆系统：三层模型 + Markdown 优先 + 主题追溯
+
+> 提交者：Zehee & K2.7 Code thinking
+> 日期：2026-06-23  
+> 性质：架构建议 / 讨论稿  
+
+---
+
+## TL;DR
+
+当前 Agent 记忆系统的主流趋势是**越堆越重**：向量数据库、图数据库、embedding 检索、多策略 rerank……这些方案在特定场景下有效，但作为通用编程助手的默认记忆基础设施，它们存在三个根本问题：
+
+1. **把记忆当成无差别囤积的数据**，而非经过判断和编排的信息；
+2. **引入沉重的外部依赖**，与 IDE/CLI 工具追求的轻量、本地、离线可用相矛盾；
+3. **模糊了"记忆"与"搜索"的边界**——如果一切都可以靠 web search 或向量检索补回，那记忆系统本身就失去了存在的意义。
+
+本文建议 kimi-code 采用一种**更轻、更结构化、更符合工程直觉**的记忆范式：
+
+- **三层记忆模型**：持续认知层、持久化知识库、上下文保持与回忆；
+- **Markdown 优先**：用人类可读的 Markdown 文件作为记忆的默认载体；
+- **主题追溯**：把跨 session 的主题关联作为上下文回忆的核心横向能力。
+
+这种方案不需要向量数据库或图数据库，却能在绝大多数 coding-agent 场景下提供足够好的记忆体验。
+
+**本文不仅提出理论，也分享了我们基于这一理论实现的一个 memory MCP server 的具体数据结构与设计权衡。**
+
+---
+
+## 一、当前记忆系统的两条歧途
+
+### 歧途一：把记忆做成"第二互联网"
+
+向量数据库 + 大规模 RAG 的思路，本质上是：
+
+> **把所有历史对话都存下来，用的时候靠语义相似度捞一捞。**
+
+这有什么问题？
+
+- **记忆失去了筛选机制**：互联网已经是全人类的"外脑"，如果 Agent 的本地记忆也是无差别的海量数据，那它和 Google 的区别只在于数据来源；
+- **检索质量不可控**：语义相似不等于主题相关，coding 场景中"相似"的代码片段往往是不同上下文下的干扰项；
+- **可解释性差**：模型为什么召回这条记忆？用户很难理解和修正。
+
+如果 Agent 的记忆只是一个小号的、私人的互联网，那它就不值得单独做一个系统。用户直接开浏览器搜索即可。
+
+### 歧途二：把记忆做成"第二数据库"
+
+图数据库（Neo4j）、时序知识图、复杂的关系schema……这些方案在语义建模上很优雅，但对 coding agent 来说：
+
+- **运维成本高**：需要额外服务、索引、迁移、备份；
+- **写放大严重**：每条对话都要经过实体抽取、关系链接、冲突消解；
+- **与人类工作流割裂**：开发者不会为了"让 Agent 记住"而先去维护一个知识图谱。
+
+记忆系统应该**服务于人的工作流**，而不是反过来要求人为记忆系统建模。
+
+---
+
+## 二、记忆的边界：什么是值得记的？
+
+在讨论"怎么实现"之前，必须先回答一个更基础的问题：
+
+> **Agent 应该记住什么？**
+
+我们的答案是：**记忆应该是经过判断、梳理、编排后的信息，而不是原始数据的堆积。**
+
+具体来说，只有三类信息值得被持久化：
+
+1. **持续认知层**：我是谁、我遵循什么规则、我的核心偏好——这是 Agent 的"人格与底线"；
+2. **持久化知识库**：项目的事实、决策、模式、约定——这是 Agent 的"工作笔记"；
+3. **上下文保持与回忆**：当前对话的近期状态——这是 Agent 的"工作记忆"。
+
+其他的，比如：
+
+- 某一次具体提问的完整原文
+- 已经过时的调试过程
+- 可以通过文件系统、git log、web search 重新获得的信息
+
+都不应该成为"记忆"。它们应该留在 wire.jsonl 里作为审计痕迹，或者干脆丢弃。
+
+---
+
+## 三、三层记忆模型
+
+### 3.1 持续认知层：永远在场的人格与规则
+
+| 属性 | 说明 |
+|---|---|
+| 作用域 | 跨 project、跨 session、始终激活 |
+| 内容 | 身份、核心价值观、关键规则、语言偏好 |
+| 更新频率 | 低，但支持热加载 |
+| 容量 | 小，必须严格限制 |
+| 载体 | `AGENTS.md` / `CLAUDE.md` / `essence.md` 等 |
+
+这一层的典型内容是：
+
+- "你是一个全栈开发工程师，负责前后端一体化实现"
+- "始终使用中文回复用户"
+- "禁止执行任何 git 突变，除非用户明确授权"
+- "涉及 IPC 信号变更时，同时维护 Rust struct + TypeScript interface"
+
+**设计原则**：
+
+- **小而确定**：宁可少记，不可多记。超出容量上限时，必须让用户主动决定替换哪一条；
+- **人类可编辑**：用户应该能直接打开文件查看和修改；
+- **热加载**：修改后下一轮即可生效，不需要重启 session。
+
+#### 我们的实践：`essence.md` 作为持续认知层
+
+在我们实现的 memory MCP server 中，持续认知层对应 `essence/essence.md`。它的设计约束是：
+
+- **大小上限 15KB**：超过则拒绝写入，强制用户精简；
+- **由 `organize_memories` 生成**：从 `memory/` 中的分散笔记提炼浓缩；
+- **人类可编辑**：用户可以直接修改，下次启动时通过 `bootstrap_workspace` 加载；
+- **来源可追溯**：每条关键事实都 inline 引用来源 memory 文件。
+
+这实际上就是把"人格与底线"从隐式的 prompt 工程，变成了显式的、受控的、可审计的文件。
+
+---
+
+### 3.2 持久化知识库：结构化工作笔记
+
+| 属性 | 说明 |
+|---|---|
+| 作用域 | 按 user / workspace / project 划分 |
+| 内容 | 事实、决策、代码模式、项目约定、历史经验 |
+| 更新频率 | 中 |
+| 容量 | 中等，持续增长但需定期归档 |
+| 载体 | Markdown 文件 + JSON 索引 |
+
+这一层不是对话历史的堆积，而是**被提炼过的知识**。例如：
+
+- `memory/decisions/persistence-design.md`：持久化架构决策
+- `memory/knowledge/frontend-stack.md`：项目前端技术栈说明
+- `memory/knowledge/hil-refactor.md`：HIL 重构方案记录
+
+**为什么用 Markdown？**
+
+- 人类可读、可编辑、可版本控制；
+- 天然支持标题、列表、代码块、链接；
+- 与 LLM 的上下文格式高度兼容；
+- 不需要专用客户端，任何文本编辑器都能打开。
+
+**为什么用 JSON 索引？**
+
+- 只记录文件路径、标题、标签等元数据；
+- 文件内容本身是真相源；
+- 索引可以高效地完成搜索、过滤、列表；
+- 索引损坏时可以通过扫描文件系统重建。
+
+#### 我们的实践：memory/ 文件夹 + `index.json` v3-kv
+
+我们在 memory MCP 中采用的存储结构如下：
+
+```
+store/workspace-110b6be4/
+├── index.json              # v3-kv 轻量索引
+├── essence/
+│   └── essence.md          # 持续认知层（≤15KB）
+├── memory/
+│   ├── decisions/          # 决策类记忆
+│   ├── knowledge/          # 知识类记忆
+│   ├── rules/              # 规则类记忆
+│   └── agent-memory-three-layer-model.md
+├── notes/
+│   └── ops-current-state.md
+├── themes/                 # 横向主题关联图
+│   └── memory-mcp-evolution.json
+└── refined/                # 按需提炼的 turn summaries
+    └── <sessionId>.jsonl
+```
+
+`index.json` 采用 v3-kv 格式，不是传统的 entries 表，而是**以文件路径为 key 的扁平索引**：
+
+```json
+{
+  "version": "3-kv",
+  "meta": {
+    "lastSyncAt": "2026-06-23T03:32:00Z",
+    "structureHash": "a1b2c3d4"
+  },
+  "index": {
+    "memory/": { "comment": "完整记忆索引" },
+    "memory/decisions/": { "comment": "关键产品/架构决策" },
+    "memory/decisions/persistence-design.md": {
+      "title": "Persistence Design",
+      "tags": ["decision", "architecture", "persistence"]
+    },
+    "memory/knowledge/agent-memory-three-layer-model.md": {
+      "title": "Agent 记忆系统三层模型",
+      "tags": ["knowledge", "memory", "architecture"]
+    }
+  }
+}
+```
+
+关键设计：
+
+- **文件是真相源**：索引只是缓存，丢失后可扫描重建；
+- **`structureHash`**：扫描 `memory/`、`notes/`、`essence/` 下所有文件路径后计算 MD5，快速判断目录结构是否变化；
+- **DAO 层**：所有工具通过 DAO 读写索引，保证索引与文件系统一致；
+- **无向量、无图数据库**：检索基于路径、标签、标题、BM25/keyword。
+
+每条 Markdown 记忆都有 YAML frontmatter：
+
+```yaml
+---
+key: agent-memory-three-layer-model
+folder: memory
+tags: [decision, memory, architecture]
+---
+```
+
+这让人类能一眼看出这条记忆的分类、用途和归属。
+
+---
+
+### 3.3 上下文保持与回忆：工作记忆 + 主题追溯
+
+| 属性 | 说明 |
+|---|---|
+| 作用域 | 单 session 为主，但可横向跨越多个 session |
+| 内容 | 当前对话状态、近期动作、未决问题、主题关联链 |
+| 更新频率 | 高，每轮交互 |
+| 容量 | 受上下文窗口限制 |
+| 载体 | wire.jsonl + 提炼层 + 主题关联图 |
+
+传统的上下文管理只关注**纵向**：时间越近越清晰，越久越远越衰减。但这忽略了真实工作的一个核心特征：
+
+> **同一个 workspace 中的多次会话，往往不是单一叙事，而是多条主题线交织并行。**
+
+例如：
+
+- Session A：开发狼人杀法官助手
+- Session B：发现上下文保存不可靠 → 开始设计 memory MCP server
+- Session C：HIL 测试框架重构
+- Session D：kimi web cwd 问题 → 向上游提 PR
+- Session E：讨论 Agent 记忆系统架构
+
+如果只看纵向，这些 session 彼此独立。但如果横向扫描，会发现 B、D、E 都属于"memory-mcp-evolution"这一主题。
+
+**主题追溯**就是：把时间线上的每个 turn 看作一个圆柱，圆柱的高度代表该 turn 的计算/思考深度，颜色/标签代表主题。Agent 应该能横向扫描，把同色圆柱找出来，建立关联。
+
+```text
+        ▓▓▓  ╔══════════════╗  ▓▓▓▓▓                ▓▓▓
+        ▓▓▓  ║  memory-mcp  ║  ▓▓▓▓▓                ▓▓▓
+        ▓▓▓  ╚══════════════╝  ▓▓▓▓▓  ▓▓▓           ▓▓▓
+   ─────▓▓▓────T2──────────────T4─────T5───T6───────T7─────► 时间
+        │                                           │
+        T1                                          T7
+        └──────── 狼人杀主线 ────────────────────────┘
+```
+
+这种能力让 Agent 可以回答：
+
+> "memory MCP server 是怎么发展成现在这样的？"
+
+而不是只能回答：
+
+> "我们刚才说了什么？"
+
+#### 3.3.1 提炼层：wire.jsonl → Refined Turn Summaries
+
+`wire.jsonl` 是真相源，但它不是给「横向主题追溯」直接消费的。它里面 90% 是过程噪声：
+
+- `Thinking...` 过程
+- 流式输出碎片
+- 重复的 tool result 头部
+- "我来看看这个文件"、"好的，现在改一下"这类废话
+
+如果直接对 `wire.jsonl` 做语义聚类，算法会被这些噪声拖垮。因此需要在 `wire.jsonl` 和 `themes/<theme>.json` 之间插入一个**按需提炼层**：
+
+```
+Raw Wire Stream
+  Turn N Begin
+    -> Step 1: Thinking...
+    -> Step 1: Tool Call (Read file A)
+    -> Step 1: Tool Result (File A content...)
+    -> Step 1: Text Output ("I see the issue is in function X...")
+    -> Step 2: Tool Call (Edit file B)
+    -> Step 2: Tool Result (Diff...)
+  Turn N End
+            │
+            ▼
+   Per-Turn Refinement Filter (on demand)
+            │
+            ▼
+{
+  "turnId": 42,
+  "summary": "修复了 MCP 服务器启动时的端口占用问题",
+  "facts": [
+    "修改了 src/mcp/server.ts 的 listen() 逻辑",
+    "增加了 port fallback 机制 (3000 -> 3001)"
+  ],
+  "entities": {
+    "files": ["src/mcp/server.ts"],
+    "tools": ["edit_file", "bash"],
+    "errors": []
+  }
+}
+```
+
+**Refined Turn 是主题关联的原子单元**。它不是主题的私有财产，而是被多个主题共享引用的公共原子：
+
+```text
+refined/<sessionId>.jsonl
+        │
+        │   一个 Refined Turn 可被多个主题引用
+        │        ┌──────────────────┐
+        │        │ themes/A.json    │───┐
+        │        │  - turn-12       │   │
+        │        │  - turn-34       │   │
+        │        └──────────────────┘   │
+        │                               │
+        │        ┌──────────────────┐   │
+        └───────▶│ themes/B.json    │   │
+                 │  - turn-12       │◄──┘
+                 │  - turn-57       │
+                 └──────────────────┘
+```
+
+这意味着：
+
+- **一份提炼，多处引用**：某轮对话如果同时涉及 "memory-mcp-evolution" 和 "kimi-web-cwd" 两个主题，它只在 `refined/` 中存储一次，但两个主题文件都指向它；
+- **主题是视图，不是容器**：`themes/<theme>.json` 不保存 turn 正文，只保存 `(sessionId, turnId)` 指针；
+- **按 turn 去重**：同一个 turn 无论被多少个主题引用，都只提炼一次，避免重复计算。
+
+这个设计让提炼层从「session 级批量产物」变成「turn 级原子库」，是横向主题追溯能低成本扩展的关键。
+
+这个提炼层**不是**在每轮结束时自动跑，而是遵循**冷启动 + 持久化复用**策略：
+
+1. **冷启动**：当用户首次要求追溯某个主题时，Agent 先向用户索要主题范围和关键词种子；
+2. **粗筛**：用关键词在原始 `wire.jsonl` 中快速召回候选 turns；
+3. **提炼**：仅对候选 turns 运行 `refineTurn()`，结果持久化到 `refined/<sessionId>.jsonl`；
+4. **聚合**：把提炼后的 turns 按实体/事实重叠度聚合成主题，写入 `themes/<theme>.json`；
+5. **深挖**：用户或 Agent 挑选关键 turns，调用 `load_turn_context` 恢复完整对话；
+6. **复用**：后续再查询同一主题时，直接读取已持久化的提炼层，无需重新计算。
+
+提炼动作包括：
+
+| 动作 | 作用 |
+|---|---|
+| 去水印 | 剔除 Thinking、流式碎片、重复 tool result 头部 |
+| 事实抽取 | 提取 Changed / Reason / Error |
+| 意图压缩 | 5000 tokens → 3-5 bullet points |
+| 实体绑定 | 把概念锚定到文件路径、函数名、错误码 |
+
+**关键结论**：横向主题追溯基于按需生成的 `Refined Turn Summaries` 进行。每个 turn 被压缩为结构化的事实单元（`summary` / `facts` / `entities`），主题聚合因此可以通过关键词与实体匹配完成，无需直接解析原始 `wire.jsonl`，也无需依赖向量数据库。
+
+例如，要回答 "我们是怎么处理 MCP 端口占用问题的？"，只需要：
+
+```
+找到所有 entities.files 包含 src/mcp/server.ts 且 facts 包含 "port" 的 refined turns。
+```
+
+这用 SQLite + FTS5，甚至简单的 JSON grep 就能秒出结果。
+
+#### 3.3.2 我们的实践：按需提炼 + `search_context` + `load_turn_context` 实现主题追溯
+
+在我们实现的 memory MCP 中，上下文恢复不再依赖 agent 手动 `save_context`，而是直接解析 Kimi CLI 的 `wire.jsonl`。为了支持横向主题追溯，我们采用**按需提炼层**：
+
+- **提炼层**：在用户触发主题追溯时，对候选 turns 生成 `Refined Turn Summary`，包含 `summary` / `facts` / `entities`，并持久化到 `refined/<sessionId>.jsonl`；
+- **`bootstrap_workspace`**：启动时加载当前 workspace 的 `recentContext`、`essence`、`memoryIndexTree`；
+- **`search_context`**：按关键词跨所有 workspace session wires 做粗筛；
+- **`refine_session_turns`**：对粗筛出的候选 turns 进行提炼；
+- **`load_more_context`**：加载某个 session 之前的更多 turn；
+- **`load_turn_context`**：精确加载某几个 turn 的完整内容；
+- **`tag_theme` / `trace_theme`**：把 turns / memories 关联到主题，并按时间线输出。
+
+主题追溯的完整链路应该是：
+
+- **冷启动确认**：Agent 向用户确认主题范围并索要关键词种子；
+- **`search_context`**：按关键词跨所有 workspace session wires 粗筛候选 turns；
+- **`refine_session_turns`**：仅对候选 turns 做提炼并持久化；
+- **`tag_theme`** / 直接写 `themes/<theme>.json`：把提炼后的 turns 聚合成主题；
+- **`load_turn_context`**：精确加载关键 turns 的完整内容；
+- **`trace_theme`**：展示主题发展脉络。
+
+这正是主题追溯的工程实现：
+
+```text
+                            主题追溯按需流水线
+
+  用户
+    │
+    │  "memory MCP 是怎么演进的？"
+    ▼
+┌─────────────────────────────────────────────┐
+│ ① 冷启动确认                                  │
+│    Agent 向用户确认主题范围，索要关键词种子      │
+│    例："mcp-server"、"wire.jsonl"、"上下文保存" │
+└─────────────────────┬─────────────────────────┘
+                      ▼
+┌─────────────────────────────────────────────┐
+│ ② search_context 粗筛                        │
+│    跨 workspace 所有 session 的 wire.jsonl    │
+│    按关键词 / 实体 / 文件路径 召回候选 turns   │
+└─────────────────────┬───────────────────────┘
+                      ▼
+┌─────────────────────────────────────────────┐
+│ ③ refine_session_turns 提炼                  │
+│    仅对候选 turns 生成 Refined Summaries      │
+│    持久化到 refined/<sessionId>.jsonl        │
+│    （已提炼过的 turn 直接复用）               │
+└─────────────────────┬───────────────────────┘
+                      ▼
+┌─────────────────────────────────────────────┐
+│ ④ 主题聚合                                   │
+│    按 entities.files / facts 重叠度聚类       │
+│    写入 themes/<theme>.json                  │
+└─────────────────────┬───────────────────────┘
+                      ▼
+┌─────────────────────────────────────────────┐
+│ ⑤ load_turn_context 深挖（可选）              │
+│    对关键 turns 恢复完整 user / agent / actions│
+└─────────────────────┬───────────────────────┘
+                      ▼
+┌─────────────────────────────────────────────┐
+│ ⑥ trace_theme 输出                           │
+│    按时间线展示主题发展脉络 + 相关 memories   │
+└─────────────────────┬───────────────────────┘
+                      ▼
+        "memory-mcp-evolution 主题发展史"
+```
+
+在我们的实际经历中，正是通过这个机制，从多个 session 的噪音中提取出了 memory MCP 从问题提出、架构设计、实现验证到上游修复的完整发展史。
+
+**主题关联可以只用一个轻量的 JSON 文件维护**：
+
+```json
+{
+  "theme": "memory-mcp-evolution",
+  "displayName": "memory-mcp-evolution",
+  "createdAt": "2026-06-22T14:00:00Z",
+  "updatedAt": "2026-06-22T14:00:00Z",
+  "turns": [
+    {"sessionId": "sess-A", "turnId": 12, "timestamp": "2026-06-20T10:00:00Z"},
+    {"sessionId": "sess-B", "turnId": 3, "timestamp": "2026-06-21T11:00:00Z"},
+    {"sessionId": "sess-C", "turnId": 8, "timestamp": "2026-06-22T12:00:00Z"}
+  ],
+  "memories": [
+    {"key": "agent-memory-three-layer-model", "folder": "memory", "title": "Agent 记忆系统三层模型"},
+    {"key": "kimi-web-mcp-workspace-parked", "folder": "memory/decisions", "title": "kimi web MCP workspace 问题 parked"}
+  ]
+}
+```
+
+不需要 Neo4j，不需要图数据库，一个 JSON 文件就足以支持主题导航。
+
+---
+
+## 四、为什么 Markdown + JSON 索引足够好？
+
+### 4.1 对编程场景的天然适配
+
+编程工作的知识本身就是结构化的：
+
+- 架构决策（Decision）
+- 技术栈说明（Knowledge）
+- 代码规范（Rule）
+- 项目历史（Reference）
+- 临时备忘（Note）
+
+这些知识用 Markdown 组织，既符合开发者的习惯，也适合 LLM 理解。相比之下，向量数据库把所有知识都压成稠密向量，反而丢失了结构信息。
+
+### 4.2 可审计、可修正、可版本控制
+
+每条记忆都是一个文件：
+
+- 用户可以打开查看；
+- 可以手动编辑修正；
+- 可以用 git 追踪变更；
+- 可以明确地删除或归档。
+
+这比黑盒向量库更符合开发者对"可解释性"的要求。
+
+### 4.3 轻量、本地、离线
+
+不需要：
+
+- Docker
+- PostgreSQL / Neo4j / Qdrant
+- embedding 服务
+- 网络连接
+
+只需要文件系统。这与 CLI/IDE 工具追求的"本地优先、离线可用"完全一致。
+
+### 4.4 检索不必依赖向量搜索
+
+对于结构化 Markdown，检索可以是：
+
+- **路径搜索**：`memory/decisions/*`
+- **标签过滤**：tag = "architecture"
+- **标题匹配**：文件名包含 "HIL"
+- **BM25/keyword**：在 Markdown 内容中搜索关键词
+- **主题图遍历**：沿着 theme → turn → session 的关联
+
+这些方法组合起来，足以覆盖绝大多数 coding-agent 场景，而且更快、更确定、更可解释。
+
+---
+
+## 五、与 kimi-code 现有架构的契合点
+
+kimi-code 已经具备实现这一方案的基础：
+
+| 我们的层 | kimi-code 现有基础 | 建议实现 |
+|---|---|---|
+| 持续认知层 | `AGENTS.md`、system prompt | 增加热加载 watcher，支持 global/user/project 多级覆盖 |
+| 持久化知识库 | `SessionStore`、配置文件 | 新增 `MemoryStore`，按 workspace 组织 Markdown + JSON 索引 |
+| 提炼层 | `wire.jsonl`、`ToolManager` | 新增 `TurnRefiner`，用户触发主题追溯时按需提炼候选 turns |
+| 上下文保持与回忆 | `wire.jsonl`、`ContextMemory` | 保留现有机制，基于按需提炼层增加主题关联图 |
+
+具体建议：
+
+1. **在 `~/.kimi-code/memory/` 下建立 workspace-scoped 的 Markdown 记忆库**；
+2. **为每个 session 创建时加载相关的 Markdown 记忆**到 system prompt 或 injection；
+3. **提供默认记忆 Skill**：教导模型何时、如何、记录什么；
+4. **提供内置工具**：`remember` / `recall` / `list_memories` / `search_context` / `refine_session_turns` / `trace_theme`；
+5. **在 session 结束或 compaction 时，自动提炼关键事实为 Markdown 记忆**；
+6. **新增按需提炼层**：在 `store/<workspace>/refined/<sessionId>.jsonl` 下保存提炼后的 turn summaries，作为主题追溯的输入；
+7. **主题的识别和关联基于按需提炼层完成**：用户确认主题范围并提供关键词种子后，才启动粗筛、提炼与聚合，不阻塞主交互循环。
+
+### 5.1 默认记忆 Skill 的作用
+
+仅有工具是不够的。模型需要知道：
+
+- 什么时候应该调用 `remember`？
+- 什么内容值得记？
+- 记忆应该放在哪个 folder？
+- 什么时候应该调用 `recall` 或 `trace_theme`？
+- 哪些信息**不应该**被保存为记忆？
+
+这些规则应该被封装在一个**默认记忆 Skill**中，作为 system prompt 的一部分注入每个 session。
+
+一个记忆 Skill 的典型内容如下：
+
+```markdown
+# Memory Skill
+
+你有权限访问当前 workspace 的长期记忆系统。记忆分为两类：
+
+1. **持续认知层**（`AGENTS.md` / `essence.md`）：身份、规则、核心偏好。
+   - 不要通过 `remember` 修改这一层。
+   - 如果你发现认知层需要更新，提示用户手动编辑相关文件。
+
+2. **持久化知识库**（`memory/` 下的 Markdown）：项目事实、决策、模式、约定。
+   - 当用户确认某个决策、方案、架构时，调用 `remember` 保存。
+   - 当用户说"记住这个"、"记录下来"、"备案"时，调用 `remember`。
+   - 当讨论中需要引用过去决策时，调用 `recall` 或 `trace_theme`。
+
+## 何时使用 remember
+
+- 用户明确说"记住"、"记录下来"、"保存"；
+- 做出了一个需要后续参考的架构/设计决策；
+- 发现项目中的重复模式或约定；
+- 解决了一个棘手的 bug，积累了可复用的调试经验。
+
+## 何时不要使用 remember
+
+- 临时性的调试过程；
+- 可以在代码、git log、文档中直接找到的信息；
+- 用户没有确认的推测或假设；
+- 过于琐碎的个人偏好（如"我今天心情不好"）。
+
+## 记忆结构规范
+
+调用 `remember` 时：
+- `folder`：分类，如 `decisions`、`knowledge`、`rules`、`reference`；
+- `key`：kebab-case 唯一标识，如 `hil-refactor-2026`；
+- `title`：一句话概括；
+- `tags`：3-5 个关键词；
+- `content`：用 Markdown 清晰书写，包含背景和结论。
+
+## 主题追溯
+
+当用户问"X 是怎么发展的"、"回顾一下 Y"、"我们之前怎么决定 Z 的"时，调用 `trace_theme(theme)`。
+```
+
+这个 Skill 的作用不是替代工具，而是**让工具被正确使用**。没有它，模型要么忘记使用记忆工具，要么把什么都存进记忆库，导致知识库膨胀和噪音。
+
+---
+
+## 六、我们的实现已经验证了这条路
+
+我们基于上述理论实现了一个 memory MCP server，验证了以下关键点：
+
+### 6.1 文件系统足以支撑结构化记忆
+
+- 35 条记忆、24 个 Markdown 文件、11 个文件夹；
+- `index.json` v3-kv 索引读取和写入延迟都在毫秒级；
+- `structureHash` 机制保证目录结构变化时能快速同步；
+- 从未遇到过性能瓶颈。
+
+### 6.2 Markdown + frontmatter 是合理的默认格式
+
+- 人类可以直接阅读、编辑、归档；
+- LLM 能直接理解标题、列表、代码块；
+- frontmatter 提供了机器所需的元数据；
+- 与 git 版本控制天然兼容。
+
+### 6.3 主题追溯不需要重型数据库
+
+- 通过解析 `wire.jsonl` + 提炼层 + 轻量主题 JSON，我们已经能从多个 session 中抽取出清晰的主题发展史；
+- 这个过程的关键不在存储或算法，而在提炼层的质量：只有把原始对话压缩成 `facts` + `entities`，横向聚合才能用简单的关键词/实体匹配完成；
+- 主题识别基于按需提炼层完成，用户触发并确认关键词后才启动，不阻塞主交互。
+
+### 6.4 人机共治是必要的
+
+- 自动提取的记忆经常有偏差；
+- 重要的决策、规则、架构知识应该由人类确认或撰写；
+- Markdown 文件的透明性让这种共治成为可能。
+
+---
+
+## 七、对常见质疑的回应
+
+### Q1：不用向量数据库，大规模记忆怎么检索？
+
+**答**：对于 coding agent，"大规模"本身就是一个需要警惕的信号。如果一个项目需要上万条记忆才能工作，说明知识没有被有效梳理。好的记忆系统应该帮助用户**压缩和结构化**知识，而不是无差别地囤积。
+
+如果确实需要向量检索，可以作为可选插件，但不应该成为默认路径。
+
+### Q2：不用图数据库，怎么做主题关联？
+
+**答**：如第 3.3.1 节所示，主题关联建立在按需提炼层之上。`wire.jsonl` 在用户触发主题追溯时被提炼成 `Refined Turn Summaries`，再按 `entities.files` 等实体交集聚合成轻量的 `themes/<theme>.json`。图数据库对于复杂关系推理有帮助，但不是默认必需。
+
+### Q3：自动提取记忆会不会质量很差？
+
+**答**：会。所以应该采用**人机共治**：
+
+- Agent 可以自动提议记忆；
+- 但重要记忆需要用户确认或手动编辑；
+- 记忆文件对人类透明，随时可以修正。
+
+这比完全自动但黑盒的向量记忆更可靠。
+
+### Q4：Markdown 不是比数据库慢吗？
+
+**答**：读取几个 Markdown 文件到 prompt 中，比向量检索 + rerank 快得多。真正的延迟不在文件读取，而在 LLM 推理。保持记忆库小而精，反而是性能优化。
+
+---
+
+## 八、给 kimi-code 的具体建议
+
+1. **不要把向量数据库作为默认记忆方案**
+   - 默认应该是 Markdown + JSON 索引；
+   - 向量/图数据库作为高级可选项。
+
+2. **优先实现三层记忆 + 提炼层的基础设施**
+   - 持续认知层：热加载的 `AGENTS.md` 类文件；
+   - 持久化知识库：workspace-scoped Markdown 记忆库；
+   - 提炼层：用户触发主题追溯时，对候选 turns 按需生成 `Refined Turn Summary`；
+   - 上下文保持：基于提炼层，增加主题关联。
+
+3. **提供清晰的记忆边界**
+   - 区分"会消失的上下文"和"会被保存的记忆"；
+   - 区分"人类显式写入的规则"和"Agent 自动提取的事实"。
+
+4. **让记忆对人类透明**
+   - 用户应该能查看、编辑、删除、归档每条记忆；
+   - 记忆应该有来源（来自哪个 session、哪一轮、哪个 tool）。
+
+5. **把主题追溯作为杀手级特性**
+   - 跨 session 的主题关联是现有竞品没有做好的；
+   - 这能让 kimi-code 从"会话内聪明"进化到"理解用户工作脉络"。
+
+---
+
+## 九、结语
+
+Agent 记忆系统的目标不应该是"记住一切"，而应该是**"在正确的时间，把经过判断的、结构化的、与人类工作流一致的信息，呈现给模型"**。
+
+向量数据库和图数据库是强大的工具，但它们解决的是"海量无组织数据中的相似性检索"问题。而 coding agent 真正需要的记忆，是**梳理过的、清晰结构的、经过判断的、精心编排的信息**。
+
+我们已经用一个基于 Markdown + JSON 索引 + 主题追溯的 memory MCP server 验证了这条路。它不是学术玩具，而是一个真实可运行、已经承载了我们多个 session 工作的系统。
+
+我们建议 kimi-code 认真考虑这一方向。
+
+---
+
+## 参考
+
+- CoALA: A Cognitive Architecture for Language Agents (Princeton, 2023)
+- Memory in the Age of AI Agents (arXiv:2512.13564, 2025)
+- Letta / MemGPT: Packer et al., 2023
+- Mem0: Chhikara et al., 2025
+- Zep / Graphiti: Rasmussen et al., 2025
+- Hindsight: Latimer et al., 2025
+- ChatGPT Memory reverse engineering: llmrefs.com, 2025
+- Claude Code Auto-Memory / CLAUDE.md: datastudios.org, 2026