Zum Hauptinhalt springen
DokumentationMemory · api.eu.ccsio.ai

Memories

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

Menü der Dokumentation

Die Beschreibungen der Operationen und Felder stammen aus dem Vertrag und sind auf Englisch.

GET/memory/v1/memories

List memories

Anmeldedaten
API-Key
Berechtigung
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.

Weiterlesen

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.eu.ccsio.ai/memory/v1/memories" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameter

NameInBeschreibung
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.

Antworten

  • 200

    One page of memories.

    Schema
    MemoryList
    • memoriesarray of MemorySummaryPflicht
      • idstringPflicht

        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}$

      • ownerobjectPflicht

        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.

        • kindstringPflicht

          Erlaubte Werte: "user""team""org""agent"

        • idstringPflicht

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

        • teamstring or nullPflicht

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

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

      • projectstring or nullPflicht

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

      • sessionstring or nullPflicht

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

      • typeMemoryType or nullPflicht

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

      • importanceintegerPflicht

        1 to 5

      • pinnedbooleanPflicht
      • provenanceobjectPflicht

        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.

        • sourcestringPflicht

          Erlaubte Werte: "user""agent""extraction""import"

        • truststringPflicht

          Erlaubte Werte: "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

      • statestringPflicht

        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.

        Erlaubte Werte: "active""proposed""superseded""erased"

      • valid_fromstring (date-time)Pflicht
      • superseded_byMemoryId or nullPflicht

        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 nullPflicht
      • expires_atstring (date-time) or nullPflicht
      • revisionintegerPflicht

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

        at least 1

      • created_atstring (date-time)Pflicht
      • updated_atstring (date-time)Pflicht
      • snippetstringPflicht

        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 nullPflicht

      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:

    Weiterlesen

    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.

    Weiterlesen

    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

Anmeldedaten
API-Key
Berechtigung
memory.use
Request-Body
Body bis 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.

Weiterlesen

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.eu.ccsio.ai/memory/v1/memories" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "string"
}'
Aus den Pflichtfeldern des Schemas erzeugt: ersetze die Werte.

Parameter

NameInBeschreibung
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
  • contentstringPflicht

    The text to remember: 1 to 8000 characters.

    1 to 8000 characters

  • typestringoptional

    Defaults to fact.

    Erlaubte Werte: "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.

    • kindstringPflicht

      Erlaubte Werte: "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}$

Antworten

  • 201

    The memory, `active` or `proposed`.

    Schema
    Memory
    • idstringPflicht

      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}$

    • ownerobjectPflicht

      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.

      • kindstringPflicht

        Erlaubte Werte: "user""team""org""agent"

      • idstringPflicht

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

      • teamstring or nullPflicht

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

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

    • projectstring or nullPflicht

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

    • sessionstring or nullPflicht

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

    • typestring or nullPflicht

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

      Erlaubte Werte: "preference""fact""decision""event""task-state""lesson"

    • importanceintegerPflicht

      1 to 5

    • pinnedbooleanPflicht
    • provenanceobjectPflicht

      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.

      • sourcestringPflicht

        Erlaubte Werte: "user""agent""extraction""import"

      • truststringPflicht

        Erlaubte Werte: "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

    • statestringPflicht

      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.

      Erlaubte Werte: "active""proposed""superseded""erased"

    • valid_fromstring (date-time)Pflicht
    • superseded_bystring or nullPflicht

      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 nullPflicht
    • expires_atstring (date-time) or nullPflicht
    • revisionintegerPflicht

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

      at least 1

    • created_atstring (date-time)Pflicht
    • updated_atstring (date-time)Pflicht
    • contentstringPflicht

      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:

    Weiterlesen

    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.

    Weiterlesen

    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

Anmeldedaten
API-Key
Berechtigung
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.eu.ccsio.ai/memory/v1/memories/{memory}" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameter

NameInBeschreibung
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
Pflicht
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.

Antworten

  • 200

    The memory.

    Schema
    Memory
    • idstringPflicht

      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}$

    • ownerobjectPflicht

      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.

      • kindstringPflicht

        Erlaubte Werte: "user""team""org""agent"

      • idstringPflicht

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

      • teamstring or nullPflicht

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

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

    • projectstring or nullPflicht

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

    • sessionstring or nullPflicht

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

    • typestring or nullPflicht

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

      Erlaubte Werte: "preference""fact""decision""event""task-state""lesson"

    • importanceintegerPflicht

      1 to 5

    • pinnedbooleanPflicht
    • provenanceobjectPflicht

      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.

      • sourcestringPflicht

        Erlaubte Werte: "user""agent""extraction""import"

      • truststringPflicht

        Erlaubte Werte: "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

    • statestringPflicht

      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.

      Erlaubte Werte: "active""proposed""superseded""erased"

    • valid_fromstring (date-time)Pflicht
    • superseded_bystring or nullPflicht

      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 nullPflicht
    • expires_atstring (date-time) or nullPflicht
    • revisionintegerPflicht

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

      at least 1

    • created_atstring (date-time)Pflicht
    • updated_atstring (date-time)Pflicht
    • contentstringPflicht

      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:

    Weiterlesen

    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.

    Weiterlesen

    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

