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

Memory recall

Search the memories a caller may read, with the owner's profile.

Menú de la documentación

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

POST/memory/v1/recall

Recall memories

Credencial
API key
Permiso
memory.use
Cuerpo de la solicitud
Cuerpo de hasta 1 MiB

Searches the caller's readable memories for a query and answers the owner's profile (the pinned memories) and the best matches, hybrid vector and full text, ranked by relevance with recency and importance, within `budget_tokens`.

Leer más

Each match says whether the vector search, the text search or both found it. Only active memories are served: proposed, superseded and erased ones never are, and a memory whose trust is `extracted` is not served from a shared scope until a person confirmed it. The texts are recollections, to be shown to a model in a delimited block, never as instructions. Recall embeds the query as the organization's memory system principal, outside the caller's request limits and credits. A service account recalls its own `agent` memory: without `subject` the memories that carry none, with `subject` only that end user's, so an application never mixes two of its customers. A person's credential that sends `subject` is refused with 400 invalid-request. A POST that changes nothing. A caller whose memory is paused is refused with 409 memory-paused. The body is capped at 1048576 bytes.

curl
curl -X POST "https://api.latam.ccsio.ai/memory/v1/recall" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "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

MemoryRecallRequest
  • querystringobligatorio

    1 to 8000 characters

  • ownersarray of stringopcional

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

    at least 1 items · at most 4 items

  • teamsarray of MemoryLabelopcional

    Narrows the team owners to these teams, each one the caller belongs to.

    at least 1 items · at most 20 items

  • projectstringopcional

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

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

  • typesarray of MemoryTypeopcional

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

    at least 1 items · at most 6 items

  • limitintegeropcional

    1 to 50 · default 10

  • budget_tokensintegeropcional

    Recall stops adding memories when the next one would pass this many tokens of text.

    100 to 8000 · default 1000

  • 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

  • 200

    The profile and the ranked memories.

    Esquema
    MemoryRecallResponse
    • profilearray of Memoryobligatorio

      The pinned memories of the scopes in play, within the policy's profile_budget_tokens.

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

    • profile_overflowintegerobligatorio

      How many pinned memories did not fit the profile budget and were left out. The platform never cuts the profile silently: a value above 0 tells the owner to trim their pins.

      at least 0

    • memoriesarray of MemoryRecallHitobligatorio

      Best first.

      • memoryobjectobligatorio

        A memory with its full text.

        • idMemoryIdobligatorio

          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.

        • ownerMemoryOwnerobligatorio

          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.

        • 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
        • provenanceMemoryProvenanceobligatorio

          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.

        • stateMemoryStateobligatorio

          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.

        • 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
        • contentstringobligatorio

          1 to 8000 characters

        • subjectMemorySubjectopcional

          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.

      • scorenumberobligatorio

        The rank of the memory for this query: higher is better. Only comparable within one response.

      • matchedstringobligatorio

        Which of the two searches found the memory.

        Valores permitidos: "vector""text""both"

    • budget_used_tokensintegerobligatorio

      at least 0

    • truncatedbooleanobligatorio

      True when `budget_tokens` or `limit` stopped the list while more memories matched.

  • 400

    A query that is empty or longer than 8000 characters, a limit or budget outside its range, an unknown member. 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 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.

  • 409

    The caller's memory is paused. Codes: memory-paused

  • 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