kimi-code-memory-mcp-server 0.1.0

package/AGENTS.md

@@ -0,0 +1,144 @@
+## 强制启动协议
+
+每次会话开始后、回答用户第一个问题或执行任何可能改变项目状态的操作之前，**必须调用** `mcp__kimi-memory__bootstrap_workspace()`。
+
+必须读取并内化：
+1. `essence.md` —— 当前工作区什么最重要
+2. `memoryIndexTree` —— 记忆目录结构，关注标记 `[new]` 的最近变化
+3. `recentContext` —— 当前 session 的最近对话
+4. `notesRefs` —— 是否有待处理的速记
+
+---
+
+## 记忆分类约定
+
+| 类型 | folder | tags | 用途 |
+|------|--------|------|------|
+| 决策 | `memory/decisions/` | `decision` | 架构、接口、流程决策 |
+| 规则 | `memory/rules/` | `rule` | 编码规范、协作红线 |
+| 知识 | `memory/knowledge/` | `knowledge` | 技术栈、业务背景 |
+| 参考 | `memory/reference/` | `reference` | 外部链接、文档引用 |
+| 速记 | `notes/` | `scratch` | 临时便签，不进入长期精要 |
+
+---
+
+## 什么时候必须 `remember`？
+
+出现以下信号时立即写入 `memory/`：
+
+- 用户说"我们决定…"、"拍板了" → `memory/decisions/`，tag `decision`
+- 用户说"这里必须…"、"红线是…" → `memory/rules/`，tag `rule`
+- 技术选型、接口约定首次出现 → `memory/knowledge/`，tag `knowledge`
+- 定位到 bug 根因和修复方案 → `memory/decisions/` 或 `memory/knowledge/`，tag `fix`
+- 编码风格、目录结构、命名规范 → `memory/rules/`，tag `convention`
+
+---
+
+## 什么时候不要 `remember`？
+
+- ❌ 临时调试命令或探索性代码
+- ❌ 用户未确认的推测
+- ❌ 一次性报错（没有形成通用结论）
+- ❌ 当前会话的临时上下文（由 `wire.jsonl` 自动捕获）
+- ❌ 已经在 `memory/` 中存在的知识
+
+判断口诀：如果这条信息三天后回头看仍然有价值，才写入 `memory/`。
+
+---
+
+## 决策守卫
+
+准备执行任何可能改变项目状态的操作之前（写文件、改结构、做选择、引入依赖）：
+
+1. 提取关键词（技术实体 + 动作）
+2. 并行查询：
+   - `search(query, folder="memory")` —— 查决策/规则/知识
+   - `search_context(query)` —— 查历史对话
+3. 命中且一致 → 引用来源后继续
+4. 命中但矛盾 → 向用户报告冲突，请求澄清
+5. 未命中但重要 → 询问用户"这是一个新决策，是否记录？"
+
+---
+
+## 引用来源的纪律
+
+所有从 `memory/` 召回的关键结论，回复中必须标注来源：
+
+- ✅ "根据 `memory/decisions/xxx`，我们决定…"
+- ❌ "我们之前决定…"（无来源）
+
+---
+
+## 主题追溯
+
+当用户要求追溯某个主题时：
+
+1. 确认主题范围
+2. 用 `search_context` 打捞相关 turns（调用时会自动按 90 秒时间簇扩展并提炼命中的 turns）
+3. 用 `list_search_views` 查看最近的搜索视图，作为 theme 挂载的候选集
+4. 对搜索命中的 turns 做语义分析，用 `tag_theme` 把 genuinely belongs to the theme 的 turns 逐个挂载到 `themes/<theme>.json`
+5. 如果候选不足，用新的 query 再次 `search_context` 打捞，生成新的 search view
+6. 用 `trace_theme` 输出主题时间线
+
+`search_context` 已内置提炼能力，不需要单独调用 `refine_session_turns`。
+
+---
+
+## 记忆卫生检查清单
+
+每次调用 `remember` 前：
+
+- [ ] 这条信息三天后还有价值吗？
+- [ ] 是否已有重复记忆？（先 `search`）
+- [ ] `folder` 选对了吗？项目相关不进 `notes/`
+- [ ] `tags` 是否包含最贴切的分类标签？
+- [ ] 正文是否包含决策原因/影响范围/相关文件？
+
+每次做决策前：
+
+- [ ] 是否已 `search` 相关历史决策？
+- [ ] 是否已检查 `essence.md` 中的核心约束？
+- [ ] 如果与历史记忆冲突，是否已向用户澄清？
+
+---
+
+## MCP Server 版本号规则
+
+项目存在两个版本号，必须区分并保持一致：
+
+| 版本号 | 位置 | 用途 |
+|--------|------|------|
+| 仓库版本 | `package.json#version` | 发布包、Git tag、CHANGELOG 的版本 |
+| 运行实例版本 | `src/version.ts` → `src/server.ts` | MCP 协议握手时报告的版本 |
+
+- 采用 SemVer 2.0.0（`MAJOR.MINOR.PATCH`）。
+- 单一事实来源：`package.json#version`。
+- 运行实例版本通过 `npm run sync-version` 从 `package.json` 同步到 `src/version.ts`。
+- `npm run build` 会自动执行同步。
+- 禁止手动修改 `src/version.ts`；改版本只改 `package.json`。
+
+### 升级触发条件
+
+| 位 | 触发条件 |
+|----|----------|
+| MAJOR | 不兼容的协议/存储格式/工具签名变更 |
+| MINOR | 新增工具或能力、非破坏性增强 |
+| PATCH | Bug 修复、性能优化、文档/测试更新 |
+
+### 代码变更后验证顺序
+
+1. 仓库内：`npm run typecheck && npm run lint && npm test`
+2. **运行实例实测**：当仓库测试受本地环境干扰（例如仓库本身积累了大量历史 sessions、数据状态复杂，导致难以在干净条件下验证）时，将新代码同步到实际 MCP 运行实例（如 Kimi Code CLI 调用的 server），用真实工作区验证行为。
+3. 严禁仅以仓库测试通过为由跳过必要的运行实例实测，尤其是涉及环境变量、路径解析、缓存/模块状态的变更。
+
+---
+
+## 禁止行为
+
+- 禁止用 `folder="notes"` 保存项目相关记忆
+- 禁止写入空 tags
+- 禁止只口头答应而不调用工具
+- 禁止手动修改 `~/.kimi-code/sessions/` 下的 `wire.jsonl`
+- 禁止手动修改 `src/version.ts`（应通过 `package.json` + `npm run sync-version` 同步）
+- **当用户输入以 `？` / `?` 结尾时，禁止执行任何写入/修改/构建/运行等改变项目状态的操作**：只能回答问题和进行讨论，必须等待用户明确说出「确定」「可以」「开始吧」等指令后才能行动
+

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-24
+
+### Added
+- Initial release of Kimi Code Memory MCP Server.
+- Modular source structure (`src/tools`, `src/dao`, `src/context`, `src/utils`).
+- Memory CRUD tools: `remember`, `recall`, `recall_recent`, `search`, `list`, `list_tags`, `delete`, `move`.
+- Context recovery tools: `bootstrap_workspace`, `load_workspace_context`, `load_more_context`, `search_context`, `load_turn_context`.
+- Theme tracing tools: `tag_theme`, `trace_theme`, `list_themes`, `refine_session_turns`.
+- System tools: `organize_memories`, `sync_workspace_index`, `get_current_workspace`.
+- Markdown + YAML frontmatter storage with rebuildable `index.json` v3-kv cache.
+- ESLint + Prettier configuration.
+- Basic integration tests.
+- English and Chinese READMEs.
+- GitHub issue and PR templates.
+- CI workflow running tests and lint on pull requests.
+- MCP server versioning rules: SemVer for repository version, runtime version synced from `package.json`, and a release workflow that includes real-instance validation.
+
+[Unreleased]: https://github.com/Zehee/kimi-code-memory-mcp-server/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Zehee/kimi-code-memory-mcp-server/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kimi-code-memory-mcp-server contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# Kimi Code Memory MCP Server
+
+[中文](./README.zh-CN.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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+A local stdio MCP server that gives [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) cross-session memory.
+
+> **Note:** This package is not yet published to npm. Install and run it from source (see below).
+
+User-facing memories are stored as plain Markdown files on disk. Refined turn summaries use a local SQLite cache, but no vector database, graph database, or external cloud service is required.
+
+## Features
+
+- **Markdown-first memories** — human-readable, git-friendly, LLM-compatible.
+- **Structured long-term memory** — `memory/decisions/`, `memory/knowledge/`, `memory/rules/`, `memory/reference/`.
+- **Workspace essence** — condensed digest (≤15 KB) generated from `memory/`.
+- **Cross-session context recovery** — parses Kimi Code CLI's `wire.jsonl` directly.
+- **Theme tracing** — associate conversation turns and memories with themes, then trace their evolution.
+- **Refined turn summaries** — reusable turn-level atomic summaries shared across themes.
+- **Rebuilding index** — `index.json` is a cache; `.md` files are the source of truth.
+
+## Why Markdown?
+
+Most agent memory systems default to vector databases. That works for fuzzy retrieval, but it also makes memories opaque, hard to audit, and hard to version-control.
+
+This project starts from the opposite assumption:
+
+> Memories should be **judged, structured, and owned by the user** before they are stored.
+
+Markdown + YAML frontmatter gives you:
+
+- Full readability and editability
+- Native git diff support
+- No required external database or cloud service
+- Compatibility with any LLM that can read text
+
+See [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the design rationale.
+
+## Install
+
+Currently the package must be installed from source. Node.js ≥ 18 is required.
+
+```bash
+git clone https://github.com/Zehee/kimi-code-memory-mcp-server.git
+cd kimi-code-memory-mcp-server
+npm install
+npm run build
+```
+
+## Configure Kimi Code CLI
+
+Edit `~/.kimi-code/mcp.json` and point to the built server entry:
+
+```json
+{
+  "mcpServers": {
+    "kimi-memory": {
+      "command": "node",
+      "args": ["/absolute/path/to/kimi-code-memory-mcp-server/dist/server.js"],
+      "enabled": true
+    }
+  }
+}
+```
+
+The server name **`kimi-memory`** is important because the bundled `AGENTS.md` rules call tools as `mcp__kimi-memory__*` (for example `mcp__kimi-memory__bootstrap_workspace`).
+
+Restart Kimi Code CLI to load the server.
+
+## Optional: Install User-Level AGENTS.md Startup Hook
+
+For automatic memory recovery and behavioral rules on every session start, copy the bundled `AGENTS.md` to your Kimi Code user directory:
+
+```bash
+cp AGENTS.md ~/.kimi-code/AGENTS.md
+```
+
+This installs a startup hook that tells Kimi Code CLI to call `bootstrap_workspace` at the beginning of every session, and to follow the memory classification and decision-guard rules. Because `AGENTS.md` is injected into **every** session, it is the right place for memory-related behavior protocols.
+
+> **Note:** Keep `AGENTS.md` focused on memory-related conventions only. Do not include tool preferences that belong to other MCP servers.
+>
+> **Prerequisite:** The MCP server must be registered under the name `kimi-memory` in `~/.kimi-code/mcp.json`, otherwise the `mcp__kimi-memory__*` calls in `AGENTS.md` will fail.
+
+## Optional: Install the Memory Skill
+
+This repository also includes a lightweight Skill (`skills/memory-manage/SKILL.md`) that reminds Kimi Code CLI to call the memory tools when the user expresses a memory-related intent.
+
+```bash
+cp -r skills/memory-manage ~/.kimi-code/skills/memory-manage
+```
+
+The Skill does **not** enforce behavior on its own; it is a dispatcher. The actual protocols (when to remember, decision guard, etc.) live in `AGENTS.md`.
+
+## Quick Start
+
+After the server is loaded, the agent can call memory tools naturally (tool names are prefixed with the MCP server name you configured, e.g. `mcp__kimi-memory__*`):
+
+```text
+User: Let's use SQLite for the cache layer.
+Agent: [calls mcp__kimi-memory__remember] key=use-sqlite-cache, folder=memory/decisions
+
+User: Why did we choose SQLite?
+Agent: [calls mcp__kimi-memory__search] query=SQLite cache decision
+       [calls mcp__kimi-memory__recall] key=use-sqlite-cache, folder=memory/decisions
+       → "We chose SQLite over Redis because..."
+
+User: How has the cache design evolved?
+Agent: [calls mcp__kimi-memory__tag_theme] theme=cache-design
+       [calls mcp__kimi-memory__trace_theme] theme=cache-design
+       → shows related turns and decisions across sessions
+```
+
+## Storage Layout
+
+The server stores data under `~/.kimi-code-memory/<workspace-id>/`:
+
+```text
+~/.kimi-code-memory/workspace-a1b2c3d4/
+├── index.json              # v3-kv metadata cache (rebuildable)
+├── memory/
+│   ├── decisions/          # architecture and product decisions
+│   ├── knowledge/          # project-specific knowledge
+│   ├── rules/              # conventions and guardrails
+│   └── reference/          # external references
+├── essence/
+│   └── essence.md          # workspace digest (≤15 KB)
+├── notes/                  # scratch notes
+├── themes/
+│   └── my-theme.json       # theme -> turn/memory refs
+└── refined/
+    └── refined.sqlite      # turn-level summaries
+```
+
+You can override the storage root with the `MEMORY_STORE_ROOT` environment variable.
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `MEMORY_STORE_ROOT` | Override the default `~/.kimi-code-memory` storage root. |
+| `MEMORY_SESSIONS_ROOT` | Override the default `~/.kimi-code/sessions` path used to discover `wire.jsonl` files. |
+| `KIMI_CODE_HOME` | Alternative to `MEMORY_SESSIONS_ROOT`; sessions are read from `<KIMI_CODE_HOME>/sessions`. |
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `remember` | Write a Markdown memory |
+| `recall` | Read a memory by key |
+| `recall_recent` | List recently updated memories |
+| `search` | Keyword search across memories |
+| `list` | List memories |
+| `list_tags` | List all tags |
+| `delete` | Delete a memory |
+| `move` | Move or rename a memory |
+| `organize_memories` | Distill `memory/` into `essence/essence.md` |
+| `sync_workspace_index` | Rebuild `index.json` from disk |
+| `bootstrap_workspace` | Load context, essence, and memory tree |
+| `load_workspace_context` | Load recent conversation context |
+| `load_more_context` | Load older conversation rounds |
+| `search_context` | Search across all session wires |
+| `load_turn_context` | Load specific turn details |
+| `tag_theme` | Associate a turn or memory with a theme |
+| `trace_theme` | Trace a theme's evolution |
+| `list_themes` | List themes |
+| `refine_session_turns` | Generate refined turn summaries |
+
+## Development
+
+```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
+```
+
+See [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) for contribution guidelines.
+
+## Project Structure
+
+```text
+src/
+├── server.ts              # MCP server entry
+├── config.ts              # defaults and paths
+├── theme-manager.ts       # theme storage
+├── refined-manager.ts     # refined turn storage
+├── dao/
+│   ├── index.ts           # index.json DAO (v3-kv)
+│   └── memory-store.ts    # Markdown file operations
+├── context/
+│   └── wire-context.ts    # wire.jsonl parsing
+├── tools/
+│   ├── index.ts           # tool schemas & dispatch
+│   ├── memory-tools.ts    # memory CRUD
+│   ├── context-tools.ts   # context recovery
+│   ├── theme-tools.ts     # theme tracing
+│   └── system-tools.ts    # organize/sync/bootstrap
+└── utils/
+    ├── frontmatter.ts
+    ├── paths.ts
+    └── validation.ts
+```
+
+## Roadmap
+
+- [x] Modular source structure
+- [x] ESLint + Prettier
+- [x] Basic integration tests
+- [x] Core test coverage for context/theme tools
+- [ ] Optional local embedding search
+- [ ] Optional LLM-based turn refinement
+- [ ] Pluggable wire format adapters
+- [ ] Memory usage benchmarks
+
+## Related Documents
+
+- [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) — system design and data flow
+- [`docs/search-logic.md`](./docs/search-logic.md) — how `search` and `search_context` work
+- [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) — how to contribute
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,227 @@
+# Kimi Code Memory MCP Server
+
+[English](./README.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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+一个为 [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) 提供跨会话记忆的本地 stdio MCP 服务器。
+
+> **注意：** 本包尚未发布到 npm，请按下面的说明从源码安装运行。
+
+面向用户的记忆以普通 Markdown 文件存储在磁盘上。精炼轮次摘要使用本地 SQLite 缓存，但无需向量数据库、图数据库或外部云服务。
+
+## 特性
+
+- **Markdown 优先的记忆** —— 人类可读、适合 git、兼容 LLM。
+- **结构化长期记忆** —— `memory/decisions/`、`memory/knowledge/`、`memory/rules/`、`memory/reference/`。
+- **工作区精要** —— 从 `memory/` 提炼生成的浓缩摘要（≤15 KB）。
+- **跨会话上下文恢复** —— 直接解析 Kimi Code CLI 的 `wire.jsonl`。
+- **主题追溯** —— 将对话轮次和记忆关联到主题，并追踪其演化。
+- **精炼轮次摘要** —— 可在多个主题间共享的轮次级原子摘要。
+- **可重建索引** —— `index.json` 只是缓存，`.md` 文件才是真相来源。
+
+## 为什么用 Markdown？
+
+大多数 Agent 记忆系统默认使用向量数据库。这在模糊检索场景有效，但也让记忆变得不透明、难以审计、难以版本控制。
+
+本项目从相反的假设出发：
+
+> 记忆在存储之前应该经过**判断、结构化，并由用户拥有**。
+
+Markdown + YAML frontmatter 带来：
+
+- 完全可读、可编辑
+- 原生支持 git diff
+- 无需外部数据库或云服务
+- 兼容任何能读取文本的 LLM
+
+设计 rationale 见 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)。
+
+## 安装
+
+目前本包需要从源码安装。需要 Node.js ≥ 18。
+
+```bash
+git clone https://github.com/Zehee/kimi-code-memory-mcp-server.git
+cd kimi-code-memory-mcp-server
+npm install
+npm run build
+```
+
+## 配置 Kimi Code CLI
+
+编辑 `~/.kimi-code/mcp.json`，指向构建后的服务器入口：
+
+```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 以加载该服务器。
+
+## 可选：安装用户级 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` 读取。 |
+
+## 工具列表
+
+| 工具 | 用途 |
+|------|------|
+| `remember` | 写入一条 Markdown 记忆 |
+| `recall` | 按 key 读取记忆 |
+| `recall_recent` | 列出最近更新的记忆 |
+| `search` | 在记忆中关键词搜索 |
+| `list` | 列出记忆 |
+| `list_tags` | 列出所有标签 |
+| `delete` | 删除记忆 |
+| `move` | 移动或重命名记忆 |
+| `organize_memories` | 将 `memory/` 提炼为 `essence/essence.md` |
+| `sync_workspace_index` | 从磁盘重建 `index.json` |
+| `bootstrap_workspace` | 加载上下文、精要和记忆树 |
+| `load_workspace_context` | 加载最近对话上下文 |
+| `load_more_context` | 加载更早的对话轮次 |
+| `search_context` | 跨所有会话 wire 搜索 |
+| `load_turn_context` | 加载指定轮次详情 |
+| `tag_theme` | 将轮次或记忆关联到主题 |
+| `trace_theme` | 追溯主题演化 |
+| `list_themes` | 列出主题 |
+| `refine_session_turns` | 生成精炼轮次摘要 |
+
+## 开发
+
+```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/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

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Global configuration.
+ *
+ * The store root can be overridden via the MEMORY_STORE_ROOT environment
+ * variable. When unset, it defaults to ~/.kimi-code-memory/ so that the
+ * server behaves like a user-level tool even when installed as a package.
+ */
+export declare const homedir: string;
+export declare function getStoreRoot(): string;
+/**
+ * Resolve the directory where Kimi Code CLI session wires are stored.
+ *
+ * Priority:
+ * 1. MEMORY_SESSIONS_ROOT environment variable (absolute path)
+ * 2. KIMI_CODE_HOME environment variable (<KIMI_CODE_HOME>/sessions)
+ * 3. Default ~/.kimi-code/sessions
+ */
+export declare function getSessionsRoot(): string;
+export interface ContextWindow {
+    detailedRounds: number;
+    defaultSummaryRounds: number;
+    loadMoreChunkSize: number;
+}
+export declare const DEFAULT_CONTEXT_WINDOW: ContextWindow;
+export declare const DEFAULT_RECENT_CHANGE_LIMIT = 5;
+export declare const ESSENCE_SIZE_LIMIT: number;
+/**
+ * search_context 用于把相邻 turn 聚成「簇」的默认时间间隔（秒）。
+ *
+ * 「簇」是指一小段连续的来回对话，通常围绕同一个决策或讨论展开。
+ * 如果两个相邻 turn 的时间间隔超过这个值，就认为它们属于不同的簇。
+ *
+ * 90 秒适合典型的 agent-user 对话：既能区分开不同话题，又足以保留
+ * 一段流畅讨论的完整性。每次搜索可以通过 cluster_gap_seconds 参数覆盖。
+ */
+export declare const DEFAULT_CLUSTER_GAP_SECONDS = 90;