Skip to main content
DocumentationMemory · api.us.ccsio.ai

Memories

Store, list, read, edit and erase a member's memories.

Documentation menu

The descriptions of the operations and fields are the contract’s own, in English.

GET/memory/v1/memories

List memories

Credential
API key
Permission
memory.use

Lists the memories the caller may read in the organization they act in, newest updated_at first, as summaries with a snippet of at most 200 characters; the full text is never in a list. Without `state` it lists the active ones; use the proposals route for the ones that wait for a decision.

Read more

A filter narrows the list and never widens what the caller may read. A service account reads its own `agent` memory: the memories that carry no subject, or, with `subject`, only that end user's; without `subject` it never lists a memory that carries one. Listing works while memory is paused, disabled or over capacity.

curl
curl "https://api.us.ccsio.ai/memory/v1/memories" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

owner
optional
querystring

Only memories of this owner kind. Absent lists every owner the caller may read.

team
optional
querystring

Only memories of this team, which the caller must belong to.

project
optional
querystring

Only memories with this project label. A label narrows reads and grants no access.

type
optional
querystring

Only memories of this type.

state
optional
querystring

Only memories in this state. Absent lists the active ones.

pinned
optional
queryboolean

Only pinned (true) or unpinned (false) memories.

subject
optional
querystring

Only the agent memories of this end user of the caller's application. Meaningful only for a service-account caller; a person's credential that sends it is refused with 400 invalid-request.

cursor
optional
querystring

The `next_cursor` of the previous page; absent starts at the first item. A cursor that this plane did not write is refused with 400 invalid-request.

limit
optional
queryinteger

The largest page, 1 to 100. Default 50.

Responses

  • 200

    One page of memories.

    Schema
    MemoryList
    • memoriesarray of MemorySummaryrequired
      • idstringrequired

        A memory's id. It is the entry's C6 fact id, so it matches the C6 identifier pattern; core generates it as `m-` plus a lowercase ULID. Clients treat it as opaque.

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • ownerobjectrequired

        Whose memory it is, as stored. `id` is the id of the owner: the person for user, the team for team, the organization for org, the service account for agent. The organization is never part of an owner: it is the caller's own, from the verified principal.

        • kindstringrequired

          Allowed values: "user""team""org""agent"

        • idstringrequired

          pattern ^[a-z][a-z0-9._-]{0,127}$

        • teamstring or nullrequired

          The team id for kind team; null for every other kind.

          pattern ^[a-z][a-z0-9._-]{0,127}$

      • projectstring or nullrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • sessionstring or nullrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • typeMemoryType or nullrequired

        null for an entry stored through the C6 entries routes, which carry no type.

      • importanceintegerrequired

        1 to 5

      • pinnedbooleanrequired
      • provenanceobjectrequired

        Where a memory came from and how far it is trusted. It is decided by the surface that wrote the memory, never by the credential type and never by the body: a person calling the REST /memory/v1 routes is `user` and `user-confirmed`, whether they use a session or their own personal API key; a service-account principal (agent owners) and the MCP tools (`memory_save`, M2) are `agent` and `agent-written`; an extraction job is `extraction` and `extracted`. A memory whose trust is `extracted` is never served in a shared scope until a person confirms it.

        • sourcestringrequired

          Allowed values: "user""agent""extraction""import"

        • truststringrequired

          Allowed values: "user-confirmed""agent-written""extracted"

        • agentstringoptional

          The agent that wrote the memory, when source is agent.

          at most 128 characters

        • evidencearray of stringoptional

          References to where the memory came from, such as `conversation:<id>`. Omitted when there are none.

          at most 32 items

      • statestringrequired

        active: served by recall. proposed: waits for a reviewer or the owner to accept it and is never served. superseded: replaced by a newer memory (`superseded_by`), kept in history until erased, never served. erased: the terminal tombstone; the text is gone and only a journaled receipt remains.

        Allowed values: "active""proposed""superseded""erased"

      • valid_fromstring (date-time)required
      • superseded_byMemoryId or nullrequired

        A memory's id. It is the entry's C6 fact id, so it matches the C6 identifier pattern; core generates it as `m-` plus a lowercase ULID. Clients treat it as opaque.

      • superseded_atstring (date-time) or nullrequired
      • expires_atstring (date-time) or nullrequired
      • revisionintegerrequired

        1 when the memory is created; every edit adds one.

        at least 1

      • created_atstring (date-time)required
      • updated_atstring (date-time)required
      • snippetstringrequired

        The start of the text, at most 200 characters. The full text is never in a list: read the memory.

        at most 200 characters

      • subjectstringoptional

        The end user of the application this agent memory is about. Present only on a memory the caller's agent owns that carries one; omitted otherwise.

        pattern ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$

    • next_cursorstring or nullrequired

      The cursor of the next page; null on the last one.

  • 400

    A filter or a limit outside its range, a cursor this plane did not write, an unknown or repeated query parameter, a subject sent by a person's credential. Codes: invalid-request

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    No role of the caller holds `memory.use` in the organization. Codes: policy-denied, memory-scope-forbidden (the caller may not act in the owner scope the request names, or does not own the memory)

  • 404

    The plane has no memory database configured (MEMORY_DATABASE_URL), so the Memory M1 routes are off. Codes: memory-not-enabled

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure. Codes: internal-error

