Khwan

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.