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

package/docs/design-story.md

@@ -0,0 +1,350 @@
+# Kimi Code Memory MCP Server 设计笔记
+
+> 一份写给工程师看的设计记录：在没有向量数据库、图数据库和云 API 的前提下，如何让 Agent 记得住、找得回、想得起来龙去脉。
+
+---
+
+## 一、从一个老问题开始
+
+每个用过 AI 编程助手的人都经历过这一幕：
+
+> 你花了一个下午和 Agent 讨论完项目的架构、踩过的坑、临时决定放弃的接口。第二天新开一个会话，Agent 客气地问：“请问这是什么项目？”
+
+你愣住了。昨天那些上下文明明还在终端的滚动日志里，却像没发生过一样。
+
+这就是我们要解决的最朴素的问题：**让 Agent 拥有真正属于这个项目的长期记忆**。
+
+但怎么做到？
+
+---
+
+## 二、两条诱人的歧途
+
+在动手之前，我们先看看市面上的主流方向。
+
+### 歧途一：把记忆做成“第二互联网”
+
+向量数据库 + 大规模 RAG 的思路很性感：
+
+> 把所有历史对话都存下来，用的时候靠语义相似度捞一捞。
+
+听起来很强大，但用在 coding agent 上会有三个致命问题：
+
+1. **记忆失去了筛选机制**。互联网已经是全人类的外脑，如果 Agent 的本地记忆也是无差别囤积的数据，那它和 Google 的区别只在于数据来源。
+2. **检索质量不可控**。语义相似不等于主题相关。两个都提到“路由”的代码片段，一个是前端页面跳转，一个是后端消息路由，向量距离可能很近，但 engineering 意义完全不同。
+3. **可解释性差**。模型为什么召回这条记忆？用户很难理解和修正。
+
+如果 Agent 的记忆只是一个小号的、私人的互联网，那它就不值得单独做一个系统。
+
+### 歧途二：把记忆做成“第二数据库”
+
+图数据库、时序知识图、复杂的关系 schema……这些方案在语义建模上很优雅，但对 coding agent 来说：
+
+- 运维成本高：需要额外服务、索引、迁移、备份；
+- 写放大严重：每条对话都要经过实体抽取、关系链接、冲突消解；
+- 与人类工作流割裂：开发者不会为了“让 Agent 记住”而先去维护一个知识图谱。
+
+**记忆系统应该服务于人的工作流，而不是反过来要求人为记忆系统建模。**
+
+---
+
+## 三、我们的答案：一本“会思考的笔记本”
+
+我们决定回到工程师最熟悉的东西：**文件**。
+
+不是数据库，不是向量索引，而是普通的 Markdown 文件。因为：
+
+- 工程师每天都会读、写、搜索 Markdown；
+- Markdown 天然适合 git diff，适合代码审查，适合在 IDE 里直接编辑；
+- 任何能读文本的 LLM 都能理解它；
+- 它足够轻量，不需要安装任何外部服务。
+
+但光有文件不够。我们还需要一套**分层**的存储和召回机制，让不同类型的信息各得其所。
+
+于是我们提出了 **三层记忆模型**。
+
+---
+
+## 四、三层记忆模型：像人一样分层思考
+
+### 第一层：持续认知层 —— 你的“工作宪法”
+
+想象一下，你每天早上醒来，不需要重新学习“我是谁、我会说什么语言、我有什么原则”。这些是你的底层认知，一直在线。
+
+Agent 也需要这样的东西。我们把它放在：
+
+- `essence/essence.md` —— 每个工作区一份，不超过 15 KB 的精要；
+- `AGENTS.md` —— 跨所有会话注入的行为规则和协议。
+
+这里存的不是具体知识，而是**人格、规则、偏好、红线**。比如：
+
+- “始终用中文回复用户”
+- “涉及 IPC 信号变更时，同时维护文档”
+- “禁止执行任何 git 突变，除非用户明确授权”
+
+这些规则在每个 session 开始时就通过 `bootstrap_workspace` 注入，Agent 不需要临时去“回忆”，因为它从未忘记。
+
+### 第二层：持久化知识库 —— 你的“项目笔记”
+
+这是真正需要被长期保存的项目资产，按类型分门别类放在 `memory/` 下：
+
+```text
+memory/
+├── decisions/     # 架构和产品决策
+├── knowledge/     # 项目特定知识
+├── rules/         # 协作规范和红线
+└── reference/     # 外部参考和术语
+```
+
+每条记忆都是一个 `.md` 文件，带 YAML frontmatter，记录标题、标签、创建时间、更新时间。比如：
+
+```markdown
+---
+title: 选择 SQLite 作为缓存层
+tags: [decision, database, sqlite]
+createdAt: 2026-06-24T12:00:00.000Z
+updatedAt: 2026-06-24T12:00:00.000Z
+---
+
+我们选择 SQLite 而不是 Redis，因为：
+- 项目追求本地离线可用；
+- 缓存数据量小，SQLite 完全够用；
+- 避免引入额外服务。
+```
+
+这些文件是**真相源**。`index.json` 只是它们的缓存和索引，损坏后可以通过 `sync_workspace_index` 一键重建。
+
+### 第三层：上下文保持与回忆 —— 你的“近期工作记忆”
+
+长期记忆解决了“知道什么”，但还缺一个能力：**想起刚刚发生了什么**。
+
+Kimi Code CLI 本身会把每次对话以事件流的形式写入 `wire.jsonl`。我们直接读取它，而不是让 Agent 自己手动“保存上下文”。因为：
+
+> 既然完整上下文已经被持久化在 `~/.kimi-code/sessions/.../wire.jsonl` 里，为什么还要让 Agent 再写一份？
+
+但 `wire.jsonl` 是原始事件流，直接解析很贵。于是我们引入了 **refined turns**：
+
+```text
+wire.jsonl  ──►  refined/refined.sqlite  ──►  search_context / trace_theme
+原始事件流        结构化摘要（SQLite 本地索引）      快速搜索与主题追溯
+```
+
+`refined.sqlite` 不是用户资产，而是**派生索引**。它让历史对话可以被关键词快速搜索，同时保留原始 wire 作为真相源。
+
+---
+
+## 五、主题追溯：在时间轴上重新打捞相关思考
+
+大多数上下文窗口只按**时间纵向**查看： turn 1、turn 2、turn 3……当前窗口满了，旧的 turn 就被压缩、打包、存档，细节随之流逝。
+
+但人类的思考往往是**横向**的：
+
+> “上周我们讨论过登录模块的 JWT 方案，前天又聊到 OAuth 流程，今天用户问登录怎么做，我应该把这三段连起来。”
+
+这就是 **Theme Tracing（主题追溯）**——它不是简单的“按主题筛选”，而是在**时间轴的废墟**里把同一个主题的碎片重新串成一条线。
+
+### 时间轴上的真实形状
+
+想象一条水平向右延伸的时间轴。上面的每一个小圆柱都是一次对话轮（turn）：
+
+![时间轴上的 turns、簇、session 与主题追溯](../assets/contextFlow.svg)
+
+图中元素：
+
+- **竖条（turn）**：每次对话轮，高度代表计算深度——思考、工具调用越多，条越高。
+- **粗横线（cluster）**：紧密相邻、围绕同一决策的若干 turn 被聚成一个簇，簇通常对应一次具体决策或结论。
+- **灰框（session）**：横向包裹一段时间内的 turns 与 clusters；上下文窗口满了会被整体压缩打包。
+- **彩色括号（theme）**：跨越多个 session，把属于同一主题的 turns / clusters 横向串联起来，形成一条跨时间的认知线。
+
+关键隐喻：**session 会下沉**。旧 session 被压缩、打包、存档后，原始细节逐渐不可见，只剩下 `refined.sqlite` 里的结构化摘要；而主题线被单独保存下来，即使原始 session 已经下沉，主题仍然鲜活可用。
+
+### trace_theme 做了什么？
+
+当用户问“登录模块是怎么演进的？”时，主题追溯会沿时间轴反向扫描：
+
+1. 在 `refined.sqlite` 里搜索与“登录模块”相关的 turn 和簇；
+2. 把散落在多个 session 中的相关片段重新捞出来；
+3. 用 `themes/<theme>.json` 把它们按时间顺序串联成一条主题线。
+
+```text
+trace_theme(theme=login-module):
+╭─────────────────────────────────────────────────────────────────────╮
+│  沿时间线回溯，把属于“登录模块”的 turns / clusters 重新串联：        │
+│                                                                     │
+│  [Session A: 登录决策簇] ──→ [Session B: 认证方案簇] ──→            │
+│  [Session C: OAuth流程]                                             │
+│                                                                     │
+│  保存为 themes/login-module.json（只存引用，不复制内容）              │
+╰─────────────────────────────────────────────────────────────────────╯
+```
+
+主题文件只存引用，不存内容。这意味着：
+
+- 一个 turn 可以同时属于多个主题；
+- 主题之间没有冗余复制；
+- 即使原始 session 已经被压缩存档，主题线仍然鲜活可用；
+- Agent 的思考从“最近说了什么”变成“这个主题是怎么发展过来的”。
+
+### 为什么是“横向提炼”？
+
+纵向看，信息会随时间衰减：窗口满了，旧的就被压成摘要。
+
+横向看，主题追溯把不同时间、不同 session 中围绕同一主题的碎片重新组织起来，形成一条**跨时间的认知线**。它不是在保存所有信息，而是在保存“哪些信息属于同一个思想”。
+
+这让 Agent 的记忆变得更加聚焦：不是记住一切，而是记住**思考的脉络**。
+
+---
+
+## 六、精炼：让机器替你先读一遍历史
+
+`search_context` 是这个系统里最有趣的工具之一。它做了几件事：
+
+1. **关键词搜索**：先在 `refined.sqlite` 里用 SQL `LIKE` 快速命中；
+2. **簇扩展**：命中一个 turn 后，向前后扩展 90 秒内的相邻 turn，把一段连续讨论聚成一个“簇”；
+3. **自动提炼**：对簇中还没提炼的 turn，调用 `refinedManager.refineTurn()` 生成结构化摘要；
+4. **保存搜索视图**：把这次搜索的簇结构存到 `searches/search-<hash>.json`，供后续 `tag_theme` 使用。
+
+> **重要：当前的会话提炼不调用 LLM，因此没有 token 开销。**
+>
+> 提炼规则是纯本地、确定性的。它基于正则和启发式规则从 `wire.jsonl` 中提取结构化信息，而不是把历史对话再送给大模型总结一次。
+
+它识别：
+
+- Markdown 标题（如 `## 已完成`、`## 下一步`、`## 阻塞项`）；
+- 列表项和编号列表；
+- 中英文动作关键词（`已完成`、`Fixed`、`Next step`、`阻塞` 等）；
+- 工具调用、文件路径、错误信息。
+
+这让历史对话从“一堆文本”变成“可搜索、可分类、可挂载到主题”的素材，同时保持低成本和可复现性。
+
+---
+
+## 七、数据流：一图胜千言
+
+```text
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│  Kimi Code CLI  │────▶│  wire.jsonl      │────▶│ wire-context.ts │
+│  (conversation) │     │  (event stream)  │     │ (parser)        │
+└─────────────────┘     └──────────────────┘     └────────┬────────┘
+                                                          │
+                                                          ▼
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│  Agent tools    │◀────│  MCP server      │◀────│  context-tools  │
+│  remember/      │     │  src/server.ts   │     │                 │
+│  search/        │     │                  │     │                 │
+│  trace_theme/   │     │                  │     │                 │
+└─────────────────┘     └────────┬─────────┘     └─────────────────┘
+                                 │
+           ┌─────────────────────┼─────────────────────┐
+           │                     │                     │
+           ▼                     ▼                     ▼
+   ┌───────────────┐    ┌───────────────┐    ┌───────────────┐
+   │ memory-tools  │    │ theme-tools   │    │ system-tools  │
+   │ CRUD memory   │    │ tag/trace/    │    │ organize/     │
+   │ files         │    │ refine        │    │ sync/bootstrap│
+   └───────┬───────┘    └───────┬───────┘    └───────┬───────┘
+           │                    │                    │
+           ▼                    ▼                    ▼
+   ┌───────────────┐    ┌───────────────┐    ┌───────────────┐
+   │ memory-store  │    │ theme-manager │    │ refined-      │
+   │ (.md I/O)     │    │ (themes/*.json)│   │ manager       │
+   └───────┬───────┘    └───────────────┘    │ (refined/     │
+           │                                  │  refined.sqlite)│
+           ▼                                  └───────────────┘
+   ┌───────────────┐
+   │ IndexDao      │
+   │ (index.json)  │
+   └───────────────┘
+```
+
+所有工具共享同一个 `Ctx`，里面持有：
+
+- `IndexDao`：管理 `index.json` 缓存；
+- `MemoryStore`：读写 Markdown 文件；
+- `ThemeManager`：管理主题关联；
+- `RefinedManager`：管理 SQLite 中的提炼摘要。
+
+---
+
+## 八、为什么轻量反而更强
+
+我们刻意不做几件事：
+
+| 我们没做 | 为什么不做 |
+|---|---|
+| 向量数据库默认检索 | coding 场景最有价值的记忆是决策、规则、事实，用路径+标签+关键词更确定、更可解释 |
+| 图数据库 | 引入运维负担，与人类工作流割裂 |
+| LLM 提炼摘要 | **当前实现不调用 LLM**：会话提炼基于本地确定性规则，无 token 开销；本地规则提取已覆盖大多数场景 |
+| 云端存储 | 数据留在本地，离线可用，隐私可控 |
+
+我们坚持 **local-first, offline, zero external dependencies**。整个系统只依赖：
+
+- 文件系统；
+- 一个本地 SQLite 文件（仅用于 refined 派生索引）；
+- Node.js 运行时。
+
+这让 Kimi Code Memory MCP Server 可以像 `~/.ssh/` 或 `~/.aws/` 一样，安静地待在你的用户目录里，不需要守护进程，不需要 Docker，不需要网络。
+
+---
+
+## 九、一些生动的使用场景
+
+### 场景一：你还记得上周的决定吗？
+
+```text
+User: 我们之前决定用什么做缓存？
+Agent: [search] query=缓存层 decision
+       [recall] key=choose-sqlite-cache, folder=memory/decisions
+       → "我们选择 SQLite 而不是 Redis，因为项目追求本地离线可用……"
+```
+
+### 场景二：这个功能是怎么演进的？
+
+```text
+User: 登录模块是怎么演进的？
+Agent: [tag_theme] theme=login-module
+       [trace_theme] theme=login-module
+       → 展示跨三个 session 的 five turns：
+         - 登录表单设计
+         - JWT 策略
+         - OAuth 流程
+         - 密码重置
+         - 双因素认证
+```
+
+### 场景三：我又回到这个项目了
+
+```text
+[session start]
+Agent: [bootstrap_workspace]
+       → 加载 essence.md、memory/ 索引、最近对话上下文
+       → “欢迎回来。当前项目是 kimicode-memory-mcp-server，
+          上次我们在改 README 的主题追溯示例……”
+```
+
+---
+
+## 十、写在最后
+
+Kimi Code Memory MCP Server 不是又一个“把所有东西存下来再靠语义搜索”的记忆系统。
+
+它是一个**有判断力的记忆系统**：
+
+- 知道什么值得记（决策、规则、知识）；
+- 知道什么是临时噪音（具体某次提问、过时的调试过程）；
+- 知道怎么把零散的对话重新组织成主题；
+- 知道用人类可读的文件作为真相源，用轻量索引作为加速器。
+
+如果把它比作一个工具，它不是一台庞大的数据中心，而是一本**会思考的笔记本**：
+
+> 你随手写下笔记，它替你整理目录、标注重点、关联前后文；当你再次翻开时，它不仅能告诉你“上次写了什么”，还能告诉你“这些想法是怎么发展过来的”。
+
+这就是我们选择的设计。
+
+---
+
+## 相关文档
+
+- [`ARCHITECTURE.md`](./ARCHITECTURE.md) —— 更干、更技术化的架构说明
+- [`three-layer-memory-model.md`](./three-layer-memory-model.md) —— 三层记忆模型的完整理论
+- [`search-logic.md`](./search-logic.md) —— `search` 与 `search_context` 的实现细节