POST/memory/v1/memories

Store a memory

Credential
API key
Permission
memory.use
Request body
Body up to 1 MiB

Stores one memory and answers 201 with it. The organization is the caller's own, from the verified principal; the body never names it. Without `owner` it is the caller's own user memory.

Read more

Provenance is decided by the surface: a person calling this route, with a session or with their own personal API key, writes `user` / `user-confirmed`; a service-account principal (agent owners) writes `agent` / `agent-written`. A person's memory in their own user scope is `active` at once. What an agent writes into a person's own scope is `active` only while the organization's policy (agents_may_write_user_scope) and the person's setting (agents_may_write) both allow it; otherwise it is stored `proposed` and the person accepts or rejects it, and the answer is still 201. In a team or organization scope the memory is `proposed` until a reviewer accepts it (the policy's review_required), and a person may only propose into a team they belong to; any other scope the caller may not write in is 403 memory-scope-forbidden. Owner kind `agent` and a `session` require a service-account principal: its default owner, when `owner` is absent, is `agent` with its own id, and a person's credential that names either is 403 memory-scope-forbidden. `subject` names an end user of the caller's application, is allowed only on a memory the caller's `agent` owner holds, and is 400 invalid-request on any other owner; erasing a subject erases these memories without reading them. `supersedes` marks the older memory superseded in the same step. A caller whose memory is paused is refused with 409 memory-paused, an organization over its capacity with 409 memory-capacity-exceeded (nothing is deleted to make room). The body is capped at 1048576 bytes.

curl
curl -X POST "https://api.us.ccsio.ai/memory/v1/memories" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "string"
}'
Built from the schema’s required members: replace the values.

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

Request body application/json

