user id, add your documents once, and Recall does the rest.
You will find Recall under Services > Recall.
Turning Recall on
Use the Enabled switch in the top right of the page. It takes effect the moment you flip it, so there is no separate save step. While it is off, nothing is stored and nothing is recalled, even if a request carries auser field or names a collection.
The page has four tabs: Memory (facts and the knowledge graph, per end-user), Documents (your collections), Settings (extraction, thread and retrieval configuration), and Activity (the audit log).
When you disable Recall and there is stored data (facts or collections), you are asked whether to keep or delete everything. Keeping it leaves all data in place so retrieval works again the moment you re-enable the service; deleting clears every fact, thread, and document, and cannot be undone.
Identifying the end-user
Long-term memory is scoped to your end-users, not to your workspace as a whole. To associate a request with a specific end-user, include"user": "<your-end-user-id>" in the chat-completions body, the same field OpenAI uses:
user, the platform has no identity to attach facts to: nothing is learned or recalled for that end-user, though a request can still be grounded in your workspace’s documents (see below).
How retrieval works
By default, Recall runs one blended search across the caller’s personal memory (when auser is supplied), the workspace’s shared knowledge, and every collection in it, and injects the most relevant facts and passages as context before the model runs. Nothing needs naming: the blend covers all of it in a single pass. This suits an internal assistant, where a question may span HR and Legal and the person asking should not have to know which collection holds the answer.
Retrieval runs whenever there is something to consult: a user was supplied, or the workspace holds at least one ready document. A request with neither triggers no retrieval and is not augmented.
Narrowing to one collection
Name a collection and the request reads only that one, plus the caller’s own personal memory. The workspace’s shared knowledge is not included: “only this collection” means only this collection. Use it when a workspace holds knowledge that must not mix. A customer-facing bot built on a workspace that also holds internal documents should read only the public collection; an agency running a collection per end client should read only that client’s. The field iscollection everywhere: on chat completions, on the Recall search endpoints, and as the argument to the MCP knowledge-search tool. It accepts a single slug or a list of them:
rag. It was accepted but never applied: a request naming a collection was answered from the whole workspace. It is now rejected with a 422 telling you to use collection, rather than ignored, so a caller that still sends it finds out instead of quietly getting a wider answer than it asked for.
A slug your workspace does not have is rejected with a 422, naming the slug. It is never ignored and never quietly widened back to the blend, so a typo surfaces as an error rather than as an answer drawn from more than you asked for.
Every response carries an additive sources array (empty when nothing was retrieved) naming what was recalled, grouped and ordered by relevance: one entry per source document or collection, plus one grouped entry for memory facts. Use it to show your users what grounded an answer.
If a request opts into retrieval (by supplying a user, or by the workspace having ready documents) and the knowledge graph is unavailable, the platform returns an error rather than quietly answering without the context you expected.
How facts are learned
After each exchange, an EU-sovereign model extracts durable facts from the end-user’s message in the background: stated preferences, roles, constraints, or decisions that are unlikely to expire. New facts are reconciled against what is already known for that end-user: changed ones update, contradicted ones are retired. This runs after the response is returned, so it adds no latency to the call your user is waiting on. A conversation’s messages are extracted together, a few minutes after the first of them, rather than one at a time. Extraction over several turns resolves references a single message cannot (“book the same seat as last time”), and it is billed once per batch instead of once per message. The practical consequence: something an end-user says becomes recallable in another conversation a few minutes later, not instantly. Within the same conversation nothing waits, because a thread’s recent messages are replayed into every request (see Conversation threads below). Extraction runs on one EU-sovereign model at one rate, with nothing to configure. There were briefly two tiers to choose between; they differed by a rounding error in price, and the cheaper one was worse at recognising that two mentions were the same thing, so the choice cost more than it saved.Shared conversations
A conversation in Akumi Chat can be shared with named colleagues. A shared conversation carries no personal memory: nothing a person has taught Akumi about themselves is blended into it, and nothing said in it becomes a stored fact. Blending one member’s personal facts into a prompt whose answer everyone else in the conversation reads would disclose them to the room. The workspace’s own knowledge still reaches a shared conversation as normal; it is the personal scope, and only the personal scope, that is withdrawn. A conversation’s payload carriesmember_count: how many colleagues it is shared with, excluding its owner. A private conversation reads 0, and shared is any count above 0.
Clients say this in these words:
Shared threads carry no personal memory. What you have taught Akumi about yourself stays out of conversations other people can read.That sentence is the canonical wording, used verbatim wherever the disclosure appears, so one governance decision is never described two ways.
Managing facts
The Memory tab lists every stored fact, with a graph view (the entities and relationships a selected end-user’s facts form) and a list view (search by end-user or text, sortable and filterable). Each row shows the fact’s content, the end-user it belongs to, and when it was added. Use Delete on any row to remove a fact immediately. Each fact also has a Promote to collection action. Promoting moves the fact into one or more of your document collections: the fact’s text is ingested as a document in each collection you pick, and the fact is then removed from personal memory. Once promoted, the content is retrieved as part of the workspace’s shared knowledge for any request, regardless of which end-user sent it. Use this when a fact should be available to everyone rather than scoped to a single end-user. The action is disabled until you have at least one collection.Conversation threads
Threads let the platform track conversation history server-side. Instead of resending the full transcript on every call, you send a thread id alongside your new messages and the platform replays the recent history automatically, then appends the new turn before passing the conversation to the model. If you are arriving from another platform: a thread is what Langfuse calls a session, and what OpenTelemetry calls a conversation. Akumi usesthread because that is what the OpenAI API calls it, and Akumi mirrors OpenAI’s request shape.
Threads are opt-in and effective only when Recall is enabled.
Opting in
Include"thread": "<your-conversation-id>" in the chat-completions body, alongside user or any other field you already send:
The sliding window
Only the most recent N messages are replayed into each request. N defaults to 50 and is set on the Settings tab under Messages kept per conversation. Messages that fall outside the window are dropped from replay, but any durable facts already extracted from them remain in long-term memory for as long as the end-user’s facts are retained.Managing threads
The/v1/recall/threads API lets you manage threads directly:
Threads are also created implicitly the first time a request carries a
thread id you have not created manually.
Collections and documents
Your workspace keeps documents in one or more named collections: separate, walled-off knowledge bases. You add documents to a collection; the platform reads them into the same knowledge graph as memory facts. A document belongs to exactly one collection. Every collection is included in the blended retrieval by default, and a request can name one to read it alone. You will find collections under the Documents tab.- Create a collection with New collection and give it a name. The platform derives a URL-safe slug from the name (“Support docs” becomes
support-docs). Your plan sets how many collections you can have: Pay as you go includes one, and Team, Business and Enterprise are unlimited. At the limit, New collection is disabled with an upgrade prompt. - Rename a collection from its row. Only the display name changes: the slug is fixed when the collection is created, because it is the value your requests send to read that collection, and moving it would break them.
- Delete a collection from its row; its documents and their chunks are removed with it.
- Open a collection to manage the documents inside it.
- Upload files. Drop or choose one or more PDF, text (
.txt), or markdown (.md) files, up to 20 MB each. Each file becomes its own document, so this doubles as a bulk import. PDFs are read for their embedded text (a scanned, image-only PDF has no text to extract and is marked failed). - Paste text. Give a title, an optional source label, and the body text.
Erasing an end-user’s memory (GDPR)
To remove all long-term facts and threads for a specific end-user, for example when they delete their account in your app, call:Exporting an end-user’s data (GDPR)
To hand an end-user a copy of everything Recall holds about them (GDPR Article 15), call:next_cursor so you can page through everything. Documents are your workspace’s shared knowledge base rather than that end-user’s personal data, so they are not included in the export.
Exporting everything your organization holds
The per-end-user export above answers “tell me everything you hold about this person”. To take out everything your organization holds, across every workspace, use Settings > Data export in the dashboard. That is a dashboard action rather than an API endpoint, because exporting an organization is an administrative act by a person rather than something your application does. See Data export for what the file contains, what it deliberately leaves out, and how long it lasts.Metering and records
Recall meters each part of the lifecycle separately:- Extraction is metered once per learned turn, at a single rate.
- Ingest is metered once per document, scaled to how much of it there was to read into the graph.
- Retrieval is metered once per request that triggers a blended search, whether or not it found anything relevant.
- Threads are metered per turn appended to a conversation thread.
- Storage is a recurring meter on the tokens your collections hold, measured per month. Your plan includes a free allowance; usage beyond it is metered on top.
Good to know
Personal memory needs auser; document retrieval does not. A request without a user is never augmented from personal memory and never triggers extraction, but it can still be grounded in your workspace’s documents if any are ready.
Extraction and embedding stay in the EU. The models that read conversations, derive facts, and embed documents run on EU-sovereign endpoints, and the graph lives in an EU-resident store.
Facts are per end-user, not per workspace. Each end-user’s memory is isolated from every other user’s, within your workspace and across tenants. Promoting a fact to a collection is the one deliberate way to make its content workspace-wide.