Skip to content
Developer docs
Docs menu

Memory dreaming

Markdown

Offline memory consolidation. These operations exist only on deployments that enable it.

Read a dream's reportDeployment option

GET/v2/memory/dreams/{dream_id}

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

One dream's report. Needs knowledge:read; returns 404 for a dream you cannot see. Only on deployments with memory dreaming enabled; elsewhere 404.

Capability knowledge:read

Guide: Memory

Parameters

NameInTypeDescription
dream_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/memory/dreams/$DREAM_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "scope": "project",
  "status": "queued",
  "trigger": "manual",
  "created_at": "2026-11-06T00:00:00Z",
  "undoable": false,
  "counts": {
    "dormant_marked": 1
  },
  "model_tokens": 1
}

List a dream's actionsDeployment option

GET/v2/memory/dreams/{dream_id}/actions

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

The changes a dream made, in order, limited to memories whose source you can see. Needs knowledge:read. Only on deployments with memory dreaming enabled; elsewhere 404.

Capability knowledge:read

Guide: Memory

Parameters

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

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevDreamAction[]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/memory/dreams/$DREAM_ID/actions" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "seq": 1,
      "memory_id": "<memory_id>",
      "entry_id": "<entry_id>",
      "action": "dormant",
      "reason": "quote_missing",
      "state": "applied",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

List a dream's judgmentsDeployment option

GET/v2/memory/dreams/{dream_id}/judgments

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

Every pair of memories this dream asked a model to compare, oldest first: proposals it wrote, judgments it only recorded (the shadow setting), and ones it discarded (they keep no text, only the reason). Needs knowledge:read; you see a judgment only when you can see the source of every member. Only on deployments with memory dreaming enabled; elsewhere 404.

Capability knowledge:read

Guide: Memory

Parameters

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

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevDreamJudgment[]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/memory/dreams/$DREAM_ID/judgments" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "id": "<id>",
      "dream_id": "<dream_id>",
      "outcome": "open",
      "member_ids": [
        "<member_ids>"
      ],
      "layer": "rule",
      "signals": [
        "<signals>"
      ],
      "prompt_version": 1,
      "cached": false,
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

Undo a dreamDeployment option

POST/v2/memory/dreams/{dream_id}/undo

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

Take back what a finished dream did, action by action, and return its report; its open proposals become withdrawn, and approved merge and supersede proposals are reversed. The same rights as starting it. A memory that changed since (forgotten, confirmed, corrected, re-distilled, or taken over by a later dream) is left alone and counts in conflict_skipped; for an approved proposal, so does a change to the memory that stayed. A forgotten memory never comes back. Confirming does not block undoing an unused mark. reported actions changed nothing and are not undone. Later dreams do not redo an undone action on the same version of the memory (each reason on its own), and do not propose an undone pair again. Allowed until 30 days after the dream finished, or after its last approved proposal if that is later, or until three later dreams of the scope succeed after that moment, whichever comes first (409 conflict after); a dream still running returns 409 dream_run_in_flight; undoing it again returns the report. Only on deployments with memory dreaming enabled; elsewhere 404. Needs knowledge:write; the project scope also needs memory:confirm.

Capability knowledge:write

Guide: Memory

Parameters

NameInTypeDescription
dream_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 DevEmptyRequest

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/memory/dreams/$DREAM_ID/undo" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "scope": "project",
  "status": "queued",
  "trigger": "manual",
  "created_at": "2026-11-06T00:00:00Z",
  "undoable": false,
  "counts": {
    "dormant_marked": 1
  },
  "model_tokens": 1
}

Read a memory proposalDeployment option

GET/v2/memory/proposals/{proposal_id}

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

One proposal. Needs knowledge:read; returns 404 for a proposal you cannot see, or one whose members' sources you cannot all see. Only on deployments with memory dreaming enabled; elsewhere 404.

Capability knowledge:read

Parameters

