Khwan
ai.khwanPublished by khwan.aiOfficial publisherv0.3.12Updated Oct 24, 2026
Durable AI memory: recall distilled facts in a later session or subagent, and remember new ones.
Overview
Gives an assistant durable AI memory: recall distilled facts and lessons in a later session or subagent, and store new durable facts.
- What you can do
- Khwan is a memory layer that persists distilled facts so a later session or subagent can recall them instead of replaying an old transcript. Tools include khwan_recall (seed a session with synthesised lessons plus up to three relevant facts), khwan_remember (persist a durable fact or preference), khwan_prepare and khwan_record (a full per-turn loop for custom agents), khwan_memory (inspect what is stored) and khwan_cores (list isolated brains). Memory is isolated per core and per sub-brain, so one account can hold several separate brains.
- When to use it
- Use it when work spans sessions, projects or subagents and you want decisions, preferences and lessons to carry over without re-reading a long transcript. It is aimed at clients such as Claude Code or Claude Desktop; within a single cached session it adds tokens rather than saving them, so the recommended pattern is to seed once and remember durable facts.
- Requirements
- A Khwan account and API key supplied as KHWAN_API_KEY (a kwk_live_ value from the Khwan dashboard); this is not your model provider's key. Runs as a remote endpoint or locally via the khwan-mcp PyPI package (pip install or uvx). Optional settings: KHWAN_CORE, KHWAN_USER, KHWAN_BASE_URL. Network access to the Khwan service.
Installation
In SourceWeft
- Open Khwan in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Other MCP clients
Follow the launch instructions in the repository.
README
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:
Then point the config at the launcher and keep only non-secret settings inline:
.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:
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:
Which means one-brain-per-project works on the free plan, for up to four
projects — and it needs no KHWAN_CORE at all:
Named 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:
Two 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.:
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:
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)
Tools
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.
Always-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.
Source: README.md at commit b136474
Tools
0Version history
1- v0.3.12LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 daysRequired25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declaredRequired10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts