Sokko Docs
Platform API

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:

  1. Your account. The Sokko team enables memory for your account. Without it, memory: true on a workspace answers 402 memory_not_enabled.
  2. The workspace. Send "memory": true when you create the workspace. It cannot be turned on later. The workspace object shows "memory": true once the memory exists.
  3. The agent. Send "memory": true when you create an agent, or change it later with PATCH. An agent without it neither reads nor writes the memory. Both audiences (operator and end_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.

POST /workspaces/{workspaceId}/memory/search
FieldTypeRules
querystringRequired. 1 to 500 characters.
limitintegerOptional. 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"
    }
  ]
}
FieldMeaning
profileShort facts the memory holds about the customer.
representationWhat the memory concludes for this query, as text. null when it has nothing.
matchesSaved 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
FieldTypeRules
contentstringRequired. 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/import

Use the import to load what you already know about a customer: a profile, a price list, notes.

FieldTypeRules
filesarrayRequired. 1 to 200 files. Each filename appears once.
files[].filenamestringMEMORY.md, USER.md, IDENTITY.md, or memory/<name> with no further /.
files[].contentstringThe 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": []
}
FieldMeaning
importedFiles that reached the memory.
unchangedFiles with the same content as at their last import. They are not sent again.
skippedFiles 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 memory off for that agent.

An agent with memory: false neither reads nor writes the memory. Your server can still give it what it must know:

  1. Before you send a message, search the memory for what this conversation needs, with your own rules for what this person may learn.
  2. Put the result in the text of the message, for example as a short block of facts before the person's words.
  3. 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.

On this page