Memories
MarkdownThe governed list of memories: write, review, correct, forget, and trace them to their sources.
List memories
GET/v2/memories
List memories, newest first. Without status you get candidate and confirmed; ask for rejected or superseded by name. Account memory is listed for its owner only, and not when space_id is set. Requesting scope=account as an Agent or with a narrowed key returns 403. On deployments with memory dreaming enabled, distilled memories that say the same sentence are listed once per group (group_id, sources), and pages count groups. Needs knowledge:read.
Capability knowledge:read
Guide: Memory
Parameters
| Name | In | Type | Description |
|---|---|---|---|
cursor | Query | DevCursor | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
scope | Query | DevMemoryScope | Keep the memories of one scope: project, agent, or account. |
space_id | Query | DevSpaceRef | Keep the memories of this Space. default names your default Space, as it does in a path. Account memory is not listed when it is set.length 1..256 |
status | Query | DevMemoryStatus | Keep the memories with this status. Without it the list has candidate and confirmed. |
kind | Query | string | Keep one kind, such as preference, decision, or event: the kind a memory reports. An unknown kind returns an empty list.length 1..64 |
entry_id | Query | DevId | Keep the memories that come from this Entry: the Entry itself when it was written as a memory, and the facts distilled from it. Use it after ingesting a conversation to read what that conversation produced. An Entry you cannot see lists nothing.length 1..256 |
q | Query | string | Keep the memories whose text contains this, ignoring case. It is a literal match for browsing and cleaning up, not retrieval: to find memories by meaning, call search with include: ["memory"].length 1..200 |
Responses
200application/json
| Field | Type | Description |
|---|---|---|
dataRequired | DevMemory[] | The items on this page. |
next_cursor | DevCursor | Pass it as cursor to get the next page. Absent on the last page. |
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/memories" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"data": [
{
"id": "<id>",
"scope": "project",
"kind": "<kind>",
"status": "candidate",
"text": "The launch moved to March 14.",
"pinned": false,
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z"
}
]
}Create a memory
POST/v2/memories
Write a memory that is already confirmed. account needs memory:confirm. project needs memory:confirm and knowledge:write, and a person must own the Space (an Agent in proposal mode cannot write project). agent needs knowledge:write and an Agent key, and writes that Agent's own memory. To propose candidate memories rather than write confirmed ones, ingest a conversation. A project or agent memory whose text matches a current memory of the same Space, scope, and kind is not written twice: the endpoint returns 200 with the existing memory (and pins it if you sent pinned: true). A statement worded differently is a new memory.
Capability Depends on the request, as the description above says.
Guide: Memory
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | Header | DevIdempotencyKey | The same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512 |
Request body
application/json DevCreateMemoryRequest
| Field | Type | Description |
|---|---|---|
scopeRequired | DevMemoryScope | Whose memory to write: project, agent, or account. |
space_id | DevSpaceRef | Required for project and agent; default names your default Space, as it does in a path. Account memory takes none. |
kindRequired | string | preference, decision, or progress. Account memory has its own list: role, project, commitment, preference, person, fact, episode_summary, interview_answer, first_screen_pin, ask_less.length 1..64 |
textRequired | string | The memory itself, 1 to 2000 characters.length 1..2000 |
pinned | boolean | Not on account memory.default: false |
Responses
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/memories" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scope":"project","space_id":"default","kind":"preference","text":"Ada prefers release notes in British English."}'Example response
{
"id": "ent_01JD2M8A7C",
"space_id": "col_01JD2M7QK3",
"scope": "project",
"kind": "preference",
"status": "confirmed",
"text": "Ada prefers release notes in British English.",
"pinned": false,
"created_at": "2026-11-17T08:05:00Z",
"updated_at": "2026-11-17T08:05:00Z"
}Read a memory
GET/v2/memories/{memory_id}
Read one memory. A distilled fact's id contains :, so percent-encode it in the path. A memory you cannot see returns 404 not_found, the same as one that does not exist. Needs knowledge:read.
Capability knowledge:read
Guide: Memory
Parameters
| Name | In | Type | Description |
|---|---|---|---|
memory_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
200application/jsonDevMemory
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"id": "ent_01JD2M8A7C",
"space_id": "col_01JD2M7QK3",
"scope": "project",
"kind": "preference",
"status": "confirmed",
"text": "Ada prefers release notes in British English.",
"pinned": false,
"created_at": "2026-11-17T08:05:00Z",
"updated_at": "2026-11-17T08:05:00Z"
}Update a memory
PATCH/v2/memories/{memory_id}
Pin or unpin a memory written as an Entry, or set valid_to to close a distilled fact or an account memory. Sending a field that does not apply to this memory type returns 422. Updating a candidate memory returns 409 (memory_pending_review on a distilled fact, conflict on an account memory); review it first. Needs knowledge:write for a Space memory, or memory:confirm for an account memory.
Capability Depends on the request, as the description above says.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
memory_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Request body
application/json DevUpdateMemoryRequest Send at least one.
| Field | Type | Description |
|---|---|---|
pinned | boolean | Only on a memory written as an Entry. Pinning changes what a Space starts with, so a person must own the Space. |
valid_to | string (date-time) | Closes a distilled fact or an account memory. A memory written as an Entry has no validity window: forget or correct it. |
Responses
200application/jsonDevMemory
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X PATCH "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Example response
{
"id": "ent_01JD2M8A7C",
"space_id": "col_01JD2M7QK3",
"scope": "project",
"kind": "preference",
"status": "confirmed",
"text": "Ada prefers release notes in British English.",
"pinned": false,
"created_at": "2026-11-17T08:05:00Z",
"updated_at": "2026-11-17T08:05:00Z"
}Forget a memory
DELETE/v2/memories/{memory_id}
Forget a memory permanently. A distilled fact needs knowledge:write and the editor role in the Space; a memory written as an Entry needs knowledge:write; an account memory needs memory:confirm. A forgotten fact does not return when its source is republished, restored, edited, or moved, and the same sentence is not distilled again in that Space; the source Entry is untouched. A memory written as an Entry is erased along with any memories it superseded. Deleting a memory a second time returns 404 not_found. To keep an Entry from being distilled at all, set memory_exclude on it.
Capability Depends on the request, as the description above says.
Guide: Memory
Parameters
| Name | In | Type | Description |
|---|---|---|---|
memory_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
200application/jsonDevMemoryForgetReceipt
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X DELETE "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"memory_id": "<memory_id>",
"status": "forgotten"
}Correct a memory
POST/v2/memories/{memory_id}/correct
Replace a memory with what you say instead. Needs memory:confirm. The old one is closed and does not come back. A distilled fact or a memory written as an Entry is replaced by a new memory Entry in the same Space, which only the Space owner or an Agent can write, so the response has a new id; supersedes names the old one. An account memory is replaced by another account memory. A memory written as an Entry that was already replaced returns 409 memory_superseded.
Capability memory:confirm
Guide: Memory
Parameters
| Name | In | Type | Description |
|---|---|---|---|
memory_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Idempotency-Key | Header | DevIdempotencyKey | The same Idempotency-Key, principal, API key, operation, and input replay the original result for 24 hours. The same Idempotency-Key with different input returns 409 conflict.length 1..512 |
Request body
application/json DevCorrectMemoryRequest Writes a replacement and closes the validity of the old memory.
| Field | Type | Description |
|---|---|---|
textRequired | string | The corrected statement, 1 to 2000 characters.length 1..2000 |
Responses
200application/jsonDevMemory
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/correct" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"The launch moved to March 14."}'Example response
{
"id": "ent_01JD2M8A7C",
"space_id": "col_01JD2M7QK3",
"scope": "project",
"kind": "preference",
"status": "confirmed",
"text": "Ada prefers release notes in British English.",
"pinned": false,
"created_at": "2026-11-17T08:05:00Z",
"updated_at": "2026-11-17T08:05:00Z"
}Read a memory's provenance
GET/v2/memories/{memory_id}/provenance
The Entry versions a memory rests on, with quotes where there are any. Needs knowledge:read.
Capability knowledge:read
Guide: Memory
Parameters
| Name | In | Type | Description |
|---|---|---|---|
memory_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
200application/jsonDevMemoryProvenance
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID/provenance" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"memory_id": "<memory_id>",
"sources": [
{
"entry_id": "<entry_id>",
"version_id": "<version_id>"
}
]
}Review a memory
POST/v2/memories/{memory_id}/review
Review a candidate memory. Needs memory:confirm. confirm makes it confirmed, so retrieval uses it; reject makes it rejected, and the same sentence is not distilled again in that Space. Repeating a decision returns the memory unchanged; the opposite decision returns 409 memory_already_reviewed (conflict on an account memory). To remove a confirmed memory, forget it.
Capability memory:confirm
Guide: Memory
Parameters
| Name | In | Type | Description |
|---|---|---|---|
memory_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Request body
application/json DevReviewMemoryRequest
| Field | Type | Description |
|---|---|---|
decisionRequired | confirm | reject | confirm makes the candidate a memory; reject turns it down. |
Responses
200application/jsonDevMemory
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/review" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"decision":"confirm"}'Example response
{
"id": "ent_01JD2M8A7C",
"space_id": "col_01JD2M7QK3",
"scope": "project",
"kind": "preference",
"status": "confirmed",
"text": "Ada prefers release notes in British English.",
"pinned": false,
"created_at": "2026-11-17T08:05:00Z",
"updated_at": "2026-11-17T08:05:00Z"
}Undo a memory write
POST/v2/memories/{memory_id}/undo
Take back a memory you wrote or a correction you made, within 30 minutes. Needs memory:confirm. Call it on the new memory: it is erased and what it replaced comes back in restored. After the 30-minute window or once another memory has superseded it, the endpoint returns 409 (undo_window_expired or memory_superseded on a memory written as an Entry, conflict on an account memory). Calling undo on a distilled fact returns 409 undo_not_applicable: nobody wrote it, and forgetting cannot be undone. Undoing a memory written as an Entry a second time returns 404, because the first undo erased it.
Capability memory:confirm
Guide: Memory
Parameters
| Name | In | Type | Description |
|---|---|---|---|
memory_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
200application/jsonDevMemoryUndoReceipt
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/undo" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"memory_id": "<memory_id>",
"status": "undone",
"restored": [
{
"id": "<id>",
"scope": "project",
"kind": "<kind>",
"status": "candidate",
"text": "The launch moved to March 14.",
"pinned": false,
"created_at": "2026-11-06T00:00:00Z",
"updated_at": "2026-11-06T00:00:00Z"
}
]
}