Khwan MCP 是一个持久记忆层，作为 MCP 服务器接入 Claude Code、Claude Desktop 或任何 MCP 客户端。它的核心定位是：让记忆在会话结束后依然存活，并把重要内容持久化、蒸馏成可在后续会话中召回、或用于初始化子代理的紧凑事实集合，而不是重放整段对话记录。
用途与定位 Khwan 本身不运行你的模型，客户端才是模型。它的职责是持久化并蒸馏重要内容，形成可召回的记忆。一个账户可以持有多个隔离的 core（大脑），在付费方案上还可为每个终端用户提供隔离的子大脑（sub-brain）。
主要能力
- 记忆读写：khwan_recall 与 khwan_remember 是面向缓存型宿主的“省 token 组合”，二者在读写路径上都不产生推理调用。
- 完整循环：khwan_prepare 与 khwan_record 面向自定义代理，需把 prepare 返回的精确 turn_token 传回 record。
- 夜间蒸馏：Khwan 按计划运行自己的一个模型，将存储的对话轮次蒸馏为长期经验（lessons）。资料给出的一个真实生产运行示例为：8 个大脑、245 条存储轮次蒸馏为 11 条经验，成本 $0.0094。该成本由 Khwan 承担，而非用户。
- 召回上限：khwan_recall 最多返回三条事实（上限由服务器设定，limit 只能调低不能调高），外加由多轮历史蒸馏出的经验。经验会排在 seed_text 前面。
- 相关性下限：检索设有相关性下限，因此返回空 facts 也是一种答案，表示该大脑中没有接近此问题的内容，应理解为“此处未知”，而不是失败。
使用方式 接入 Claude Code：使用 --scope project 会把 .mcp.json 写入仓库，使配置随项目迁移。注意不要把密钥写进该文件。避免密钥入库有两种方式：其一，在启动 claude 的 shell 中导出 KHWAN_API_KEY，服务器会继承；其二，使用启动器（桌面应用同样适用），从文件读取密钥，配置中只保留非机密设置。
接入 Claude Desktop：Claude Desktop 与 Claude Code 的 MCP 配置相互独立，claude mcp add 不会改动该文件。需在 claude_desktop_config.json 中添加，并使用绝对路径，因为桌面应用不会继承 shell 的 PATH。整个应用只选择一个 core，没有按项目切换的机制，因此应选择较宽泛的 core。
按项目隔离记忆 隔离有两个维度，且都提供完全隔离：子大脑是完整独立的大脑，而非过滤器，account::@web 与 account::@api 不共享任何内容。两个维度相乘，免费账户即可拥有四个隔离大脑：核心本身加三个子大脑。因此“每个项目一个大脑”在免费方案下最多可支持四个项目，且无需设置 KHWAN_CORE。命名 core 是付费维度，当四个大脑不够用，或希望按客户而非按仓库分组时使用。注意：core 必须先在仪表盘中创建，未知 slug 会返回 404 而非自动创建；免费方案下创建命名 core 会返回 402，此时应保持 KHWAN_CORE 未设置并使用 KHWAN_USER。子大脑则在首次写入时创建。
推荐模式（省 token） 在 Claude Code 这类缓存型宿主上，优先使用“播种 + 记忆”而非逐轮循环：会话或子代理开始时调用 khwan_recall(query="<任务>") 并将返回的 seed_text 作为上下文；出现持久事实时调用 khwan_remember(fact="…")。可在项目的 CLAUDE.md 中强化这一约定。为子代理播种收益最明显：给它一份有界简报，而不是整段对话记录。
Token 节省的边界 需诚实说明机制：MCP 会增加宿主的上下文，无法替代宿主已发送的对话记录。因此，在单个热会话内它不省 token——Claude Code 会缓存不断增长的历史（缓存读取约 0.1×），每轮重新注入记忆只会增加开销。跨会话和子代理时它才省 token：缓存几分钟即失效，会话会结束，而 Khwan 持久化蒸馏后的事实，使下一次运行能低成本召回，无需冷重放旧记录，已滚出上下文的事实也可再次检索。
从已有工作播种 新大脑一无所知，最初几周的召回内容较薄，而答案往往已存在于宿主自身的对话记录中。examples/backfill/ 可将 Claude Code 对话记录重放进大脑：确定性、无模型调用、默认 dry-run。
常开记忆（Claude Code hooks） examples/claude-code-hooks/ 提供 hook 预设：UserPromptSubmit hook 在每个提示时注入记忆，Stop hook 记录每个回答。注意在缓存型宿主上这是彻底方案而非廉价方案，会增加每轮 token；当召回可靠性比 token 成本更重要（或在非缓存客户端上）时优先使用，否则在会话开始时使用 khwan_recall。
限制与注意
- 运行时读写不产生推理调用，但夜间蒸馏由 Khwan 运行自己的模型。
- 召回最多三条事实，且受相关性下限约束。
- 免费方案下命名 core 不可用（返回 402），子大脑首次写入时创建。
- 桌面应用不继承 shell 的 PATH 与环境变量，需使用绝对路径并从文件读取密钥。
- 该服务器在本机运行，使用你的密钥，读取你输入的内容，安装前应先阅读其代码。
- 许可证为 MIT，© Khwan Labs。