MemoryCreateRequest
  • contentstringrequired

    The text to remember: 1 to 8000 characters.

    1 to 8000 characters

  • typestringoptional

    Defaults to fact.

    Allowed values: "preference""fact""decision""event""task-state""lesson"

    default "fact"

  • ownerobjectoptional

    Whose memory it is. The caller's own `user` when the member is absent, and the caller's own `agent` for a service account. `team` names the team and is required for kind team and refused for every other kind. Kind `agent` requires a service-account principal, which owns and reads its own: the id is always the caller's, never sent. A person's credential that names it is refused with 403 memory-scope-forbidden.

    • kindstringrequired

      Allowed values: "user""team""org""agent"

    • teamstringoptional

      A C6 identifier: a project label, a session id or a team id.

      pattern ^[a-z][a-z0-9._-]{0,127}$

  • projectstringoptional

    A C6 identifier: a project label, a session id or a team id.

    pattern ^[a-z][a-z0-9._-]{0,127}$

  • sessionstringoptional

    Marks working memory with a short life (the policy's session_ttl_hours, 24 by default). A session requires a service-account principal: a person's credential that sends it is refused with 403 memory-scope-forbidden.

  • importanceintegeroptional

    1 to 5 · default 3

  • pinnedbooleanoptional

    A pinned memory belongs to its owner's profile, which recall always returns.

    default false

  • ttl_daysintegeroptional

    The memory stops being served after this many days. Absent means the retention of its owner kind in the policy.

    1 to 3650

  • supersedesstringoptional

    A memory of the same owner and project that this one replaces. The old one becomes superseded and stops being served; it stays in history until erased.

  • subjectstringoptional

    An opaque id of one end user of the calling application (a customer of a support bot), as the application knows it: 1 to 128 characters, letters, digits and . _ : @ -, starting with a letter or a digit. The platform stores it in a column of its own, indexed, so that erasing a subject is one delete that reads nothing; it never stores a meaning for it and never puts it in a log or a security event. Meaningful only on agent-owned memory.

    pattern ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$

Responses

  • 201

    The memory, `active` or `proposed`.

    Schema
    Memory
    • idstringrequired

      A memory's id. It is the entry's C6 fact id, so it matches the C6 identifier pattern; core generates it as `m-` plus a lowercase ULID. Clients treat it as opaque.

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • ownerobjectrequired

      Whose memory it is, as stored. `id` is the id of the owner: the person for user, the team for team, the organization for org, the service account for agent. The organization is never part of an owner: it is the caller's own, from the verified principal.

      • kindstringrequired

        Allowed values: "user""team""org""agent"

      • idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • teamstring or nullrequired

        The team id for kind team; null for every other kind.

        pattern ^[a-z][a-z0-9._-]{0,127}$

    • projectstring or nullrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • sessionstring or nullrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • typestring or nullrequired

      null for an entry stored through the C6 entries routes, which carry no type.

      Allowed values: "preference""fact""decision""event""task-state""lesson"

    • importanceintegerrequired

      1 to 5

    • pinnedbooleanrequired
    • provenanceobjectrequired

      Where a memory came from and how far it is trusted. It is decided by the surface that wrote the memory, never by the credential type and never by the body: a person calling the REST /memory/v1 routes is `user` and `user-confirmed`, whether they use a session or their own personal API key; a service-account principal (agent owners) and the MCP tools (`memory_save`, M2) are `agent` and `agent-written`; an extraction job is `extraction` and `extracted`. A memory whose trust is `extracted` is never served in a shared scope until a person confirms it.

      • sourcestringrequired

        Allowed values: "user""agent""extraction""import"

      • truststringrequired

        Allowed values: "user-confirmed""agent-written""extracted"

      • agentstringoptional

        The agent that wrote the memory, when source is agent.

        at most 128 characters

      • evidencearray of stringoptional

        References to where the memory came from, such as `conversation:<id>`. Omitted when there are none.

        at most 32 items

    • statestringrequired

      active: served by recall. proposed: waits for a reviewer or the owner to accept it and is never served. superseded: replaced by a newer memory (`superseded_by`), kept in history until erased, never served. erased: the terminal tombstone; the text is gone and only a journaled receipt remains.

      Allowed values: "active""proposed""superseded""erased"

    • valid_fromstring (date-time)required
    • superseded_bystring or nullrequired

      A memory's id. It is the entry's C6 fact id, so it matches the C6 identifier pattern; core generates it as `m-` plus a lowercase ULID. Clients treat it as opaque.

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • superseded_atstring (date-time) or nullrequired
    • expires_atstring (date-time) or nullrequired
    • revisionintegerrequired

      1 when the memory is created; every edit adds one.

      at least 1

    • created_atstring (date-time)required
    • updated_atstring (date-time)required
    • contentstringrequired

      1 to 8000 characters

    • subjectstringoptional

      The end user of the application this agent memory is about. Present only on a memory the caller's agent owns that carries one; omitted otherwise.

      pattern ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$

  • 400

    A body that is not strict JSON, a content that is empty or longer than 8000 characters, a value outside its range or pattern, a team missing for kind team or sent with another kind, a subject outside its pattern or sent with an owner that is not `agent`. Codes: invalid-request

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    No role of the caller holds `memory.use` in the organization. Codes: policy-denied, memory-disabled (the organization turned memory off in its policy, or has no memory entitlement), memory-scope-forbidden (the caller may not act in the owner scope the request names, or does not own the memory)

  • 404

    The memory named by `supersedes` does not exist or is not one the caller may replace; or the plane has no memory database configured (MEMORY_DATABASE_URL), so the Memory M1 routes are off. Codes: memory-not-found, memory-not-enabled

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 409

    The caller's memory is paused, or the organization reached its capacity. Codes: memory-paused, memory-capacity-exceeded

  • 500

    Platform failure. Codes: internal-error

GET/memory/v1/memories/{memory}

Read a memory

Credential
API key
Permission
memory.use

Answers one memory with its full text, provenance and revision. A memory the caller may not read is answered as one that does not exist.

curl
curl "https://api.us.ccsio.ai/memory/v1/memories/{memory}" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

memory
required
pathstring

The memory's id. A value outside the C6 identifier pattern, or one the caller may not read, is answered as a memory that does not exist.

Responses

  • 200

    The memory.

    Schema
    Memory
    • idstringrequired

      A memory's id. It is the entry's C6 fact id, so it matches the C6 identifier pattern; core generates it as `m-` plus a lowercase ULID. Clients treat it as opaque.

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • ownerobjectrequired

      Whose memory it is, as stored. `id` is the id of the owner: the person for user, the team for team, the organization for org, the service account for agent. The organization is never part of an owner: it is the caller's own, from the verified principal.

      • kindstringrequired

        Allowed values: "user""team""org""agent"

      • idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • teamstring or nullrequired

        The team id for kind team; null for every other kind.

        pattern ^[a-z][a-z0-9._-]{0,127}$

    • projectstring or nullrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • sessionstring or nullrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • typestring or nullrequired

      null for an entry stored through the C6 entries routes, which carry no type.

      Allowed values: "preference""fact""decision""event""task-state""lesson"

    • importanceintegerrequired

      1 to 5

    • pinnedbooleanrequired
    • provenanceobjectrequired

      Where a memory came from and how far it is trusted. It is decided by the surface that wrote the memory, never by the credential type and never by the body: a person calling the REST /memory/v1 routes is `user` and `user-confirmed`, whether they use a session or their own personal API key; a service-account principal (agent owners) and the MCP tools (`memory_save`, M2) are `agent` and `agent-written`; an extraction job is `extraction` and `extracted`. A memory whose trust is `extracted` is never served in a shared scope until a person confirms it.

      • sourcestringrequired

        Allowed values: "user""agent""extraction""import"

      • truststringrequired

        Allowed values: "user-confirmed""agent-written""extracted"

      • agentstringoptional

        The agent that wrote the memory, when source is agent.

        at most 128 characters

      • evidencearray of stringoptional

        References to where the memory came from, such as `conversation:<id>`. Omitted when there are none.

        at most 32 items

    • statestringrequired

      active: served by recall. proposed: waits for a reviewer or the owner to accept it and is never served. superseded: replaced by a newer memory (`superseded_by`), kept in history until erased, never served. erased: the terminal tombstone; the text is gone and only a journaled receipt remains.

      Allowed values: "active""proposed""superseded""erased"

    • valid_fromstring (date-time)required
    • superseded_bystring or nullrequired

      A memory's id. It is the entry's C6 fact id, so it matches the C6 identifier pattern; core generates it as `m-` plus a lowercase ULID. Clients treat it as opaque.

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • superseded_atstring (date-time) or nullrequired
    • expires_atstring (date-time) or nullrequired
    • revisionintegerrequired

      1 when the memory is created; every edit adds one.

      at least 1

    • created_atstring (date-time)required
    • updated_atstring (date-time)required
    • contentstringrequired

      1 to 8000 characters

    • subjectstringoptional

      The end user of the application this agent memory is about. Present only on a memory the caller's agent owns that carries one; omitted otherwise.

      pattern ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    No role of the caller holds `memory.use` in the organization. Codes: policy-denied

  • 404

    The memory does not exist, is erased, or is not one the caller may read; or the plane has no memory database configured (MEMORY_DATABASE_URL), so the Memory M1 routes are off. Codes: memory-not-found, memory-not-enabled

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure. Codes: internal-error

PATCH/memory/v1/memories/{memory}

Edit a memory

Credential
API key
Permission
memory.use
Request body
Body up to 1 MiB

Adds a revision to an active memory the caller owns and answers 200 with the memory at its new revision. `expected_revision` is required: when the current revision differs the edit is refused with 409 memory-revision-conflict and nothing changes.

Read more

Only an active memory can be edited; a proposal is edited by accepting it with `content`. A memory the caller can read but does not own is 403 memory-scope-forbidden. A change that makes the text larger can be refused with 409 memory-capacity-exceeded. The body is capped at 1048576 bytes.

curl
curl -X PATCH "https://api.us.ccsio.ai/memory/v1/memories/{memory}" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_revision": 0
}'
Built from the schema’s required members: replace the values.

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

