# Dead-end memory (mistakes)

> tokenade mistake records approaches that did not work, so your agent is reminded of them at the start of every session and does not try them again.

Source: https://tokenade.net/en/docs/mistakes · Updated: 2026-10-07

`tokenade mistake` keeps a short list of directions that did not work: an approach you abandoned, a change you reverted. At the start of each session, your agent is reminded of the most recent ones, so it does not spend another afternoon on an idea already ruled out.

## Usage

```text
tokenade mistake [list]
tokenade mistake add <summary…> [--ref <commit>]
git show … | tokenade mistake from-revert
```

Alias: `mistakes`.

| Subcommand | Effect |
| --- | --- |
| `list` (default) | Print what has been recorded. `tokenade mistake list --json` prints the records as JSON (`--json` needs the explicit `list`) |
| `add <summary…>` | Record a dead end in your own words |
| `--ref <commit>` | With `add`: tie the record to the commit it came from |
| `from-revert` | Read git output on stdin and record a mistake only if it describes a revert |

## Record a dead end by hand

```bash
tokenade mistake add "tried a global mutable cache, caused races" --ref deadbee
```

Keep the summary short and specific. The agent sees at most 120 characters of it.

## Record a revert

```bash
git show HEAD | tokenade mistake from-revert
```

`from-revert` looks for the first line containing `Revert`. With the standard `Revert "<subject>"` message it records `reverted: <subject>`. If the input is not a revert, nothing is recorded and it prints `no revert detected`, so it is safe to pipe any commit into it, for example from a git hook of your own.

Tokenade does not watch your repository: a revert is recorded only when you pipe it in.

## List

```text
$ tokenade mistake
tokenade mistake — 2 recorded
  [manual] tried global mutable cache, caused races (deadbee)
  [revert] reverted: add broken cache layer
```

`[manual]` comes from `add`, `[revert]` from `from-revert`.

## What your agent sees

At session start, when at least one record exists, the SessionStart hook adds one line to the agent's context:

```text
[tokenade:mistakes] N dead ends recorded on this machine (3 shown; …) — do not re-propose: "…"
```

- Only the 3 newest records are shown, each summary cut at 120 characters.
- Nothing is added when the list is empty, so an unused feature costs no tokens.
- Agents with a session-start hook get it: Claude Code (CLI and desktop Code tab), Codex, Copilot CLI, Droid and Gemini-family agents. Grok ignores session-start output, so it does not see the reminder.

## Storage

| Item | Value |
| --- | --- |
| File | `~/.tokenade/mistakes.jsonl` |
| Fields | `ts`, `kind` (`revert` or `manual`), `summary`, optional `reference` |
| Retention | 30 days, then rotated out |
| Scope | Per machine, shared by all projects |

The file is local and never uploaded. To remove a record, edit or delete the file; it is plain JSON Lines.

## Related

- [How hooks intercept tool calls](https://tokenade.net/en/docs/hooks)
- [Files and paths](https://tokenade.net/en/docs/files-and-paths)
- [Claude Code (CLI and desktop)](https://tokenade.net/en/docs/claude-code)
