项目目的与定位

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。

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

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 提供三个可复用的指令模板，客户端可在调用工具前拉取：

资料来源：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。

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

资料来源：README.en.md:21-26。

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

See Also

• docs/ARCHITECTURE.md — 系统设计与数据流
• docs/three-layer-memory-model.md — 理论记忆模型
• docs/search-logic.md — search 与 search_context 实现细节
• docs/CONTRIBUTING.md — 贡献指南

架构概览

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

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

工具、提示与资源

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

工具注册由 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 — 系统设计与数据流
• docs/three-layer-memory-model.md — 三层记忆模型理论
• docs/search-logic.md — search 与 search_context 的实现细节
• CHANGELOG.md — 版本演进记录

存储布局与数据模型

概述

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）是一个以存储根目录为基准的子目录，其内部布局如下：

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 字段包括：

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

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

MCP Tools、Prompts 与 Resources

概述

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

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

Pitfall Log / 踩坑日志

项目：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