Skip to main content
DocumentationDevelopers

Memory and the Brain

Give your applications and agents what your organization knows and what the platform remembers, through the same key as inference.

Documentation menu

Two capabilities add context to your applications and agents. The Brain is what your organization knows: documents and pages that people can cite. Memory is what the platform remembers from working with someone: short notes about a person, an agent or a piece of work. Both answer on the inference host of your region, under /brain/v1/ and /memory/v1/, with the key you already use for inference, and as MCP tools on /mcp/.

Which one to use

BrainMemory
AnswersWhat does the organization know?What should the assistant remember about this person, agent or piece of work?
AuthorityOfficial: a source of truth to cite.A recollection: useful, possibly wrong or out of date, never official.
Written bySources that sync, and people who own pages.The person or the agent, while they work.
Who sees itThe spaces of their audience: the whole organization or a team.Its owner: one person, one agent, one team or the organization.
LifetimeAs long as its source.Retention and expiry; replaced when a newer memory supersedes it; erased on request.
RetrievalSearch with citations, and the standing context of a project.Recall: a small profile and the memories most relevant to a query.

Keys and permissions

Use either kind of key from Authentication: a service-account key for an application or an agent, or a person's own personal key, which is how a Personal plan, with no service accounts, uses Memory and the Brain. Send it as for inference. The key acts with its holder's roles, and the permission an operation needs decides what it may do.

PermissionAllows
brain.readSearch, read and browse the spaces of your audience. Every member holds it.
brain.manageCreate and delete spaces and sources. An admin of a team also manages that team's spaces.
memory.useStore, recall, edit and erase the memory you own, and your own settings. Every member holds it.
memory.reviewDecide the proposals of the teams you review.
memory.manageDecide the organization's proposals, erase a member's memory and an end user's, and set the memory policy.
memory.readRead the memory policy and usage.

Memory and the Brain also answer on the console host, with the same rules. Applications and agents use the inference host. Each belongs to your plan: an organization without Brain capacity answers 403 brain-disabled, and one whose memory is turned off answers 403 memory-disabled.

Memory

A memory is a short text of 1 to 8000 characters with a type (preference, fact, decision, event, task-state or lesson), an owner and, optionally, a project label. Every memory is a recollection: useful, never official.

Store a memory

Without owner, the memory is the caller's own. Name {"kind": "team", "team": "<team>"} or {"kind": "org"} to remember for a team or the organization, or let a service account keep its own agent memory. pinned adds it to its owner's profile, which recall always returns; importance runs from 1 to 5; ttl_days shortens its life; supersedes replaces an older memory of the same owner and project.

curl "https://api.us.ccsio.ai/memory/v1/memories" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Answers in Spanish, short and direct.",
    "type": "preference",
    "pinned": true
  }'
JSON
{
  "id": "m-01k9x4q2c8e6g0j3m5p7r9t1v2",
  "owner": { "kind": "user", "id": "u-01k7yp2c9w4x5e8h3j6m0n1q2r", "team": null },
  "project": null,
  "session": null,
  "type": "preference",
  "content": "Answers in Spanish, short and direct.",
  "importance": 3,
  "pinned": true,
  "provenance": { "source": "user", "trust": "user-confirmed" },
  "state": "active",
  "valid_from": "2026-11-12T10:15:00Z",
  "superseded_by": null,
  "superseded_at": null,
  "expires_at": "2027-11-12T10:15:00Z",
  "revision": 1,
  "created_at": "2026-11-12T10:15:00Z",
  "updated_at": "2026-11-12T10:15:00Z"
}

The surface that writes decides the provenance, not the body: a person, with a session or a personal key, writes user memories the person confirmed; a service account writes agent memories. What an agent writes into a person's own scope is active only while the organization's policy and that person's setting both allow agents to write there; otherwise it is stored as a proposal, and the answer is still 201.

Recall

Recall searches every memory the caller may read, by meaning and by words together, and answers the owner's profile (the pinned memories) and the best matches, within budget_tokens. Each match says whether the vector search, the text search or both found it. Only active memories are served.

