khwanlabs/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: khwan_recall and
khwan_remember 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.
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:
- **Within one hot session, it does not save tokens.** Claude Code caches its
growing history (cache reads ≈ 0.1×), so re-injecting memory every turn only
adds. Don't do that here.
- **Across sessions and subagents, it does.** A cache dies in minutes; a session
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.
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
Connect to Claude Code
--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 KHWAN_API_KEY=… 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 KHWAN_API_KEY out of the config entirely and
export it in the shell that launches claude. The server inherits it.
**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:
md
- At the start of a task, call khwan_recall to seed relevant memory.
- When a durable decision/preference/fact emerges, call khwan_remember.