khwan-mcp

能跨会话存续的持久记忆。 一个 MCP 服务器，将 Khwan——一个纯 AI 记忆层——接入 Claude Code、Claude Desktop 或任何 MCP 客户端。

Khwan 从不运行模型。客户端即模型。 它负责把重要的内容持久化并提炼成一颗大脑，让你可以在后来的会话中召回它，或用它来初始化一个子代理——这是一组紧凑、有界的事实，而不是回放的转录记录。一个账户可以拥有多个相互隔离的核心（cores，即大脑），在付费套餐中，还可以为每个最终用户提供隔离的子脑。

它如何节省 token（以及在哪些地方不节省）

对机制我们要坦诚——MCP 是向宿主上下文中添加内容，它不能替换宿主已经发送的对话记录。所以：

• 在一个热会话中，它并不节省 token。 Claude Code 会缓存不断增长的历史（缓存读取 ≈ 0.1×），因此每轮重新注入记忆只会增加开销。这里不要这么做。

• 跨会话和跨子代理时，它确实能节省。 缓存在几分钟内会失效；会话也会结束。Khwan 会持久化提炼后的事实，好让下一种运行低成本地召回它们——无需冷回放旧转录，且那些已经滚出上下文的事实可以再次被检索到。

省 token 的用法是：初始化（seed）一次，记住持久事实（见下文），而不是在缓存宿主的每一轮中都跑完整的循环。完整的 prepare → record 循环在非缓存宿主上的自定义代理中仍然大放异彩，在那里，用蒸馏后的记忆替换历史能直接约束每轮成本。

Related MCP server: LedgerMem MCP Server

安装

pip install khwan-mcp          # or: uvx khwan-mcp

连接到 Claude Code

claude mcp add khwan --scope project \
  -e KHWAN_CORE=default \
  -- khwan-mcp

--scope project 会把 .mcp.json 写入仓库，所以这个设置会跟着项目走。注意该命令中没有什么：密钥。

让密钥不进入仓库

claude mcp add -e KHWAN_API_KEY=… 会把字面量写入 .mcp.json——而这个文件的意义正是要被提交。有两种方式可以避免，第二种是在所有环境下都有效的方式：

Shell 环境变量。 完全不要让 KHWAN_API_KEY 出现在配置里，而是在启动 claude 的 shell 中导出它。服务器会继承它。

export KHWAN_API_KEY=kwk_live_xxx

一个启动器（在桌面应用中也有效）。 桌面应用是从 Dock 或菜单启动的，而不是从登录 shell 启动的，所以它不会继承你的任何 shell 导出，上面那种方法会静默地拿不到密钥。改为从文件读取：

mkdir -p ~/.khwan && chmod 700 ~/.khwan
printf 'KHWAN_API_KEY=kwk_live_xxx\n' > ~/.khwan/env && chmod 600 ~/.khwan/env

cat > ~/.khwan/khwan-mcp <<'SH'
#!/bin/sh
set -a
[ -f "$HOME/.khwan/env" ] && . "$HOME/.khwan/env"
set +a
exec khwan-mcp "$@"
SH
chmod 700 ~/.khwan/khwan-mcp

然后把配置指向这个启动器，只保留非机密设置内联：

claude mcp add khwan --scope project \
  -e KHWAN_CORE=acme -e KHWAN_USER=Web \
  -- ~/.khwan/khwan-mcp

现在 .mcp.json 可以安全提交了，每个新仓库只需要两行职责，而不是一段粘贴的密钥。团队里的其他人写自己的 ~/.khwan/env 即可。

每个项目一个大脑

记忆只有在正确的项目记忆被取回时才有用。两个维度，它们都提供完全隔离：

子脑是一个完全独立的大脑，而不是一层过滤器：account::acme::@Web 与 account::acme::@Api 不共享任何内容。所以一个客户端如果有多个仓库，可以让它们共用一个核心、各配一个子脑，而不是每个仓库各占一个原创：

