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.

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

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

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.

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.

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.