The descriptions of the operations and fields are the contract’s own, in English.
/memory/v1/memoriesList memories
- Credential
- API key
- Permission
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.
Read more
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 "https://api.eu.ccsio.ai/memory/v1/memories" \
-H "Authorization: Bearer $CCSIO_API_KEY"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. |
owneroptional | query | string Only memories of this owner kind. Absent lists every owner the caller may read. |
teamoptional | query | string Only memories of this team, which the caller must belong to. |
projectoptional | query | string Only memories with this project label. A label narrows reads and grants no access. |
typeoptional | query | string Only memories of this type. |
stateoptional | query | string Only memories in this state. Absent lists the active ones. |
pinnedoptional | query | boolean Only pinned (true) or unpinned (false) memories. |
subjectoptional | query | string 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. |
cursoroptional | query | string 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. |
limitoptional | query | integer The largest page, 1 to 100. Default 50. |
Responses
- 200
One page of memories.
Schema
MemoryListmemoriesarray of MemorySummaryrequiredidstringrequiredA 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)requiredsnippetstringrequiredThe start of the text, at most 200 characters. The full text is never in a list: read the memory.
at most 200 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}$
next_cursorstring or nullrequiredThe 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:
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-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
/memory/v1/memoriesStore a memory
- Credential
- API key
- Permission
memory.use- Request body
- Body up to 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.
Read more
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 -X POST "https://api.eu.ccsio.ai/memory/v1/memories" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "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
contentstringrequiredThe text to remember: 1 to 8000 characters.
1 to 8000 characters
typestringoptionalDefaults to fact.
Allowed values:
"preference""fact""decision""event""task-state""lesson"default "fact"
ownerobjectoptionalWhose 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.
kindstringrequiredAllowed values:
"user""team""org""agent"teamstringoptionalA C6 identifier: a project label, a session id or a team id.
pattern ^[a-z][a-z0-9._-]{0,127}$
projectstringoptionalA C6 identifier: a project label, a session id or a team id.
pattern ^[a-z][a-z0-9._-]{0,127}$
sessionstringoptionalMarks 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.
importanceintegeroptional1 to 5 · default 3
pinnedbooleanoptionalA pinned memory belongs to its owner's profile, which recall always returns.
default false
ttl_daysintegeroptionalThe memory stops being served after this many days. Absent means the retention of its owner kind in the policy.
1 to 3650
supersedesstringoptionalA 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.
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
- 201
The memory, `active` or `proposed`.
Schema
MemoryidstringrequiredA 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}$
typestring or nullrequirednull for an entry stored through the C6 entries routes, which carry no type.
Allowed values:
"preference""fact""decision""event""task-state""lesson"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_bystring 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.
pattern ^[a-z][a-z0-9._-]{0,127}$
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}$
- 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:
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 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
/memory/v1/memories/{memory}Read a memory
- Credential
- API key
- Permission
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 "https://api.eu.ccsio.ai/memory/v1/memories/{memory}" \
-H "Authorization: Bearer $CCSIO_API_KEY"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. |
memoryrequired | path | string 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. |
Responses
- 200
The memory.
Schema
MemoryidstringrequiredA 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}$
typestring or nullrequirednull for an entry stored through the C6 entries routes, which carry no type.
Allowed values:
"preference""fact""decision""event""task-state""lesson"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_bystring 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.
pattern ^[a-z][a-z0-9._-]{0,127}$
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}$
- 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
- 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
/memory/v1/memories/{memory}Edit a memory
- Credential
- API key
- Permission
memory.use- Request body
- Body up to 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.
Read more
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 -X PATCH "https://api.eu.ccsio.ai/memory/v1/memories/{memory}" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expected_revision": 0
}'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. |
memoryrequired | path | string 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. |
Request body application/json
contentstringoptional1 to 8000 characters
typestringoptionalA tag for filtering and ranking; it changes no storage rule. Carried as `type` on the C6 content profile.
Allowed values:
"preference""fact""decision""event""task-state""lesson"pinnedbooleanoptionalimportanceintegeroptional1 to 5
projectstring or nulloptionalpattern ^[a-z][a-z0-9._-]{0,127}$
expected_revisionintegerrequiredThe revision the caller read. A different current revision refuses the edit with 409 memory-revision-conflict.
at least 1
Responses
- 200
The memory at its new revision.
Schema
MemoryidstringrequiredA 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}$
typestring or nullrequirednull for an entry stored through the C6 entries routes, which carry no type.
Allowed values:
"preference""fact""decision""event""task-state""lesson"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_bystring 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.
pattern ^[a-z][a-z0-9._-]{0,127}$
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}$
- 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:
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 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
/memory/v1/memories/{memory}/revisionsList the revisions of a memory
- Credential
- API key
- Permission
memory.use
Lists the revisions of a memory the caller owns, newest first, the current one included. Each carries its text.
curl "https://api.eu.ccsio.ai/memory/v1/memories/{memory}/revisions" \
-H "Authorization: Bearer $CCSIO_API_KEY"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. |
memoryrequired | path | string 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. |
cursoroptional | query | string 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. |
limitoptional | query | integer The largest page, 1 to 100. Default 50. |
Responses
- 200
One page of revisions.
Schema
MemoryRevisionListrevisionsarray of MemoryRevisionrequiredNewest first, the current revision included.
revisionintegerrequiredat least 1
contentstringrequired1 to 8000 characters
typeMemoryType or nullrequiredA tag for filtering and ranking; it changes no storage rule. Carried as `type` on the C6 content profile.
importanceintegerrequired1 to 5
pinnedbooleanrequiredprojectstring or nullrequiredpattern ^[a-z][a-z0-9._-]{0,127}$
created_atstring (date-time)requiredWhen this revision was written.
next_cursorstring or nullrequired
- 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:
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-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
/memory/v1/memories/{memory}/eraseErase a memory
- Credential
- API key
- Permission
- Any of
memory.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.
Read more
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 -X POST "https://api.eu.ccsio.ai/memory/v1/memories/{memory}/erase" \
-H "Authorization: Bearer $CCSIO_API_KEY"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. |
memoryrequired | path | string 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. |
Responses
- 200
The receipt of the erasure.
Schema
MemoryEraseReceiptidstringrequiredA 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}$
statestringrequiredAllowed values:
"erased"event_idstringrequiredjournal_headobjectrequiredA {journalId, sequence, chainDigest} position in the deletion chain. Sequence zero is the explicit genesis, never an absent digest.
journal_idstringrequiredpattern ^[a-z][a-z0-9._-]{0,127}$
sequenceintegerrequiredat least 0
chain_digeststringrequiredpattern ^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:
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
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
/memory/v1/subjects/{subject}/eraseErase an end user's memory
- Credential
- API key
- Permission
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.
Read more
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 -X POST "https://api.eu.ccsio.ai/memory/v1/subjects/{subject}/erase" \
-H "Authorization: Bearer $CCSIO_API_KEY"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. |
subjectrequired | path | string The end user's id, as the application sent it on the memories. |
Responses
- 200
The receipt of the erasure.
Schema
MemorySubjectErasureerasedintegerrequiredHow many memories were erased. 0 when the subject has none: the answer does not tell whether the subject ever existed.
at least 0
event_idstringrequiredjournal_headobjectrequiredA {journalId, sequence, chainDigest} position in the deletion chain. Sequence zero is the explicit genesis, never an absent digest.
journal_idstringrequiredpattern ^[a-z][a-z0-9._-]{0,127}$
sequenceintegerrequiredat least 0
chain_digeststringrequiredpattern ^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:
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.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
Generated from the platform contracts at commit 5954fbc1.