khwan-mcp

Khwan MCP is a persistent memory layer that connects to Claude Code, Claude Desktop, or any MCP client as an MCP server. Its core positioning is: to let memory survive after a session ends, and to persist and distill important content into a compact set of facts that can be recalled in subsequent sessions or used to initialize subagents, rather than replaying the entire conversation record.

Purpose and positioning Khwan itself does not run your model; the client is the model. Its responsibility is to persist and distill important content into recallable memory. One account can hold multiple isolated cores (brains), and on paid plans can also provide an isolated sub-brain for each end user.

Main capabilities

• Memory read/write: khwan_recall and khwan_remember are the "token-saving combination" for cache-oriented hosts; neither produces inference calls on the read or write path.
• Full loop: khwan_prepare and khwan_record are for custom agents, and the exact turn_token returned by prepare must be passed back to record.
• Nightly distillation: Khwan runs one of its own models on a schedule to distill stored conversation turns into long-term lessons. A real production run example given in the material is: 8 brains, 245 stored turns distilled into 11 lessons, at a cost of $0.0094. This cost is borne by Khwan, not the user.
• Recall limit: khwan_recall returns at most three facts (the limit is set by the server; limit can only be lowered, not raised), plus lessons distilled from multiple turns of history. Lessons are placed before seed_text.
• Relevance floor: retrieval has a relevance floor, so returning empty facts is also an answer, meaning there is nothing in that brain close to this question, and it should be understood as "unknown here" rather than a failure.

How to use Connecting to Claude Code: using --scope project will write .mcp.json into the repository, so the configuration travels with the project. Note that you should not write secrets into that file. There are two ways to avoid putting secrets into the repository: first, export KHWAN_API_KEY in the shell that starts claude, and the server will inherit it; second, use a launcher (also applicable to desktop apps) that reads the secret from a file, keeping only non-confidential settings in the configuration.

Connecting to Claude Desktop: The MCP configurations of Claude Desktop and Claude Code are independent of each other, and claude mcp add will not modify this file. It must be added in claude_desktop_config.json, and absolute paths must be used, because the desktop application does not inherit the shell's PATH. The entire application selects only one core, with no mechanism for switching by project, so a broader core should be chosen.

Per-project memory isolation Isolation has two dimensions, and both provide complete isolation: a sub-brain is a complete independent brain, not a filter, and account::@web and account::@api share nothing. Multiplying the two dimensions, a free account can have four isolated brains: the core itself plus three sub-brains. Therefore, "one brain per project" can support up to four projects under the free plan, without needing to set KHWAN_CORE. Named cores are a paid dimension, used when four brains are not enough, or when you want to group by client rather than by repository. Note: a core must first be created in the dashboard; an unknown slug returns 404 rather than being created automatically; under the free plan, creating a named core returns 402, in which case KHWAN_CORE should remain unset and KHWAN_USER should be used. Sub-brains are created on first write.

Recommended pattern (token-saving) On cache-based hosts such as Claude Code, prefer "seeding + memory" over round-by-round looping: at the start of a session or sub-agent, call khwan_recall(query="<task>") and use the returned seed_text as context; when a persistent fact appears, call khwan_remember(fact="…"). This convention can be reinforced in the project's CLAUDE.md. Seeding a sub-agent has the most obvious benefit: give it a bounded brief instead of the entire conversation transcript.

The boundaries of token savings It must be stated honestly how the mechanism works: MCP increases the host's context and cannot replace the conversation transcript the host has already sent. Therefore, within a single hot session it does not save tokens—Claude Code caches the growing history (cache reads at about 0.1×), and re-injecting memory every round only adds overhead. It saves tokens across sessions and sub-agents: the cache expires after a few minutes, sessions end, and Khwan persists distilled facts, so the next run can recall them at low cost without cold-replaying old records, and facts that have rolled out of context can also be retrieved again.

Seeding from existing work A new brain knows nothing, so recall is thin in the first few weeks, while the answers often already exist in the host's own conversation transcript. examples/backfill/ can replay Claude Code conversation transcripts into the brain: deterministic, with no model calls, dry-run by default.

Always-on memory (Claude Code hooks) examples/claude-code-hooks/ provides hook presets: the UserPromptSubmit hook injects memory on every prompt, and the Stop hook records every answer. Note that on cache-based hosts this is a thorough solution rather than a cheap one, and it increases tokens per round; prefer it when recall reliability matters more than token cost (or on non-caching clients), otherwise use khwan_recall at the start of the session.

Limitations and cautions

• Runtime reads and writes do not produce inference calls, but nightly distillation is run by Khwan using its own model.
• Recall returns at most three facts, subject to a relevance floor.
• Named cores are unavailable under the free plan (returns 402); sub-brains are created on first write.
• The desktop application does not inherit the shell's PATH and environment variables; absolute paths must be used and secrets read from files.
• This server runs locally, uses your keys, and reads the content you enter; you should read its code before installing.
• The license is MIT, © Khwan Labs.