Connect your agent

Khwan is a memory layer, not an agent framework — it plugs into whichever one you already run. Every integration is the same three calls in the same two places, no matter what the host is called. This page is the pattern; build your own from it.

The shape of every integration


before the model is called ──► POST /prepare  → memory + constitution + gate  (no LLM)
      [ your agent's model answers ]           ← Khwan never touches it
after the answer exists ─────► POST /record   → persist + learn

That is the whole contract. If your framework gives you a seam before the prompt is assembled and another one after the answer is produced, it can carry Khwan.

Host	before the model	after the answer
Claude Code (MCP)	`khwan_recall` tool	`khwan_remember` tool
ChatGPT (Custom GPT)	`prepareTurn` action	`recordAnswer` action
CrewAI	a `Flow` step before `kickoff()`	after `kickoff()` returns
LangChain / custom	your callback or middleware	same callback, after generation

Nothing here is framework-specific. If you are writing a plain loop with no framework at all, the Quickstart is the same three calls without the hooks.

The calls

`POST /prepare`

Send the user’s input. You get back messages (constitution + recalled memory + coherence context), a turn_token, and an allowed flag.

Feed messages to your own model. If allowed is false, skip generation and surface reason — the gate decided this turn conflicts with what the brain knows.

Your model answers

Khwan is not involved. It never sees your provider key and never makes this call.

`POST /record`

Send turn_token plus the answer your model produced. Khwan persists the turn and learns from it.

On a correction — a human edited the answer before it shipped — record the edited text. That correction is the most valuable thing the brain can learn.

See the API Reference for the full request and response shapes.

Optional: a hard gate on the answer

/prepare gates the turn before generation. To also gate the answer, call POST /verify after your model responds and before you ship the reply.

It scores the answer against the brain and returns { ok, reason, coherence, contradiction }. It is non-destructive: it never consumes the turn_token and never persists, so a later /record still works normally.


your model answers ──► POST /verify ──► ok:false ──► block or regenerate
                                    └─► ok:true  ──► ship it, then POST /record

Hosts reach it two ways: a seam that fires before the reply is sent, or — where the host lets the model call tools — exposing it as a tool so the model can check itself before answering.

Rules a good integration follows

These are not style preferences. Each one is a failure mode we hit shipping real integrations — the CrewAI one among them — and your integration will hit them too.

Recall fails open. Race /prepare against a timeout. On timeout or error, continue the turn without memory. A memory layer that can hang the agent is worse than no memory layer.

Decide whether capture blocks — do not default into it. /prepare for the next turn retrieves what has been written, so a /record still in flight means the turn you just had is missing from the next turn’s context. It shows up only under load, and it reads as “the memory is flaky” rather than as a race.

Both SDKs block by default and take background to opt out. Dispatch without waiting when the turn is the last one, or when the next /prepare is far enough away that the write will have landed; keep the wait when turns come back to back.

Decide what a brain is per. One brain per account is the default and usually wrong. Per repository, per workspace, per customer — pick the axis that matches how your users think about isolation, and set X-Khwan-Core accordingly.

Core count is bounded by plan. If you derive cores automatically (one per repo, one per customer), more active cores than the plan allows will spill into the default core — which quietly breaks the isolation you promised. Size the plan to the axis, or cap the derivation.

Hold turn_token on the turn, not in a session dict. Keying pending tokens by a session id the framework owns means the answer of turn N can be recorded against the input of turn N-1. Put the token on a per-turn object that travels with the request, and clear it before dispatching /record so a retry cannot record twice.

Per-end-user sub-brains are a header, not an architecture. If you are building multi-tenant SaaS, send X-Khwan-User: <your end-user id> and each of your users gets their own brain inside your core (account::core::@user). You do not design that storage yourself.

Worked examples

CrewAI — a plain Python client called around kickoff(), with the multi-tenant scoping and answer-gate wired in.
Claude Code — the same two calls as MCP tools, so the model reaches for them itself.

Owning the learning step too

prepare → your model → record covers answering. The same shape covers learning: POST /synthesize/prepare returns the clusters and the distill instruction, your model turns each into a rule, and /synthesize/record stores them.

Reach for it when no packet text may reach a provider you did not choose, or when you want to pick the model that writes your agent’s rules. Otherwise the nightly pass does it for you.

Claude Code — the MCP shape, where the tools are called by the model rather than by a hook.

All three are the same three calls. What changes is only where the host lets you stand.