# Cross-session memory



Cluster Build stores local, inspectable Markdown memory below
`~/.cluster/memories/`. A persisted session is summarized asynchronously after
its foreground turn completes; the extracted candidates become available on
the next request, and later consolidation deduplicates and organizes them into
a curated file. Sessions can also fetch detail on demand with the
`memory_search` and `memory_get` tools.

Two independent controls govern the feature:

* **Use memories** — inject a bounded overview of curated and recent memory
  into new requests, and allow the read-only memory tools.
* **Learn from sessions** — automatically extract candidates from completed
  turns and consolidate them into curated memory.

## Slash commands [#slash-commands]

* **`/remember [global|project] <text>`** writes an immediately available
  pinned memory after confirmation. Project is the default inside a resolved
  project; global is the fallback.
* **`/forget <query>`** searches memory, then requires selecting and
  confirming an exact entry before removing it. Deleting an entry also removes
  matching unconsolidated candidates, so a later consolidation can't
  reintroduce it.
* **`/memory`** opens a bottom dialog with **Global**, **Project**, **Recent**,
  and **Status** views:
  * Toggle **Use memories** and **Learn from sessions** from the Status view.
  * `c` copies the current file's path to your clipboard.
  * `Ctrl-O` opens the current file in `$VISUAL`/`$EDITOR` — the curated file
    in the Global/Project views, or the selected candidate file in Recent. The
    terminal is restored and the dialog's contents refresh when the editor
    exits.
  * Reset a scope from its view after a destructive-action confirmation; this
    clears curated content and pending candidates for that scope.
* **`/status`** reports effective controls, resolved project storage, queued
  extraction work, pending candidates, and the last consolidation.

Natural-language remember/forget requests use the same underlying tools as the
slash commands. Model-initiated writes only happen when your current request
explicitly asks to remember, update, or forget something — ordinary
conversation never becomes an implicit memory write.

## Configuration [#configuration]

```sh
cluster config set memory_use false
cluster config set memory_generate false
```

* `memory_use` controls overview injection and the read-only memory tools.
* `memory_generate` controls automatic extraction and consolidation. Explicit
  `/remember` still works when this is off.
* `--no-memory` is a stronger per-process override: it disables reads,
  automatic generation, and explicit writes for that run without changing
  saved configuration. It's a global flag, so it also applies to `cluster exec`.
* `cluster exec --ephemeral` may read existing memory (unless `--no-memory` is
  also passed) but never generates or updates memory.

## Storage [#storage]

`~/.cluster/memories/MEMORY.md` holds global memory; project memory lives
under `~/.cluster/memories/projects/<slug>-<hash>/MEMORY.md`, keyed to the
Git common directory (or the cwd outside Git) so linked worktrees share one
scope. Each curated file has two sections:

```markdown
# Memory

## Pinned

Explicit user memories. Automatic consolidation never rewrites this section.

## Learned

Automatically consolidated knowledge. The consolidator owns this section.
```

Direct edits to `MEMORY.md` are supported — keep the `## Pinned` and
`## Learned` boundaries intact, since malformed boundaries stay readable but
block automatic rewrites until repaired. Files are private to your OS user
(directories `0700`, files `0600`) and are shared across every Cluster
account that user signs into.

`cluster doctor --summary` reports the persistent controls and on-disk memory
health without printing memory bodies or search queries.

## Model tools [#model-tools]

The assistant can read memory in any mode, but writing requires an explicit
user request:

| Tool            | Access                       | What it does                                            |
| --------------- | ---------------------------- | ------------------------------------------------------- |
| `memory_search` | read-only, plan mode allowed | Search curated and raw memory                           |
| `memory_get`    | read-only, plan mode allowed | Fetch a memory file by path and line range              |
| `memory_add`    | mutating                     | Append to `Pinned` in a scope                           |
| `memory_delete` | mutating                     | Remove an exact entry previously returned by search/get |

`memory_add` and `memory_delete` are rejected in [plan mode](/docs/build/interactive#plan-mode),
the same as any other mutating tool.

## Next steps [#next-steps]

* **[Interactive sessions](/docs/build/interactive)** — the full slash-command
  reference and keybindings.
* **[Config basics](/docs/build/config/basic)** — the rest of
  `config.toml`.