/memory

name: memory
description: Use before the first memory verb — read or write — whenever the orchestrator is about to touch memory as this turn's subject, or the user voices a doubt, an idea or a pending, in passing or on purpose, or asks to save, remember or hand something on, or a `~ user memory changed:` or `~ project memory changed:` block arrives beside a prompt: deciding what persists and where it goes, searching, curating, or triaging what a session injected at start.

Memory

Memory is the curation technique that turns selected experience into continuity: durable knowledge kept small, live work kept visible, and raw operational history left on the automatic event floors where it belongs. Every curated row is one claim of a closed kind, held by one owner, and Gaia delivers it to the readers that kind and owner reach.

What memory is for

Gaia's harness -- its identity, skills, hooks, CLI and the Environment every session is born with -- is what Gaia does for anyone. Memory holds only the difference this user, one of his workspaces, groups or projects makes to it. That one idea decides both whether something is kept and how it is written:

• **What Gaia already knows is no difference.** Kept again, it is a second

source that goes stale.

• **What would hold for any user is no difference either.** It is a missing

standard or a defect, fixed in the harness and never patched into his rows.

• **A difference lives only where the harness leaves a choice.** A default

bends to him once he has agreed to the bend. A wall never does -- consent, security, the contract every agent closes -- because a wall memory could move would not be a wall. Signing every PR as JLA is a difference; accepting every destroy is nothing memory can hold.

• **Whose difference it is decides its owner,** so he never has to name one.
• **A row carries the difference alone,** never the context Gaia already has,

which is what keeps it short.

• **A decision goes to its home when it is made;** the conversation is only a

cache of it (When to save, below).

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.

Every row answers three questions

**What it claims -- its kind.** `--kind` is required on every `gaia memory add`, and the list is closed; a missing or unknown kind is refused with the list.

| Kind | What it claims | |---|---| | `fact` | something true; it commands nothing | | `preference` | a rule every output on a surface obeys; its title is the rule | | `decision` | one choice among alternatives, with its why | | `lesson` | something learned, or a dead end | | `pending` | work owed | | `defect` | Gaia failing in use; a bug in a product is that project's `pending` | | `tool` | a program built for the user; its title says how to use it |

**Whose it is -- its owner.** Five owners, each holding only some kinds. The scope flags place the row; a kind its owner cannot hold is refused, and the refusal names the right home.

| Owner | Kinds it holds | Placed by | |---|---|---| | user | fact, preference, tool | `--type=user`, no scope flag | | workspace | fact, preference, decision | `--workspace=<ws>` alone | | group | fact, preference, decision, lesson, pending | `--initiative=<group key> --workspace=<ws>` | | project | fact, preference, decision, lesson, pending | `--project=<name> --workspace=<ws>` | | gaia | lesson, defect | `--initiative=gaia_system --workspace=<ws>` |

**Which role it plays -- its class.** An `anchor` is durable and reaches its readers; a `thread` is one live concern that must reappear until it is closed; a `log` is kept for audit and never reinjected.

Both tables are what `gaia map memory` and `gaia memory add --help` print, and both render from `gaia/store/memory_placement.py::KINDS_BY_OWNER` and `gaia/store/memory_placement.py::KIND_MEANING`; where this page and the CLI differ, the CLI is right and this page is the drift. `--type` is still the CLI's row family, which a curated slug's prefix must match (`atom_`, `decision_`, `negative_`); the kind is what a reader decides on.

For Gaia itself, choose from how the fact was produced, not from the current directory: Gaia observed failing or rubbing in use belongs to owner gaia, a `defect` or a `lesson` under `--initiative=gaia_system`, host-scoped by `gaia/store/writer.py::apply_host_scope` (a project anchor is refused); a decision to build or change Gaia belongs to the project `gaia`.

**When owners disagree, the most specific wins:** Gaia < user < workspace < group < project (`gaia/store/memory_placement.py::PRECEDENCE`). A project receives its group's and its workspace's rows. Consent, security and the contract every agent closes never move, whatever a row says.

Who reads what

Gaia delivers by kind and owner; no row is marked for a reader.

| Where | Who reads it | What it carries | |---|---|---| | `## User memory`, at birth | the orchestrator only | the user's live facts and preferences, grouped by kind, conversation preferences first, each line its title, `surface=` and `until=` when it has them, and `ref=memory:user/<slug>` | | `~ Your conversation preferences:`, beside every prompt | the orchestrator only | the titles of the first four conversation preferences in full, within 660 characters; past four rows, the count of the rest with their coordinates | | `## Environment`, at birth and in every kernel | everyone | one `tool=<binary>` line per user tool whose binary is on PATH, with `replaces=` and its ref; a kernel carries at most five | | `# Scope memory`, in a kernel | a dispatched agent | the preferences, facts and lessons of