Saltar al contenido principal
DocumentaciónMemoria · api.latam.ccsio.ai

Memories

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

Menú de la documentación

Las descripciones de las operaciones y los campos son las del contrato, en inglés.

GET/memory/v1/memories

List memories

Credencial
API key
Permiso
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.

Leer más

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

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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
opcional
querystring

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

team
opcional
querystring

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

project
opcional
querystring

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

type
opcional
querystring

Only memories of this type.

state
opcional
querystring

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

pinned
opcional
queryboolean

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

subject
opcional
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
opcional
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
opcional
queryinteger

The largest page, 1 to 100. Default 50.

Respuestas

  • 200

    One page of memories.

    Esquema
    MemoryList
    • memoriesarray of MemorySummaryobligatorio
      • idstringobligatorio

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

      • ownerobjectobligatorio

        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.

        • kindstringobligatorio

          Valores permitidos: "user""team""org""agent"

        • idstringobligatorio

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

        • teamstring or nullobligatorio

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

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

      • projectstring or nullobligatorio

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

      • sessionstring or nullobligatorio

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

      • typeMemoryType or nullobligatorio

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

      • importanceintegerobligatorio

        1 to 5

      • pinnedbooleanobligatorio
      • provenanceobjectobligatorio

        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.

        • sourcestringobligatorio

          Valores permitidos: "user""agent""extraction""import"

        • truststringobligatorio

          Valores permitidos: "user-confirmed""agent-written""extracted"

        • agentstringopcional

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

          at most 128 characters

        • evidencearray of stringopcional

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

          at most 32 items

      • statestringobligatorio

        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.

        Valores permitidos: "active""proposed""superseded""erased"

      • valid_fromstring (date-time)obligatorio
      • superseded_byMemoryId or nullobligatorio

        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 nullobligatorio
      • expires_atstring (date-time) or nullobligatorio
      • revisionintegerobligatorio

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

        at least 1

      • created_atstring (date-time)obligatorio
      • updated_atstring (date-time)obligatorio
      • snippetstringobligatorio

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

        at most 200 characters

      • subjectstringopcional

        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 nullobligatorio

      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:

    Leer más

    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.

    Leer más

    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

Credencial
API key
Permiso
memory.use
Cuerpo de la solicitud
Cuerpo de hasta 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.

Leer más

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.latam.ccsio.ai/memory/v1/memories" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "string"
}'
Construido con los campos obligatorios del esquema: reemplaza los valores.

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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.

Cuerpo de la solicitud application/json

MemoryCreateRequest
  • contentstringobligatorio

    The text to remember: 1 to 8000 characters.

    1 to 8000 characters

  • typestringopcional

    Defaults to fact.

    Valores permitidos: "preference""fact""decision""event""task-state""lesson"

    default "fact"

  • ownerobjectopcional

    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.

    • kindstringobligatorio

      Valores permitidos: "user""team""org""agent"

    • teamstringopcional

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

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

  • projectstringopcional

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

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

  • sessionstringopcional

    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.

  • importanceintegeropcional

    1 to 5 · default 3

  • pinnedbooleanopcional

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

    default false

  • ttl_daysintegeropcional

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

    1 to 3650

  • supersedesstringopcional

    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.

  • subjectstringopcional

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

Respuestas

  • 201

    The memory, `active` or `proposed`.

    Esquema
    Memory
    • idstringobligatorio

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

    • ownerobjectobligatorio

      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.

      • kindstringobligatorio

        Valores permitidos: "user""team""org""agent"

      • idstringobligatorio

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

      • teamstring or nullobligatorio

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

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

    • projectstring or nullobligatorio

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

    • sessionstring or nullobligatorio

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

    • typestring or nullobligatorio

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

      Valores permitidos: "preference""fact""decision""event""task-state""lesson"

    • importanceintegerobligatorio

      1 to 5

    • pinnedbooleanobligatorio
    • provenanceobjectobligatorio

      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.

      • sourcestringobligatorio

        Valores permitidos: "user""agent""extraction""import"

      • truststringobligatorio

        Valores permitidos: "user-confirmed""agent-written""extracted"

      • agentstringopcional

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

        at most 128 characters

      • evidencearray of stringopcional

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

        at most 32 items

    • statestringobligatorio

      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.

      Valores permitidos: "active""proposed""superseded""erased"

    • valid_fromstring (date-time)obligatorio
    • superseded_bystring or nullobligatorio

      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 nullobligatorio
    • expires_atstring (date-time) or nullobligatorio
    • revisionintegerobligatorio

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

      at least 1

    • created_atstring (date-time)obligatorio
    • updated_atstring (date-time)obligatorio
    • contentstringobligatorio

      1 to 8000 characters

    • subjectstringopcional

      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:

    Leer más

    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.

    Leer más

    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

Credencial
API key
Permiso
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.latam.ccsio.ai/memory/v1/memories/{memory}" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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
obligatorio
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.

