How to keep sessions and resume them

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101

# How to keep sessions and resume them

This guide shows how to make `mm` save every conversation of a project and get one back later, in the terminal and from an editor. It assumes `mm` runs with a configuration file you can edit.

## Steps

1. Turn the feature on in the YAML file:

   ```yaml
   sessions:
     enabled: true
     dir: .mm/sessions
   ```

   `dir` is relative to the project: the directory you start `mm` from in the terminal, the project the editor opened in ACP mode. Add `.mm/` to the project's `.gitignore`: a session file holds every command output the model read.

2. Start `mm` from the project directory. The banner now ends with a `sessions:` line:

   ```text
   sessions: saved under /work/project/.mm/sessions · 2 earlier — /resume to continue the latest, /sessions to list
   ```

   This run is a new session. Its file appears with the first question and is rewritten after every turn, after `/compact` and after `/new`.

3. List the project's sessions when you need one back:

   ```text
   > /sessions
   3 session(s) in /work/project/.mm/sessions — /resume <id> to continue one, /resume for the latest
   * 20260916-101530-4f2a9c1e  2026-09-16 10:15  2 turn(s)  add a /new command
     20260916-093012-77be01d3  2026-09-16 09:41  5 turn(s)  fix the skills loader
     20260915-181200-0a1b2c3d  2026-09-15 18:20  1 turn(s)  list the files
   ```

   The `*` marks the current session. Ids sort by creation time.

4. Continue one:

   ```text
   > /resume
   ↩️ resumed 20260916-093012-77be01d3 — 14 message(s), started with "fix the skills loader"
   ```

   A bare `/resume` takes the most recently updated conversation other than the current one, skipping empty ones; `/resume <id>` names one. From there, the model sees the resumed history — under the current system prompt — and every new turn is saved to that session's file. Nothing is replayed on screen: the one line says what came back.

## Find out why a run failed

1. Spot the session in the listing: a session that showed at least one error ends its line with ` · ⚠️ N error(s)`. The same tail appears in the `↩️ resumed …` report.

   ```text
   > /sessions
   2 session(s) in /work/project/.mm/sessions — /resume <id> to continue one, /resume for the latest
   * 20260918-141321-db582a3d  2026-09-18 16:13  1 turn(s)  say just: ok
     20260918-141225-02790c82  2026-09-18 16:12  0 turn(s)   · ⚠️ 1 error(s)
   ```

2. Read the `errors` array of its file. Each record says when, at which turn, on which question, what the screen showed (`message`) and, when the raw error says more, what it was (`detail`); `where` is `generation`, `compaction` or `resume`:

   ```bash
   jq .errors .mm/sessions/20260918-141225-02790c82.json
   ```

   ```json
   [
     {
       "at": "2026-09-18T14:12:25Z",
       "turn": 1,
       "where": "generation",
       "message": "dmr: \"no/such-model:none\" not found at http://localhost:12434/engines/v1 — docker model pull no/such-model:none",
       "detail": "failed to create completion: POST \"http://localhost:12434/engines/v1/chat/completions\": 404 Not Found",
       "question": "hello"
     }
   ]
   ```

3. To have the failure analysed, hand the file to a coding agent (Claude Code, or `mm` itself in another project) and ask what went wrong and what to change — in the code, or in `agent.yaml` (`watchdogTimeout`, `maxOutput`, `model`, `context.*`). The history in the same file gives the context the model had; the `errors` array gives what it never saw.

   A session whose only content is an error has no turn: a bare `/resume` skips it, `/resume <id>` reaches it.

## From an editor (ACP)

1. Keep `sessions.enabled: true` in the file `AGENT_CONFIG` points at. Each thread the editor opens is a session, saved under `<project>/.mm/sessions/<id>.json` from its creation.

2. Use the editor's **Reload Agent** (Zed) when the agent restarted or you changed its configuration. The editor sends `session/load` with the thread's id; `mm` reads the file back and replays the whole conversation — your questions, the answers, every tool call with the input it was given and the output it returned at the time. Nothing runs again. The thread then continues as before.

3. `/new` in a thread keeps the thread (the editor's session id) but the conversation so far is kept on disk under a new id, and the thread's own file starts over empty. `/sessions` and `/resume` do not exist over ACP: the editor is the one listing threads.

## Variants

- **One store for every project.** Give `dir` an absolute path. Sessions of different projects then share one directory; each file records its `cwd`.
- **A project you cannot write to.** The banner or the `[acp]` log says `not saved` with the reason; the conversation goes on unpersisted.
- **Compression.** A `/compact` or an automatic compression rewrites the file with the shortened history; a resumed or reloaded session starts from the summary, like the live one did. The `errors` array is left as it is.
- **Errors over ACP.** The editor shows the failure in its own way; the record still goes to the thread's file, and `/new` moves it to the archived conversation with the history it belongs to.
- **Starting fresh on purpose.** Nothing to do: every start is a new session. The old ones only come back on `/resume` or on an editor reload.

## See also

- [Configuration reference](../reference/configuration.md) — the `sessions` keys
- [Slash commands reference](../reference/slash-commands.md) — `/sessions`, `/resume`, `/new`
- [ACP reference](../reference/acp.md) — `session/load` and what it replays
- [Why sessions work this way](../explanation/persistent-sessions.md)