The descriptions of the operations and fields are the contract’s own, in English.
/memory/v1/recallRecall 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 -X POST "https://api.us.ccsio.ai/memory/v1/recall" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "string"
}'Parameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string 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
querystringrequired1 to 8000 characters
ownersarray of stringoptionalAllowed values:
"user""team""org""agent"at least 1 items · at most 4 items
teamsarray of MemoryLabeloptionalNarrows the team owners to these teams, each one the caller belongs to.
at least 1 items · at most 20 items
projectstringoptionalA C6 identifier: a project label, a session id or a team id.
pattern ^[a-z][a-z0-9._-]{0,127}$
typesarray of MemoryTypeoptionalAllowed values:
"preference""fact""decision""event""task-state""lesson"at least 1 items · at most 6 items
limitintegeroptional1 to 50 · default 10
budget_tokensintegeroptionalRecall stops adding memories when the next one would pass this many tokens of text.
100 to 8000 · default 1000
subjectstringoptionalAn 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
MemoryRecallResponseprofilearray of MemoryrequiredThe pinned memories of the scopes in play, within the policy's profile_budget_tokens.
idstringrequiredA 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}$
ownerobjectrequiredWhose 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.
kindstringrequiredAllowed values:
"user""team""org""agent"idstringrequiredpattern ^[a-z][a-z0-9._-]{0,127}$
teamstring or nullrequiredThe team id for kind team; null for every other kind.
pattern ^[a-z][a-z0-9._-]{0,127}$
projectstring or nullrequiredpattern ^[a-z][a-z0-9._-]{0,127}$
sessionstring or nullrequiredpattern ^[a-z][a-z0-9._-]{0,127}$
typeMemoryType or nullrequirednull for an entry stored through the C6 entries routes, which carry no type.
importanceintegerrequired1 to 5
pinnedbooleanrequiredprovenanceobjectrequiredWhere 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.
sourcestringrequiredAllowed values:
"user""agent""extraction""import"truststringrequiredAllowed values:
"user-confirmed""agent-written""extracted"agentstringoptionalThe agent that wrote the memory, when source is agent.
at most 128 characters
evidencearray of stringoptionalReferences to where the memory came from, such as `conversation:<id>`. Omitted when there are none.
at most 32 items
statestringrequiredactive: 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)requiredsuperseded_byMemoryId or nullrequiredA 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 nullrequiredexpires_atstring (date-time) or nullrequiredrevisionintegerrequired1 when the memory is created; every edit adds one.
at least 1
created_atstring (date-time)requiredupdated_atstring (date-time)requiredcontentstringrequired1 to 8000 characters
subjectstringoptionalThe 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_overflowintegerrequiredHow 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 MemoryRecallHitrequiredBest first.
memoryobjectrequiredA memory with its full text.
idMemoryIdrequiredA 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.
ownerMemoryOwnerrequiredWhose 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 nullrequiredpattern ^[a-z][a-z0-9._-]{0,127}$
sessionstring or nullrequiredpattern ^[a-z][a-z0-9._-]{0,127}$
typeMemoryType or nullrequirednull for an entry stored through the C6 entries routes, which carry no type.
importanceintegerrequired1 to 5
pinnedbooleanrequiredprovenanceMemoryProvenancerequiredWhere 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.
stateMemoryStaterequiredactive: 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)requiredsuperseded_byMemoryId or nullrequiredA 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 nullrequiredexpires_atstring (date-time) or nullrequiredrevisionintegerrequired1 when the memory is created; every edit adds one.
at least 1
created_atstring (date-time)requiredupdated_atstring (date-time)requiredcontentstringrequired1 to 8000 characters
subjectMemorySubjectoptionalThe 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.
scorenumberrequiredThe rank of the memory for this query: higher is better. Only comparable within one response.
matchedstringrequiredWhich of the two searches found the memory.
Allowed values:
"vector""text""both"
budget_used_tokensintegerrequiredat least 0
truncatedbooleanrequiredTrue 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.