Skip to main content
Glama

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-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 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_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.

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

KHWAN_CORE

1 — default only

5 (starter) → 25 (pro)

sub-brain

KHWAN_USER

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 4

Which 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-mcp

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:

# 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-mcp

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.

On a caching host like Claude Code, prefer seed + remember over the per-turn loop:

  1. Seed at the start of a session or subagent:

    "Call khwan_recall(query="<the task>") and use the returned seed_text as context."

  2. 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 that seed_text plus 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

KHWAN_API_KEY

yes

Your key from the Khwan dashboard (kwk_live_…).

KHWAN_CORE

no

Select a named core. Paid plans only — free has just default.

KHWAN_USER

no

A separate brain inside the core — 3 on free, unlimited on paid.

KHWAN_BASE_URL

no

Override the API base — e.g. http://127.0.0.1:8010 for a local engine.

Tools

Tool

When

khwan_recall(query, limit=3)

seed a session/subagent — synthesised lessons + up to 3 relevant facts, as seed_text.

khwan_remember(fact)

persist a durable fact/preference for future sessions.

khwan_prepare(input)

full loop, before answering — memory context + a turn_token.

khwan_record(turn_token, answer)

full loop, after answering — persists the turn so Khwan learns.

khwan_memory(limit=20)

inspect what the brain currently remembers.

khwan_cores()

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.json

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_recall at 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 tools
khwan_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_CORE environment 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_CORE does 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 limit can only narrow that further, never widen it. Asking for more returns three.

  • A relevance floor applies, so an EMPTY facts is 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

    A4.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      5
      14 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to persist memory across sessions through MCP, supporting semantic retrieval, source-backed context, knowledge graph relationships, supersession lineage, and topic digests.
      43
      1
      MIT