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

package/docs/2.memory-architecture-overview.md

@@ -0,0 +1,417 @@
+# Kimi Code 原生记忆系统架构大图
+
+> 本文档用一张大图 + 分层说明，展示如果把记忆系统原生集成进 Kimi Code 会是什么样子。重点体现：memory 文件夹的自由归纳创建、`organize_memories` 对精要的提炼约束、完整工具列表、以及 memory 变更触发 index.json 重建的索引机制。图中标签使用英文便于渲染，图外说明使用中文。
+
+---
+
+## TL;DR
+
+原生记忆系统分为四层：
+
+| 分层 | 职责 | 核心组件/文件 |
+|---|---|---|
+| 注入层 | 决定 Agent 是谁、遵循什么规则、当前什么重要 | `AGENTS.md`、`CLAUDE.md`、`essence.md` |
+| 路由层 | 把用户自然语言翻译成记忆工具调用 | 内置默认 Memory Skill |
+| 工具层 | 执行具体记忆操作 | `ToolManager` + `MemoryToolProvider`（20 个工具） |
+| 存储层 | 持久化保存所有记忆数据 | `~/.kimi-code/memory/<workspace-hash>/` |
+
+关键特性：
+- `memory/` 下可自由创建任意子目录和 Markdown 文件
+- `organize_memories` 把 `memory/` 提炼浓缩为 `essence.md`，建议 ≤15KB，超限警告
+- `memory/` 的任何变更都会通过 `MemoryDAO` 重建/更新 `index.json`
+- 主题追溯基于 `refined/` 原子库和 `themes/` 视图
+
+---
+
+## 一、全架构大图
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│              Kimi Code CLI Session                           │
+│  ┌──────────┐  ┌──────────┐  ┌────────────────────────┐    │
+│  │ User     │→ │ Agent/   │→ │ Native Tools           │    │
+│  │ Input    │  │ LLM      │  │ (Memory/File/Bash...)  │    │
+│  └────┬─────┘  └──────────┘  └───────────┬────────────┘    │
+└───────┼───────────────────────────────────┼─────────────────┘
+        │                                   │
+        │  ① boot injection                 │
+        ▼                                   ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 1: Injection (AGENTS.md / CLAUDE.md / essence.md)    │
+└──────────────────────────────────┬──────────────────────────┘
+                                   │
+                                   │  system prompt + skill rules
+                                   ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 2: Built-in Memory Skill                              │
+│  "remember this" → remember()                                │
+│  "search X" → search()                                       │
+│  "how X evolve?" → trace_theme()                             │
+│  "link to X" → tag_theme()                                   │
+│  Rules: ask for seeds; RefinedTurn atomic; no blind refine  │
+└──────────────────────────────────┬──────────────────────────┘
+                                   │
+                                   ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 3: Native Memory Tools (MemoryToolProvider)           │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │ Tool Inventory (20 tools)                           │   │
+│  │                                                     │   │
+│  │ remember  recall  recall_recent  search  list_tags │   │
+│  │ list  delete  move  organize_memories              │   │
+│  │ get_current_workspace  sync_workspace_index        │   │
+│  │ bootstrap_workspace  load_workspace_context        │   │
+│  │ load_more_context  search_context  load_turn_context│   │
+│  │ tag_theme  trace_theme  list_themes                │   │
+│  │ refine_session_turns                               │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  Supporting: TurnRefiner | ThemeDetector | ContextMemory    │
+│              MemoryDAO | MemoryStore                        │
+└──────────────────────────────────┬──────────────────────────┘
+                                   │
+                                   │  file I/O + index sync
+                                   ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 4: Persistent Store                                   │
+│                                                              │
+│  ~/.kimi-code/memory/<workspace-hash>/                       │
+│  │                                                           │
+│  ├── memory/        ◄── free Markdown creation/organization │
+│  │   ├── decisions/                                          │
+│  │   ├── knowledge/     (user/agent can create any folder)  │
+│  │   ├── rules/                                              │
+│  │   └── reference/                                          │
+│  │        │                                                  │
+│  │        │  free creation/editing triggers                 │
+│  │        ▼                                                  │
+│  │   ┌─────────────┐                                         │
+│  │   │ MemoryDAO   │  →  rebuild / update index.json        │
+│  │   │ (v3-kv)     │                                         │
+│  │   └─────────────┘                                         │
+│  │                                                           │
+│  ├── organize_memories()  ──►  essence/                     │
+│  │   (distill memory/ into    essence.md                    │
+│  │    workspace digest 建议 ≤15KB，超限警告)                 │
+│  │                                                           │
+│  ├── notes/        ◄── scratch notes                        │
+│  ├── themes/       ◄── theme views                          │
+│  ├── refined/      ◄── refined turn atoms                   │
+│  └── index.json    ◄── metadata cache (rebuildable)         │
+│       ▲                                                     │
+│       └── bootstrap_workspace() → memoryIndexTree (ASCII)   │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+        ▲
+        │  read-only
+        │
+  ~/.kimi-code/sessions/<sid>/agents/main/wire.jsonl
+```
+
+---
+
+## 二、分层职责
+
+### Layer 1：注入层
+
+| 组件 | 路径 | 职责 |
+|---|---|---|
+| User-level AGENTS.md | `~/.kimi-code/AGENTS.md` | 全局人格、强制启动协议、内置 skill 列表 |
+| Project-level AGENTS.md | `<project>/AGENTS.md` | 项目特定规则、角色、工作方式约定 |
+| CLAUDE.md | `<project>/CLAUDE.md` | AGENTS.md 的可选伴侣文件 |
+| essence.md | `~/.kimi-code/memory/<hash>/essence/essence.md` | 由 `memory/` 自动提炼生成的工作区摘要（建议 ≤15KB，超限警告） |
+
+原生实现中，boot loader 在**首轮用户输入之前**就读取这些文件并拼接到 system prompt。Agent 不需要显式调用任何启动工具。
+
+### Layer 2：内置 Memory Skill
+
+Kimi Code 内置一个**默认记忆 skill**，直接注入 system prompt。它教会模型：
+
+- 什么时候调用 `remember`
+- 该用哪个 folder 和 tags
+- 什么时候**不该**保存（临时调试、未确认的推测）
+- 如何冷启动主题追溯：先确认主题范围 + 索要关键词种子
+- `refined/` 中的 turn 是原子单元，可被多个主题共享
+
+### Layer 3：原生工具层
+
+#### 完整工具列表（19 个）
+
+**记忆管理（9 个）**
+- `remember`：写入/覆盖一条记忆
+- `recall`：按 key 读取单条记忆
+- `recall_recent`：读取最近更新的记忆
+- `search`：在记忆标题和内容中搜索
+- `list`：列出某 folder 下的记忆
+- `list_tags`：列出所有标签
+- `delete`：删除一条记忆
+- `move`：移动或重命名记忆
+- `organize_memories`：整理 `memory/` 并生成/更新 `essence.md`
+
+**工作区与索引（3 个）**
+- `get_current_workspace`：获取当前 workspace 信息
+- `sync_workspace_index`：同步 `index.json` 与文件系统
+- `bootstrap_workspace`：启动时加载上下文、精要、目录树
+
+**上下文恢复（4 个）**
+- `load_workspace_context`：加载当前 session 最近上下文
+- `load_more_context`：加载更早的轮次摘要
+- `search_context`：跨所有 session 搜索关键词
+- `load_turn_context`：批量加载指定轮次的完整内容
+
+**主题追溯（4 个）**
+- `tag_theme`：把 turn 或 memory 关联到主题
+- `trace_theme`：按时间线输出主题发展脉络
+- `list_themes`：列出所有主题
+- `refine_session_turns`：把 `wire.jsonl` 提炼为 Refined Turn Summaries
+
+#### 内部组件
+
+| 组件 | 职责 |
+|---|---|
+| `ToolManager` | Kimi Code 已有组件，把工具调用分发给各 provider |
+| `MemoryToolProvider` | 新 provider，注册上述 19 个记忆工具 |
+| `MemoryDAO` | 读写 `index.json`，保持与文件系统一致 |
+| `TurnRefiner` | 解析 `wire.jsonl`，生成 `RefinedTurn` 摘要 |
+| `ThemeDetector` | 冷启动流水线：粗筛 → 提炼 → 聚合 |
+| `ContextMemory` | Kimi Code 已有组件，把 `wire.jsonl` 加载进上下文窗口 |
+| `MemoryStore` | `memory/`、`notes/`、`essence/` 的文件系统 DAO |
+
+### Layer 4：原生持久化存储层
+
+#### `memory/`：自由归纳创建
+
+`memory/` 不是由系统预定义的固定结构，而是**用户和 Agent 可以自由创建子目录和 Markdown 文件**的知识空间。常见分类：
+
+- `decisions/`：关键产品/架构决策
+- `knowledge/`：项目技术栈、方案记录
+- `rules/`：协作规范、编码红线
+- `reference/`：参考资料
+
+**自由度体现**：
+- 可以创建任意子目录，如 `memory/experiments/`、`memory/meetings/`
+- 可以直接手动编辑 Markdown 文件
+- 可以移动、重命名、删除文件
+
+**约束**：
+- 每个 `.md` 文件必须有唯一的 `key`（与文件名一致）
+- frontmatter 包含 `key`、`title`、`tags`、`createdAt`、`updatedAt`
+- 文件变更后，下次 `sync_workspace_index` 或 `bootstrap_workspace` 会更新 `index.json`
+
+#### `index.json`：v3-kv 索引
+
+`index.json` 是**可重建的元数据缓存**，不是真相源。真相源是 `memory/`、`notes/`、`essence/` 下的文件本身。
+
+当 `memory/` 下发生以下变更时，`MemoryDAO` 会重建或更新 `index.json`：
+
+- `remember` 写入或覆盖文件
+- `move` 移动/重命名文件
+- `delete` 删除文件
+- `sync_workspace_index` 被调用
+- `bootstrap_workspace` 启动时检测到 `structureHash` 变化
+
+`structureHash`：对 `memory/`、`notes/`、`essence/` 下所有 `.md` 文件路径和空目录路径排序后取 MD5，用于快速判断是否需要完整重建索引。
+
+#### `memoryIndexTree`：启动时的动态目录树
+
+`memoryIndexTree` 不是磁盘上的文件，而是 `bootstrap_workspace` 在启动时根据 `index.json` 和 `memory/` 文件实时生成的 **ASCII 目录树**。它让 Agent 在首轮用户输入之前就能看到当前工作区的记忆结构。
+
+**生成流程：**
+
+1. `bootstrap_workspace` 先调用 `reconcileIndex()` 确保 `index.json` 与文件系统一致
+2. 从 `index.json` 中筛选所有以 `memory/` 开头的条目
+3. 按文件夹路径构建树形结构；文件节点包含 `key`、`title`、`tags`
+4. 读取每个 `.md` 文件的 `updatedAt` 和 `createdAt`
+5. 按 `updatedAt` 降序、再按 `createdAt` 降序排序，取前 `recentChangeLimit` 条（默认 5）
+6. 在最近变更的文件名后追加 `[new]` 标记
+7. 渲染成带缩进的 ASCII 树文本返回给 Agent
+
+**输出示例：**
+
+```text
+memory/ — 项目记忆根目录
+├── decisions/
+│   ├── persistence-design — 持久化设计 [decision] [new]
+│   └── ipc-spec — IPC 接口规范 [decision]
+├── knowledge/
+│   └── tech-stack — 技术栈记录 [knowledge] [new]
+└── rules/
+    └── coding-style — 编码规范 [rule]
+```
+
+**设计意图：**
+
+- 让 Agent 在冷启动时快速感知工作区知识拓扑
+- `[new]` 标记把注意力引导到最近活跃的记忆上
+- 只返回文本树，不返回完整内容，避免占用过多上下文窗口
+- 它是只读视图，修改必须通过 `remember`/`move`/`delete` 等工具
+
+#### `organize_memories`：提炼浓缩为精要
+
+`organize_memories` 是一个**两态工具**：
+
+1. **准备态（空参调用）**
+   - 返回现有 `essence.md` 内容
+   - 返回 `memory/` 下待整理的条目
+   - 返回整理规则
+
+2. **存储态（传入 `content`）**
+   - Agent 基于原材料生成新的精要 Markdown
+   - 工具校验大小，超过 15KB 时提示但不阻止
+   - 覆盖写入 `essence/essence.md`
+
+**提炼约束**：
+- `essence.md` 建议大小上限 **15KB**，超过时工具会提示但不阻止写入
+- 内容由 `memory/` 中的分散笔记提炼浓缩而来
+- 关键结论必须 inline 标注来源，如 `> 来源：memory/decisions/persistence-design`
+- **不删除**任何 `memory/` 源文件
+
+这个约束强制把长期记忆做"减法"：只有最核心、最常被召回的知识才进入 `essence.md`。
+
+#### 其他存储
+
+- `notes/`：临时速记 / 个人便签
+- `themes/<theme>.json`：主题视图，只保存 `(sessionId, turnId)` 和 `(key, folder, title)` 引用
+- `refined/<sessionId>.jsonl`：turn 级原子提炼摘要，每行一个 JSON
+
+---
+
+## 三、数据流示例
+
+### 3.1 创建一条记忆并同步索引
+
+```text
+User: "记住这个决策"
+  │
+  ▼
+Agent 调用 remember(key, content, folder, tags)
+  │
+  ▼
+MemoryToolProvider → MemoryStore 写入 .md 文件
+  │
+  ▼
+MemoryDAO 调用 upsertEntry() 更新 index.json
+  │
+  ▼
+bootstrap_workspace 启动时：
+  - reconcileIndex() 校验 index.json
+  - buildMemoryIndexTree() 扫描 memory/ 条目
+  - 按 updatedAt/createdAt 排序，标记前 N 条为 [new]
+  - 返回 ASCII memoryIndexTree
+```
+
+### 3.2 整理精要
+
+```text
+User: "整理一下 memory"
+  │
+  ▼
+Agent 调用 organize_memories() 空参
+  │
+  ▼
+返回现有 essence.md + memory/ 原材料 + 规则
+  │
+  ▼
+Agent 生成新的精要 content
+  │
+  ▼
+Agent 调用 organize_memories(content)
+  │
+  ▼
+校验 ≤15KB（超限仅警告） → 覆盖写入 essence/essence.md
+```
+
+### 3.3 主题追溯
+
+```text
+User: "How did X evolve?"
+  │
+  ▼
+Agent asks for scope & keyword seeds
+  │
+  ▼
+search_context coarse screen across sessions
+  │
+  ▼
+refine_session_turns (candidate turns, merge by turnId)
+  │
+  ▼
+tag_theme / aggregate → themes/<theme>.json
+  │
+  ▼
+trace_theme → timeline + memories
+```
+
+### 3.4 启动时加载 memoryIndexTree
+
+```text
+Agent 启动 / 用户输入前
+  │
+  ▼
+bootstrap_workspace()
+  │
+  ├──► reconcileIndex() 同步 index.json
+  │
+  ├──► buildWorkspaceContext() 加载最近对话
+  │
+  ├──► loadEssenceFile() 加载 essence.md
+  │
+  └──► buildMemoryIndexTree(recentChangeLimit=5)
+         │
+         ├── 扫描 index.json 中 memory/ 条目
+         ├── 构建文件夹/文件树
+         ├── 读取 frontmatter.updatedAt / createdAt
+         ├── 排序取最近 N 条
+         ├── 标记 [new]
+         └── 渲染 ASCII 树
+                  │
+                  ▼
+          Agent context window
+```
+
+---
+
+## 四、设计要点
+
+1. **文件层是真相源**
+   - `index.json` 只是缓存，丢失后可以扫描文件系统重建
+   - 用户可以直接编辑 `memory/` 下的 Markdown，系统会检测到变化
+
+2. **memory 归纳高度自由**
+   - 不限定固定子目录，Agent 和用户可以根据需要创建
+   - folder 备注通过 `sync_workspace_index` 维护，帮助理解目录用途
+
+3. **精要是强约束的蒸馏产物**
+   - 建议 ≤15KB，超限警告，强制聚焦
+   - 从 `memory/` 提炼，不替代 `memory/`
+   - 来源可追溯
+
+4. **索引自动维护**
+   - 所有会改变 `memory/` 结构的操作都会触发 `index.json` 更新
+   - `structureHash` 避免不必要的完整扫描
+
+5. **Refined Turn 原子化**
+   - `refined/<sessionId>.jsonl` 按 turn 存储
+   - `themes/<theme>.json` 只保存引用
+   - 同一 turn 可被多个主题引用，只提炼一次
+
+6. **memoryIndexTree 是只读启动视图**
+   - 每次启动时从 `index.json` 和 `memory/` 文件实时生成
+   - 用 `[new]` 标记引导 Agent 关注最近活跃记忆
+   - 不持久化，修改必须通过记忆管理工具
+
+---
+
+## 五、关键设计口诀
+
+> **AGENTS.md 定义你是谁。essence.md 定义现在什么重要。memory/ 定义你知道什么。themes/ 定义知识如何连接。refined/ 定义你实际做了什么。**
+>
+> **memory/ 是自由生长的花园，essence.md 是剪出来的盆景，index.json 是花园的导览图，memoryIndexTree 是导览图上高亮最近改动的批注。**
+>
+> **wire.jsonl 是录音，refined/ 是翻译稿，themes/ 是索引，memory/ 是正典。**
+
+---
+
+*文档生成时间：2026-06-23*  
+*描述对象：Kimi Code 原生记忆子系统设计*