Khwan MCP server

khwan-mcp

Durable memory that survives the session. An MCP server that plugs Khwan — a pure AI-memory layer — into Claude Code, Claude Desktop, or any MCP client.

Khwan never runs your model. The client is the model. Its job is to persist and distil what matters into a brain you can recall in a later session or seed a subagent with — a compact, bounded set of facts instead of a replayed transcript. One account can hold many isolated cores (brains), and — on paid plans — an isolated sub-brain per end-user.

Nothing on the read or write path costs you an inference call: khwanrecall and khwanremember make none. Khwan does run one model of its own, on a schedule — a nightly pass that distils stored turns into standing lessons. A real production run was 8 brains and 245 stored turns distilled into 11 lessons, for $0.0094. That pass is Khwan's cost, not yours, and it is the whole difference from memory layers that compress, graph, or consolidate on every turn.

<!-- The MCP Registry verifies ownership of a PyPI package by finding this name in the package README, which is what PyPI shows as the description. It must match name in server.json, and it only reaches PyPI on the next release — so do not rename one without re-releasing. --> <!-- mcp-name: ai.khwan/khwan-mcp -->

How it saves tokens (and where it doesn't)

Be honest about the mechanism — an MCP adds to a host's context, it cannot replace the transcript the host already sends. So:

growing history (cache reads ≈ 0.1×), so re-injecting memory every turn only adds. Don't do that here.

• Within one hot session, it does not save tokens. Claude Code caches its

ends. Khwan persists distilled facts so the next run recalls them cheaply — no cold-replay of an old transcript, and facts that already scrolled out of context are retrievable again.

• Across sessions and subagents, it does. A cache dies in minutes; a session

The token-smart pattern: seed once, remember durable facts (below), rather than running the full loop on every turn of a caching host. The full prepare → record loop still shines in a custom agent on a non-caching host, where replacing history with distilled memory bounds per-turn cost directly.

Install

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

Connect to Claude Code

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

--scope project writes .mcp.json into the repo, so the setting travels with the project. Note what is not in that command: the key.

Keeping the key out of the repo

claude mcp add -e KHWANAPIKEY=… writes the literal value into .mcp.json — a file whose whole point is being committed. Two ways to avoid that, and the second is the one that works everywhere:

Shell environment. Leave KHWANAPIKEY out of the config entirely and export it in the shell that launches claude. The server inherits it.

export KHWAN_API_KEY=kwk_live_xxx

A launcher (works in the desktop app too). A desktop app is started from a dock or menu, not a login shell, so it inherits none of your shell exports and the approach above silently yields no key. Read it from a file instead:

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

Then point the config at the launcher and keep only non-secret settings inline:

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

.mcp.json is now safe to commit, and every new repo costs two lines instead of a pasted key. Anyone else on the team writes their own ~/.khwan/env.

Shortened. The full README is on GitHub.