# https://github.com/Zehee/kimi-code-memory-mcp-server 项目说明书

生成时间：2026-06-29 11:26:31 UTC

## 目录

- [Project Overview](#page-overview)
- [System Architecture](#page-architecture)
- [Storage Layout and Data Model](#page-data-model)
- [MCP Tools, Prompts and Resources](#page-tools)

<a id='page-overview'></a>

## Project Overview

### 相关页面

相关主题：[System Architecture](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/README.md)
- [README.en.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/README.en.md)
- [CHANGELOG.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/CHANGELOG.md)
- [package.json](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/package.json)
- [src/prompts/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/prompts/index.ts)
- [src/resources/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/resources/index.ts)
- [src/tools/system-tools.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/tools/system-tools.ts)
- [examples/README.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/examples/README.md)
</details>

# Project Overview

## 项目目的与定位

`kimi-code-memory-mcp-server`（简称 `kimi-memory`）是一个面向 Kimi Code CLI 的 **Model Context Protocol (MCP) 记忆服务器**。它解决一个核心痛点：CLI 会话上下文会被压缩甚至归档，导致跨会话开发时丢失"为什么这样做"的设计理由 资料来源：[README.en.md:1-15]()。

项目自 v0.1.0（2026-06-24）发布，定位是"由用户审阅、结构化、拥有的记忆"，反对将记忆默认放进向量数据库的"黑盒"做法 资料来源：[CHANGELOG.md:18-30]()。v0.1.1 引入 `kimi-memory-setup` 一键集成命令；v0.1.2 进一步加入 MCP Prompts 与 Resources 支持 资料来源：[CHANGELOG.md:8-17]()。

## 核心架构与目录结构

服务器在 Node.js ≥ 18 环境下运行，使用 stdio 传输与 MCP 客户端通信，依赖项包括 `@modelcontextprotocol/sdk`、`hono`、`@hono/node-server` 与 `better-sqlite3` 资料来源：[package.json:42-50]()。

源码按职责拆分为四个目录：

```text
src/
├── tools/         # MCP 工具定义
│   ├── memory-tools.ts   # 记忆 CRUD
│   ├── context-tools.ts  # 上下文恢复
│   ├── theme-tools.ts    # 主题追溯
│   └── system-tools.ts   # organize / sync / bootstrap
├── dao/           # 数据访问层
├── context/       # 会话上下文解析
├── prompts/       # MCP Prompts
├── resources/     # MCP Resources
└── utils/         # 公共工具
```

工作区以 `~/.kimi-code-memory/<workspace-id>/` 为根目录，包含 `memory/`（按 `decisions/knowledge/rules/reference` 四类组织）、`essence/essence.md`（≤15 KB 的工作区精要）、`themes/` 与 `refined/refined.sqlite`（轮次级精炼摘要） 资料来源：[README.en.md:8-26]()。`src/resources/index.ts` 将 `memory://<folder>/<key>`、`theme://<theme>` 与 `essence://essence` 三类 URI 暴露为可读取的 Resource 资料来源：[src/resources/index.ts:25-44]()。

## 主要工具与能力

服务器同时提供 **Tools、Prompts、Resources** 三类 MCP 原语。

**记忆与上下文工具**包括 `remember`、`recall`、`search`、`list`、`list_tags`、`delete`、`move`，以及 `bootstrap_workspace`、`load_workspace_context`、`load_more_context`、`search_context`、`load_turn_context` 等跨会话恢复工具 资料来源：[README.en.md:30-44]()。

**主题追溯工具**包含 `tag_theme`、`trace_theme`、`list_themes`、`refine_session_turns`，它们把不同会话中同一主题的轮次"横向"串成主题线 资料来源：[README.en.md:48-55]()。

**Prompts** 提供三个可复用的指令模板，客户端可在调用工具前拉取：

| Prompt | 用途 |
|--------|------|
| `memory-decision-check` | 修改文件前先检查与其相关的历史决策 |
| `memory-theme-trace` | 追溯某个主题在多次会话中的演化 |
| `memory-session-summary` | 总结当前会话并建议值得挂载的主题 |

资料来源：[src/prompts/index.ts:18-38]()。

**系统级工具** `organize_memories`、`sync_workspace_index`、`bootstrap_workspace` 等负责把 `memory/` 提炼为精要、重建 `index.json` 缓存，以及加载工作区快照 资料来源：[src/tools/system-tools.ts:1-50]()。

## 存储模型与配置

存储采用 **Markdown + YAML frontmatter** 而非纯向量库。每个记忆是一条 `.md` 文件，包含 `key`、`title`、`tags`、`createdAt`、`updatedAt` 等字段；`index.json` 是 v3-kv 缓存，`.md` 文件才是真相来源——可通过 `sync_workspace_index` 重建 资料来源：[README.en.md:64-70]()。

可通过环境变量定制存储根：

| 变量 | 用途 |
|------|------|
| `MEMORY_STORE_ROOT` | 覆盖默认 `~/.kimi-code-memory` 存储根 |
| `MEMORY_SESSIONS_ROOT` | 覆盖 `~/.kimi-code/sessions` 路径 |
| `KIMI_CODE_HOME` | 替代项，会话从 `<KIMI_CODE_HOME>/sessions` 读取 |

资料来源：[README.en.md:21-26]()。

示例工程 `examples/sample-workspace/` 完整演示了上述目录结构与约定，可直接复制后通过 `MEMORY_STORE_ROOT` 挂载使用 资料来源：[examples/README.md:1-22]()。

## See Also

- [docs/ARCHITECTURE.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/docs/ARCHITECTURE.md) — 系统设计与数据流
- [docs/three-layer-memory-model.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/docs/three-layer-memory-model.md) — 理论记忆模型
- [docs/search-logic.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/docs/search-logic.md) — `search` 与 `search_context` 实现细节
- [docs/CONTRIBUTING.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/docs/CONTRIBUTING.md) — 贡献指南

---

<a id='page-architecture'></a>

## System Architecture

### 相关页面

相关主题：[Project Overview](#page-overview), [Storage Layout and Data Model](#page-data-model)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/server.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/server.ts)
- [src/config.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/config.ts)
- [src/types.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/types.ts)
- [src/dao/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/dao/index.ts)
- [src/dao/memory-store.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/dao/memory-store.ts)
- [src/theme-manager.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/theme-manager.ts)
- [src/refined-manager.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/refined-manager.ts)
- [src/tools/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/tools/index.ts)
- [src/prompts/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/prompts/index.ts)
- [src/resources/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/resources/index.ts)
- [README.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/README.md)
- [package.json](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/package.json)
- [CHANGELOG.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/CHANGELOG.md)
- [examples/sample-workspace/index.json](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/examples/sample-workspace/index.json)
</details>

# System Architecture

## 架构概览

`kimi-code-memory-mcp-server` 是一个基于 stdio 传输的本地 Model Context Protocol（MCP）服务器，目标是给 Kimi Code CLI 提供跨会话的记忆能力。系统刻意回避了外部数据库与云服务，所有持久化数据都以 **Markdown 文件 + 可重建 JSON 索引** 的形式保存在本地工作区中。资料来源：[README.md]()

整体架构可以分为四个层次：

1. **协议接入层**——`Server` + `StdioServerTransport`，负责处理 MCP 的 `tools/list`、`tools/call`、`prompts/list`、`prompts/get`、`resources/list`、`resources/read` 等请求。资料来源：[src/server.ts]()
2. **应用服务层**——`tools`、`prompts`、`resources` 三个注册表，把 MCP 原语映射到具体业务能力。资料来源：[src/tools/index.ts]()、[src/prompts/index.ts]()、[src/resources/index.ts]()
3. **领域管理层**——`IndexDao`、`MemoryStore`、`ThemeManager`、`RefinedManager`，封装记忆读写、主题追踪、精炼轮次摘要等核心逻辑。资料来源：[src/dao/index.ts]()、[src/theme-manager.ts]()、[src/refined-manager.ts]()
4. **持久化层**——文件系统中的 `.md` 记忆文件、`themes/*.json` 主题文件、`refined/refined.sqlite` 摘要数据库与 `index.json` 索引缓存。资料来源：[README.md]()

```mermaid
flowchart TB
    Client[MCP Client / Kimi Code CLI]
    subgraph Protocol[协议接入层]
        Server[Server + StdioServerTransport]
    end
    subgraph App[应用服务层]
        Tools[tools registry]
        Prompts[prompts registry]
        Resources[resources registry]
    end
    subgraph Domain[领域管理层]
        MemoryStore[MemoryStore]
        IndexDao[IndexDao]
        ThemeMgr[ThemeManager]
        RefinedMgr[RefinedManager]
    end
    subgraph Storage[持久化层]
        MD[memory/*.md]
        Theme[themes/*.json]
        Refined[refined/refined.sqlite]
        Index[index.json cache]
    end
    Client --> Server
    Server --> Tools
    Server --> Prompts
    Server --> Resources
    Tools --> MemoryStore
    Tools --> IndexDao
    Tools --> ThemeMgr
    Tools --> RefinedMgr
    MemoryStore --> MD
    IndexDao --> Index
    ThemeMgr --> Theme
    RefinedMgr --> Refined
```

## 核心组件

**入口与上下文组装**：`src/server.ts` 在启动时读取 `process.cwd()`，通过 `computeWorkspaceId` 生成工作区 ID，并拼出 `<storeRoot>/<workspaceId>/` 路径。它会确保 `memory`、`notes`、`essence`、`themes`、`refined` 等基础目录存在，然后构造一个 `Ctx` 对象注入到所有子系统中。资料来源：[src/server.ts]()

**配置与路径**：`src/config.ts` 中的 `getStoreRoot` 默认返回 `~/.kimi-code-memory`，但允许通过环境变量 `MEMORY_STORE_ROOT`、`MEMORY_SESSIONS_ROOT`、`KIMI_CODE_HOME` 覆盖，从而支持多工作区与便携部署。资料来源：[src/config.ts]()、[README.md]()

**记忆 CRUD**：由 `MemoryStore` 与 `IndexDao` 协作完成。`MemoryStore` 负责 Markdown 文件的读写与 YAML frontmatter 解析，`IndexDao` 维护 `index.json` 这一 v3-kv 缓存，对外暴露 `listRefs`、`upsert`、`remove` 等接口。当 `.md` 源文件被外部修改时，可通过 `sync_workspace_index` 重建缓存。资料来源：[src/dao/memory-store.ts]()、[src/dao/index.ts]()

**主题追踪**：`ThemeManager` 是横向叙事能力的核心。它把会话轮次按主题打标，并把这种关联写入 `themes/<theme>.json`，使多个会话之间同一主题的演化历史可以被检索与回放。资料来源：[src/theme-manager.ts]()、[README.md]()

**精炼轮次摘要**：`RefinedManager` 把原始 `wire.jsonl` 中的轮次压缩成可跨主题复用的原子摘要，存储在 `refined/refined.sqlite`。即使原始会话文件丢失，`search_context` 仍可基于精炼摘要返回结果。资料来源：[src/refined-manager.ts]()、[CHANGELOG.md]()

## 工具、提示与资源

应用层通过三个并列的注册表对外暴露能力：

| 注册表 | 作用 | 典型示例 |
|--------|------|----------|
| `tools` | 执行读写与计算动作 | `remember`、`recall`、`search`、`trace_theme`、`refine_session_turns` |
| `prompts` | 预置指令模板 | `memory-decision-check`、`memory-theme-trace`、`memory-session-summary` |
| `resources` | 按 URI 暴露只读内容 | `memory://<folder>/<key>`、`theme://<theme>`、`essence://essence` |

工具注册由 `createTools(ctx)` 统一编排，它把 `memory-tools`、`context-tools`、`theme-tools`、`system-tools` 合并成一个数组，再分别导出 `toolSchemas`（用于 `ListToolsRequestSchema`）与 `dispatch`（用于 `CallToolRequestSchema`）。当调用未知工具时，`dispatch` 会返回 `error: Unknown tool: <name>`；当 handler 抛错时，会被捕获并以 `success: false` 的形式回写，避免协议层崩溃。资料来源：[src/tools/index.ts]()

Prompts 与 Resources 则通过 `getPrompt(name, args)` 与 `readResource(uri)` 提供结构化的指令模板和可寻址的 Markdown 视图，方便客户端在不调用 LLM 的情况下先完成上下文准备工作。资料来源：[src/prompts/index.ts]()、[src/resources/index.ts]()

## 数据流与存储约定

一次典型的写入流程如下：客户端发起 `tools/call` → `Server` 路由到 `dispatch` → 对应 handler 调用 `MemoryStore.write` → 更新 Markdown 文件并刷新 `IndexDao` 缓存 → 如涉及主题则同步更新 `ThemeManager`。读取流程则相反，优先命中 `index.json`，必要时回落到 Markdown 解析。资料来源：[src/server.ts]()、[src/tools/index.ts]()

存储目录遵循 `examples/sample-workspace/` 中的约定：`memory/` 下分 `decisions`、`knowledge`、`rules`、`reference` 四个子目录；`essence/essence.md` 是工作区精要（≤15 KB）；`themes/` 记录主题关联；`refined/` 保存轮次摘要。所有路径都通过 `utils/paths.ts` 中的辅助函数计算，便于在迁移或重命名时统一调整。资料来源：[examples/sample-workspace/index.json]()、[README.md]()

## 扩展点与失败模式

- **可选嵌入检索**：`README.md` 的 Roadmap 明确列出了“可选本地嵌入搜索”与“可选 LLM 轮次精炼”，二者将以插件形式接入，不影响现有 Markdown 主路径。资料来源：[README.md]()
- **传输适配**：协议层使用 `StdioServerTransport`，但 MCP SDK 支持替换为 HTTP/SSE 传输，只需替换 `server.ts` 中的 transport 即可。资料来源：[src/server.ts]()、[package.json]()
- **缓存一致性**：`index.json` 只是缓存，`.md` 文件才是真相来源。当外部编辑器修改记忆后，需调用 `sync_workspace_index` 重建，否则可能出现工具读到旧元数据的窗口。资料来源：[README.md]()
- **依赖演进**：当前依赖 `@modelcontextprotocol/sdk ^1.0.0`、`better-sqlite3 ^12.11.1`，升级 SDK 版本时应同步更新 `examples/sample-workspace/memory/reference/mcp-spec.md` 等参考条目。资料来源：[package.json]()

## See Also

- [docs/ARCHITECTURE.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/docs/ARCHITECTURE.md) — 系统设计与数据流
- [docs/three-layer-memory-model.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/docs/three-layer-memory-model.md) — 三层记忆模型理论
- [docs/search-logic.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/docs/search-logic.md) — `search` 与 `search_context` 的实现细节
- [CHANGELOG.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/CHANGELOG.md) — 版本演进记录

---

<a id='page-data-model'></a>

## Storage Layout and Data Model

### 相关页面

相关主题：[System Architecture](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/utils/paths.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/utils/paths.ts)
- [src/utils/frontmatter.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/utils/frontmatter.ts)
- [src/utils/validation.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/utils/validation.ts)
- [src/dao/index-store.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/dao/index-store.ts)
- [src/dao/index-catalog.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/dao/index-catalog.ts)
- [src/dao/index-reconciler.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/dao/index-reconciler.ts)
- [src/resources/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/resources/index.ts)
- [examples/sample-workspace/index.json](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/examples/sample-workspace/index.json)
- [examples/sample-workspace/memory/reference/sample-reference.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/examples/sample-workspace/memory/reference/sample-reference.md)
- [examples/sample-workspace/essence/essence.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/examples/sample-workspace/essence/essence.md)
</details>

# 存储布局与数据模型

## 概述

`kimi-code-memory-mcp-server` 采用 **Markdown + YAML frontmatter + JSON 索引缓存** 的纯文本存储方案，避免依赖外部向量数据库或云服务。所有记忆以人类可读的 `.md` 文件形式落地，配合 `index.json` 加速检索，`.md` 文件始终是数据真相来源（source of truth），索引仅作为可重建的缓存层。

存储根目录默认为 `~/.kimi-code-memory`，可通过环境变量 `MEMORY_STORE_ROOT` 覆盖。系统会同时读取 Kimi Code CLI 的会话目录（默认 `~/.kimi-code/sessions`，可通过 `MEMORY_SESSIONS_ROOT` 或 `KIMI_CODE_HOME` 覆盖）下的 `wire.jsonl` 文件，用于跨会话上下文恢复。

## 目录结构

工作区（workspace）是一个以存储根目录为基准的子目录，其内部布局如下：

```mermaid
graph TD
    Root[workspace 根目录] --> Index[index.json<br/>v3-kv 索引缓存]
    Root --> Memory[memory/]
    Memory --> Decisions[decisions/]
    Memory --> Knowledge[knowledge/]
    Memory --> Rules[rules/]
    Memory --> Reference[reference/]
    Root --> Essence[essence/essence.md<br/>≤15 KB]
    Root --> Notes[notes/]
    Root --> Themes[themes/]
    Root --> Refined[refined/refined.sqlite]
```

各子目录的语义约定如下：

- `memory/decisions/`：架构与产品决策记录，标签 `decision`。
- `memory/knowledge/`：项目特定知识，标签 `knowledge`。
- `memory/rules/`：编码规范与协作红线，标签 `rule`。
- `memory/reference/`：外部链接与文档引用，标签 `reference`。
- `notes/`：临时便签，标签 `scratch`，不进入长期精要。
- `essence/essence.md`：从 `memory/` 提炼生成的浓缩摘要，大小上限 15 KB。
- `themes/*.json`：主题（theme）与轮次（turn）/记忆之间的关联映射。
- `refined/refined.sqlite`：轮次级原子摘要数据库，可在多个主题间共享。
- `index.json`：v3-kv 格式的索引缓存，可通过 `sync_workspace_index` 工具从磁盘重建。

> 来源：README.en.md、examples/README.md

## 记忆文件格式

每条记忆是一个独立的 Markdown 文件，使用 YAML frontmatter 描述元数据，正文为 Markdown 内容。标准 frontmatter 字段包括：

| 字段 | 必填 | 说明 |
|------|------|------|
| `key` | 是 | 记忆唯一标识，对应文件名（不含扩展名） |
| `title` | 是 | 人类可读的标题 |
| `tags` | 否 | 字符串数组，用于分类与过滤 |
| `createdAt` | 是 | ISO 8601 创建时间戳 |
| `updatedAt` | 是 | ISO 8601 最后更新时间戳 |

工具层在写入或修改记忆时会自动维护 `createdAt` 与 `updatedAt` 字段，确保时间序列的可追溯性。

下面是一个完整的记忆文件示例（来自 `examples/sample-workspace/memory/reference/sample-reference.md`）：

```markdown
---
key: 'mcp-spec'
title: 'MCP Specification Reference'
tags:
  - reference
  - mcp
  - external
createdAt: '2026-06-20T10:15:00.000Z'
updatedAt: '2026-06-20T10:15:00.000Z'
---

# MCP Specification Reference

- **URL**: https://modelcontextprotocol.io/
- **Type**: External reference
- **Relevance**: Defines the stdio transport and tool schema used by this server.
```

> 来源：examples/sample-workspace/memory/reference/sample-reference.md

## 索引缓存与资源寻址

`index.json` 采用 v3-kv（key-value）结构，以 `folder/key` 为键聚合记忆的元信息（标题、标签、文件路径等）。索引在以下场景被更新：

- 调用 `remember`、`delete`、`move` 等工具时即时增量更新。
- 调用 `sync_workspace_index`（空参数）时全量扫描并报告差异。
- 调用 `sync_workspace_index` 并传入 `folderComments` 时为指定目录设置描述。

`index.json` 的条目示例（摘自 `examples/sample-workspace/index.json`）：

```json
"memory/reference/mcp-spec": {
  "title": "MCP Specification Reference",
  "tags": ["reference", "mcp", "external"]
}
```

MCP Resources 通过统一的 URI 方案暴露这些数据，供客户端按需读取：

| URI 模式 | 对应内容 |
|----------|----------|
| `memory://<folder>/<key>` | `memory/` 下的某条 Markdown 记忆 |
| `theme://<theme>` | 某个主题的关联摘要（Markdown 格式） |
| `essence://essence` | 工作区精要 `essence/essence.md` |

> 来源：src/resources/index.ts、examples/sample-workspace/index.json

## 数据来源

- 目录结构与默认值：[README.en.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/README.en.md)
- 路径工具与环境变量：[src/utils/paths.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/utils/paths.ts)
- Frontmatter 解析与维护：[src/utils/frontmatter.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/utils/frontmatter.ts)
- 字段校验规则：[src/utils/validation.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/utils/validation.ts)
- 索引持久化与 v3-kv 格式：[src/dao/index-store.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/dao/index-store.ts)
- 索引查询接口：[src/dao/index-catalog.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/dao/index-catalog.ts)
- 索引协调与重建：[src/dao/index-reconciler.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/dao/index-reconciler.ts)

## See Also

- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — 系统设计与数据流
- [docs/three-layer-memory-model.md](./docs/three-layer-memory-model.md) — 三层记忆模型理论
- [docs/search-logic.md](./docs/search-logic.md) — `search` 与 `search_context` 的检索逻辑

---

<a id='page-tools'></a>

## MCP Tools, Prompts and Resources

### 相关页面

相关主题：[System Architecture](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/server.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/server.ts)
- [src/tools/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/tools/index.ts)
- [src/tools/memory-tools.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/tools/memory-tools.ts)
- [src/tools/context-tools.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/tools/context-tools.ts)
- [src/tools/theme-tools.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/tools/theme-tools.ts)
- [src/tools/system-tools.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/tools/system-tools.ts)
- [src/prompts/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/prompts/index.ts)
- [src/resources/index.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/resources/index.ts)
- [src/setup.ts](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/src/setup.ts)
- [README.en.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/README.en.md)
- [CHANGELOG.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/CHANGELOG.md)
- [AGENTS.md](https://github.com/Zehee/kimi-code-memory-mcp-server/blob/main/AGENTS.md)
</details>

# MCP Tools、Prompts 与 Resources

## 概述

Kimi Code Memory MCP Server 通过 Model Context Protocol（MCP）向 [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) 暴露三类核心能力：**Tools（工具）**、**Prompts（提示模板）** 与 **Resources（资源）**。三者统一由 [src/server.ts]() 通过 `StdioServerTransport` 在 stdio 通道上分发，底层数据完全保存在本地 Markdown 文件与可重建的 `index.json` 中，README 明确声明「no required external database or cloud service」（[README.en.md]()）。这种「Markdown 优先」的设计让记忆保持人类可读、可审计、可 Git 化。

```mermaid
flowchart LR
    C[Kimi Code CLI 客户端] -- stdio --> S[MCP Server<br/>src/server.ts]
    S --> T[Tools<br/>memory/context/theme/system]
    S --> P[Prompts<br/>src/prompts/index.ts]
    S --> R[Resources<br/>src/resources/index.ts]
    T --> FS[(Markdown + index.json)]
    R --> FS
    P -. 预热提示 .-> T
```

## MCP Tools（工具）

工具是模型可主动调用的函数入口，由 `createTools(ctx)` 集中注册（[src/tools/index.ts]()），按职责拆分为四个文件：

- **记忆 CRUD**（[src/tools/memory-tools.ts]()）：`remember`、`recall`、`recall_recent`、`search`、`list`、`list_tags`、`delete`、`move`，操作 `memory/decisions/`、`memory/knowledge/`、`memory/rules/`、`memory/reference/` 下的 Markdown 文件。
- **上下文恢复**（[src/tools/context-tools.ts]()）：`bootstrap_workspace`、`load_workspace_context`、`load_more_context`、`search_context`、`load_turn_context`，直接解析 `wire.jsonl` 重建跨会话上下文。
- **主题追溯**（[src/tools/theme-tools.ts]()）：`tag_theme`、`trace_theme`、`list_themes`、`refine_session_turns`，把分散的轮次与记忆聚合为主题并支持回溯演化。
- **系统维护**（[src/tools/system-tools.ts]()）：`organize_memories` 把 `memory/` 蒸馏成 ≤15 KB 的 `essence/essence.md`；`sync_workspace_index` 重建索引（README 强调 `.md` 是唯一事实来源）。

按 [AGENTS.md]() 的强制协议，每个会话开始后必须先调用 `mcp__kimi-memory__bootstrap_workspace()`，把 `essence.md`、`memoryIndexTree`、`recentContext`、`notesRefs` 注入上下文。

## MCP Prompts（提示模板）

`Prompts` 让客户端在调用工具前显式拉取指令模板，避免重复拼接提示词。注册逻辑在 [src/prompts/index.ts]()：元信息声明于 `prompts` 数组，消息体由 `getPrompt(name, args)` 渲染，均返回 `role: 'user'` 的文本消息。三类模板覆盖「事前查证」「事中串联」「事后归档」三个时间点（[CHANGELOG.md]() v0.1.2 新增项）：

- `memory-decision-check`：修改文件前先查询相关历史决策；可选参数 `filePath`。
- `memory-theme-trace`：跨会话追溯某一主题的演化；可选参数 `theme`。
- `memory-session-summary`：总结当前会话并建议可挂载的主题标签；无参数。

## MCP Resources（资源）

`Resources` 把工作区文件以 URI 形式暴露为可寻址对象，模型只读不可写。实现位于 [src/resources/index.ts]() 的 `createResources(ctx)` 工厂，三种 URI 模式分别为：

- `memory://<folder>/<key>`：通过 `ctx.indexDao.listRefs()` 枚举 `memory/` 下的条目，描述里附带 tags 列表。
- `theme://<theme>`：枚举 `ctx.themeManager.listThemes()` 下的全部主题。
- `essence://essence`：仅当 `essence/essence.md` 存在时返回，受 `fs.existsSync` 守卫保护。

所有 Resource 的 `mimeType` 均为 `text/markdown`，与 Markdown 优先的设计哲学保持一致；客户端可在不触发任何 Tool 的情况下拉取工作区静态视图。

## 注册与分发

[src/server.ts]() 通过 `ListToolsRequestSchema`、`ListPromptsRequestSchema` / `GetPromptRequestSchema`、`ListResourcesRequestSchema` / `ReadResourceRequestSchema` 五个 schema 处理三类能力。Tools 由 `createTools(ctx)` 注入 `CallToolRequestSchema` 派发表；Prompts 直接复用 `prompts` 与 `getPrompt`；Resources 通过 `createResources(ctx)` 与 `indexDao`、`themeManager` 协作枚举工作区。安装阶段，[src/setup.ts]() 会在 `~/.kimi-code/AGENTS.md`、`mcp.json` 与 `skills/memory-manage/` 写入带 `KIMI-MEMORY-INJECTED-START/END` 边界标记的协议块，确保客户端按 [AGENTS.md]() 在会话开始时自动调用 `bootstrap_workspace` 并读取对应资源。

## 常见失败模式

- `essence://essence` 缺失：首次启动或尚未执行 `organize_memories` 时返回空数组（[src/resources/index.ts]() 中存在 `existsSync` 守卫）。
- 索引滞后：`index.json` 是缓存，必须定期 `sync_workspace_index`，否则 Resources 与 Tools 枚举可能与 `.md` 不一致（[README.en.md]()）。
- 工作区错位：`MEMORY_STORE_ROOT`、`MEMORY_SESSIONS_ROOT`、`KIMI_CODE_HOME` 任一被错误设置都会让所有 Tools 与 Resources 指向错误目录（[README.en.md]()）。

## 另请参阅

- 架构与数据流：[docs/ARCHITECTURE.md]()
- 三层记忆模型：[docs/three-layer-memory-model.md]()
- 搜索逻辑：[docs/search-logic.md]()
- 协议注入与回滚：[src/setup.ts]()
- 启动协议约束：[AGENTS.md]()

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：Zehee/kimi-code-memory-mcp-server

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Zehee/kimi-code-memory-mcp-server | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Zehee/kimi-code-memory-mcp-server | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Zehee/kimi-code-memory-mcp-server | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Zehee/kimi-code-memory-mcp-server | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Zehee/kimi-code-memory-mcp-server | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Zehee/kimi-code-memory-mcp-server | release_recency=unknown

<!-- canonical_name: Zehee/kimi-code-memory-mcp-server; human_manual_source: deepwiki_human_wiki -->