curl "https://api.us.ccsio.ai/memory/v1/recall" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How should I answer this user?", "limit": 5, "budget_tokens": 800}'
JSON
{
  "profile": [
    {
      "id": "m-01k9x4q2c8e6g0j3m5p7r9t1v2",
      "owner": { "kind": "user", "id": "u-01k7yp2c9w4x5e8h3j6m0n1q2r", "team": null },
      "project": null,
      "session": null,
      "type": "preference",
      "content": "Answers in Spanish, short and direct.",
      "importance": 3,
      "pinned": true,
      "provenance": { "source": "user", "trust": "user-confirmed" },
      "state": "active",
      "valid_from": "2026-11-12T10:15:00Z",
      "superseded_by": null,
      "superseded_at": null,
      "expires_at": "2027-11-12T10:15:00Z",
      "revision": 1,
      "created_at": "2026-11-12T10:15:00Z",
      "updated_at": "2026-11-12T10:15:00Z"
    }
  ],
  "profile_overflow": 0,
  "memories": [
    {
      "memory": {
        "id": "m-01k9x6d4f0h2k4n6q8s0v2x4z6",
        "owner": { "kind": "user", "id": "u-01k7yp2c9w4x5e8h3j6m0n1q2r", "team": null },
        "project": "billing",
        "session": null,
        "type": "decision",
        "content": "We chose pgvector on 2026-11-09 because the data stays in one database.",
        "importance": 4,
        "pinned": false,
        "provenance": { "source": "user", "trust": "user-confirmed" },
        "state": "active",
        "valid_from": "2026-11-10T08:00:00Z",
        "superseded_by": null,
        "superseded_at": null,
        "expires_at": "2027-11-10T08:00:00Z",
        "revision": 1,
        "created_at": "2026-11-10T08:00:00Z",
        "updated_at": "2026-11-10T08:00:00Z"
      },
      "score": 0.82,
      "matched": "both"
    }
  ],
  "budget_used_tokens": 41,
  "truncated": false
}

List, edit and erase

A list returns summaries with a snippet of at most 200 characters, newest first; read a memory for its full text. Filter by owner, team, project, type, state and pinned. To edit a memory you own, send the expected_revision you read: if somebody edited it in between, nothing changes and the answer is 409 memory-revision-conflict. Only an active memory can be edited, and each edit adds a revision you can list.

# Read the memory: the answer carries its revision.
curl "https://api.us.ccsio.ai/memory/v1/memories/m-01k9x4q2c8e6g0j3m5p7r9t1v2" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

# Edit it, naming the revision you read. Another edit in between refuses yours with 409 memory-revision-conflict.
curl -X PATCH "https://api.us.ccsio.ai/memory/v1/memories/m-01k9x4q2c8e6g0j3m5p7r9t1v2" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Answers in Spanish, short and direct, with an example.", "expected_revision": 1}'

# The revisions of a memory you own, newest first.
curl "https://api.us.ccsio.ai/memory/v1/memories/m-01k9x4q2c8e6g0j3m5p7r9t1v2/revisions" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

The owner erases a memory, and so does an admin with memory.manage for a member, without reading it. Erasing removes the text and its vector in one transaction and journals it; the answer is a receipt and never the text. Erasing keeps working while memory is paused, over its capacity or turned off. A person can also pause their own memory, and export it, under /memory/v1/me/settings and /memory/v1/exports.

curl
# The text and its vector go in one transaction; the answer is a receipt and never the text.
curl -X POST "https://api.us.ccsio.ai/memory/v1/memories/m-01k9x4q2c8e6g0j3m5p7r9t1v2/erase" \
  -H "Authorization: Bearer $CCSIO_API_KEY"
# → {"id": "m-01k9x4q2c8e6g0j3m5p7r9t1v2", "state": "erased", "event_id": "...", "journal_head": {...}}

Proposals and who reviews them

A memory waits as a proposal, and recall never serves it, when an agent writes into a person's scope that does not allow it, or when anyone writes into a team or organization scope that the policy puts under review (both by default). Who decides:

  • A personal proposal: only its owner.
  • A team's proposal: the team's reviewers, with memory.review.
  • An organization's proposal: admins with memory.manage.

Accepting makes the memory active, optionally with a corrected content. Rejecting erases it and journals the erasure.

curl
# The proposals you may decide on: yours, your teams' (memory.review) or the organization's (memory.manage).
curl "https://api.us.ccsio.ai/memory/v1/proposals" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

# Accept one, as proposed or with a corrected text. It is served by recall from then on.
curl -X POST "https://api.us.ccsio.ai/memory/v1/proposals/m-01k9x7f6h2k4n6q8s0v2x4z6b8/accept" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Releases go out on Thursdays, after the freeze."}'

# Reject one: its text and vector are erased and the erasure is journaled.
curl -X POST "https://api.us.ccsio.ai/memory/v1/proposals/m-01k9x7f6h2k4n6q8s0v2x4z6b8/reject" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Your application's end users

