Consolidation

Consolidation is the job that turns what agents write during the day into durable memory. It runs on a schedule you set, outside the agent, so the agent never waits for it.

It does three things:

1. Drains the queue. Moves queued writes and feedback into the store.
2. Extracts memories from notes (optional). Reads an agent’s dated notes and stores the facts, events and commitments in them.
3. Compiles the memory file. Rebuilds MEMORY.md, a ranked summary of the agent’s memory sized for its context window.

Why writes are queued

When an agent calls mm_remember, most memories go into a queue in its workspace (the .mm-journal/ directory) instead of straight into the store. The agent gets an answer at once and is never held up by the store. The writing agent can search its own queued memories immediately; everyone else sees them after the next drain. When memories become searchable has the details.

Commitments skip the queue: a promise is stored when the write returns, so it is never missing from the due list.

Feedback is queued the same way. mm_feedback answers QUEUED — not yet applied, and the change lands at the next drain.

Running it

The Quickstart schedules the drain nightly:

MM_BACKEND=file meaning-memory consolidate --agent-id support-bot --drain-only \
    --workspace /srv/support-bot-mm --config-dir /srv/support-bot-mm

consolidation: agent=support-bot facts_added=0 watermark=n/a dry_run=False drain_only=True promote_only=False

facts_added=0 is expected for a drain: the queued memories were already written by the agent, and the drain only moves them. The run:

• validates each queued write and sets aside any that fail, without losing the rest;
• adds the valid ones to the store and applies queued feedback, exactly once even if a run is repeated;
• archives what it processed under .mm-journal/archive/.

It exits 0 on success and 2 if the drain fails, in which case the queued writes stay where they are for the next run. Run it as often as you like. More often means shared memories reach other agents sooner; nightly is enough for most agents.

A drain runs no model, so it costs nothing per run.

Extracting memories from notes

Agents that keep dated notes in their workspace (files named like 2026-10-03.md) can have consolidation read them and store what they contain as separate memories: facts, decisions, events and commitments. This step uses a language model you choose, from OpenAI, Anthropic or a local model through Ollama, and it is the only part of Meaning Memory that calls a language model you supply. It also removes duplicates: an exact repeat is skipped, and a near-repeat raises the significance of the memory already stored instead of adding a second copy.

Extraction is optional. An agent that writes its memories with mm_remember gets everything on this page from the drain alone.

Note

The scheduled full run that meaning-memory init sets up does not yet perform the drain. Schedule the --drain-only command above for now.

The compiled memory file

MEMORY.md is the agent’s memory at a glance, written to its workspace. Load it into the agent’s context at the start of a session, and the agent starts with what matters instead of nothing. After a drain it looks like this:

## Capabilities

- ————— To issue a refund, run scripts/refund.sh with the order id; amounts over 500 EUR need a second approver. `mem_id: 2b47366a861a87ca`

## Core Facts

- ●○——— Zephyr Logistics renews its support contract every March; the renewal decides next year's budget. `mem_id: 83f33219d7033862`

## Key Episodes

- ————— Dana from Zephyr Logistics escalated ticket 4411 on the call today; we agreed a workaround. `mem_id: 1e66c92f07e2d62d`

Each line ends with the memory’s id, so the agent can act on it with any tool. The marks at the start show its STARE scores.

Sections. Procedures come first, under Capabilities. The other memories are grouped by category: Core Facts, Key Decisions, Key Episodes and one section for each further category you use. Memories that are archived, superseded or only discussed are left out. With MM_COMMITMENT_COMPILE=true set on the consolidation command, open commitments also get their own Commitments (due / overdue) section near the top, in the same format as mm_due_commitments.

Budget. The file has a size limit, so it fits the agent’s context window. meaning-memory init --budget-preset sets it: lean (12,000 characters), balanced (25,000, the default), rich (40,000) or max-context (60,000). When the memories do not fit, the least significant go first. Three kinds are protected and go only if they alone overflow the budget: procedures, pinned memories, and memories with significance 0.90 or above.

When it is rebuilt. A drain rebuilds the file when it brought in something that matters: a memory with significance 0.70 or above, a pinned memory, or a deadline or commitment. Rebuilds are at most one a minute. Set MM_AUTO_REFRESH_DISABLED=1 to turn this off.

The file is generated. Do not edit it by hand; change the memory instead, with mm_remember or mm_feedback, and the next rebuild reflects it.

What consolidation does not do

• It does not age memories in the store. Significance changes only through feedback and duplicate detection. Age affects search ranking, not the stored value; see STARE.
• It does not delete anything. Superseded and archived memories stay in the store with their history; see Provenance.
• It does not cross workspaces. Each agent’s consolidation handles that agent’s queue.