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

Memory recall

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

Documentation menu

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

POST/memory/v1/recall

Recall memories

Credential
API key
Permission
memory.use
Request body
Body up to 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`.

Read more

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.us.ccsio.ai/memory/v1/recall" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "string"
}'
Built from the schema’s required members: replace the values.

Parameters

NameInDescription
X-Request-ID
optional
headerstring

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

Request body application/json

MemoryRecallRequest
  • querystringrequired

    1 to 8000 characters

  • ownersarray of stringoptional

    Allowed values: "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

    Allowed values: "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}$

Responses

  • 200

    The profile and the ranked memories.

    Schema
    MemoryRecallResponse
    • profilearray of Memoryrequired

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

      • idstringrequired

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

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

      • ownerobjectrequired

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

        • kindstringrequired

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

        • idstringrequired

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

        • teamstring or nullrequired

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

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

      • projectstring or nullrequired

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

      • sessionstring or nullrequired

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

      • typeMemoryType or nullrequired

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

      • importanceintegerrequired

        1 to 5

      • pinnedbooleanrequired
      • provenanceobjectrequired

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

        • sourcestringrequired

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

        • truststringrequired

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

        • agentstringoptional

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

          at most 128 characters

        • evidencearray of stringoptional

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

          at most 32 items

      • statestringrequired

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

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

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

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

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

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

        at least 1

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

        1 to 8000 characters

      • subjectstringoptional

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

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

    • profile_overflowintegerrequired

      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 MemoryRecallHitrequired

      Best first.

      • memoryobjectrequired

        A memory with its full text.

        • idMemoryIdrequired

          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.

        • ownerMemoryOwnerrequired

          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 nullrequired

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

        • sessionstring or nullrequired

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

        • typeMemoryType or nullrequired

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

        • importanceintegerrequired

          1 to 5

        • pinnedbooleanrequired
        • provenanceMemoryProvenancerequired

          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.

        • stateMemoryStaterequired

          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)required
        • superseded_byMemoryId or nullrequired

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

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

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

          at least 1

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

          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.

      • scorenumberrequired

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

      • matchedstringrequired

        Which of the two searches found the memory.

        Allowed values: "vector""text""both"

    • budget_used_tokensintegerrequired

      at least 0

    • truncatedbooleanrequired

      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:

    Read more

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

  • 402

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

    Read more

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

  • 403

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

  • 404

    The 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

Generated from the platform contracts at commit 5954fbc1.

Explore the platform

Get your first API key

Registration is open. Four steps to your first call: create your account, create your organization, create your API key, and start using it.

  1. 01Create your account
  2. 02Create your organization
  3. 03Create your API key
  4. 04Start using it