Memory
Search, add to and import the shared memory of a workspace.
A workspace can have a shared memory: facts about the customer and its business that every agent of the workspace knows, across conversations and restarts.
One workspace has one memory. All agents of the workspace share it, and so does everyone who talks to those agents: an agent with memory can use what one person told it in its answer to another person. Create one workspace per customer. Do not put unrelated people behind one workspace's agent if they must not see each other's information. See Who shares a memory.
All paths below are relative to https://sokko.ai/api/v1.
Turn memory on
Memory has three switches, and all three must be on:
- Your account. The Sokko team enables memory for your account. Without
it,
memory: trueon a workspace answers 402memory_not_enabled. - The workspace. Send
"memory": truewhen you create the workspace. It cannot be turned on later. The workspace object shows"memory": trueonce the memory exists. - The agent. Send
"memory": truewhen you create an agent, or change it later withPATCH. An agent without it neither reads nor writes the memory. Both audiences (operatorandend_users) can have it.
The calls on this page need the first two switches only.
Each call on this page answers 402 memory_not_enabled for a workspace
without memory.
What the memory costs is paid from the workspace's credits. It shows as
memoryCents in the usage.
Search
POST /workspaces/{workspaceId}/memory/search| Field | Type | Rules |
|---|---|---|
query | string | Required. 1 to 500 characters. |
limit | integer | Optional. 1 to 50, default 20. |
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/memory/search \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "opening hours", "limit": 5 }'{
"profile": ["Bakery in Leuven with two shops", "Closed on Mondays"],
"representation": "The business is open Tuesday to Sunday from 7:00 to 18:00. Orders for the next day close at 16:00.",
"matches": [
{
"content": "Opening hours: Tuesday to Sunday, 7:00 to 18:00.",
"createdAt": "2026-11-20T09:40:18.220Z"
}
]
}| Field | Meaning |
|---|---|
profile | Short facts the memory holds about the customer. |
representation | What the memory concludes for this query, as text. null when it has nothing. |
matches | Saved entries that match the query, most relevant first. At most limit. |
A workspace with an empty memory answers empty fields, not an error. The call
only reads, so it costs 1 against your rate limit although it is a POST.
Errors: 400 invalid_request, 402 memory_not_enabled, 404 not_found.
Remember a fact
POST /workspaces/{workspaceId}/memory/facts| Field | Type | Rules |
|---|---|---|
content | string | Required. 1 to 20,000 characters. |
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/memory/facts \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{ "content": "The shop in Tiensestraat closes for renovation from 1 to 14 December 2026." }'{ "saved": true }The answer is 201. Every agent of the workspace with memory on can use the fact from then on.
The memory has no replace and no delete for one fact. Two calls with the same text save the text twice. To correct a fact, save a new one that says what changed.
Errors: 400 invalid_request, 402 memory_not_enabled, 404 not_found.
Import files
POST /workspaces/{workspaceId}/memory/importUse the import to load what you already know about a customer: a profile, a price list, notes.
| Field | Type | Rules |
|---|---|---|
files | array | Required. 1 to 200 files. Each filename appears once. |
files[].filename | string | MEMORY.md, USER.md, IDENTITY.md, or memory/<name> with no further /. |
files[].content | string | The text of the file, up to 262,144 characters. |
curl https://sokko.ai/api/v1/workspaces/$WORKSPACE/memory/import \
-H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{
"files": [
{ "filename": "MEMORY.md", "content": "# Bakkerij Janssens\n\nTwo shops in Leuven. Closed on Mondays.\n" },
{ "filename": "memory/prices.md", "content": "Croissant: 1.40 EUR. Sourdough loaf: 4.80 EUR.\n" }
]
}'{
"imported": 2,
"unchanged": 0,
"skipped": []
}| Field | Meaning |
|---|---|
imported | Files that reached the memory. |
unchanged | Files with the same content as at their last import. They are not sent again. |
skipped | Files that were left out, each with a reason. An empty file is skipped. |
A file whose content did not change since its last import is skipped, so you can send your whole set each time. A file whose content did change is imported again as new text: the earlier text stays in the memory.
Errors: 400 invalid_request (a bad filename, a filename twice, a file that
is too long), 402 memory_not_enabled, 404 not_found.
Who shares a memory
One workspace has one memory. Three things follow:
- All agents of the workspace share it. What one agent with memory learns, every other agent with memory can use.
- Everyone who talks to those agents shares it. The memory has no part per person. An agent with memory can use what one person said in its answer to another person.
- Workspaces never share a memory. Nothing of one workspace's memory reaches an agent of another workspace.
So the workspace is the border:
- Create one workspace per customer. An accounting firm is one workspace, and the next firm is another one.
- Do not put unrelated people behind one workspace's agent if they must not
see each other's information. For those people, use one workspace each, or
leave
memoryoff for that agent.
An agent with memory: false neither reads nor writes the memory. Your server
can still give it what it must know:
- Before you send a message, search the memory for what this conversation needs, with your own rules for what this person may learn.
- Put the result in the
textof the message, for example as a short block of facts before the person's words. - After the turn, save what is worth keeping with a fact or an import.
A recipe follows the same rule: agent.memory: true and a memorySeed are
accepted for both audiences.
What the API does not do
- No memory per person, and no way to read "what the memory knows about user X".
- No call that deletes or edits one fact. Deleting the workspace deletes its memory.
- Deleting an end user's data does not remove what the memory learned from that user.
Integrations
Let your customer connect an app such as Gmail or Google Calendar to an agent, from a button in your own product.
Conversations
Open a conversation for one of your end users, send messages, read the answer as JSON or as an event stream, answer the agent's questions, attach files and stop a turn.