package/docs/three-layer-memory-model.md

@@ -0,0 +1,153 @@
+> **Note:** This document is adapted from a discussion on agent memory architecture between Zehee and K2.7 Code thinking.
+
+# Three-Layer Memory Model
+
+## TL;DR
+
+`kimi-code-memory-mcp-server` uses a lightweight, file-system-based memory architecture:
+
+- **Continuous cognition layer** — `AGENTS.md` / `essence.md`: rules, identity, and core constraints carried into every session.
+- **Persistent knowledge layer** — `memory/`: structured Markdown notes for decisions, knowledge, rules, and references.
+- **Context retention & recall layer** — `wire.jsonl` parsed on demand, with a `refined/` SQLite cache and `themes/` for cross-session tracing.
+
+No vector database or graph database is required.
+
+---
+
+## 1. What is Worth Remembering?
+
+Not everything deserves persistence. We keep only three kinds of information:
+
+1. **Continuous cognition** — who the agent is, what rules it follows, core project constraints.
+2. **Persistent knowledge** — decisions, patterns, conventions, and reference material worth revisiting.
+3. **Context & recall** — recent conversation state and cross-session theme associations.
+
+Everything else stays in `wire.jsonl` as an audit trace or is discarded.
+
+---
+
+## 2. Layer One: Continuous Cognition
+
+File: `essence/essence.md` (and optionally user-level `~/.kimi-code/AGENTS.md`)
+
+This layer is small, hot-reloadable, and always present. It contains:
+
+- Identity and role expectations
+- Hard rules (e.g., "no git mutations without explicit user approval")
+- Language and style preferences
+- Project-wide conventions
+
+In this MCP server, `essence.md` is constrained to **≤15 KB**. If it grows beyond that, `organize_memories` refuses to write until the user condenses it. The file is loaded at session start via `bootstrap_workspace`.
+
+---
+
+## 3. Layer Two: Persistent Knowledge
+
+Directory: `memory/`
+
+Structured Markdown files, categorized by purpose:
+
+| Folder | Purpose | Tag |
+|---|---|---|
+| `memory/decisions/` | Architecture and product decisions | `decision` |
+| `memory/knowledge/` | Project-specific technical knowledge | `knowledge` |
+| `memory/rules/` | Conventions, guardrails, and red lines | `rule` |
+| `memory/reference/` | External links and documentation references | `reference` |
+
+Each file has YAML frontmatter:
+
+```yaml
+---
+key: agent-memory-three-layer-model
+folder: memory
+tags: [knowledge, memory, architecture]
+---
+```
+
+A lightweight `index.json` v3-kv cache records file paths, titles, and tags. The cache is rebuildable from disk via `sync_workspace_index`; the Markdown files are the source of truth.
+
+---
+
+## 4. Layer Three: Context Retention & Theme Tracing
+
+Source: Kimi Code CLI's `wire.jsonl`
+Cache: `refined/refined.sqlite`
+Associations: `themes/<theme>.json`
+
+### 4.1 Why not use raw `wire.jsonl`?
+
+Raw wire streams contain a lot of noise: streaming fragments, "Thinking..." traces, repeated tool headers. Searching and clustering them directly produces poor results.
+
+### 4.2 Refined turns
+
+When the user triggers theme tracing, `search_context` finds candidate turns across all workspace sessions. `refine_session_turns` then compresses them into structured records:
+
+```json
+{
+  "sessionId": "sess-a",
+  "turnId": 42,
+  "summary": "Fixed port occupation issue when MCP server starts",
+  "facts": [
+    "Modified listen() logic in src/mcp/server.ts",
+    "Added port fallback mechanism (3000 -> 3001)"
+  ],
+  "entities": {
+    "files": ["src/mcp/server.ts"],
+    "tools": ["edit_file", "bash"],
+    "errors": []
+  }
+}
+```
+
+These refined turns are stored in `refined/refined.sqlite` and reused on later queries.
+
+### 4.3 Themes as views, not containers
+
+A theme file only holds pointers to turns and memories:
+
+```json
+{
+  "theme": "memory-mcp-evolution",
+  "turns": [
+    {"sessionId": "sess-a", "turnId": 12},
+    {"sessionId": "sess-b", "turnId": 3}
+  ],
+  "memories": [
+    {"key": "agent-memory-three-layer-model", "folder": "memory"}
+  ]
+}
+```
+
+A single refined turn can be referenced by multiple themes. This avoids duplicating content and keeps the storage model simple.
+
+---
+
+## 5. Tools by Layer
+
+| Layer | Tools |
+|---|---|
+| Continuous cognition | `bootstrap_workspace`, `organize_memories` |
+| Persistent knowledge | `remember`, `recall`, `search`, `list`, `move`, `delete`, `sync_workspace_index` |
+| Context & themes | `load_workspace_context`, `load_more_context`, `search_context`, `refine_session_turns`, `load_turn_context`, `tag_theme`, `trace_theme`, `list_themes` |
+
+---
+
+## 6. Why No Vector or Graph Database?
+
+For coding agents, the hard problem is usually **curation**, not **retrieval scale**. A well-structured Markdown library with path/tag/keyword search covers most needs:
+
+- Path search: `memory/decisions/*`
+- Tag filter: `tag = architecture`
+- Keyword search: `search` and `search_context`
+- Theme traversal: `trace_theme`
+
+These are fast, deterministic, and explainable. If vector retrieval is ever needed, it can be added as an optional plugin, not the default.
+
+---
+
+## 7. References
+
+- CoALA: A Cognitive Architecture for Language Agents (Princeton, 2023)
+- Mem0: Chhikara et al., 2025
+- Zep / Graphiti: Rasmussen et al., 2025
+- Claude Code Auto-Memory / CLAUDE.md: datastudios.org, 2026

