memory git:20260813.d947a3aA

Immutable. This exact content is served forever at /api/v1/blob/5bb23419b7e0a4f4.

---
name: memory
description: Use when reading, searching, saving, or curating Gaia memory, deciding whether a session finding should persist, or triaging injected memory at session start
---

# Memory

Memory is the curation technique that turns selected experience into useful
continuity. It keeps durable knowledge small, keeps live work visible, and
leaves raw operational history on the automatic event floors where it belongs.

## The three floors

| Floor | Purpose | Lifecycle |
|---|---|---|
| Events | Commands, dispatches, session events, and other operational facts | Automatic and short-lived |
| Episodes | Searchable agent-turn outcomes and anomalies | Automatic, retained for diagnosis |
| Curated memory | User-governed knowledge and work that must affect future decisions | Deliberate and long-lived |

Events and episodes are evidence, not durable truth. Promote from them only
when a future decision would change and the information has no better home.
The table names, retention, and query mechanics live in `reference.md`.

## Think in roles, not storage vocabulary

Every curated item serves one human-facing role:

- **Durable knowledge**: stable facts, accepted decisions, useful dead ends,
  user preferences, and meaningful project milestones.
- **Live thread**: one actionable concern that must reappear in a later session.
- **Historical log**: append-only context useful for audit but not reinjection.

The internal `class`, `status`, `type`, slug, and link enums implement these
roles. Consult `reference.md` only when materializing or debugging them.

## Other home first

Before saving, ask: **does this already have a canonical home?**

- Work in flight belongs in a brief, plan, or task.
- Domain state belongs in project context or the owning system.
- Raw execution detail belongs in events, episodes, or the transcript.
- Curated memory holds only cross-cutting knowledge, closed decisions and dead
  ends, meaningful milestones, and homeless work that must survive the session.

Do not copy a fact into memory merely because it matters. A second source of
truth becomes stale; a durable reference to the canonical object is enough.

## Process

1. **Read the injected memory, then sweep what you are about to touch.** The
   digest and anchors in context are a worklist under a SessionStart budget, not
   the corpus. Before writing into an initiative — or whenever the question is
   what it still owes — read its whole live-pending set with
   `gaia memory get-relevant --initiative=<key>`, uncapped and with bodies. A
   reader who only sees the digest can add rows and never retire one.
2. **Search before writing; do not read silence as absence.** Find the existing
   owner of the topic and its lineage — a duplicate divides relevance instead of
   strengthening knowledge. An empty result answers "no row matches this
   phrasing", never "this initiative owes nothing": a pending is worded in the
   terms of the problem as it looked when it opened, not in the terms of the
   thing that just resolved it, so step 1's sweep is what finds it.
3. **Choose the home.** Prefer brief, plan, task, project context, event, or
   episode when one owns the fact. Continue only for genuinely curated value.
4. **Adjudicate the change.** The orchestrator chooses scope, create/append/
   correct/transition/link, role, lifecycle, initiative, and verification.
   Preserve lineage when knowledge replaces or graduates from earlier work.
5. **Show exact values and obtain consent.** The user may correct the proposed
   values before durable persistence. A request such as “reflexionemos y
   guardemos” authorizes writing only after the proposal has been shown.
   `checkpoint` is one atomic operation and remains all-or-nothing.
6. **Verify the durable result.** Read back the affected rows, lifecycle, scope,
   and links. Report partial batch failures per operation.

## Reading a row leaves a trace

Two counters bump as a side effect of being read; two questions classify any
surface, including one not built yet — who asked, and did the answer carry the
BODY? **Injection**: an automatic block rendered it for someone who did not ask
(digest, sections, kernel); rows trimmed out of the block do not count.
**Deliberate**: someone asked and got the body (`show`, `query --json`,
`--initiative` in JSON). **Neither**: a projection stood in (`search`, `list`,
`show --links`, `--initiative` in text). Never rank them together: a blended
number lets injection read as demand, and selection ignores both anyway.

## When curated memory earns attention

- **Decision:** it was accepted, is not already captured canonically, and will
  constrain a future choice.
- **Project milestone:** it closes a meaningful arc. A routine session close is
  not a milestone and does not automatically create a checkpoint.
- **Live handoff:** one unresolved concern has no structured work object and
  must resurface. Keep one concern per thread.
- **Learning or dead end:** it prevents repeated investigation or error.
- **Gaia improvement:** a concrete symptom, component, evidence, and
  reproduction deserves visible follow-up. After consent, persist it as a
  `feedback` live thread in initiative `gaia_system`, carried forward until
  closed or graduated.

## When curated memory loses it

Attention is finite and a live thread spends it every session. Two exits, and
neither is deletion:

- **Closed** — the concern was resolved or stopped being relevant.
  `reclassify --status=closed` retires it from the worklist and keeps the row.
- **Graduated** — the work finished and left knowledge worth holding.
  `reclassify --status=graduated`, or `--class=anchor` when future dispatches
  should carry the knowledge; `link --kind=graduated_to` preserves the lineage
  from the thread to the anchor it became.

Both verbs are non-mutative, so cost is never the reason a thread stays open.
Whoever observes the resolution owns the exit: a session that resolves a thread
and does not close it has moved that thread's cost onto every session after it.

## Ownership

- The **user** is the authority for durable personal and project knowledge.
- The **orchestrator** resolves ownership, searches, adjudicates, presents the
  proposal, and verifies it.
- Other specialists only propose (`memory_delta`, `memorialize_suggestions`);
  they never write curated memory directly.
- The runtime enforces the writer boundary and core data invariants. The skill
  supplies curation judgment; it does not duplicate enforcement details.

## Handoffs

- `session-reflection` recovers decisions, live work, learnings, Gaia
  improvements, and the closures its sweep found, then produces the curation
  proposal consumed here.
- `gaia-compact` runs after durable persistence and carries only transient
  continuity plus references to what was saved.
- `reference.md` contains exact CLI forms, enums, scope rules, retrieval,
  checkpoint payloads, history coverage, and graph mechanics.
- `examples.md` contains worked create/update/batch/checkpoint cases.

## Anti-patterns

- **Writing without knowing what the initiative owes:** an empty search means
  no row matched your phrasing, not that nothing is pending; the write adds a
  parallel note and leaves open the pending it duplicates, unseen.
- **Copying what already has a home:** briefs, plans, tasks, project state,
  events, and episodes already retain it; a copy is a stale rival source.
- **Treating every close as a milestone:** turns long-term memory into session
  summaries and consumes retrieval attention.
- **Bundling live work:** one status cannot honestly represent several
  independent concerns; use one thread per concern.
- **Claiming perfect history:** ordinary updates are audited, but hard deletion
  and workspace removal can destroy records. Exact tracked fields are defined
  by the current schema and migration, not by prose.