khwan-mcp
Officialkhwan-mcp is an MCP server that gives AI clients durable, cross-session memory via Khwan, letting them seed context and persist facts without per-call model costs.
Seed a session or subagent with
khwan_recall(query, limit=3), returning distilled lessons plus up to 3 relevant facts as ready-to-useseed_text.Persist durable facts/preferences with
khwan_remember(fact)so future sessions can recall corrections, decisions, and standing rules.Run a full prepare → record loop with
khwan_prepare(input)andkhwan_record(turn_token, answer)for custom agents needing memory-enriched context before answering and learning after.Inspect the brain with
khwan_memory(limit=20)to debug what is stored and confirm writes landed.List isolated cores (brains) on the account with
khwan_cores().Use one brain per project via
KHWAN_USERsub-brains (free: 3) andKHWAN_COREnamed cores (paid), giving complete isolation.Backfill a new brain from existing Claude Code transcripts using the provided example scripts.
Enable always-on memory via Claude Code hooks for deterministic recall/recording, at the cost of extra per-turn tokens.
Keep the API key out of repos using shell env or a launcher that reads
~/.khwan/env, safe for committed MCP configs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@khwan-mcp Recall what we decided about the API design last session."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: memory-mcp
Install
pip install khwan-mcp # or: uvx khwan-mcpConnect 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 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.
export KHWAN_API_KEY=kwk_live_xxxA 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-mcpThen 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.
One brain per project
Memory is only useful if the right project's memory comes back. Two axes, and both give complete isolation:
selected by | free | paid | |
core |
| 1 — | 5 (starter) → 25 (pro) |
sub-brain |
| 3 | unlimited |
A sub-brain is a full separate brain, not a filter: account::@web shares
nothing with account::@api. So the two axes multiply, and a free account
already holds four isolated brains — the core on its own, plus three
sub-brains:
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 4Which means one-brain-per-project works on the free plan, for up to four
projects — and it needs no KHWAN_CORE at all:
# 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-mcpNamed cores are the paid axis. Reach for one when four brains stop being enough, or when you want them grouped per client rather than per repository:
# 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-mcpTwo things to know before you point KHWAN_CORE anywhere. A core must exist
first — an unknown slug answers 404, not "created it for you" — and they are
created in the dashboard. On the free plan there is nothing to point at: the
cap of one is spent on default, so creating a named core answers 402. Leave
KHWAN_CORE unset there and use KHWAN_USER. Sub-brains, by contrast, are
created on first write.
Recommended pattern (token-smart)
On a caching host like Claude Code, prefer seed + remember over the per-turn loop:
Seed at the start of a session or subagent:
"Call
khwan_recall(query="<the task>")and use the returnedseed_textas context."Remember durable facts as they emerge:
"That's a standing decision — call
khwan_remember(fact="…")."
Reinforce it in your project's CLAUDE.md, e.g.:
- 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.Seeding a subagent is where the win is clearest — hand it a bounded brief instead of the whole transcript:
"Recall deploy memory with
khwan_recall(query="deploy runbook"), then spawn a subagent whose brief is thatseed_textplus the task."
Connect to Claude Desktop
Claude Desktop and Claude Code keep separate MCP configuration — a server
added to one is invisible to the other, and claude mcp add does not touch this
file. Add to claude_desktop_config.json:
{
"mcpServers": {
"khwan": {
"command": "/Users/you/.khwan/khwan-mcp",
"env": {
"KHWAN_CORE": "acme",
"KHWAN_USER": "Web"
}
}
}
}Use an absolute path: a desktop app does not get your shell's PATH either, so
a bare khwan-mcp may not resolve. One core is selected for the whole app —
there is no per-project switch here, so choose a broad one.
Configuration (environment)
Var | Required | Purpose |
| yes | Your key from the Khwan dashboard ( |
| no | Select a named core. Paid plans only — free has just |
| no | A separate brain inside the core — 3 on free, unlimited on paid. |
| no | Override the API base — e.g. |
Tools
Tool | When |
| seed a session/subagent — synthesised |
| persist a durable fact/preference for future sessions. |
| full loop, before answering — memory context + a |
| full loop, after answering — persists the turn so Khwan learns. |
| inspect what the brain currently remembers. |
| list the isolated cores on the account. |
khwan_recall / khwan_remember are the token-smart pair for a caching host;
khwan_prepare / khwan_record are the full loop for custom agents (pass the
exact turn_token from prepare back into record).
What comes back, and what an empty answer means
khwan_recall returns at most three facts — that ceiling is the server's,
so limit can lower it but not raise it — plus any lessons synthesis has
distilled from many past turns. Lessons lead the seed_text: a rule earned over
months outranks a single turn that happens to sit nearby in the index.
Retrieval applies a relevance floor, so an empty facts is an answer: the
brain has nothing close to this question. Read it as "not known here" rather than
as a failure, and do not fill the gap by leaning on whichever fact was nearest.
The floor is deliberately loose, because a memory wrongly dropped is invisible while a memory wrongly kept is not. Expect a returned fact to be plausibly related, not certainly relevant — read it before relying on it.
Seeding a brain from work you have already done
A new brain knows nothing, so its first weeks of recall are thin — while the
answers are often already sitting in the host's own transcripts, unread.
examples/backfill/ replays Claude Code transcripts into a
brain: deterministic, no model calls, dry-run by default.
python3 examples/backfill/backfill_claude_code.py --map cores.jsonAlways-on memory (Claude Code hooks)
The tools above are called when Claude decides to. For deterministic memory
— no reliance on the model — use the hook preset in
examples/claude-code-hooks/: a UserPromptSubmit
hook injects memory on every prompt and a Stop hook records every answer.
⚠️ On a caching host this is the thorough option, not the cheap one — it adds per-turn tokens. Prefer it when recall reliability matters more than token cost (or on a non-caching client); otherwise use
khwan_recallat session start.
Source
github.com/khwanlabs/khwan-mcp — this server runs on your machine, with your key, reading what you type. Read it before you install it.
License
MIT — © Khwan Labs. See LICENSE.
Available Tools
6 toolskhwan_coresA
List the isolated cores (brains) available on this account.
Each core is a fully isolated brain — its own memory, identity and learning.
HOW A CORE IS SELECTED DEPENDS ON HOW YOU CONNECTED, and the two are not interchangeable:
stdio (this package run locally): the
KHWAN_COREenvironment variable, read once at startup. Changing it needs a restart.remote (a hosted URL): the path —
/mcp/{core}/{user}. The path asks, the token answers.KHWAN_COREdoes NOTHING here; setting it and expecting the brain to change is a silent no-op.
On a remote connection, do not advise KHWAN_CORE. To reach a different
brain, point the client at a different URL — usually by adding a second MCP
server entry for it, so each keeps its own credentials and no re-auth is
needed to switch.
Inputs: no named parameters. Returns: result
khwan_memoryA
Inspect what this brain currently remembers, newest first.
A DEBUGGING window on the brain, not a way to seed a session. It returns
recent entries in time order and ignores what you are working on, so it
answers "is anything in here / did that write land" — not "what is relevant
to this task". For the latter use khwan_recall, which ranks by meaning
and returns a bounded set. No model is called.
Reach for it when a recall came back empty and you want to know whether the
brain is empty or merely has nothing close, when confirming a
khwan_remember persisted, or when the user asks what Khwan knows.
Args: limit: max entries to return, newest first (default 20).
Returns: The brain's recent memory entries, in the order they were written.
Inputs: limit. Returns: result
khwan_prepareA
Pull the memory-enriched context for a turn BEFORE you answer.
Khwan builds context from memory + the brain's constitution + a coherence
gate. No model is called. Ground your reply in the returned context and
respect allowed/reason. Keep the returned turn_token and pass it
to khwan_record after you answer.
Args: input: The user's message / the turn you are about to answer.
Returns: context: ready-to-use messages (memory + constitution) to ground your reply. coherence: optional float — how coherent this turn is with the brain (may be None). allowed: whether Khwan's coherence gate permits answering. reason: why, when not allowed (else None). turn_token: opaque token — pass it verbatim to khwan_record.
Inputs: input (required). Returns: result
khwan_recallA
SEED a session/subagent with a COMPACT, bounded set of relevant memories.
The token-smart entry point for a caching host (Claude Code, Claude Desktop): call it ONCE at the start of a session or subagent — or when you need a fact that has scrolled out of context — NOT on every turn. It returns only the relevant facts (not Khwan's full prepared prompt), so you seed a fresh, bounded context instead of replaying a transcript. No model is called.
Two limits are worth knowing, because neither is this tool's to set:
Three facts is the ceiling. The server ranks a wider candidate pool and keeps its top three, so
limitcan only narrow that further, never widen it. Asking for more returns three.A relevance floor applies, so an EMPTY
factsis an answer. It means the brain has nothing close to this question — read it as "not known here", not as a failure. Do not retry with a reworded query hoping for more, and do not fill the gap with whichever fact happened to be nearest.
Lessons — what synthesis distilled from many turns — come back alongside the raw exchanges and LEAD the seed text: a rule earned over months outranks any single turn that happens to sit nearby in the index.
Args: query: the task or topic to recall memory for. Phrase it as the work you are about to do, not as a keyword — it is matched on meaning. limit: cap on facts returned, 1-3. The server's own ceiling is 3, so this can only lower it. Leave it alone unless you want fewer than three.
Returns: lessons: rules synthesis distilled from many past turns. facts: [{you_said, khwan_knows}] — the relevant remembered exchanges. count: how many facts were returned. seed_text: a ready-to-drop-in memory block for a subagent's brief ("" if none).
Inputs: query (required), limit. Returns: result
khwan_recordA
Hand your answer back to Khwan AFTER you reply, so it persists + learns.
Args:
turn_token: the exact token returned by the matching khwan_prepare.
answer: the answer you gave the user for that turn.
Returns: Khwan's record acknowledgement (persisted state / next-turn hints).
Inputs: answer (required), turn_token (required). Returns: result
khwan_rememberA
Persist a durable fact/preference so FUTURE sessions can recall it.
A convenience over the prepare→record loop for the common "just remember this"
case: it stores fact in the brain (no model call) so it outlives this
session's context window and is available to the next khwan_recall.
Reach for this the moment you are corrected. A user rejecting your work, or telling you how they want it done, is the most durable thing a session produces and the easiest to lose — you fix the thing, the session ends, and the next one makes the same mistake. If the user is telling you something for the second time, the first time should have been stored here.
Write the standing RULE, not the utterance. "Deploys go to staging first, never straight to production" survives into a session that never saw the conversation; "no, not like that" does not.
Args: fact: the durable rule/preference to store, phrased to stand alone.
Returns: stored: whether the fact was persisted; reason when not.
Inputs: fact (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The tools split into two semantically overlapping pairs—prepare/recall for retrieval and record/remember for persistence—but the descriptions clearly separate turn-by-turn context from session seeding, and structured recording from standalone fact storage. khwan_memory and khwan_cores are unambiguous. An agent must read carefully, but misselection risk is low.
All tools share the khwan_ prefix and use lowercase snake_case, with most names being imperative verbs: prepare, record, recall, remember. khwan_memory and khwan_cores break the verb pattern by being plain nouns, making the set slightly inconsistent but still readable and predictable.
Six tools is a well-scoped size for a memory/context server: two for the turn loop, one for session seeding, one for direct persistence, one for debugging, and one for core isolation. Each tool has a clear job and none feels redundant.
The core memory lifecycle is covered: prepare/record for turns, remember for durable facts, recall for retrieval, and memory for inspection. However, there is no explicit forget/update or memory-editing tool, which is a notable gap for a persistent brain, though it does not break the main workflows.
Maintenance
Related MCP Connectors
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Related MCP Servers
AlicenseNot gradedqualityBmaintenanceEnables persistent memory storage and retrieval for MCP clients, allowing AI assistants to remember facts and context across conversations.26 npmMIT- AlicenseAqualityDmaintenanceProvides persistent memory for AI assistants via MCP, enabling them to store and recall facts, preferences, and tasks across conversations using either local file storage or a cloud backend with semantic search.514 npmMIT
- AlicenseNot gradedqualityBmaintenanceProvides AI agents with persistent, human-like memory infrastructure via MCP, enabling them to store, search, summarize, and forget episodic, semantic, procedural, and working memories across sessions.658 npmMIT
- AlicenseAqualityCmaintenanceEnables AI agents to persist memory across sessions through MCP, supporting semantic retrieval, source-backed context, knowledge graph relationships, supersession lineage, and topic digests.431MIT