Respuestas

  • 200

    The memory.

    Esquema
    Memory
    • idstringobligatorio

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

    • ownerobjectobligatorio

      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.

      • kindstringobligatorio

        Valores permitidos: "user""team""org""agent"

      • idstringobligatorio

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

      • teamstring or nullobligatorio

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

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

    • projectstring or nullobligatorio

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

    • sessionstring or nullobligatorio

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

    • typestring or nullobligatorio

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

      Valores permitidos: "preference""fact""decision""event""task-state""lesson"

    • importanceintegerobligatorio

      1 to 5

    • pinnedbooleanobligatorio
    • provenanceobjectobligatorio

      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.

      • sourcestringobligatorio

        Valores permitidos: "user""agent""extraction""import"

      • truststringobligatorio

        Valores permitidos: "user-confirmed""agent-written""extracted"

      • agentstringopcional

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

        at most 128 characters

      • evidencearray of stringopcional

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

        at most 32 items

    • statestringobligatorio

      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.

      Valores permitidos: "active""proposed""superseded""erased"

    • valid_fromstring (date-time)obligatorio
    • superseded_bystring or nullobligatorio

      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 nullobligatorio
    • expires_atstring (date-time) or nullobligatorio
    • revisionintegerobligatorio

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

      at least 1

    • created_atstring (date-time)obligatorio
    • updated_atstring (date-time)obligatorio
    • contentstringobligatorio

      1 to 8000 characters

    • subjectstringopcional

      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:

    Leer más

    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.

    Leer más

    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

Credencial
API key
Permiso
memory.use
Cuerpo de la solicitud
Cuerpo de hasta 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.

Leer más

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.latam.ccsio.ai/memory/v1/memories/{memory}" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_revision": 0
}'
Construido con los campos obligatorios del esquema: reemplaza los valores.

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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
obligatorio
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.

Cuerpo de la solicitud application/json

MemoryUpdateRequest
  • contentstringopcional

    1 to 8000 characters

  • typestringopcional

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

    Valores permitidos: "preference""fact""decision""event""task-state""lesson"

  • pinnedbooleanopcional
  • importanceintegeropcional

    1 to 5

  • projectstring or nullopcional

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

  • expected_revisionintegerobligatorio

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

    at least 1

Respuestas

  • 200

    The memory at its new revision.

    Esquema
    Memory
    • idstringobligatorio

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

    • ownerobjectobligatorio

      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.

      • kindstringobligatorio

        Valores permitidos: "user""team""org""agent"

      • idstringobligatorio

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

      • teamstring or nullobligatorio

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

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

    • projectstring or nullobligatorio

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

    • sessionstring or nullobligatorio

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

    • typestring or nullobligatorio

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

      Valores permitidos: "preference""fact""decision""event""task-state""lesson"

    • importanceintegerobligatorio

      1 to 5

    • pinnedbooleanobligatorio
    • provenanceobjectobligatorio

      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.

      • sourcestringobligatorio

        Valores permitidos: "user""agent""extraction""import"

      • truststringobligatorio

        Valores permitidos: "user-confirmed""agent-written""extracted"

      • agentstringopcional

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

        at most 128 characters

      • evidencearray of stringopcional

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

        at most 32 items

    • statestringobligatorio

      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.

      Valores permitidos: "active""proposed""superseded""erased"

    • valid_fromstring (date-time)obligatorio
    • superseded_bystring or nullobligatorio

      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 nullobligatorio
    • expires_atstring (date-time) or nullobligatorio
    • revisionintegerobligatorio

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

      at least 1

    • created_atstring (date-time)obligatorio
    • updated_atstring (date-time)obligatorio
    • contentstringobligatorio

      1 to 8000 characters

    • subjectstringopcional

      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:

    Leer más

    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.

    Leer más

    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

Credencial
API key
Permiso
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.latam.ccsio.ai/memory/v1/memories/{memory}/revisions" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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
obligatorio
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
opcional
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
opcional
queryinteger

The largest page, 1 to 100. Default 50.

Respuestas

  • 200

    One page of revisions.

    Esquema
    MemoryRevisionList
    • revisionsarray of MemoryRevisionobligatorio

      Newest first, the current revision included.

      • revisionintegerobligatorio

        at least 1

      • contentstringobligatorio

        1 to 8000 characters

      • typeMemoryType or nullobligatorio

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

      • importanceintegerobligatorio

        1 to 5

      • pinnedbooleanobligatorio
      • projectstring or nullobligatorio

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

      • created_atstring (date-time)obligatorio

        When this revision was written.

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

    Leer más

    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.

    Leer más

    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

Credencial
API key
Permiso
Cualquiera dememory.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.

Leer más

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

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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
obligatorio
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.

Respuestas

  • 200

    The receipt of the erasure.

    Esquema
    MemoryEraseReceipt
    • idstringobligatorio

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

    • statestringobligatorio

      Valores permitidos: "erased"

    • event_idstringobligatorio
    • journal_headobjectobligatorio

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

      • journal_idstringobligatorio

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

      • sequenceintegerobligatorio

        at least 0

      • chain_digeststringobligatorio

        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:

    Leer más

    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.

    Leer más

    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

Credencial
API key
Permiso
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.

Leer más

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

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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
obligatorio
pathstring

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

Respuestas

  • 200

    The receipt of the erasure.

    Esquema
    MemorySubjectErasure
    • erasedintegerobligatorio

      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_idstringobligatorio
    • journal_headobjectobligatorio

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

      • journal_idstringobligatorio

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

      • sequenceintegerobligatorio

        at least 0

      • chain_digeststringobligatorio

        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:

    Leer más

    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.

    Leer más

    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

Generado a partir de los contratos de la plataforma en el commit 5954fbc1.

Explora la plataforma

Obtén tu primera key API

El registro está abierto. Cuatro pasos hasta tu primera llamada: crea tu cuenta, crea tu organización, crea tu API key y empieza a usarla.

  1. 01Crea tu cuenta
  2. 02Crea tu organización
  3. 03Crea tu API key
  4. 04Empieza a usarla