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

• /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

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

~/.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:

# 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

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

memory_add and memory_delete are rejected in plan mode, the same as any other mutating tool.

Next steps

• Interactive sessions — the full slash-command reference and keybindings.
• Models & configuration — the rest of config.toml.