08. Extending Matcha

Memory

Memory is a **local** store of notes and session metadata under ~/.matcha/memory/. You turn it on for a session, save a fact with /remember, browse the files with /memory, and clear them from the shell. Nothing here is a MatchaCode cloud memory service.

Turn memory on

Memory is **off** by default. Enable it in one of these ways (first match wins):

matcha --no-memory — always off
matcha --experimental-memory — on
MATCHA_MEMORY=1 or 0
[memory] enabled = true in ~/.matcha/config.toml
Default: off

Mid-session toggle

/memory on
/memory off

Alias: /mem. The toggle is **session-scoped**. It does not rewrite config.toml. Off removes the memory tools for this session and leaves files on disk. On re-initializes local storage and registers the tools again.

/memory with no argument opens the browser (needs a configured memory destination, even if you currently have it toggled off). In that modal, t is the same on/off toggle.

Save a note: `/remember`

/remember is always in the slash menu.

/remember always open PR links after pushing

With no text, Matcha CLI enters remember mode (the prompt shows a remember accent). The next line you type becomes the note.

A review panel opens. Confirm to write. On save you should see something like Memory saved to ~/.matcha/memory/MEMORY.md. Project-specific notes go in the workspace MEMORY.md; cross-project preferences go in the global file.

You can also say “remember …” in ordinary chat. The durable copy is still the Markdown file. For a guaranteed delete, edit the file yourself (or use matcha memory clear). Asking the assistant to “forget …” is best-effort.

What is on disk

Path	Scope
`~/.matcha/memory/MEMORY.md`	Global
`~/.matcha/memory/<project-slug>-<hash8>/MEMORY.md`	This workspace
`…/sessions/`	Per-session metadata logs

Clones and worktrees that share the same git origin (org/repo) share one workspace directory. Otherwise the hash is from the directory path.

When a session ends, Matcha CLI may append a **metadata** summary (message counts, a few topics, UTC time) **without** an LLM call. Trivial sessions are skipped. That is local bookkeeping, not /flush.

A file watcher reindexes edits you make in an editor. The preview in /memory is read-only; edit the path you copy with y.

Browse: `/memory`

/memory

Split view: file list (Global / Workspace / Sessions) and a preview. Narrow terminals hide the preview.

Key	Action
`↑`/`↓` or `j`/`k`	Move
`/`	Filter
`y`	Copy the selected path
`x` twice	Delete a session file only
`t`	Toggle memory on or off
`Esc`	Close

Clear from the shell

matcha memory clear
matcha memory clear --workspace
matcha memory clear --global
matcha memory clear --all
matcha memory clear --yes

Default scope is workspace (MEMORY.md, sessions/, and the local index). --yes skips the confirmation prompt.

What is not available

Surface	Why it is out
`/flush`	LLM session summary — not a supported procedure
`/dream`	LLM consolidation — not a supported procedure
Auto-dream / embedding config	Same inference family
Vector “semantic” search setup	Needs embedding inference

To keep a fact, use /remember (or edit MEMORY.md). To drop a store, use matcha memory clear or delete the file.

What you should see

You ran	Result
`matcha --experimental-memory` then `/memory on`	“Memory enabled for this session.”
`/remember always use conventional commits` then confirm	`Memory saved to ~/.matcha/memory/…`
`/memory`	File list + preview
`/flush` or `/dream`	Not a supported procedure