# Memory

Write, distill, review, correct, and forget memories, and consolidate them offline.

## The memory model

`/v2/memories` returns three sources in one shape: account memories, memories written as Entries, and facts distilled from Entries. Only a memory written as an Entry has an Entry id as its `id`. A distilled fact leads back to its Entry and version through `provenance`.

Every memory has a scope and a status: the scope says whose memory it is ([DevMemoryScope](https://mirabase.io/developers/api/schemas.md#DevMemoryScope)), and the status says whether retrieval uses it ([DevMemoryStatus](https://mirabase.io/developers/api/schemas.md#DevMemoryStatus)).

Forgetting deletes for good and leaves no text to return, so there is no `forgotten` status.

## Write a memory

Write a statement that stays true, such as a preference or a decision, with [`POST /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-create). It is `confirmed` at once, and context and answers use it from then on. Submitting the same text again does not create a duplicate; see the reference for required permissions by scope.

curl:

```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": "'$SPACE_ID'", "kind": "decision", "text": "Releases go out on Thursdays."}'
```

TypeScript:

```ts
const memory = await mirabase.memories.create({
  scope: "project",
  space_id: spaceId,
  kind: "decision",
  text: "Releases go out on Thursdays.",
});
```

Python:

```python
memory = mb.memories.create({
    "scope": "project",
    "space_id": space_id,
    "kind": "decision",
    "text": "Releases go out on Thursdays.",
})
```

## Distill memories from a conversation

To propose rather than state, ingest a conversation: [`POST /v2/spaces/{space_id}/ingest`](https://mirabase.io/developers/api/ingest.md#ingest-ingest) with `kind: conversation`, `session_id`, and `messages` returns 202. One batch is one Entry, however many turns it has. Facts distilled from it are `confirmed` if you hold `memory:confirm` when you send it, otherwise `candidate`; the receipt's `memory_status` says which.

curl:

```bash
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/ingest" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Idempotency-Key: chat-42-batch-1" \
  -H "Content-Type: application/json" \
  -d '{"kind": "conversation", "session_id": "chat-42", "messages": [
    {"role": "user", "content": "Let us ship on Thursdays from now on.", "timestamp": 1762416000000},
    {"role": "assistant", "content": "Noted: releases on Thursdays."}
  ]}'
```

TypeScript:

```ts
const receipt = await mirabase.conversations.add(
  [
    { role: "user", content: "Let us ship on Thursdays from now on.", timestamp: 1762416000000 },
    { role: "assistant", content: "Noted: releases on Thursdays." },
  ],
  { sessionId: "chat-42", idempotencyKey: "chat-42-batch-1" },
);
```

Python:

```python
receipt = mb.conversations.add(
    [
        {"role": "user", "content": "Let us ship on Thursdays from now on.", "timestamp": 1762416000000},
        {"role": "assistant", "content": "Noted: releases on Thursdays."},
    ],
    session_id="chat-42",
    idempotency_key="chat-42-batch-1",
)
```

Distillation runs after indexing, so the processing job can be `succeeded` before any memory exists. Poll [`GET /v2/entries/{entry_id}/processing`](https://mirabase.io/developers/api/entries.md#entries-processing) until `memory.state` is no longer `pending`: at `ready`, [`GET /v2/memories?entry_id=`](https://mirabase.io/developers/api/memories.md#memories-list) lists what the batch wrote; `skipped` means this version is not distilled, for the reasons below; `failed` means distillation failed.

curl:

```bash
# Repeat until memory.state is no longer "pending".
# "skipped" means the batch is not distilled: memory.reason says why.
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/processing" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Then list what the batch wrote.
curl "https://api.mirabase.dev/v2/memories?entry_id=$ENTRY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

TypeScript:

```ts
let processing = await mirabase.entries.processing(receipt.entry_id);
for (let attempt = 0; attempt < 30 && processing.memory?.state === "pending"; attempt += 1) {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  processing = await mirabase.entries.processing(receipt.entry_id);
}

if (processing.memory?.state === "skipped") {
  // Not distilled. reason says why, for example "model_not_configured";
  // remediation.action, when present, says what to do.
  console.log(processing.memory.reason, processing.memory.remediation?.action);
} else {
  for await (const memory of mirabase.memories.list({ entry: receipt.entry_id })) {
    console.log(memory.status, memory.text);
  }
}
```

Python:

```python
import time

processing = mb.entries.processing(receipt["entry_id"])
for _ in range(30):
    if processing.get("memory", {}).get("state") != "pending":
        break
    time.sleep(2)
    processing = mb.entries.processing(receipt["entry_id"])

memory_state = processing.get("memory", {})
if memory_state.get("state") == "skipped":
    # Not distilled. reason says why, for example "model_not_configured";
    # remediation["action"], when present, says what to do.
    print(memory_state.get("reason"), memory_state.get("remediation", {}).get("action"))
else:
    for memory in mb.memories.list(entry=receipt["entry_id"]):
        print(memory["status"], memory["text"])
```

- Ingesting the same batch twice makes two Entries, so send `Idempotency-Key` when retrying; see [Idempotency](https://mirabase.io/developers/conventions.md#idempotency).
- To record a conversation as it goes, send each batch with the same `session_id`. The `session_id` is also stored as the metadata key `session_id`, so [`GET /v2/entries?metadata={"session_id":"…"}`](https://mirabase.io/developers/api/entries.md#entries-list) lists them together and `filter.metadata` in search narrows to that conversation.
- When an Agent in `proposal` mode ingests a conversation, distilled facts are always `candidate`.

### Why distillation is skipped

The `memory` object is the same in the ingest receipt, in the processing status, and in the job. When `state` is `skipped`, `reason` says why; when the reason is actionable, `remediation` comes with it, so act on its `remediation.action`: for example, when the deployment has no model for distillation, [write the memories directly](https://mirabase.io/developers/memory.md#create). When the deployment does not distill memories or the Entry has `memory_exclude`, the receipt is already `skipped` at write time, so there is nothing to poll. `distill_disabled`, `model_not_configured`, and `distill_paused` describe the deployment's setup and the account's usage, so only a key that belongs to a `tenant_admin` or holds `knowledge:manage`, and is not limited to Spaces or a metadata scope, sees them; other keys see `distill_unavailable` in place of the first two, and no reason in place of `distill_paused`: the state stays `pending`. A version distilled before the deployment stopped distilling stays `ready`. Every reason and its remediation are in [DevMemoryProcessingReason](https://mirabase.io/developers/api/schemas.md#DevMemoryProcessingReason) and [remediation](https://mirabase.io/developers/api/schemas.md#DevMemoryProcessing.remediation).

## Review, correct, and forget memories

```bash
# Candidates waiting for review in one Space.
curl "https://api.mirabase.dev/v2/memories?space_id=$SPACE_ID&status=candidate" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Confirm one, or send "reject".
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"}'

# Replace it with what is true now. The response is a new memory whose supersedes names the old one.
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": "Releases go out on Wednesdays."}'

# Where it came from.
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID/provenance" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Forget it for good.
curl -X DELETE "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

- A candidate waits for a person: confirm or reject it with [`POST /v2/memories/{memory_id}/review`](https://mirabase.io/developers/api/memories.md#memories-review).
- When a memory is wrong, write the right statement with [`POST /v2/memories/{memory_id}/correct`](https://mirabase.io/developers/api/memories.md#memories-correct): the old memory is closed and kept as history. You can undo a new memory or correction within 30 minutes with [`POST /v2/memories/{memory_id}/undo`](https://mirabase.io/developers/api/memories.md#memories-undo).
- [`DELETE /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-forget) forgets for good and cannot be undone. After a distilled fact is rejected or forgotten, the same sentence is not distilled again in that Space.
- [`GET /v2/memories/{memory_id}/provenance`](https://mirabase.io/developers/api/memories.md#memories-provenance) lists the Entry versions a memory rests on, with the quoted words.
- To keep a source from producing memories, set `memory_exclude: true` with [`PATCH /v2/entries/{entry_id}`](https://mirabase.io/developers/api/entries.md#entries-update): the facts distilled from it are retired, and search and reading are unaffected. Setting it back to `false` distills again, without what you forgot or corrected.

## MEMORY.md

`/.mirabase/memory/MEMORY.md` is a generated, read-only view of this Space's memory for an Agent starting work. The same memories give the same bytes and the `ETag` is a content hash, which suits a prompt cache prefix. Read it with [`GET /v2/spaces/{space_id}/files`](https://mirabase.io/developers/api/files.md#files-read); it has raw bytes only, and a write returns 405 `virtual_file`. In the default layout, facts distilled from conversations are not in it: use [`GET /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-list) or retrieval for those. Deployments with offline consolidation switch to an index layout and add `RECENT.md`; see [the index layout](https://mirabase.io/developers/memory.md#memory-index).

```bash
# Send back the ETag you have. 304 means nothing changed.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/.mirabase/memory/MEMORY.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H 'If-None-Match: "<etag>"'
```

## Offline consolidation (dreams)

While no Agent is working, the service tidies the memories that already exist. The API calls one such run a dream. A dream **only reorganizes and never generates**: it writes no new memory and changes no memory's text, and every action carries its evidence and can be undone. Merges and supersessions are only proposed: a model never changes a memory on its own, and nothing takes effect until a person approves it.

> **Note:** Offline consolidation is optional per deployment. Where it is not enabled, the endpoints in this section and the next two return 404, `MEMORY.md` keeps the default layout above, and there is no `RECENT.md`.

### What it does

- Checks quotes: it compares each distilled memory's verbatim quotes with the current version of its source Entry. When none of them are found anymore, the dream marks the memory dormant (`quote_missing`).
- Finds unused memories: distilled memories that have not been served for a long time and that no person confirmed are only reported by default. With `apply`, the dream marks them dormant (`unused`), and serving them wakes them up.
- Counts duplicates: it finds groups of memories that say the same thing and records the number and tokens of active memories before and after in the report (`view`).
- Compares memories: once the Space owner turns `d4` on, it asks a model whether pairs of distilled memories repeat, supersede, or contradict each other. The conclusions only ever become [memory proposals](https://mirabase.io/developers/memory.md#memory-proposals). By default no model is called.
- Runs automatically: it starts when a scope has new memories, or you can start one on demand.

### What it does not do

- It generates nothing: no new memories, no changed text, no Entries, files, or versions, and nothing written outside `MEMORY.md` and `RECENT.md`.
- The model changes nothing: it only says how two memories relate and quotes the sources verbatim. It writes no text that lands in memory and applies no change. There is no `auto` mode yet.
- It leaves alone what a person decided: approved candidates and memories distilled from a conversation ingested with `memory:confirm` are never marked for missing quotes or for being unused, and memories written as Entries and account memories are never touched. Only distilled memories that took effect without review can go dormant; they too have `status: "confirmed"`.
- It never brings back a forgotten memory, and undoing a dream does not either.
- It stays in one scope, either a Space's project memory or one Agent's private memory: it never crosses scopes or Spaces, and never runs on branches.
- It deletes nothing: the strongest thing a dream does on its own is mark a memory dormant, and a memory is closed only after a person approves a proposal, which can be undone too. Only your own forget and erase calls delete for good.

### Memory layers

Different memories follow different rules: a rule that is rarely needed but important should not be set aside for being quiet, and events have an order and should not be merged as duplicates. The layer comes from a memory's `kind` and validity date and is worked out during a dream. A memory has no such field; proposals and judgments carry `layer`.

Which memories each of the four layers holds, and which layers are compared and proposed on, are in [DevMemoryLayer](https://mirabase.io/developers/api/schemas.md#DevMemoryLayer); how long a memory stays unused before it goes dormant is in [DevMemoryDormancyReason](https://mirabase.io/developers/api/schemas.md#DevMemoryDormancyReason).

A supersession stands only when the model's order agrees with the dates of the sources. Otherwise it becomes a `conflict`, shown to a person only.

### Dormancy and waking up

A dormant memory carries `dormant: {reason, dream_id}`. It leaves `RECENT.md` and is not compared by the model, but it is still listed and searchable. `MEMORY.md` holds only what people wrote or confirmed, and none of that ever goes dormant. The conditions of the two reasons and what clears each are in [DevMemoryDormancyReason](https://mirabase.io/developers/api/schemas.md#DevMemoryDormancyReason).

- Waking up takes no call of its own: reading it with [`GET /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-read), or having a search, context pack, or answer hand it back, wakes it up. Reading `MEMORY.md`, `RECENT.md`, or the list does not count.
- Switching from `apply` back to `report` leaves existing marks; undo the dream to clear them.

### Settings: proposals by default

Each Space has three settings: `memory_dreaming` (default `propose`, dreams run; `off` stops them), `dormancy` (default `report`, unused memories are only reported; `apply` marks them dormant), and `d4` (default `off`, no model is asked; `shadow` only records judgments; `propose` writes the judgments that pass validation as proposals). Under `propose`, dreams on their own only make undoable marks that change no text. Merging duplicates, letting a newer memory supersede an older one, flagging memories that contradict each other, or promoting an Agent's private memory to the project only ever become [memory proposals](https://mirabase.io/developers/memory.md#memory-proposals) for a person to decide. Only the Space owner can change the settings.

curl:

```bash
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/settings" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Stop dreams for this Space. What they already did stays; undo a dream to take it back.
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 '{"memory_dreaming": "off"}'

# Mark unused memories dormant, and let a model propose merges and supersessions.
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 '{"dormancy": "apply", "d4": "propose"}'
```

TypeScript:

```ts
const settings = await mirabase.memory.settings.get();
// settings.memory_dreaming is "propose" unless someone changed it.

await mirabase.memory.settings.update("off");

// A field left out keeps its value. settings.d4_available says whether this deployment can ask a model.
await mirabase.memory.settings.update({ dormancy: "apply", d4: "propose" });
```

Python:

```python
settings = mb.memory.settings.get()
# settings["memory_dreaming"] is "propose" unless someone changed it.

mb.memory.settings.update("off")

# A field left out keeps its value. settings["d4_available"] says whether this deployment can ask a model.
mb.memory.settings.update(dormancy="apply", d4="propose")
```

- Read a report before switching `dormancy` to `apply`.
- Run `shadow` for a while and read the judgments before switching to `propose`: recorded judgments become proposals without asking the model again.
- When `d4_available` in the response is false, this deployment asks no model, whatever `d4` says.

### Start, inspect, and undo a dream

[`POST /v2/spaces/{space_id}/memory/dreams`](https://mirabase.io/developers/api/memory-dreaming.md#memorydreams-start) starts a dream now and returns 202; `job_id` is the dream id, followed with [`GET /v2/jobs/{job_id}`](https://mirabase.io/developers/api/jobs.md#jobs-read). [`GET /v2/memory/dreams/{dream_id}`](https://mirabase.io/developers/api/memory-dreaming.md#memorydreams-read) is its report, [`GET /v2/memory/dreams/{dream_id}/actions`](https://mirabase.io/developers/api/memory-dreaming.md#memorydreams-actions) lists each change and its reason, and [`GET /v2/memory/dreams/{dream_id}/judgments`](https://mirabase.io/developers/api/memory-dreaming.md#memorydreams-judgments) lists every pair a model compared. [`POST /v2/memory/dreams/{dream_id}/undo`](https://mirabase.io/developers/api/memory-dreaming.md#memorydreams-undo) undoes the whole dream. A scope runs one dream at a time.

curl:

```bash
# Start one now. job_id is the dream id (drm_...).
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 '{"scope": "project"}'

# Poll until status is succeeded or failed.
curl "https://api.mirabase.dev/v2/jobs/$DREAM_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# The report, then every change with its reason.
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/actions" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Every pair a model was asked about, proposed or not.
curl "https://api.mirabase.dev/v2/memory/dreams/$DREAM_ID/judgments" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Take it back.
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 '{}'
```

TypeScript:

```ts
const started = await mirabase.memory.dreams.start({ scope: "project" });
let job = await mirabase.jobs.get(started.job_id);
while (job.status === "queued" || job.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  job = await mirabase.jobs.get(started.job_id);
}

const dream = await mirabase.memory.dreams.get(started.job_id);
console.log(dream.counts.checked, dream.counts.dormant_marked, dream.view?.live_before, dream.view?.live_after);
for await (const action of mirabase.memory.dreams.actions(dream.id)) {
  console.log(action.seq, action.memory_id, action.action, action.reason, action.state);
}
for await (const judgment of mirabase.memory.dreams.judgments(dream.id)) {
  console.log(judgment.outcome, judgment.kind, judgment.member_ids, judgment.evidence);
}

if (dream.undoable) await mirabase.memory.dreams.undo(dream.id);
```

Python:

```python
started = mb.memory.dreams.start(scope="project")
# Polls until status is succeeded, failed, or cancelled.
mb.jobs.wait(started["job_id"])

dream = mb.memory.dreams.get(started["job_id"])
print(dream["counts"]["dormant_marked"], dream.get("view"))
for action in mb.memory.dreams.actions(dream["id"]):
    print(action["seq"], action["memory_id"], action["action"], action["reason"], action["state"])
for judgment in mb.memory.dreams.judgments(dream["id"]):
    print(judgment["outcome"], judgment.get("kind"), judgment["member_ids"], judgment.get("evidence"))

if dream["undoable"]:
    mb.memory.dreams.undo(dream["id"])
```

- Undo covers the whole dream, action by action: dormant marks clear, its open proposals become `withdrawn`, and approved merges and supersessions are reversed. A memory that changed since is left alone and counts in `conflict_skipped`.
- Reports and actions count only memories whose source you can see, and an `agent` dream is visible only to that Agent and the Space owner.

## Memory proposals

A change a dream suggests but does not make is a memory proposal, which is not the same thing as a [file proposal](https://mirabase.io/developers/files.md#proposals). Its kinds are in [DevMemoryProposalKind](https://mirabase.io/developers/api/schemas.md#DevMemoryProposalKind) and its statuses in [DevMemoryProposalStatus](https://mirabase.io/developers/api/schemas.md#DevMemoryProposalStatus). You see it only when you can see the source of every member.

> **Note:** A dream writes proposals only when the Space's `d4` setting is `propose` and this deployment has a model (`d4_available` is true). Otherwise the list is empty.

### Verbatim quotes

Because a model writes no conclusion of its own, `proposed_text` is always absent for now. Everything to judge by is the sources' own words: each `evidence` item has `memory_id`, `entry_id`, `version_id`, and a verbatim `quote`, `times` holds the dates that decided which memory is newer, and `plan` says which memory stays (`keep`) and which memories close (`close`) if you approve. A quote must be found word for word in its memory's source, otherwise the whole judgment is discarded and never becomes a proposal.

curl:

```bash
# Open proposals of one dream, oldest first.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/memory/proposals?dream_id=$DREAM_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Read the exact version a quote came from.
curl "https://api.mirabase.dev/v2/entries/$ENTRY_ID/content?view=text&version=$VERSION_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# Carry it out. It takes effect only now.
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 '{}'

# Or close it without changing any memory.
curl -X POST "https://api.mirabase.dev/v2/memory/proposals/$OTHER_PROPOSAL_ID/reject" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

TypeScript:

```ts
for await (const proposal of mirabase.memory.proposals.list({ dreamId: dream.id })) {
  console.log(proposal.kind, proposal.layer, proposal.plan, proposal.times);
  for (const { entry_id, version_id, quote } of proposal.evidence ?? []) {
    // Read the exact version the quote came from, and show both to the person deciding.
    const source = await mirabase.entries.content(entry_id, { view: "text", version: version_id });
    console.log(quote, source.text?.includes(quote));
  }
}

// Once a person has decided.
await mirabase.memory.proposals.approve(proposalId);
await mirabase.memory.proposals.reject(otherProposalId);
```

Python:

```python
proposals = mb.memory.proposals.list(dream_id=dream["id"]).to_list()
for proposal in proposals:
    print(proposal["kind"], proposal.get("layer"), proposal.get("plan"), proposal.get("times"))
    for evidence in proposal.get("evidence", []):
        # Read the exact version the quote came from, and show both to the person deciding.
        source = mb.entries.content(evidence["entry_id"], view="text", version=evidence["version_id"])
        print(evidence["quote"], evidence["quote"] in source.get("text", ""))

# Once a person has decided: proposal_id is the one approved, other_proposal_id the one rejected.
mb.memory.proposals.approve(proposal_id)
mb.memory.proposals.reject(other_proposal_id)
```

### Approve and reject

[`POST /v2/memory/proposals/{proposal_id}/approve`](https://mirabase.io/developers/api/memory-dreaming.md#memoryproposals-approve) carries out a `merge` or `supersede`: the memories in `plan.close` are closed and `plan.keep` stays, its text unchanged. [`POST /v2/memory/proposals/{proposal_id}/reject`](https://mirabase.io/developers/api/memory-dreaming.md#memoryproposals-reject) closes the proposal without changing any memory.

- A `conflict` or `promote` cannot be approved. Settle a conflict by [correcting or forgetting](https://mirabase.io/developers/memory.md#govern) one side, or reject it.
- To undo an approval, [undo the dream](https://mirabase.io/developers/memory.md#dreams). Undo covers the whole dream, not one proposal.

### Find proposals from a memory

On deployments with offline consolidation, [`GET /v2/memories`](https://mirabase.io/developers/api/memories.md#memories-list) and [`GET /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-read) carry `pending_proposals` when there are open proposals: the ids of those about this memory (or a member of its group), oldest first, limited to proposals you can see, and absent when there are none. It is all you need to flag a memory as awaiting a decision in your interface.

curl:

```bash
# pending_proposals is present only when there are open proposals you can see.
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

curl "https://api.mirabase.dev/v2/memory/proposals/$PROPOSAL_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

TypeScript:

```ts
const memory = await mirabase.memories.get("distill:ent_7f20:fact_31");

for (const id of memory.pending_proposals ?? []) {
  const proposal = await mirabase.memory.proposals.get(id);
  console.log(proposal.kind, proposal.plan, proposal.evidence);
}
```

Python:

```python
memory = mb.memories.get("distill:ent_7f20:fact_31")

for pending_id in memory.get("pending_proposals", []):
    proposal = mb.memory.proposals.get(pending_id)
    print(proposal["kind"], proposal.get("plan"), proposal.get("evidence"))
```

## The MEMORY.md index and RECENT.md

On deployments with offline consolidation, `MEMORY.md` is an index: sections for rules and preferences, decisions and progress, and facts, one memory per line ending in a reference such as `[m1]`, and a `References` table at the end that maps each reference to a memory id. It holds what people wrote (account memories and memories written as Entries) and distilled memories a person confirmed, none of which ever goes dormant, and memories that say the same sentence appear once.

```markdown
# Memory

## Rules and preferences

- Keep answers short and in English. [m1]

## Decisions and progress

- Releases go out on Thursdays. [m2]

## Facts

- The staging database runs PostgreSQL 16. [m3]

## References

[m1]: mem_5d02
[m2]: ent_9a41
[m3]: distill:ent_7f20:fact_31
```

- The whole file is at most 2,000 tokens, of which distilled memories take at most 800. Nothing is cut mid-sentence: what does not fit is left out whole and counted on a last line, `… N more: GET /v2/memories?space_id=...`.
- There are no dates or times, and the order changes only with the content: what people wrote first, then distilled memories a person confirmed, ordered by how recent they are and id, never by how often they were served. So a search hit does not change the `ETag`, which starts with `mf2.`, and the file still suits a prompt cache prefix.

`/.mirabase/memory/RECENT.md` is the second generated file: project and Agent memories written in this Space in the last 7 days, candidates included, newest first, at most 50 of them and 1,000 tokens. Each line names its kind and status, references look like `[r1]`, and the `ETag` starts with `rf1.`. Account memories and dormant ones are not in it. It is read and protected like `MEMORY.md`.

```markdown
# Recent memory

- (decision, confirmed) Releases go out on Thursdays. [r1]
- (preference, candidate) Use metric units in reports. [r2]

## References

[r1]: ent_9a41
[r2]: distill:ent_7f20:fact_44
```

curl:

```bash
# The stable part: send back the ETag you have, 304 means nothing changed.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/.mirabase/memory/MEMORY.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H 'If-None-Match: "mf2.<sha256>"'

# The part that moves: what was written in the last 7 days.
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/files?path=/.mirabase/memory/RECENT.md" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

TypeScript:

```ts
const index = await mirabase.files.read("/.mirabase/memory/MEMORY.md");
const recent = await mirabase.files.read("/.mirabase/memory/RECENT.md");

// MEMORY.md first, as the cached prefix; RECENT.md later, where the prompt changes anyway.
const prompt = [index.text(), recent.text()].join("\n");
```

Python:

```python
index = mb.files.read("/.mirabase/memory/MEMORY.md")
recent = mb.files.read("/.mirabase/memory/RECENT.md")

# MEMORY.md first, as the cached prefix; RECENT.md later, where the prompt changes anyway.
prompt = index.text() + "\n" + recent.text()

# Later, send back the ETag you have: None means nothing changed.
newer = mb.files.read_if_changed("/.mirabase/memory/MEMORY.md", index.etag)
```

- Put `MEMORY.md` early in the prompt as the stable prefix, and `RECENT.md` later, where the prompt changes anyway.
- Both files show only memories you can see, so two callers can get different bytes and `ETag`s.

## Read a memory by id

The index holds one sentence and an id. For the details, call [`GET /v2/memories/{memory_id}`](https://mirabase.io/developers/api/memories.md#memories-read) with an id from `References`; for its source versions and quotes, call [`GET /v2/memories/{memory_id}/provenance`](https://mirabase.io/developers/api/memories.md#memories-provenance).

curl:

```bash
# An id from the References table.
export MEMORY_ID="distill:ent_7f20:fact_31"
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

# The versions and quotes it rests on.
curl "https://api.mirabase.dev/v2/memories/$MEMORY_ID/provenance" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

TypeScript:

```ts
const memory = await mirabase.memories.get("distill:ent_7f20:fact_31");
// memory.group_id and memory.sources when other memories say the same; memory.dormant when a dream set it aside.

const provenance = await mirabase.memories.provenance(memory.id);
```

Python:

```python
# An id from the References table.
memory = mb.memories.get("distill:ent_7f20:fact_31")
# memory["group_id"] and memory["sources"] when other memories say the same; memory["dormant"] when a dream set it aside.

# The versions and quotes it rests on.
provenance = mb.memories.provenance(memory["id"])
```

An Agent working over MCP uses the tool `mira.memory.get`: give it `memory_id` and by default it returns `{memory, provenance}`; with `include_provenance: false` it returns the memory alone. It is in the tool list only on deployments with offline consolidation.

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "mira.memory.get",
    "arguments": {
      "memory_id": "distill:ent_7f20:fact_31"
    }
  }
}
```

On deployments with offline consolidation, distilled memories that say the same sentence are listed as one group, with `group_id` and `sources`; forget, correct, and review still take a single id.

## Next steps

- [Retrieval and context](https://mirabase.io/developers/retrieval.md): how memory reaches context and answers.
- [Connect an Agent](https://mirabase.io/developers/agents.md): an Agent reads and writes memory with MCP tools.
- [Permissions](https://mirabase.io/developers/permissions.md): who may confirm, correct, and forget memories.