Anmeldedaten
API-Key
Berechtigung
memory.use
Request-Body
Body bis 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.

Weiterlesen

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.eu.ccsio.ai/memory/v1/memories/{memory}" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_revision": 0
}'
Aus den Pflichtfeldern des Schemas erzeugt: ersetze die Werte.

Parameter

NameInBeschreibung
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
Pflicht
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.

    Erlaubte Werte: "preference""fact""decision""event""task-state""lesson"

  • pinnedbooleanoptional
  • importanceintegeroptional

    1 to 5

  • projectstring or nulloptional

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

  • expected_revisionintegerPflicht

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

    at least 1

Antworten

  • 200

    The memory at its new revision.

    Schema
    Memory
    • idstringPflicht

      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}$

    • ownerobjectPflicht

      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.

      • kindstringPflicht

        Erlaubte Werte: "user""team""org""agent"

      • idstringPflicht

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

      • teamstring or nullPflicht

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

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

    • projectstring or nullPflicht

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

    • sessionstring or nullPflicht

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

    • typestring or nullPflicht

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

      Erlaubte Werte: "preference""fact""decision""event""task-state""lesson"

    • importanceintegerPflicht

      1 to 5

    • pinnedbooleanPflicht
    • provenanceobjectPflicht

      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.

      • sourcestringPflicht

        Erlaubte Werte: "user""agent""extraction""import"

      • truststringPflicht

        Erlaubte Werte: "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

    • statestringPflicht

      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.

      Erlaubte Werte: "active""proposed""superseded""erased"

    • valid_fromstring (date-time)Pflicht
    • superseded_bystring or nullPflicht

      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 nullPflicht
    • expires_atstring (date-time) or nullPflicht
    • revisionintegerPflicht

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

      at least 1

    • created_atstring (date-time)Pflicht
    • updated_atstring (date-time)Pflicht
    • contentstringPflicht

      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:

    Weiterlesen

    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.

    Weiterlesen

    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

Anmeldedaten
API-Key
Berechtigung
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.eu.ccsio.ai/memory/v1/memories/{memory}/revisions" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameter

NameInBeschreibung
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
Pflicht
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.

Antworten

  • 200

    One page of revisions.

    Schema
    MemoryRevisionList
    • revisionsarray of MemoryRevisionPflicht

      Newest first, the current revision included.

      • revisionintegerPflicht

        at least 1

      • contentstringPflicht

        1 to 8000 characters

      • typeMemoryType or nullPflicht

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

      • importanceintegerPflicht

        1 to 5

      • pinnedbooleanPflicht
      • projectstring or nullPflicht

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

      • created_atstring (date-time)Pflicht

        When this revision was written.

    • next_cursorstring or nullPflicht
  • 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:

    Weiterlesen

    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.

    Weiterlesen

    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

Anmeldedaten
API-Key
Berechtigung
Eine vonmemory.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.

Weiterlesen

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.eu.ccsio.ai/memory/v1/memories/{memory}/erase" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameter

NameInBeschreibung
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
Pflicht
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.

Antworten

  • 200

    The receipt of the erasure.

    Schema
    MemoryEraseReceipt
    • idstringPflicht

      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}$

    • statestringPflicht

      Erlaubte Werte: "erased"

    • event_idstringPflicht
    • journal_headobjectPflicht

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

      • journal_idstringPflicht

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

      • sequenceintegerPflicht

        at least 0

      • chain_digeststringPflicht

        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:

    Weiterlesen

    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.

    Weiterlesen

    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

Anmeldedaten
API-Key
Berechtigung
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.

Weiterlesen

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.eu.ccsio.ai/memory/v1/subjects/{subject}/erase" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameter

NameInBeschreibung
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
Pflicht
pathstring

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

Antworten

  • 200

    The receipt of the erasure.

    Schema
    MemorySubjectErasure
    • erasedintegerPflicht

      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_idstringPflicht
    • journal_headobjectPflicht

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

      • journal_idstringPflicht

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

      • sequenceintegerPflicht

        at least 0

      • chain_digeststringPflicht

        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:

    Weiterlesen

    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.

    Weiterlesen

    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

Erzeugt aus den Plattformverträgen beim Commit 5954fbc1.

Plattform entdecken

Deinen ersten API-Key holen

Die Registrierung ist offen. Vier Schritte bis zum ersten Aufruf: Konto erstellen, Organisation anlegen, API-Key erzeugen, loslegen.

  1. 01Konto erstellen
  2. 02Organisation anlegen
  3. 03API-Key erzeugen
  4. 04Loslegen