# Memories

The governed list of memories: write, review, correct, forget, and trace them to their sources.

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

## 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](https://mirabase.io/developers/memory.md#conversation)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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 | `DevMemoryScope` | Optional | Keep the memories of one scope: `project`, `agent`, or `account`. |
| `space_id` | Query | `DevSpaceRef` | Optional | 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` | Optional | Keep the memories with this status. Without it the list has `candidate` and `confirmed`. |
| `kind` | Query | `string` | Optional | 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` | Optional | 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` | Optional | 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

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevMemory[]` | 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/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](https://mirabase.io/developers/memory.md#create)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `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` `DevCreateMemoryRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scope` | `DevMemoryScope` | Required | Whose memory to write: `project`, `agent`, or `account`. |
| `space_id` | `DevSpaceRef` | Optional | Required for `project` and `agent`; `default` names your default Space, as it does in a path. Account memory takes none. |
| `kind` | `string` | Required | `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 |
| `text` | `string` | Required | The memory itself, 1 to 2000 characters. length 1..2000 |
| `pinned` | `boolean` | Optional | Not on account memory. default: false |

### Responses

- `200` `application/json` `DevMemory`
- `201` `application/json` `DevMemory`

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

### Parameters

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

### Responses

- `200` `application/json` `DevMemory`

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

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

### Request body

`application/json` `DevUpdateMemoryRequest` Send at least one.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `pinned` | `boolean` | Optional | 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)` | Optional | Closes a distilled fact or an account memory. A memory written as an Entry has no validity window: forget or correct it. |

### Responses

- `200` `application/json` `DevMemory`

### 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/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](https://mirabase.io/developers/memory.md#govern)

### Parameters

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

### Responses

- `200` `application/json` `DevMemoryForgetReceipt`

### 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 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](https://mirabase.io/developers/memory.md#govern)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `memory_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` `DevCorrectMemoryRequest` Writes a replacement and closes the validity of the old memory.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | Required | The corrected statement, 1 to 2000 characters. length 1..2000 |

### Responses

- `200` `application/json` `DevMemory`

### 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/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](https://mirabase.io/developers/memory.md#govern)

### Parameters

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

### Responses

- `200` `application/json` `DevMemoryProvenance`

### 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/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](https://mirabase.io/developers/memory.md#govern)

### Parameters

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

### Request body

`application/json` `DevReviewMemoryRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | `confirm \| reject` | Required | `confirm` makes the candidate a memory; `reject` turns it down. |

### Responses

- `200` `application/json` `DevMemory`

### 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/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](https://mirabase.io/developers/memory.md#govern)

### Parameters

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

### Responses

- `200` `application/json` `DevMemoryUndoReceipt`

### 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/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"
    }
  ]
}
```