An application that serves its own customers keeps what an agent learns about each one under a subject: an opaque id of 1 to 128 characters that you choose, such as your customer id. Only a service account can use it, on its own agent memory. Recall and list without a subject never return a memory that carries one, so an application never mixes two of its customers. A person's key that sends a subject is refused with 400 invalid-request.

# With the key of a service account, in the name of one of your application's end users.
curl "https://api.us.ccsio.ai/memory/v1/memories" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Asked about a refund for order 4411.", "type": "event", "subject": "customer-4711"}'

# Recall only what the agent remembers about that end user.
curl "https://api.us.ccsio.ai/memory/v1/recall" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "open questions", "subject": "customer-4711"}'

# A privacy request: erase everything remembered about the end user (permission memory.manage).
curl -X POST "https://api.us.ccsio.ai/memory/v1/subjects/customer-4711/erase" \
  -H "Authorization: Bearer $CCSIO_API_KEY"
# → {"erased": 3, "event_id": "...", "journal_head": {...}}

Erasing a subject is the answer to a privacy request from an end user. It needs memory.manage, erases every memory that carries the subject in one transaction without reading any, and answers erased with the number of memories. A subject with none is also 200 with erased 0, so the route does not reveal whether the end user ever existed. The subject is never written to a log or to a security event.

The Brain

Your organization has one Brain, divided into spaces. A source brings documents into a space, and a source that holds pages brings pages: Markdown knowledge that people have verified. Search, context and browse read both.

Spaces

A space is the unit of access: everyone in its audience reads everything in it. An organization space is for every member; a team space is for that team's members. You see only the spaces of your audience, and a space you cannot see is dropped from a search, never an error. Deleting a space deletes its sources, documents and pages, their search data and the stored originals, and frees the capacity at once.

curl
# An organization space is readable by every member (permission brain.manage to create it).
curl "https://api.us.ccsio.ai/brain/v1/spaces" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support", "kind": "organization"}'

# A team space is readable by that team's members; a team admin may create it too.
curl "https://api.us.ccsio.ai/brain/v1/spaces" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Platform runbooks", "kind": "team", "team": "platform"}'

# The spaces you can reach.
curl "https://api.us.ccsio.ai/brain/v1/spaces" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Sources

SourceWhat it bringsKept up to date
A fileOne document: text, Markdown, CSV, JSON or PDF, up to 50 MiB. Images are not accepted.It does not change.
A linkOne public web page, up to 20 MiB.Fetched again every sync_interval_minutes (5 to 1440), or by the sync route.
A repositoryA folder of a repository on gitlab.com or github.com. It reads .md, .markdown, .txt, .csv, .json and .pdf files, up to 5 MiB each and 5,000 files.Polled for changes, and by the sync route.

A repository has two modes. In documents mode its files are indexed as raw documents. In pages mode they become Brain pages and the repository stays their source of truth: pages change by merge request, and the API only reads them. The access token of a private repository is sealed and write-only: the API never returns it, only whether one is set. Self-managed GitLab and GitHub Enterprise are not supported.

# A file: text, Markdown, CSV, JSON or PDF, up to 50 MiB. The space is a query parameter.
curl "https://api.us.ccsio.ai/brain/v1/sources?space=sp-01k9xa2c4e6g8j0m2p4r6t8v0w" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -F file=@./refund-policy.pdf

# A public web page, fetched again every 6 hours.
curl "https://api.us.ccsio.ai/brain/v1/sources?space=sp-01k9xa2c4e6g8j0m2p4r6t8v0w" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "url", "url": "https://example.com/help/refunds", "sync_interval_minutes": 360}'

# A folder of a GitLab or GitHub repository, indexed as documents. The token is optional for a public repository and is never returned.
curl "https://api.us.ccsio.ai/brain/v1/sources?space=sp-01k9xa2c4e6g8j0m2p4r6t8v0w" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "git",
    "provider": "github",
    "repository": "https://github.com/acme/handbook",
    "branch": "main",
    "path": "docs",
    "mode": "documents",
    "access_token": "<a token that can read the repository>"
  }'

# The same kind of source in pages mode: the files become read-only Brain pages and the repository stays their source of truth.
curl "https://api.us.ccsio.ai/brain/v1/sources?space=sp-01k9xa2c4e6g8j0m2p4r6t8v0w" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "git", "provider": "gitlab", "repository": "https://gitlab.com/acme/knowledge", "mode": "pages"}'