NameInTypeDescription
proposal_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/memory/proposals/$PROPOSAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "scope": "project",
  "dream_id": "<dream_id>",
  "kind": "merge",
  "member_ids": [
    "<member_ids>"
  ],
  "status": "open",
  "created_at": "2026-11-06T00:00:00Z"
}

Approve a memory proposalDeployment option

POST/v2/memory/proposals/{proposal_id}/approve

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

Carry out a merge or supersede proposal: plan.close is closed (status superseded), and so is any memory saying the same sentence in that scope; plan.keep stays, its text unchanged. A merge adds the closed memory's quotes to the kept memory's provenance; forgetting the kept memory then forgets what was merged into it. The sentence closed is not distilled again. Members are checked again first: if a member changed since the proposal was written, the proposal becomes stale and the request returns 409 proposal_closed, as for any proposal no longer open. A conflict or promote proposal returns 422: settle a conflict by correcting or forgetting one side, or reject it. The same rights as reject. Returns 409 space_busy while a source is being written. To take an approval back, undo the dream (POST /v2/memory/dreams/{dream_id}/undo says how long that is allowed). Only on deployments with memory dreaming enabled; elsewhere 404. Needs knowledge:write; the project scope also needs memory:confirm.

Capability knowledge:write

Guide: Memory

Parameters

NameInTypeDescription
proposal_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 DevEmptyRequest

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/memory/proposals/$PROPOSAL_ID/approve" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "scope": "project",
  "dream_id": "<dream_id>",
  "kind": "merge",
  "member_ids": [
    "<member_ids>"
  ],
  "status": "open",
  "created_at": "2026-11-06T00:00:00Z"
}

Reject a memory proposalDeployment option

POST/v2/memory/proposals/{proposal_id}/reject

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

Close the proposal without changing any memory; the same members are not proposed for the same change again. The same rights as undoing a dream of its scope: for the project scope knowledge:write, memory:confirm, and editor, not an Agent in proposal mode (403 proposal_required), and no write_root or read_root in the Space (403 outside_write_root); for an agent scope only that Agent. A delegated grant returns 403. A proposal that is no longer open returns 409 proposal_closed. Only on deployments with memory dreaming enabled; elsewhere 404.

Capability knowledge:write

Guide: Memory

Parameters

NameInTypeDescription
proposal_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 DevEmptyRequest

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/memory/proposals/$PROPOSAL_ID/reject" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "scope": "project",
  "dream_id": "<dream_id>",
  "kind": "merge",
  "member_ids": [
    "<member_ids>"
  ],
  "status": "open",
  "created_at": "2026-11-06T00:00:00Z"
}

List dreamsDeployment option

GET/v2/spaces/{space_id}/memory/dreams

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

Dreams of this Space, newest first. Needs knowledge:read and a Space you can see; an agent dream is listed only for that Agent and the Space owner. Only on deployments with memory dreaming enabled; elsewhere 404.

Capability knowledge:read

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256
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
scopeQueryDevDreamScopeKeep the dreams of one scope: project or agent.
statusQueryDevDreamStatusKeep the dreams with this status.

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevDream[]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/spaces/$SPACE_ID/memory/dreams" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "scope": "project",
      "status": "queued",
      "trigger": "manual",
      "created_at": "2026-11-06T00:00:00Z",
      "undoable": false,
      "counts": {
        "dormant_marked": 1
      },
      "model_tokens": 1
    }
  ]
}

Start a dreamDeployment option

POST/v2/spaces/{space_id}/memory/dreams

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

Start a dream now, always as a job: returns 202 with job_id (the dream id) and Location; follow it with GET /v2/jobs/{job_id}. Dreams also run on their own when a scope has new memories. A dream checks each distilled memory's quotes against the current version of its source and marks the ones whose quotes are all gone as dormant (quote_missing); it never marks a memory a person confirmed this way (an approved candidate, or one distilled from a conversation ingested with memory:confirm), never brings back forgotten ones, and never crosses scopes. status: "confirmed" also covers distilled memories that took effect without review; only those get quote_missing. Then it looks for unused distilled memories (counted in counts.dormancy_candidates): under the Space setting dormancy: "report", the default, it only reports them; under apply it marks them dormant (unused), and they wake up when served again. Rules and preferences are never marked unused (quote_missing still applies to them); memories a person confirmed are never marked. The project scope needs knowledge:write, memory:confirm, and editor, not an Agent in proposal mode (403 proposal_required), and no write_root or read_root in the Space (403 outside_write_root); an Agent key's own agent scope needs knowledge:write and editor. A delegated grant returns 403. One dream per scope runs at a time (409 dream_run_in_flight); with the Space setting off, returns 409 dreaming_disabled. Only on deployments with memory dreaming enabled; elsewhere 404. The body can be left out, the same as {}.

