Khwan

khwan-mcp

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

Khwan 绝不会运行你的模型。模型就是客户端。 它的工作是持久保存并提炼重要信息，存入一个大脑，供你在之后的会话中回忆，或用来为子 Agent 提供初始信息——一组精简且有界的事实，而不是重放对话记录。一个账户可以容纳多个相互隔离的核心（大脑），并且在付费方案中，还可为每位最终用户提供一个隔离的子脑。

读取或写入路径都不会产生推理调用费用：khwan_recall 和 khwan_remember 都不会触发推理。Khwan 确实会按计划运行自己的一个模型——每晚进行一次处理，将存储的对话轮次提炼为长期经验。一次真实的生产运行处理了 8 个大脑和 245 条已存储对话轮次，提炼出 11 条经验，费用为 $0.0094。 这笔费用由 Khwan 承担，不会转嫁给你；这正是它与每轮都进行压缩、构建图谱或整合的记忆层之间的全部区别。

它如何节省令牌（以及不会节省的地方）

坦诚说明其机制——MCP 会为宿主的上下文增加内容，无法替代宿主已经发送的对话记录。因此：

• 在同一个活跃会话中，它不会节省令牌。 Claude Code 会缓存不断增长的历史记录（缓存读取费用约为普通费用的 0.1 倍），因此每轮重新注入记忆只会增加消耗。不要在这里这样做。
• 跨会话和子 Agent 时，它能节省令牌。 缓存几分钟后就会失效；会话也会结束。Khwan 会持久保存提炼出的事实，让下一次运行以较低成本回忆这些信息——无需冷启动重放旧对话记录，也能重新检索已从上下文中滚出的事实。

节省令牌的模式：只注入一次，记住持久事实（见下文），而不是在使用缓存的宿主上每轮都运行完整流程。在不使用缓存的宿主上运行自定义 Agent时，完整的 prepare → record 流程仍然很有用，因为用提炼后的记忆替代历史记录，可以直接限制每轮的成本。

安装

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

启动器（桌面应用也适用）。 桌面应用由程序坞或菜单启动，而不是由登录 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。

每个项目一个大脑

只有在能取回正确项目的记忆时，记忆才有用。有两个维度，而且 两者都能实现完全隔离：

	选择方式	免费	付费
核心	KHWAN_CORE	1 个——仅 default	5 个（starter）→ 25 个（pro）
子大脑	KHWAN_USER	3 个	不限

子大脑是完全独立的大脑，不是筛选器：account::@web 与 account::@api 之间毫无共享。因此两个维度相乘，免费账户 已经拥有四个相互隔离的大脑——核心本身一个，外加三个 子大脑：

account              default core, no KHWAN_USER      brain 1
account::@web        KHWAN_USER=web                   brain 2
account::@api        KHWAN_USER=api                   brain 3
account::@docs       KHWAN_USER=docs                  brain 4

这意味着，免费方案就能实现每个项目一个大脑，最多支持四个 项目——而且完全不需要设置 KHWAN_CORE：

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

命名核心属于付费维度。当四个大脑不够用，或者你希望按客户而非 代码仓库对它们分组时，就可以使用命名核心：

# 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

设置 KHWAN_CORE 之前，有两点需要了解。核心必须先存在 ——未知的 slug 会返回 404，而不是“自动为你创建”，并且核心 需要在控制面板中创建。免费方案没有可供选择的核心：唯一名额 已被 default 占用，因此创建命名核心会返回 402。在免费方案中， 请将 KHWAN_CORE 留空并使用 KHWAN_USER。相比之下，子大脑会在 首次写入时创建。

推荐模式（节省令牌）

在 Claude Code 这类带缓存的宿主中，优先使用注入 + 记忆， 而不是每轮都循环调用：

1. 注入：在会话或子 Agent 开始时：

   “调用 khwan_recall(query="<the task>")，并将返回的 seed_text 作为 上下文使用。”

2. 记忆：在持久事实出现时记下来：

   “这是一项长期决策——调用 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.

为子 Agent 注入上下文最能体现这种做法的优势——交给它一份范围明确的简报， 而不是整段对话记录：

“使用 khwan_recall(query="deploy runbook") 检索部署记忆，然后启动一个 子 Agent，将该 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_API_KEY	是	你从 Khwan 控制面板获取的密钥（kwk_live_…）。
KHWAN_CORE	否	选择一个命名核心。仅限付费方案——免费方案只有 default。
KHWAN_USER	否	核心内的独立大脑——免费方案有 3 个，付费方案不限。
KHWAN_BASE_URL	否	覆盖 API 基础地址——例如，本地引擎可使用 http://127.0.0.1:8010。

工具

工具	使用时机
khwan_recall(query, limit=3)	为会话/子 Agent 注入上下文 — 合成的 lessons + 最多 3 条相关事实，作为 seed_text。
khwan_remember(fact)	持久化可供未来会话使用的长期事实/偏好。
khwan_prepare(input)	完整流程，回答之前调用 — 记忆上下文 + 一个 turn_token。
khwan_record(turn_token, answer)	完整流程，回答之后调用 — 持久化本轮对话，让 Khwan 从中学习。
khwan_memory(limit=20)	查看大脑当前记住的内容。
khwan_cores()	列出账户上的隔离核心。

khwan_recall / khwan_remember 是适用于缓存型主机、节省 token 的工具组合； khwan_prepare / khwan_record 是适用于自定义 Agent 的完整流程（将 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/ 中的 hook 预设：UserPromptSubmit hook 会在每次提示词提交时注入记忆，Stop hook 会记录每个答案。

⚠️ 在缓存型主机上，这是全面的方案，而不是省钱的方案 — 它会在每轮增加 token 开销。若记忆检索的可靠性比 token 成本更重要（或使用非缓存客户端），请优先选择此方案； 否则请在会话开始时使用 khwan_recall。

源码

github.com/khwanlabs/khwan-mcp — 此 服务在你的机器上运行，使用你的密钥，并读取你输入的内容。安装前请先阅读源码。

许可证

MIT — © Khwan Labs。参见 LICENSE。