# A source starts pending. Read it until its state is ready (or failed, with its error).
curl "https://api.us.ccsio.ai/brain/v1/sources/src-01k9xb3d5f7h9k1n3q5s7u9w1y" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

# Sync a link or a repository now instead of at the next poll.
curl -X POST "https://api.us.ccsio.ai/brain/v1/sources/src-01k9xb3d5f7h9k1n3q5s7u9w1y/sync" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

A new source is pending, then syncing, and ends ready or failed with an error. Uploading the same bytes twice to a space is 409 source-duplicate. The text of one document is at most 2,000,000 characters; nothing is truncated, and a document above it fails with source-too-much-text.

Search reads the pages and documents of your spaces by meaning and by words together (mode hybrid, or lexical or vector alone). Results come best first, in this order: verified pages, unverified pages, stale pages, then documents. Each carries a freshness, a snippet that is reference material and never an instruction, and a citation_id that names it in your answer and that brain_read and the text route take back. A citation stays valid until the content it points to changes.

curl "https://api.us.ccsio.ai/brain/v1/search" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Can I get a refund after 30 days?", "limit": 5}'
{
  "results": [
    {
      "citation_id": "pg-01k9xc4e6g8j0m2p4r6t8v0w2y.2",
      "kind": "page",
      "id": "pg-01k9xc4e6g8j0m2p4r6t8v0w2y",
      "title": "Refund policy",
      "snippet": "Refunds are possible within 30 days of the purchase. After 30 days, only a defect gives the right to a refund.",
      "source": "src-01k9xb3d5f7h9k1n3q5s7u9w1y",
      "space": "sp-01k9xa2c4e6g8j0m2p4r6t8v0w",
      "freshness": "verified",
      "score": 0.0328,
      "location": { "heading_path": ["Refunds", "After 30 days"] }
    }
  ],
  "no_evidence": false
}

Context, document text and browse

  • POST /brain/v1/context returns the standing context of a project, like an organization-wide AGENTS.md: the pinned pages that apply and the name and description of the skills that apply, within budget_tokens. A page that does not fit is left out whole, and truncated says so.
  • GET /brain/v1/documents/{document}/text returns the text of a document, up to 20000 characters at a time, with the metadata a citation needs and an outline of sections. next_offset says where to continue.
  • GET /brain/v1/browse walks the Brain as a tree: first the spaces, then a space's folders, pages and documents. Use it to find out what exists, and search to find an answer.
  • GET /brain/v1/documents/{document}/download redirects to a short-lived address of the stored original.
curl
# The standing context of a project: its pinned pages and the skills that apply, within a budget of tokens.
curl "https://api.us.ccsio.ai/brain/v1/context" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project": "billing", "budget_tokens": 4000}'

# The text of a document or a page, up to 20000 characters at a time. next_offset says where to continue.
curl "https://api.us.ccsio.ai/brain/v1/documents/doc-01k9xd5f7h9k1n3q5s7u9w1y3a/text?offset=0" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

# Start at one section of the outline that an earlier answer returned.
curl -G "https://api.us.ccsio.ai/brain/v1/documents/doc-01k9xd5f7h9k1n3q5s7u9w1y3a/text" \
  --data-urlencode "section=Refunds > After 30 days" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

# Walk the Brain as a tree: the spaces, then a space's folders, pages and documents.
curl "https://api.us.ccsio.ai/brain/v1/browse" \
  -H "Authorization: Bearer $CCSIO_API_KEY"
curl -G "https://api.us.ccsio.ai/brain/v1/browse" \
  --data-urlencode "space=sp-01k9xa2c4e6g8j0m2p4r6t8v0w" \
  --data-urlencode "path=policies" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

MCP tools

Agents reach both through the endpoint of the MCP guide, with the same key and no installation: the platform item ccsio appears in every organization that has Memory or the Brain, does not count toward the plan's MCP connections, and cannot be edited or limited to teams. A client sees each tool as the alias, a hyphen and the tool name:

ToolWhat it does
ccsio-context_buildStart here: the Brain's pinned pages and skills, the memory profile and the relevant memories of a project, in one pack within a budget.
ccsio-brain_contextThe standing context of a project.
ccsio-brain_searchCited excerpts, or no_evidence.
ccsio-brain_readThe text of a page, a document or a citation.
ccsio-brain_browseThe Brain as a tree.
ccsio-memory_saveStore a memory.
ccsio-memory_recallRecall by query.
ccsio-memory_getRead one memory in full.
ccsio-memory_forgetErase a memory you own, or replace it with a new one.
curl
# After "initialize" (see the MCP guide), call a tool of the item ccsio by its name as a client sees it.
curl "https://api.us.ccsio.ai/mcp/" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Mcp-Session-Id: <the id from initialize>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
       "params": {"name": "ccsio-brain_search",
                  "arguments": {"query": "Can I get a refund after 30 days?"}}}'