memory
required
pathstring

The memory's id. A value outside the C6 identifier pattern, or one the caller may not read, is answered as a memory that does not exist.

Request body application/json

MemoryUpdateRequest
  • contentstringoptional

    1 to 8000 characters

  • typestringoptional

    A tag for filtering and ranking; it changes no storage rule. Carried as `type` on the C6 content profile.

    Allowed values: "preference""fact""decision""event""task-state""lesson"

  • pinnedbooleanoptional
  • importanceintegeroptional

    1 to 5

  • projectstring or nulloptional

    pattern ^[a-z][a-z0-9._-]{0,127}$

  • expected_revisionintegerrequired

    The revision the caller read. A different current revision refuses the edit with 409 memory-revision-conflict.

    at least 1

Responses

  • 200

    The memory at its new revision.

    Schema
    Memory
    • idstringrequired

      A memory's id. It is the entry's C6 fact id, so it matches the C6 identifier pattern; core generates it as `m-` plus a lowercase ULID. Clients treat it as opaque.

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • ownerobjectrequired

      Whose memory it is, as stored. `id` is the id of the owner: the person for user, the team for team, the organization for org, the service account for agent. The organization is never part of an owner: it is the caller's own, from the verified principal.

      • kindstringrequired

        Allowed values: "user""team""org""agent"

      • idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • teamstring or nullrequired

        The team id for kind team; null for every other kind.

        pattern ^[a-z][a-z0-9._-]{0,127}$

    • projectstring or nullrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • sessionstring or nullrequired

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • typestring or nullrequired

      null for an entry stored through the C6 entries routes, which carry no type.

      Allowed values: "preference""fact""decision""event""task-state""lesson"

    • importanceintegerrequired

      1 to 5

    • pinnedbooleanrequired
    • provenanceobjectrequired

      Where a memory came from and how far it is trusted. It is decided by the surface that wrote the memory, never by the credential type and never by the body: a person calling the REST /memory/v1 routes is `user` and `user-confirmed`, whether they use a session or their own personal API key; a service-account principal (agent owners) and the MCP tools (`memory_save`, M2) are `agent` and `agent-written`; an extraction job is `extraction` and `extracted`. A memory whose trust is `extracted` is never served in a shared scope until a person confirms it.

      • sourcestringrequired

        Allowed values: "user""agent""extraction""import"

      • truststringrequired

        Allowed values: "user-confirmed""agent-written""extracted"

      • agentstringoptional

        The agent that wrote the memory, when source is agent.

        at most 128 characters

      • evidencearray of stringoptional

        References to where the memory came from, such as `conversation:<id>`. Omitted when there are none.

        at most 32 items

    • statestringrequired

      active: served by recall. proposed: waits for a reviewer or the owner to accept it and is never served. superseded: replaced by a newer memory (`superseded_by`), kept in history until erased, never served. erased: the terminal tombstone; the text is gone and only a journaled receipt remains.

      Allowed values: "active""proposed""superseded""erased"

    • valid_fromstring (date-time)required
    • superseded_bystring or nullrequired

      A memory's id. It is the entry's C6 fact id, so it matches the C6 identifier pattern; core generates it as `m-` plus a lowercase ULID. Clients treat it as opaque.

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • superseded_atstring (date-time) or nullrequired
    • expires_atstring (date-time) or nullrequired
    • revisionintegerrequired

      1 when the memory is created; every edit adds one.

      at least 1

    • created_atstring (date-time)required
    • updated_atstring (date-time)required
    • contentstringrequired

      1 to 8000 characters

    • subjectstringoptional

      The end user of the application this agent memory is about. Present only on a memory the caller's agent owns that carries one; omitted otherwise.

      pattern ^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$

  • 400

    A body that is not strict JSON, has only `expected_revision`, or has a value outside its range. Codes: invalid-request

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    No role of the caller holds `memory.use` in the organization. Codes: policy-denied, memory-disabled (the organization turned memory off in its policy, or has no memory entitlement), memory-scope-forbidden (the caller may not act in the owner scope the request names, or does not own the memory)

  • 404

    The memory does not exist, is erased, or is not one the caller may read. Also a memory that is not active; or the plane has no memory database configured (MEMORY_DATABASE_URL), so the Memory M1 routes are off. Codes: memory-not-found, memory-not-enabled

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 409

    The memory is no longer at `expected_revision`, or the edit would pass the capacity. Codes: memory-revision-conflict, memory-capacity-exceeded

  • 500

    Platform failure. Codes: internal-error