package/docs/three-layer-memory-model.zh-CN.md

@@ -0,0 +1,153 @@
+> **说明：** 本文档由 Zehee 与 K2.7 Code thinking 关于 Agent 记忆架构的讨论整理而来。
+
+# 三层记忆模型
+
+## TL;DR
+
+`kimi-code-memory-mcp-server` 采用轻量的、基于文件系统的记忆架构：
+
+- **持续认知层** —— `AGENTS.md` / `essence.md`：每个会话都会携带的规则、身份与核心约束。
+- **持久化知识层** —— `memory/`：结构化的 Markdown 笔记，记录决策、知识、规则与参考。
+- **上下文保持与追溯层** —— 按需解析 `wire.jsonl`，通过 `refined/` SQLite 缓存与 `themes/` 实现跨会话主题追溯。
+
+无需向量数据库或图数据库。
+
+---
+
+## 1. 什么值得被记住？
+
+并非所有信息都值得持久化。我们只保留三类：
+
+1. **持续认知**：Agent 是谁、遵循什么规则、核心项目约束。
+2. **持久化知识**：值得反复查阅的决策、模式、约定与参考资料。
+3. **上下文与追溯**：近期对话状态与跨会话主题关联。
+
+其余内容留在 `wire.jsonl` 作为审计痕迹，或直接丢弃。
+
+---
+
+## 2. 第一层：持续认知
+
+文件：`essence/essence.md`（以及可选的用户级 `~/.kimi-code/AGENTS.md`）
+
+这一层体积小、支持热加载、始终在场，包含：
+
+- 身份与角色期望
+- 硬性规则（例如"未经用户明确授权不得进行 git 突变"）
+- 语言与风格偏好
+- 项目级约定
+
+在本 MCP server 中，`essence.md` 被限制为 **≤15 KB**。超出时 `organize_memories` 会拒绝写入，强制用户精简。该文件通过 `bootstrap_workspace` 在会话启动时加载。
+
+---
+
+## 3. 第二层：持久化知识
+
+目录：`memory/`
+
+按用途分类的结构化 Markdown 文件：
+
+| 目录 | 用途 | 标签 |
+|---|---|---|
+| `memory/decisions/` | 架构与产品决策 | `decision` |
+| `memory/knowledge/` | 项目专属技术知识 | `knowledge` |
+| `memory/rules/` | 约定、红线与行为规范 | `rule` |
+| `memory/reference/` | 外部链接与文档引用 | `reference` |
+
+每个文件都有 YAML frontmatter：
+
+```yaml
+---
+key: agent-memory-three-layer-model
+folder: memory
+tags: [knowledge, memory, architecture]
+---
+```
+
+轻量的 `index.json` v3-kv 缓存记录文件路径、标题与标签。该缓存可通过 `sync_workspace_index` 从磁盘重建；Markdown 文件才是真相来源。
+
+---
+
+## 4. 第三层：上下文保持与主题追溯
+
+来源：Kimi Code CLI 的 `wire.jsonl`
+缓存：`refined/refined.sqlite`
+关联：`themes/<theme>.json`
+
+### 4.1 为什么不直接用原始 `wire.jsonl`？
+
+原始 wire 流包含大量噪声：流式输出碎片、"Thinking..." 痕迹、重复的 tool 头部。直接搜索和聚类效果很差。
+
+### 4.2 精炼轮次
+
+当用户触发主题追溯时，`search_context` 先跨所有工作区会话找到候选 turns。然后 `refine_session_turns` 将其压缩为结构化记录：
+
+```json
+{
+  "sessionId": "sess-a",
+  "turnId": 42,
+  "summary": "修复了 MCP 服务器启动时的端口占用问题",
+  "facts": [
+    "修改了 src/mcp/server.ts 的 listen() 逻辑",
+    "增加了端口回退机制 (3000 -> 3001)"
+  ],
+  "entities": {
+    "files": ["src/mcp/server.ts"],
+    "tools": ["edit_file", "bash"],
+    "errors": []
+  }
+}
+```
+
+精炼后的 turns 存入 `refined/refined.sqlite`，后续查询直接复用。
+
+### 4.3 主题是视图，不是容器
+
+主题文件只保存指向 turns 和记忆的指针：
+
+```json
+{
+  "theme": "memory-mcp-evolution",
+  "turns": [
+    {"sessionId": "sess-a", "turnId": 12},
+    {"sessionId": "sess-b", "turnId": 3}
+  ],
+  "memories": [
+    {"key": "agent-memory-three-layer-model", "folder": "memory"}
+  ]
+}
+```
+
+一个精炼 turn 可被多个主题引用，避免内容重复，保持存储模型简单。
+
+---
+
+## 5. 按层划分的工具
+
+| 层 | 工具 |
+|---|---|
+| 持续认知 | `bootstrap_workspace`, `organize_memories` |
+| 持久化知识 | `remember`, `recall`, `search`, `list`, `move`, `delete`, `sync_workspace_index` |
+| 上下文与主题 | `load_workspace_context`, `load_more_context`, `search_context`, `refine_session_turns`, `load_turn_context`, `tag_theme`, `trace_theme`, `list_themes` |
+
+---
+
+## 6. 为什么不用向量或图数据库？
+
+对 coding agent 来说，困难的问题通常是**整理**而非**检索规模**。结构良好的 Markdown 库配合路径/标签/关键词搜索足以覆盖大多数场景：
+
+- 路径搜索：`memory/decisions/*`
+- 标签过滤：`tag = architecture`
+- 关键词搜索：`search` 与 `search_context`
+- 主题遍历：`trace_theme`
+
+这些方法快速、确定、可解释。如果未来确实需要向量检索，可以作为可选插件加入，而不是默认路径。
+
+---
+
+## 7. 参考
+
+- CoALA: A Cognitive Architecture for Language Agents (Princeton, 2023)
+- Mem0: Chhikara et al., 2025
+- Zep / Graphiti: Rasmussen et al., 2025
+- Claude Code Auto-Memory / CLAUDE.md: datastudios.org, 2026