Skip to content
Developer docs
Docs menu

Memories

Markdown

The 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

NameInTypeDescription
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20
scopeQueryDevMemoryScopeKeep the memories of one scope: project, agent, or account.
space_idQueryDevSpaceRefKeep 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
statusQueryDevMemoryStatusKeep the memories with this status. Without it the list has candidate and confirmed.
kindQuerystringKeep one kind, such as preference, decision, or event: the kind a memory reports. An unknown kind returns an empty list.length 1..64
entry_idQueryDevIdKeep 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
qQuerystringKeep 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

  • 200 application/json
FieldTypeDescription
dataRequiredDevMemory[]The items on this page.
next_cursorDevCursorPass 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
curl "https://api.mirabase.dev/v2/memories" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
Idempotency-KeyHeaderDevIdempotencyKeyThe 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

FieldTypeDescription
scopeRequiredDevMemoryScopeWhose memory to write: project, agent, or account.
space_idDevSpaceRefRequired for project and agent; default names your default Space, as it does in a path. Account memory takes none.
kindRequiredstringpreference, 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
textRequiredstringThe memory itself, 1 to 2000 characters.length 1..2000
pinnedbooleanNot 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
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

json
{
  "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

NameInTypeDescription
memory_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

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
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
memory_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Request body

application/json DevUpdateMemoryRequest Send at least one.

FieldTypeDescription
pinnedbooleanOnly on a memory written as an Entry. Pinning changes what a Space starts with, so a person must own the Space.
valid_tostring (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

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

json
{
  "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

NameInTypeDescription
memory_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

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
curl -X DELETE "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
memory_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe 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.

FieldTypeDescription
textRequiredstringThe corrected statement, 1 to 2000 characters.length 1..2000

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

json
{
  "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

NameInTypeDescription
memory_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

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
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID/provenance" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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

NameInTypeDescription
memory_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Request body

application/json DevReviewMemoryRequest

FieldTypeDescription
decisionRequiredconfirm | rejectconfirm makes the candidate a memory; reject turns it down.

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

json
{
  "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

NameInTypeDescription
memory_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

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
curl -X POST "https://api.mirabase.dev/v2/memories/$MEMORY_ID/undo" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "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"
    }
  ]
}