# Managing Memory

Anteroom stores durable **memories** — typed notes that outlive a single conversation — as a first-class artifact type. This page covers how to browse, create, edit, and delete memories from both the CLI and the web UI.

!!! note "Scope of this page"
    This page covers the read/write/delete management surface. The candidate-review workflow (proposing, approving, rejecting with a reason) is documented separately in [Memory Promotion & Review](memory-promotion.md).

## What a memory looks like

Every memory has:

- **FQN** — a fully-qualified name, e.g. `@user/memory/prefers-dark-mode`
- **Scope** — one of `user`, `project`, `local`
- **Category** — one of `preference`, `project_fact`, `decision`, `workflow_hint`
- **Status** — one of `active`, `candidate`, `pending_review`, `rejected`, `archived`
- **Content** — the text itself
- **Provenance** — optional `conversation_id`, `message_id`, `workflow_run_id`, or `source_artifact_id` pointers

The `memory_status` field is **displayed read-only** in the management surface. Transitions between `candidate` / `pending_review` / `active` / `rejected` are handled by the review workflow (see #920) and not by this management UI.

## Scopes

| Scope | Namespace | Visible in |
|---|---|---|
| `user` | `@user` | Every conversation, every project |
| `project` | `@{project_slug}` | Conversations inside the matching space |
| `local` | `@local` | The current local space only |

Reserved namespaces (`user`, `local`) cannot be reused as a `project_slug` — the service refuses the collision.

## CLI — `aroom memory`

```bash
aroom memory list                           # list all memories
aroom memory list --scope user --status active
aroom memory show @user/memory/dark-mode    # full detail
aroom memory create --content "prefers dark mode" --scope user --category preference
aroom memory create --content - --scope user --category decision < notes.txt
aroom memory edit @user/memory/dark-mode --content "updated"
aroom memory edit @user/memory/dark-mode --status archived
aroom memory delete @user/memory/dark-mode
```

### Filters on `list`

| Flag | Values |
|---|---|
| `--scope` | `user` · `project` · `local` |
| `--status` | `active` · `candidate` · `pending_review` · `rejected` · `archived` |
| `--category` | `preference` · `project_fact` · `decision` · `workflow_hint` |
| `--namespace` | any exact namespace, e.g. `myapp` |

## REPL slash command

Inside the `aroom` REPL, the same actions are available as `/memory`:

```
/memory                                   # list
/memory list --scope user
/memory show @user/memory/dark-mode
/memory create --content ... --scope user --category preference
/memory edit @user/memory/dark-mode --status archived
/memory delete @user/memory/dark-mode
```

The slash command accepts the same flag set as `aroom memory`.

## Web UI

The memory panel is available from the sidebar. It provides:

- A **list view** with filter dropdowns for scope / status / category and a free-text namespace filter.
- A **detail view** that shows content, metadata, provenance, and recall telemetry.
- An **edit form** for updating content.
- A **delete** action.

All user-supplied values are rendered via `textContent` — no HTML escaping bugs are possible on the panel.

## REST API

```
GET    /api/memory                          # list, with ?scope/?status/?category/?namespace
GET    /api/memory/{fqn}                    # detail
POST   /api/memory                          # create
PATCH  /api/memory/{fqn}                    # update content and/or allowed metadata fields
DELETE /api/memory/{fqn}                    # delete
```

See [API reference](../api/memory.md) for the request/response shapes.

## Concurrent edits

Anteroom writes last-writer-wins on the memory `content` field. If two clients edit the same memory, the later `PATCH` overwrites the earlier one. A version history is retained for content changes in the artifact-versions table.

## Retention & pinning

Memory retention is controlled by the `memory.retention` config block — it's **off by default** and opt-in per install. Pinning (`metadata.pinned == true`) is load-bearing: any pinned memory is skipped by the retention worker unless `respect_pins` is explicitly set to `false`.

Pin and unpin from any surface:

```bash
aroom memory pin @user/memory/my-note
aroom memory unpin @user/memory/my-note
```

```text
/memory pin @user/memory/my-note
/memory unpin @user/memory/my-note
```

The web memory panel's **Retention** tab shows the dry-run preview of memories that would be purged on the next cycle, and exposes a "Run purge now" button (guarded by a confirm modal). See [Data Retention](../security/data-retention.md) for the full policy surface, the `memory.purge` audit contract, and the preview-vs-governed-purge endpoint pattern.

## What this surface does **not** do

- It does **not** promote `candidate` memories to `active`. That's the job of the review workflow — see [Memory Promotion & Review](memory-promotion.md) (#920).
- It does **not** auto-save memories from running conversations. Agent-initiated memory creation is covered by #217 (saveMemory tool) and must go through the #920 review queue by default.

## Related

- [#919](https://github.com/troylar/anteroom/issues/919) — typed memory artifacts
- [#920](https://github.com/troylar/anteroom/issues/920) — promotion and review flows
- [#921](https://github.com/troylar/anteroom/issues/921) — runtime recall injection
- [#923](https://github.com/troylar/anteroom/issues/923) — runtime context attribution
- [#625](https://github.com/troylar/anteroom/issues/625) — retention and eviction