curl "https://api.us.ccsio.ai/mcp/" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Mcp-Session-Id: <the id from initialize>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 4, "method": "tools/call",
       "params": {"name": "ccsio-memory_save",
                  "arguments": {"content": "In this repository we chose pgvector.", "type": "decision", "project": "billing"}}}'

The tools take the same arguments as the routes and hold the same permissions: memory.use for Memory, brain.read for the Brain. The tool list is the same for every caller; what a caller may do is decided when the tool is called, and a refusal is a tool error that carries the code of the route, such as memory-scope-forbidden or brain-disabled. A memory saved by a tool is written by an agent, so it follows the rules of agent memory above.

Plan limits

PlanBrainMemory
Personal2 GB1 GB
Starter10 GB5 GB
Business20 GB10 GB
Advanced50 GB25 GB
Enterprise and DatacenterBy contractBy contract
  • What counts is what you put in. For the Brain, the bytes of the stored originals plus the text of pages; for Memory, the text of the memories not erased. Vectors, indexes, extracted text, revisions and the deletion journal do not count.
  • Embeddings are included. Ingestion, search and recall embed the text for you, outside your request limits and credits.
  • At 100%, ingestion is refused with 409 brain-capacity-exceeded and new memories with 409 memory-capacity-exceeded. Reading, searching, recalling and erasing keep working, and nothing is deleted to make room.
  • An additional Brain capacity adds to the Brain of your plan. Memory has no add-on.
curl
# What Memory holds against your plan (permission memory.read), and the same for the Brain (brain.read).
curl "https://api.us.ccsio.ai/memory/v1/usage" \
  -H "Authorization: Bearer $CCSIO_API_KEY"
# → {"used_bytes": 183204, "limit_bytes": 1073741824, "percent": 0.02, "memory_count": 412}

curl "https://api.us.ccsio.ai/brain/v1/usage" \
  -H "Authorization: Bearer $CCSIO_API_KEY"
# → {"used_bytes": 52428800, "limit_bytes": 2147483648, "percent": 2.44, "documents": 37,
#    "sources": {"pending": 0, "syncing": 0, "ready": 5, "failed": 1}}

Errors worth knowing

They use the platform's error envelope; branch on code, as in Errors.

Status and codeMeaningWhat to do
404 memory-not-enabled, 404 brain-not-enabledThis region does not serve the capability.Use a region that does, or ask us at ccsio.ai/contact.
403 brain-disabledYour organization has no Brain capacity.Choose a plan that includes the Brain.
403 memory-disabledMemory is off for your organization.An admin turns it on in the memory policy.
403 memory-scope-forbiddenYou may not act in that owner scope, or the memory is not yours.Write to your own scope, or to a team you belong to.
409 memory-pausedThe person paused their memory.Skip the call; reading and erasing still work.
409 memory-revision-conflictThe memory changed since you read it.Read it again and repeat the edit.
409 memory-capacity-exceeded, 409 brain-capacity-exceededThe plan's capacity is used up.Erase memories or delete sources, or add capacity. Nothing is deleted for you.
409 source-duplicateThe same bytes are already in that space.Use the document that exists.
413 source-too-large, 415 source-type-not-supportedThe file is over 50 MiB, or is not text, Markdown, CSV, JSON or PDF.Split the file or convert it.
422 source-repository-authThe provider refused the access token, or the repository is private and none was given.Send a token that can read the repository.
{
  "error": {
    "code": "memory-revision-conflict",
    "category": "client",
    "message": "the memory changed since the revision you read",
    "request_id": "01K7YQ4D8M2P6S9V3X5Z7B1C4F"
  }
}

Reference

Every operation, with its fields, permissions and error codes, is in the API reference: Memories, Memory recall, Memory proposals, Brain spaces, Brain sources, Brain documents, Brain pages and Brain search.

Explore the platform

Get your first API key

Registration is open. Four steps to your first call: create your account, create your organization, create your API key, and start using it.

  1. 01Create your account
  2. 02Create your organization
  3. 03Create your API key
  4. 04Start using it