# 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](/claude-code) (MCP) | `khwan_recall` tool | `khwan_remember` tool | | [ChatGPT](/chatgpt) (Custom GPT) | `prepareTurn` action | `recordAnswer` action | | [CrewAI](/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](/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](/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`](/api-reference#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](/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: ` 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](/crewai)** — a plain Python client called around `kickoff()`, with the multi-tenant scoping and answer-gate wired in. - **[Claude Code](/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`](/api-reference#post-synthesizeprepare) returns the clusters and the distill instruction, your model turns each into a rule, and [`/synthesize/record`](/api-reference#post-synthesizerecord) 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](/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.