Memory

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

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.

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.