GET/memory/v1/memories/{memory}/revisions

List the revisions of a memory

Credential
API key
Permission
memory.use

Lists the revisions of a memory the caller owns, newest first, the current one included. Each carries its text.

curl
curl "https://api.us.ccsio.ai/memory/v1/memories/{memory}/revisions" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

memory
required
pathstring

The memory's id. A value outside the C6 identifier pattern, or one the caller may not read, is answered as a memory that does not exist.

cursor
optional
querystring

The `next_cursor` of the previous page; absent starts at the first item. A cursor that this plane did not write is refused with 400 invalid-request.

limit
optional
queryinteger

The largest page, 1 to 100. Default 50.

Responses

  • 200

    One page of revisions.

    Schema
    MemoryRevisionList
    • revisionsarray of MemoryRevisionrequired

      Newest first, the current revision included.

      • revisionintegerrequired

        at least 1

      • contentstringrequired

        1 to 8000 characters

      • typeMemoryType or nullrequired

        A tag for filtering and ranking; it changes no storage rule. Carried as `type` on the C6 content profile.

      • importanceintegerrequired

        1 to 5

      • pinnedbooleanrequired
      • projectstring or nullrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • created_atstring (date-time)required

        When this revision was written.

    • next_cursorstring or nullrequired
  • 400

    A limit outside 1 to 100, a cursor this plane did not write, an unknown query parameter. Codes: invalid-request

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    No role of the caller holds `memory.use` in the organization. Codes: policy-denied, memory-scope-forbidden (the caller may not act in the owner scope the request names, or does not own the memory)

  • 404

    The memory does not exist, is erased, or is not one the caller may read; or the plane has no memory database configured (MEMORY_DATABASE_URL), so the Memory M1 routes are off. Codes: memory-not-found, memory-not-enabled

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure. Codes: internal-error