# in ~/code/acme-web
claude mcp add khwan --scope project -e KHWAN_CORE=acme -e KHWAN_USER=Web -- ~/.khwan/khwan-mcp
# in ~/code/acme-api
claude mcp add khwan --scope project -e KHWAN_CORE=acme -e KHWAN_USER=Api -- ~/.khwan/khwan-mcp

核心在你指向它之前必须存在——未知核心会返回 404。请在控制台中创建。子脑会在第一次写入时自动创建。

推荐用法（省 token）

在像 Claude Code 这样的缓存主机上，优先选用 seed + remember，而不是每轮循环：

1. 初始化（seed）：在会话或子代理的开头——调用 khwan_recall(query="<the task>")，并把返回的 seed_text 作为上下文。

2. 记住（remember）：当持久的事实浮现时——>“这是个持久决定——调用 khwan_remember(fact="…")。”

在项目的 CLAUDE.md 中强化这个做法，例如：

- At the start of a task, call `khwan_recall` to seed relevant memory.
- When a durable decision/preference/fact emerges, call `khwan_remember`.
- Don't call prepare/record every turn — it adds tokens without saving them here.

初始化一个子代理是收益最明显场景：交给它的是一份有界简报，而不是整段转录：

“先用 khwan_recall(query="deploy runbook") 召回部署记忆，然后生成一个子代理，子代理收到的简报就是那段 seed_text 外加该任务。”

连接到 Claude Desktop

Claude Desktop 与 Claude Code 使用独立的 MCP 配置——给一方添加的服务器对另一方法不可见，claude mcp add 也不会动这个文件。请添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "khwan": {
      "command": "/Users/you/.khwan/khwan-mcp",
      "env": {
        "KHWAN_CORE": "acme",
        "KHWAN_USER": "Web"
      }
    }
  }
}

使用绝对路径：桌面应用同样不会获得你 shell 的 PATH，因此单独一个 khwan-mcp 可能无法解析。整个应用只能选一个核心——这里没有按项目切换的机制，所以选一个范围较宽的核心。

配置（环境变量）

工具

khwan_recall / khwan_remember 是缓存主机上省 token 的一对；khwan_prepare / khwan_record 是面向自定义代理的完整循环（把 prepare 返回的那个 turn_token 原样传入 record）。

返回了什么，以及空结果的含义

khwan_recall 最多返回三条事实——这个上限是服务器设定的，limit 只能调低，不能调高——另外还会有 lessons 从过去多轮中提炼出的内容。lessons 处于 seed_text 的开头：一份数月形成的规则优先于一条恰好出现在索引同一位置的单轮记录。

检索有一个相似度底限，所以 facts 为空也是答案：表明大脑里没有任何接近这个问题的东西。把它理解为“此处不存在”，而不是一次失败，并不要用“哪一条最近就补哪一条”的办法回避。

这个下限是有意放宽的，因为一条被误丢掉的内容是看不见的，而一条被误保留的内容并非看不见。所以返回的事实按理估计应当合理相关而不是必然相关——依赖之前先读它。

用已有工作初始化大脑

新大脑什么都不知道，所以头几周的召回会比较薄——而这些答案往往早已存在于宿主自己的转录中，从未被读取。 examples/backfill/ 会把 Claude Code 的转录回放到大脑中：确定性、不调用模型、默认试跑。

python3 examples/backfill/backfill_claude_code.py --map cores.json

常开记忆（Claude Code hooks）

上面这些工具的调用依赖 Claude 决定调用它们时。要确定性的记忆——不依赖模型——请使用 examples/claude-code-hooks/ 中的钩子预设：一个 UserPromptSubmit 钩子会在每个提示中注入记忆，一个 Stop 钩子会记录每个回答。

⚠️ 在缓存主机上，这是“彻底”而不是“廉价”的选项——它会增加每轮 token 开销。当“召回可靠性”比“token 成本”更重要时（或者在非缓存客户端上），可选它；否则请只在会话开始时使用 khwan_recall。

源码

github.com/khwanlabs/khwan-mcp —— 这个服务器运行在你自己的机器上，使用你的密钥，读取你输入的内容。在安装之前先阅读它。

License

MIT — © Khwan Labs. See LICENSE.