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

Memory recall

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

Menü der Dokumentation

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

POST/memory/v1/recall

Recall memories

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

Weiterlesen

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

MemoryRecallRequest
  • querystringPflicht

    1 to 8000 characters

  • ownersarray of stringoptional

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

    at least 1 items · at most 4 items

  • teamsarray of MemoryLabeloptional

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

    at least 1 items · at most 20 items

  • projectstringoptional

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

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

  • typesarray of MemoryTypeoptional

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

    at least 1 items · at most 6 items

  • limitintegeroptional

    1 to 50 · default 10

  • budget_tokensintegeroptional

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

    100 to 8000 · default 1000

  • 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

  • 200

    The profile and the ranked memories.

    Schema
    MemoryRecallResponse
    • profilearray of MemoryPflicht

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

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

    • profile_overflowintegerPflicht

      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 MemoryRecallHitPflicht

      Best first.

      • memoryobjectPflicht

        A memory with its full text.

        • idMemoryIdPflicht

          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.

        • ownerMemoryOwnerPflicht

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

          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.

        • stateMemoryStatePflicht

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

          1 to 8000 characters

        • subjectMemorySubjectoptional

          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.

      • scorenumberPflicht

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

      • matchedstringPflicht

        Which of the two searches found the memory.

        Erlaubte Werte: "vector""text""both"

    • budget_used_tokensintegerPflicht

      at least 0

    • truncatedbooleanPflicht

      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:

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

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