POST/memory/v1/memories/{memory}/erase

Erase a memory

Credential
API key
Permission
Any ofmemory.usememory.manage

Erases a memory to the terminal erased tombstone: the text and its vector go in one transaction, and the deletion journal records it.

Read more

The owner may erase their memory (for an `agent` memory the owner is the service account), and an organization admin holding `memory.manage` may erase on behalf of a member without reading it; the answer carries the journal receipt and never the text. Erasure keeps working while memory is paused, disabled or over capacity. Erasing a memory that is already erased is 404 memory-not-found. No body.

curl
curl -X POST "https://api.us.ccsio.ai/memory/v1/memories/{memory}/erase" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

memory
required
pathstring

The memory's id. A value outside the C6 identifier pattern, or one the caller may not read, is answered as a memory that does not exist.

Responses

  • 200

    The receipt of the erasure.

    Schema
    MemoryEraseReceipt
    • idstringrequired

      A memory's id. It is the entry's C6 fact id, so it matches the C6 identifier pattern; core generates it as `m-` plus a lowercase ULID. Clients treat it as opaque.

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • statestringrequired

      Allowed values: "erased"

    • event_idstringrequired
    • journal_headobjectrequired

      A {journalId, sequence, chainDigest} position in the deletion chain. Sequence zero is the explicit genesis, never an absent digest.

      • journal_idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • sequenceintegerrequired

        at least 0

      • chain_digeststringrequired

        pattern ^sha256:[0-9a-f]{64}$

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    The caller neither owns the memory nor holds `memory.manage`. Codes: policy-denied, memory-scope-forbidden (the caller may not act in the owner scope the request names, or does not own the memory)

  • 404

    The memory does not exist, is erased, or is not one the caller may read; or the plane has no memory database configured (MEMORY_DATABASE_URL), so the Memory M1 routes are off. Codes: memory-not-found, memory-not-enabled

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure. Codes: internal-error

