Memory: facts agents recall across sessions

atrium keeps a per-project memory: durable facts an agent wrote down once and can recall in any later session, without you re-explaining. It is a searchable store on disk, not a hidden vector database, and it works from a bare terminal as readily as from inside an agent pane.

Facts and episodes

A fact is one terse, durable statement with a kind:

Kind	For
decision	A choice that was made and should stick
gotcha	A trap that cost time once and shouldn't twice
preference	How you want things done
entity	A thing worth naming — a service, a person, a convention

An episode is a committed record of a work session, distilled from the timeline. Facts are what agents recall; episodes are the raw material they're distilled from.

Facts carry a scope: project-wide by default, global to follow you everywhere, or agent:<slug> to stay private to one agent definition.

Recall

Search is FTS-ranked, and an empty query lists the most recent facts.

atrium memory search 'libgit2 perf'
atrium memory search 'auth' --kind decision --limit 5
atrium memory search '' --agent quinn --json
atrium memory show <id> --level l0
atrium memory show <id> --no-feedback # inspect without training the relevance loop

Agents don't usually run these by hand. At session start atrium injects a bundle of pointers — a one-line preview of each relevant fact plus the exact command to expand it — so the agent spends context only on what it actually opens. Each pointer carries the fact's age, so an agent can weigh a six-month-old note against the live code. In an agent chat pane, these calls render as readable memory cards rather than raw tool output.

Expanding a pointer with memory show is itself a signal: it records that the injected pointer earned its place. atrium memory feedback summarizes that loop — expansion rate per source class, per hook event, and per relevance band — which is how the injection is tuned.

Writing

atrium memory add --kind gotcha 'sed -i needs an arg on macOS'
atrium memory add --kind preference --scope agent:quinn 'prefers pnpm'
atrium memory supersede <id> 'the corrected fact text'
atrium memory reindex        # disk is truth; rebuild the index from the fact files

Superseding closes the predecessor and writes a successor in the same scope and kind, so the history stays intact rather than being overwritten.

Consolidation

atrium memory consolidate

Consolidation ("dreaming") distills accumulated episodes into durable facts. It runs as a visible, cancellable agent task on your own subscription — never as a hidden daemon burning tokens you didn't ask for. A single-run guard keeps concurrent consolidations from piling up.

When you opt into Memory, dreaming gets a daily 3:00 AM schedule in your device's timezone, with a 250,000-token soft target per run. Near that target, the agent is asked to finish its current item, save its report, and wrap up. It may go over the target to finish cleanly; Settings shows actual usage and any overage. Settings also shows whether automatic dreaming is ready or awaiting activation verification. The durable Memory consolidation (dreaming) task is the control surface: you can pause its cadence or change its launch profile, adapter, model, effort, and other user-owned launch settings at any time.

Each operation covers an oldest-first window of at most seven days. A run processes one small chunk of at most two episodes, reports what it finished, and saves its place. Later runs resume from that checkpoint until the window is complete. An interrupted or unfinished chunk is retried without skipping evidence. Feedback is supplied as a bounded aggregate with explicit total/truncation metadata; rows created by dreaming itself are excluded. Historical dream feedback remains auditable with its original source class preserved, but no longer enters dream windows, product telemetry, or eval metrics. atrium recovers retained transcript evidence where possible. Temporarily unavailable evidence keeps the window retryable; confirmed unavailable sources remain auditable without being summarized from filenames or placeholders. The dream's own prompts and reads are excluded from episode capture and recall telemetry.

Dream panes do not receive credential-like environment variables from the app or launch profile. Adapter authentication should use the adapter's normal signed-in account rather than a secret environment variable. Token usage is recorded from native Claude Code and Codex transcripts when available; unsupported adapters report usage as unknown rather than estimating it.

Updates migrate the memory index in place. Existing facts and supported episodes are retained. Legacy summaries that explicitly say they have no prompt or transcript evidence are kept for audit but quarantined from recall; they are not deleted.

Self-improvement proposals

An agent can propose a change to its own definition — a diff against its agent.md or an attached skill, carried with the evidence that motivated it. Proposals are reviewable like a teammate's pull request.

atrium memory proposals list                  # pending first; filter by agent
atrium memory proposals show <id>             # evidence, diff, rationale
atrium memory proposals apply <id>            # an explicit human act
atrium memory proposals reject|defer <id>     # evidence is retained either way
atrium memory proposals revert <id>

atrium memory autonomy <agent>                # read the current level
atrium memory autonomy <agent> review|auto    # set it

Autonomy has two levels:

• review (the default) — every proposal queues for human review.
• auto — proposals that pass the guardrails self-apply under a 72-hour trial. Every one is announced, and every one is revertible in a click.

On disk

Facts are files; the index is derived. See Data directory for the layout, and --json on any of the above for a stable, camelCase shape suitable for scripting.