Capability knowledge:write

Guide: Memory

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.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 DevStartDreamRequest

FieldTypeDescription
scopeDevDreamScopeDefault: agent for an Agent key (its own private memory), project otherwise. Only an Agent key has an agent scope; anyone else naming it returns 422.

Responses

Response headers

  • Location /v2/jobs/{job_id}: poll it until status is succeeded or failed.

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/spaces/$SPACE_ID/memory/dreams" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

json
{
  "job_id": "<job_id>"
}

List memory proposalsDeployment option

GET/v2/spaces/{space_id}/memory/proposals

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

Proposals of this Space, oldest first; status defaults to open, dream_id narrows to one dream. Needs knowledge:read and a Space you can see; a proposal is listed only when you can see the source of every member, and an agent proposal only for that Agent and the Space owner. Only on deployments with memory dreaming enabled; elsewhere 404.

Capability knowledge:read

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.length 1..256
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
statusQueryDevMemoryProposalStatusKeep the proposals with this status. Defaults to open.
dream_idQueryDevIdKeep the proposals this dream wrote.length 1..256

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevMemoryProposal[]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/spaces/$SPACE_ID/memory/proposals" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "scope": "project",
      "dream_id": "<dream_id>",
      "kind": "merge",
      "member_ids": [
        "<member_ids>"
      ],
      "status": "open",
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

Read the consolidation settingDeployment option

GET/v2/spaces/{space_id}/memory/settings

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

The Space's memory consolidation setting. Needs knowledge:read and a Space you can see. Only on deployments with memory dreaming enabled; elsewhere 404.

Capability knowledge:read

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.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/spaces/$SPACE_ID/memory/settings" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

Example response

json
{
  "space_id": "<space_id>",
  "memory_dreaming": "off",
  "dormancy": "report",
  "d4": "off"
}

Change the consolidation settingDeployment option

PATCH/v2/spaces/{space_id}/memory/settings

This endpoint needs offline consolidation (memory-dreaming) enabled on the deployment. Where it is not enabled, the endpoint does not exist and returns 404.

Only the Space owner, with knowledge:manage; a delegated grant returns 403. off stops dreams for the Space and undoes nothing already done. dormancy decides whether unused memories are only reported or marked dormant; switching back to report leaves existing marks (undo the dream to clear them). d4 decides whether a dream compares memories with a model (off, the default, shadow, propose); shadow records judgments without proposing anything, and switching to propose proposes from recorded judgments without asking the model again. An empty body returns 422. Only on deployments with memory dreaming enabled; elsewhere 404.

Capability knowledge:manage

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA Space id; default for your default Space (your own, or the only Space you can see); or ext:<external_id> for the Space that carries your own id for it, such as ext:user-42. All three work in a path, in ?space_id=, and in space_ids. An external_id that no visible Space carries returns 404.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 DevUpdateMemorySettingsRequest Give at least one field; a field left out keeps its value.

FieldTypeDescription
memory_dreamingDevMemoryDreamingModeauto returns 422 until it is available.
dormancyDevMemoryDormancyModeWhat a dream does with unused memories: report (the default) or apply.
d4DevMemoryD4ModeWhether a dream asks a model to compare memories: off (the default), shadow, or propose.

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/spaces/$SPACE_ID/memory/settings" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

json
{
  "space_id": "<space_id>",
  "memory_dreaming": "off",
  "dormancy": "report",
  "d4": "off"
}