POST/memory/v1/subjects/{subject}/erase

Erase an end user's memory

Credential
API key
Permission
memory.manage

Erases every agent memory of the organization that carries the subject, in one transaction, to the terminal erased tombstone: the text and the vectors go, and the deletion journal records one receipt.

Read more

It is the answer to a privacy request from an end user of an application: the administrator names the subject and reads nothing. Memory of other owners never carries a subject and is untouched. The organization is the caller's own, from the verified principal. A subject with no memory is answered 200 with `erased` 0, so the route does not reveal whether the subject exists. Erasure keeps working while memory is paused, disabled or over capacity. Calling it again is the same 200. The subject is never written to a security event or a log: the event `memory.subject_erased` belongs to the organization and carries no details. No body.

curl
curl -X POST "https://api.us.ccsio.ai/memory/v1/subjects/{subject}/erase" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form.

subject
required
pathstring

The end user's id, as the application sent it on the memories.

Responses

  • 200

    The receipt of the erasure.

    Schema
    MemorySubjectErasure
    • erasedintegerrequired

      How many memories were erased. 0 when the subject has none: the answer does not tell whether the subject ever existed.

      at least 0

    • event_idstringrequired
    • journal_headobjectrequired

      A {journalId, sequence, chainDigest} position in the deletion chain. Sequence zero is the explicit genesis, never an absent digest.

      • journal_idstringrequired

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • sequenceintegerrequired

        at least 0

      • chain_digeststringrequired

        pattern ^sha256:[0-9a-f]{64}$

  • 400

    A subject outside its pattern, an unknown query parameter. Codes: invalid-request

  • 401

    The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:

    Read more

    Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled

  • 402

    The organization has to pay first: its standing is payment_required.

    Read more

    The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required

  • 403

    No role of the caller holds `memory.manage` in the organization. Codes: policy-denied

  • 404

    The plane has no memory database configured (MEMORY_DATABASE_URL), so the Memory routes are off. Codes: memory-not-enabled

  • 405

    The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.

  • 500

    Platform failure. Codes: internal-error

Generated from the platform contracts at commit 5954fbc1.

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