Kimi Code Memory MCP Server

English

一个为 Kimi Code CLI 提供跨会话记忆的本地 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 串联成主题线。

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

相关工具：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。

安装

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

从 npm 安装（推荐）

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

从源码安装

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 上没有同名独立包），二选一：

# 已按上文全局安装：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 服务器配置。

预览变更而不写入文件：

kimi-memory-setup --dry-run

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

kimi-memory-setup --undo

配置 Kimi Code CLI（手动）

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

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

{
  "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 解析开销）：

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

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

{
  "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 用户目录：

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 调用记忆工具。

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

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

快速开始

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

用户：我们用 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>/ 下：

~/.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 环境变量覆盖存储根目录。

环境变量

工具列表

Prompts

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

Resources

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

可视化仪表盘

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

启动方式

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

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

   http://127.0.0.1:58628

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

   如需禁用自动启动：

   export KIMI_MEMORY_AUTO_VIS=0

2. 手动独立启动

   安装包后：

   kimi-memory-vis

   从源码运行：

   npx tsx src/vis-cli.ts

   常用选项：

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

3. 在对话中让 Agent 打开

   让 Agent 调用记忆工具：

   mcp__kimi-memory__open_memory_dashboard

环境变量

仪表盘功能

• 工作区概览与 essence.md 浏览/编辑（默认只读，点击“编辑”后修改）

• Markdown 文档轻量级渲染，超长内容自带滚动条

• 主题时间线浏览与主题删除

• 搜索视图列表与删除（支持仅删视图或级联清理精炼轮次）

• 近期决策列表

• 显式记忆目录浏览

• 控制面板标题与面包屑根目录显示为用户工作区文件夹名

开发

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。

项目结构

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

路线图

• 模块化源码结构

• ESLint + Prettier

• 基础集成测试

• 上下文/主题工具核心测试覆盖

• 可选本地 embedding 搜索

• 可选 LLM 精炼轮次

• 可插拔 wire 格式适配器

• 内存使用 benchmark

相关文档

• docs/ARCHITECTURE.md —— 系统设计与数据流

• docs/three-layer-memory-model.zh-CN.md —— 本服务器背后的记忆模型理论

• docs/search-logic.zh-CN.md —— search 与 search_context 的实现逻辑

• docs/CONTRIBUTING.zh-CN.md —— 如何贡献

许可证

MIT