# Memory dreaming

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

API reference. Base URL: `https://api.mirabase.dev`

## Read a dream's report (Deployment 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](https://mirabase.io/developers/memory.md#dreams)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `dream_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

- `200` `application/json` `DevDream`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 actions (Deployment 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](https://mirabase.io/developers/memory.md#dreams)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `dream_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevDreamAction[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 judgments (Deployment 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](https://mirabase.io/developers/memory.md#dreams)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `dream_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevDreamJudgment[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 dream (Deployment 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](https://mirabase.io/developers/memory.md#dreams)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `dream_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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` `DevEmptyRequest`

### Responses

- `200` `application/json` `DevDream`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 proposal (Deployment 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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `proposal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

- `200` `application/json` `DevMemoryProposal`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 proposal (Deployment 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`](https://mirabase.io/developers/api/memory-dreaming.md#memorydreams-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](https://mirabase.io/developers/memory.md#memory-proposals)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `proposal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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` `DevEmptyRequest`

### Responses

- `200` `application/json` `DevMemoryProposal`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 proposal (Deployment 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](https://mirabase.io/developers/memory.md#memory-proposals)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `proposal_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | 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` `DevEmptyRequest`

### Responses

- `200` `application/json` `DevMemoryProposal`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 dreams (Deployment 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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A 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 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |
| `scope` | Query | `DevDreamScope` | Optional | Keep the dreams of one scope: `project` or `agent`. |
| `status` | Query | `DevDreamStatus` | Optional | Keep the dreams with this status. |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevDream[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 dream (Deployment 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}`](https://mirabase.io/developers/api/jobs.md#jobs-read). 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](https://mirabase.io/developers/memory.md#dreams)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A 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-Key` | Header | `DevIdempotencyKey` | Optional | 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` `DevStartDreamRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scope` | `DevDreamScope` | Optional | Default: `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

- `202` `application/json` `DevJobReceipt`

### 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 proposals (Deployment 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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A 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 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |
| `status` | Query | `DevMemoryProposalStatus` | Optional | Keep the proposals with this status. Defaults to `open`. |
| `dream_id` | Query | `DevId` | Optional | Keep the proposals this dream wrote. length 1..256 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevMemoryProposal[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | 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](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 setting (Deployment 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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A 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

- `200` `application/json` `DevMemorySettings`

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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 setting (Deployment 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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A 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-Key` | Header | `DevIdempotencyKey` | Optional | 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` `DevUpdateMemorySettingsRequest` Give at least one field; a field left out keeps its value.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `memory_dreaming` | `DevMemoryDreamingMode` | Optional | `auto` returns 422 until it is available. |
| `dormancy` | `DevMemoryDormancyMode` | Optional | What a dream does with unused memories: `report` (the default) or `apply`. |
| `d4` | `DevMemoryD4Mode` | Optional | Whether a dream asks a model to compare memories: `off` (the default), `shadow`, or `propose`. |

### Responses

- `200` `application/json` `DevMemorySettings`

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```bash
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"
}
```
