Memory
MarkdownWrite, 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), and the status says whether retrieval uses it (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. 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 -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."}'Distill memories from a conversation
To propose rather than state, ingest a conversation: POST /v2/spaces/{space_id}/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 -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."}
]}'Distillation runs after indexing, so the processing job can be succeeded before any memory exists. Poll GET /v2/entries/{entry_id}/processing until memory.state is no longer pending: at ready, GET /v2/memories?entry_id= lists what the batch wrote; skipped means this version is not distilled, for the reasons below; failed means distillation failed.
# 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"- Ingesting the same batch twice makes two Entries, so send
Idempotency-Keywhen retrying; see Idempotency. - To record a conversation as it goes, send each batch with the same
session_id. Thesession_idis also stored as the metadata keysession_id, soGET /v2/entries?metadata={"session_id":"…"}lists them together andfilter.metadatain search narrows to that conversation. - When an Agent in
proposalmode ingests a conversation, distilled facts are alwayscandidate.
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. 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 and remediation.
Review, correct, and forget memories
# 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. - When a memory is wrong, write the right statement with
POST /v2/memories/{memory_id}/correct: the old memory is closed and kept as history. You can undo a new memory or correction within 30 minutes withPOST /v2/memories/{memory_id}/undo. DELETE /v2/memories/{memory_id}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}/provenancelists the Entry versions a memory rests on, with the quoted words.- To keep a source from producing memories, set
memory_exclude: truewithPATCH /v2/entries/{entry_id}: the facts distilled from it are retired, and search and reading are unaffected. Setting it back tofalsedistills 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; 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 or retrieval for those. Deployments with offline consolidation switch to an index layout and add RECENT.md; see the index layout.
# 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.
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
d4on, it asks a model whether pairs of distilled memories repeat, supersede, or contradict each other. The conclusions only ever become 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.mdandRECENT.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
automode yet. - It leaves alone what a person decided: approved candidates and memories distilled from a conversation ingested with
memory:confirmare 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 havestatus: "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; how long a memory stays unused before it goes dormant is in 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.
- Waking up takes no call of its own: reading it with
GET /v2/memories/{memory_id}, or having a search, context pack, or answer hand it back, wakes it up. ReadingMEMORY.md,RECENT.md, or the list does not count. - Switching from
applyback toreportleaves 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 for a person to decide. Only the Space owner can change the settings.
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"}'- Read a report before switching
dormancytoapply. - Run
shadowfor a while and read the judgments before switching topropose: recorded judgments become proposals without asking the model again. - When
d4_availablein the response is false, this deployment asks no model, whateverd4says.
Start, inspect, and undo a dream
POST /v2/spaces/{space_id}/memory/dreams starts a dream now and returns 202; job_id is the dream id, followed with GET /v2/jobs/{job_id}. GET /v2/memory/dreams/{dream_id} is its report, GET /v2/memory/dreams/{dream_id}/actions lists each change and its reason, and GET /v2/memory/dreams/{dream_id}/judgments lists every pair a model compared. POST /v2/memory/dreams/{dream_id}/undo undoes the whole dream. A scope runs one dream at a time.
# 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 '{}'- 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 inconflict_skipped. - Reports and actions count only memories whose source you can see, and an
agentdream 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. Its kinds are in DevMemoryProposalKind and its statuses in DevMemoryProposalStatus. You see it only when you can see the source of every member.
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.
# 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 '{}'Approve and reject
POST /v2/memory/proposals/{proposal_id}/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 closes the proposal without changing any memory.
- A
conflictorpromotecannot be approved. Settle a conflict by correcting or forgetting one side, or reject it. - To undo an approval, undo the dream. Undo covers the whole dream, not one proposal.
Find proposals from a memory
On deployments with offline consolidation, GET /v2/memories and GET /v2/memories/{memory_id} 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.
# 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"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.
# 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 withmf2., 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.
# 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
# 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"- Put
MEMORY.mdearly in the prompt as the stable prefix, andRECENT.mdlater, where the prompt changes anyway. - Both files show only memories you can see, so two callers can get different bytes and
ETags.
Read a memory by id
The index holds one sentence and an id. For the details, call GET /v2/memories/{memory_id} with an id from References; for its source versions and quotes, call GET /v2/memories/{memory_id}/provenance.
# 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"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.
{
"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: how memory reaches context and answers.
- Connect an Agent: an Agent reads and writes memory with MCP tools.
- Permissions: who may confirm, correct, and forget memories.
