# Kimi Code Memory MCP Server

[English](./README.en.md)

[![CI](https://github.com/Zehee/kimi-code-memory-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/Zehee/kimi-code-memory-mcp-server/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/kimi-code-memory-mcp-server.svg?color=brightgreen)](https://www.npmjs.com/package/kimi-code-memory-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

一个为 [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) 提供跨会话记忆的本地 stdio MCP 服务器。

> **注意：** 本包已发布到 npm，包名为 `kimi-code-memory-mcp-server`。你可以直接安装，也可以从源码运行。


## 特性

- **Markdown 优先的记忆** —— 人类可读、适合 git、兼容 LLM。
- **结构化长期记忆** —— `memory/decisions/`、`memory/knowledge/`、`memory/rules/`、`memory/reference/`。
- **工作区精要** —— 从 `memory/` 提炼生成的浓缩摘要（≤15 KB）。
- **跨会话上下文恢复** —— 直接解析 Kimi Code CLI 的 `wire.jsonl`。
- **主题追溯** —— 将对话轮次和记忆关联到主题，并追踪其演化。
- **精炼轮次摘要** —— 可在多个主题间共享的轮次级原子摘要。
- **可重建索引** —— `index.json` 只是缓存，`.md` 文件才是真相来源。
- **主题与搜索视图删除** —— 支持删除低质量主题或搜索视图，并可选择级联清理其关联的精炼轮次。
- **可视化仪表盘增强** —— 工作区标题动态显示文件夹名、Markdown 默认只读、轻量级渲染预览、主题/搜索视图删除。

## 主题追溯

传统的上下文管理只关注**纵向**：时间越近越清晰，越久越远越衰减。但这忽略了真实工作的一个核心特征：

> **同一个 workspace 中的多次会话，往往不是单一叙事，而是多条主题线交织并行。**

例如：

- Session A：开发 auth 鉴权
- Session B：讨论orders数据表的迁移问题
- Session C：加密RSA+解密BCrypt+验证码CAPTCHA+Cookie 
- Session D：fix sql  error bug
- Session E： 登录Login API设计

如果只看纵向，这些 session 彼此独立。但如果横向扫描，会发现 A、C、E 都属于"注册登录"这一主题。

**主题追溯**就是：把时间线上的每个 turn 看作一个圆柱，圆柱的高度代表该 turn 的计算/思考深度，颜色/标签代表主题。我们甚至可以从kimi code已经压缩归档的上下文中再次挖掘，进行深度横向扫描，把同色圆柱（对话轮turns）找出来，重新建立关联，组成theme并存入记忆。当我们三周以后准备升级的我们的“注册登录”模块，或者修复某个bug的时候，不是对着已经压缩过无数次上下文的agent，重新描述对其当时的设计思路和方案，而是你的agent说：“刚刚通过trace_theme("注册登录")这个主题，发现根据3周前的设计决策和中间经历的2次调整改进，现在的问题我们应该用方案B。”

>下图展示了 `kimi-memory` 如何看待对话历史：竖条是时间轴上的 turn，粗横线是簇，灰框是 session，彩色括号把跨 session 的相关 turns / clusters 串联成主题线。

![时间轴上的 turns、簇、session 与主题追溯](./assets/contextFlow.svg)

下面是一段真实的 Kimi Code CLI 会话动图，使用 `kimi-memory`。用户先后要求总结 MCP 记忆服务器的演进历史、以及 E2E 测试工具的演进历史；Agent 跨会话召回相关记忆与对话 turns，并生成结构化总结。

![Kimi Memory MCP Server 演示](https://github.com/user-attachments/assets/a8947676-1487-47ed-8e0c-8d15f8662618)

相关工具：`tag_theme`、`trace_theme`、`list_themes`、`search_context`、`refine_session_turns`、`load_turn_context`。

## 为什么用 Markdown？

大多数 Agent 记忆系统默认使用向量数据库。这在模糊检索场景有效，但也让记忆变得不透明、难以审计、难以版本控制。

本项目从相反的假设出发：

> 记忆在存储之前应该经过**判断、结构化，并由用户拥有**。

Markdown + YAML frontmatter 带来：

- 完全可读、可编辑
- 原生支持 git diff
- 无需外部数据库或云服务
- 兼容任何能读取文本的 LLM

设计 rationale 见 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)。

## 安装

需要 Node.js ≥ 22.13（内置 `node:sqlite`，无需原生编译依赖）。

### 从 npm 安装（推荐）

```bash
npm install -g kimi-code-memory-mcp-server
```

### 从源码安装

```bash
git clone https://github.com/Zehee/kimi-code-memory-mcp-server.git
cd kimi-code-memory-mcp-server
npm install
npm run build
```

## 快速配置（推荐）

运行 setup 命令自动配置 Kimi Code CLI。`kimi-memory-setup` 是 `kimi-code-memory-mcp-server` 包提供的 bin（registry 上没有同名独立包），二选一：

```bash
# 已按上文全局安装：bin 已在 PATH 上，直接运行
kimi-memory-setup

# 未全局安装：让 npx 从包中解析该 bin
npx -p kimi-code-memory-mcp-server kimi-memory-setup
```

它会完成：

1. 检测 `~/.kimi-code` 目录。
2. 在 `~/.kimi-code/AGENTS.md` 顶部注入记忆协议规则。
3. 将 `memory-manage` Skill 安装到 `~/.kimi-code/skills/memory-manage`。
4. 在 `~/.kimi-code/mcp.json` 中添加 `kimi-memory` MCP 服务器配置。

预览变更而不写入文件：

```bash
kimi-memory-setup --dry-run
```

后续如需移除注入的配置：

```bash
kimi-memory-setup --undo
```

## 升级

```bash
# 1. 全局更新到最新版本
npm install -g kimi-code-memory-mcp-server@latest

# 2. 重新生成注入的配置（AGENTS.md 协议块、memory-manage Skill、mcp.json 条目）
kimi-memory-setup --force
```

升级后请重启 `kimi web`：正在运行的 MCP 实例内存中仍是旧代码，重启后才会加载新版本。

## 配置 Kimi Code CLI（手动）

如果你希望手动配置，编辑 `~/.kimi-code/mcp.json` 并添加服务器。

如果你用 `npm install -g` 安装，使用全局 `node_modules` 中 `dist/server.js` 的绝对路径：

```json
{
  "mcpServers": {
    "kimi-memory": {
      "command": "node",
      "args": ["/absolute/path/to/global/node_modules/kimi-code-memory-mcp-server/dist/server.js"],
      "enabled": true
    }
  }
}
```

> **Windows 原生二进制注意**：`kimi web`（原生 `kimi.exe`）的进程环境可能不包含 npm 的 bin 目录，裸 `node` / `npx` 会报 `spawn ... ENOENT`。此时把 `command` 换成 `node.exe` 的绝对路径（如 `D:\\Programs\\nodejs\\node.exe`）。`kimi-memory-setup` 生成的配置会自动使用绝对路径，推荐优先使用 setup。

或者直接通过 `npx` 运行（无需安装；仅限 npx 在客户端进程 PATH 中可用的环境，且每次启动有 registry 解析开销）：

```json
{
  "mcpServers": {
    "kimi-memory": {
      "command": "npx",
      "args": ["-y", "kimi-code-memory-mcp-server"],
      "enabled": true
    }
  }
}
```

如果你从源码构建，指向本地 `dist/server.js`：

```json
{
  "mcpServers": {
    "kimi-memory": {
      "command": "node",
      "args": ["/absolute/path/to/kimi-code-memory-mcp-server/dist/server.js"],
      "enabled": true
    }
  }
}
```

服务器名称 **`kimi-memory`** 很重要，因为本仓库自带的 `AGENTS.md` 规则以 `mcp__kimi-memory__*` 形式调用工具（例如 `mcp__kimi-memory__bootstrap_workspace`）。

重启 Kimi Code CLI 以加载该服务器。

## 故障排查

- **`spawn npx ENOENT` / `spawn node ENOENT`**：客户端进程找不到命令（常见于原生 Windows 二进制）。把 `mcp.json` 里的 `command`/`args` 改为 Node 与 `dist/server.js` 的绝对路径，或运行 `kimi-memory-setup --force` 重新生成。
- **改了 `mcp.json` 但 `/new` 后仍不生效**：MCP server 在会话启动时加载，且连接失败会被当前 `kimi web` 进程缓存，`/new` 不会重试——需要重启 `kimi web`（或 CLI）。
- **切换工作区后 MCP 不可用**：0.4.1 之前版本存在 vis dashboard 端口竞态，会拖垮 MCP 进程；升级到 0.4.1+ 并重启 `kimi web`。
- 客户端连接日志见 `~/.kimi-code/logs/kimi-code.log`。

## 可选：安装用户级 AGENTS.md 启动钩子

如需每次会话启动时自动恢复记忆并应用行为规范，将本仓库自带的 `AGENTS.md` 复制到 Kimi Code 用户目录：

```bash
cp AGENTS.md ~/.kimi-code/AGENTS.md
```

这会安装一个启动钩子，让 Kimi Code CLI 在每次会话开始时调用 `bootstrap_workspace`，并遵循记忆分类和决策守卫规则。由于 `AGENTS.md` 会注入到**每个**会话中，它是放置记忆相关行为协议的正确位置。

> **注意：** `AGENTS.md` 规则会注入到每个会话中，请只保留与记忆相关的约定，不要包含属于其他 MCP server 的工具偏好。
>
> **前提条件：** 必须在 `~/.kimi-code/mcp.json` 中将 MCP 服务器注册为 `kimi-memory`，否则 `AGENTS.md` 中的 `mcp__kimi-memory__*` 调用会失败。

## 可选：安装记忆 Skill

本仓库还包含一个轻量 Skill（`skills/memory-manage/SKILL.md`），用于在用户表达记忆相关意图时提醒 Kimi Code CLI 调用记忆工具。

```bash
cp -r skills/memory-manage ~/.kimi-code/skills/memory-manage
```

该 Skill 本身**不强制**行为，它只是一个调度器。真正的协议（何时 remember、决策守卫等）应配置在 `AGENTS.md` 中。

## 快速开始

服务器加载后，Agent 可以自然地调用记忆工具（工具名带有你在 MCP 配置中注册的 server 名称前缀，例如 `mcp__kimi-memory__*`）：

```text
用户：我们用 SQLite 作为缓存层。
Agent：[调用 mcp__kimi-memory__remember] key=use-sqlite-cache, folder=memory/decisions

用户：为什么选 SQLite？
Agent：[调用 mcp__kimi-memory__search] query=SQLite cache decision
       [调用 mcp__kimi-memory__recall] key=use-sqlite-cache, folder=memory/decisions
       → "我们选择 SQLite 而不是 Redis，因为……"

用户：缓存设计是怎么演化的？
Agent：[调用 mcp__kimi-memory__tag_theme] theme=cache-design
       [调用 mcp__kimi-memory__trace_theme] theme=cache-design
       → 展示跨会话的相关轮次和决策
```

## 存储布局

服务器将数据存储在 `~/.kimi-code-memory/<workspace-id>/` 下：

```text
~/.kimi-code-memory/workspace-a1b2c3d4/
├── index.json              # v3-kv 元数据缓存（可重建）
├── memory/
│   ├── decisions/          # 架构与产品决策
│   ├── knowledge/          # 项目相关知识
│   ├── rules/              # 约定与红线
│   └── reference/          # 外部参考
├── essence/
│   └── essence.md          # 工作区精要（≤15 KB）
├── notes/                  # 临时速记
├── themes/
│   └── my-theme.json       # theme -> turn/memory 引用
└── refined/
    └── refined.sqlite      # 轮次级摘要
```

可通过 `MEMORY_STORE_ROOT` 环境变量覆盖存储根目录。

### 环境变量

| 变量 | 用途 |
|------|------|
| `MEMORY_STORE_ROOT` | 覆盖默认存储根目录 `~/.kimi-code-memory`。 |
| `MEMORY_SESSIONS_ROOT` | 覆盖默认的 `~/.kimi-code/sessions` 路径，用于发现 `wire.jsonl` 文件。 |
| `KIMI_CODE_HOME` | `MEMORY_SESSIONS_ROOT` 的替代方案；会话从 `<KIMI_CODE_HOME>/sessions` 读取。 |
| `KIMI_MEMORY_AUTO_VIS` | 是否在 MCP 服务器启动时自动启动仪表盘。默认 `1`/`true`；设为 `0`/`false` 禁用。 |
| `KIMI_MEMORY_VIS_PORT` | 仪表盘起始端口，默认 `58628`；若被占用会自动向后尝试 10 个端口。 |
| `KIMI_MEMORY_VIS_HOST` | 仪表盘绑定地址，默认 `127.0.0.1`。 |

## 工具列表

| 工具 | 用途 |
|------|------|
| `remember` | 写入一条 Markdown 记忆 |
| `recall` | 按 key 读取记忆 |
| `search` | 在记忆中关键词搜索 |
| `list` | 列出记忆，支持按 folder / tag 过滤和 limit 限制 |
| `list_tags` | 列出所有标签 |
| `delete` | 删除记忆 |
| `move` | 移动或重命名记忆 |
| `organize_memories` | 将 `memory/` 提炼为 `essence/essence.md` |
| `sync_workspace_index` | 从磁盘重建 `index.json` |
| `bootstrap_workspace` | 加载上下文、精要和记忆树 |
| `load_more_context` | 加载更早的对话轮次 |
| `search_context` | 跨所有会话 wire 搜索 |
| `load_turn_context` | 加载指定轮次详情 |
| `tag_theme` | 将轮次或记忆关联到主题 |
| `trace_theme` | 追溯主题演化 |
| `list_themes` | 列出主题 |
| `delete_theme` | 删除主题关联文件 |
| `list_search_views` | 列出保存的搜索视图 |
| `delete_search_view` | 删除搜索视图（可选级联删除关联精炼轮次） |
| `open_memory_dashboard` | 在浏览器中打开记忆仪表盘 |
| `refine_session_turns` | 生成精炼轮次摘要 |

## Prompts

本服务器同时提供可复用的 MCP Prompt，供客户端在调用工具前拉取：

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

## Resources

本服务器暴露以下 MCP Resource URI，客户端可按需读取：

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

## 可视化仪表盘

提供独立的 Web 仪表盘，用于查看工作区记忆、主题时间线和近期决策。

### 启动方式

1. **随 MCP 服务器自动启动（默认）**

   `kimi-code-memory-mcp-server` 启动后会自动在后台启动仪表盘，并尝试打开浏览器。默认地址：

   ```text
   http://127.0.0.1:58628
   ```

   若端口被占用，会自动尝试 `58629`–`58637`。

   如需禁用自动启动：

   ```bash
   export KIMI_MEMORY_AUTO_VIS=0
   ```

2. **手动独立启动**

   安装包后：

   ```bash
   kimi-memory-vis
   ```

   从源码运行：

   ```bash
   npx tsx src/vis-cli.ts
   ```

   常用选项：

   ```bash
   kimi-memory-vis --port 8080        # 指定端口
   kimi-memory-vis --no-open          # 不自动打开浏览器
   kimi-memory-vis --workspace /path  # 查看其他工作区
   ```

3. **在对话中让 Agent 打开**

   让 Agent 调用记忆工具：

   ```text
   mcp__kimi-memory__open_memory_dashboard
   ```

### 环境变量

| 变量 | 用途 |
|------|------|
| `KIMI_MEMORY_AUTO_VIS` | 是否在 MCP 服务器启动时自动启动仪表盘。默认 `1`/`true`；设为 `0`/`false` 禁用。 |
| `KIMI_MEMORY_VIS_PORT` | 仪表盘起始端口，默认 `58628`。 |
| `KIMI_MEMORY_VIS_HOST` | 仪表盘绑定地址，默认 `127.0.0.1`。 |

### 仪表盘功能

- 工作区概览与 `essence.md` 浏览/编辑（默认只读，点击“编辑”后修改）
- Markdown 文档轻量级渲染，超长内容自带滚动条
- 主题时间线浏览与主题删除
- 搜索视图列表与删除（支持仅删视图或级联清理精炼轮次）
- 近期决策列表
- 显式记忆目录浏览
- 控制面板标题与面包屑根目录显示为用户工作区文件夹名
- 中英文界面切换（顶栏一键切换，默认跟随浏览器语言）

## 开发

```bash
git clone https://github.com/Zehee/kimi-code-memory-mcp-server.git
cd kimi-code-memory-mcp-server
npm install
npm run build
npm test
npm run lint
```

贡献指南见 [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.zh-CN.md)。

## 项目结构

```text
src/
├── server.ts              # MCP 服务器入口
├── config.ts              # 默认值与路径
├── theme-manager.ts       # 主题存储
├── refined-manager.ts     # 精炼轮次存储
├── dao/
│   ├── index.ts           # index.json DAO（v3-kv）
│   └── memory-store.ts    # Markdown 文件操作
├── context/
│   └── wire-context.ts    # wire.jsonl 解析
├── tools/
│   ├── index.ts           # 工具 schema 与分发
│   ├── memory-tools.ts    # 记忆增删改查
│   ├── context-tools.ts   # 上下文恢复
│   ├── theme-tools.ts     # 主题追溯
│   └── system-tools.ts    # 整理/同步/引导
└── utils/
    ├── frontmatter.ts
    ├── paths.ts
    └── validation.ts
```

## 路线图

- [x] 模块化源码结构
- [x] ESLint + Prettier
- [x] 基础集成测试
- [x] 上下文/主题工具核心测试覆盖
- [ ] 可选本地 embedding 搜索
- [ ] 可选 LLM 精炼轮次
- [ ] 可插拔 wire 格式适配器
- [ ] 内存使用 benchmark

## 相关文档

- [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) —— 系统设计与数据流
- [`docs/three-layer-memory-model.zh-CN.md`](./docs/three-layer-memory-model.zh-CN.md) —— 本服务器背后的记忆模型理论
- [`docs/search-logic.zh-CN.md`](./docs/search-logic.zh-CN.md) —— `search` 与 `search_context` 的实现逻辑
- [`docs/CONTRIBUTING.zh-CN.md`](./docs/CONTRIBUTING.zh-CN.md) —— 如何贡献

## 许可证

MIT