shiro-neko/docs/memory.md

# Memory and state

Four kinds of state, each with a different lifetime.

| State | Lives in | Survives |
|---|---|---|
| transcript | the message array | until compaction or `/clear` |
| task list | the system prompt, rebuilt each step | pruning and `/compact` |
| project memory | `~/.shiro-neko/memory/<hash>.json` | across sessions, forever |
| session record | `~/.shiro-neko/sessions/<uuid>.json` | until you delete it |

The split exists because compaction is destructive. `pruneMessages` deletes tool results and
`/compact` deletes the whole transcript, so anything recorded only in messages is lost
exactly when a long task needs it most.

## Project memory

Durable notes about the codebase, injected at the start of every session.

### `remember`

```
kind  fact | decision | gotcha | command
text  one self-contained line
```

- **fact** — how something is. "The API is versioned under `/v2`."
- **decision** — what was chosen and why. "We use snake_case for DB columns; the ORM
  expects it."
- **gotcha** — a trap. "The migration must run before the seed or the FK fails."
- **command** — an invocation that works. "Tests run with `bun test`, not `npm test`."

Duplicates are refused. Text is capped at 400 characters, the store at 300 entries.

### `recall`

Every term must appear. A match increments that entry's hit count, which protects it from
compaction later — an entry the agent actually uses is worth keeping verbatim.

### `forget`

Removes by substring, for a note that turned out wrong.

### What the agent sees

```
What you learned about this project in earlier sessions. Trust it, but verify anything
that contradicts what you can see in the code now:
- (command) tests run with bun test, not npm test
- (gotcha) the migration must run before the seed
- (decision) snake_case for DB columns, the ORM expects it
```

Top 20 by hit count, then recency. The "verify anything that contradicts" line matters:
memory goes stale and a confidently wrong note is worse than none.

### Compacting

`/memory` has the model merge entries. Two rules make it safe:

- Entries with at least one recall are kept verbatim and never merged.
- A model returning nothing parseable leaves the store untouched.

Without the second rule a bad response wipes everything the agent has learned.

`/notes` lists the store with hit counts. `--no-memory` disables loading and writing.

## Task list

`todo_write` replaces the whole list each call. Four states:

```
tasks ##########.............. 1/4  1 blocked
[x] read the pagination code
[~] fix the boundary
[ ] add a test
[!] update the docs  (no write access to the wiki)
```

`blocked` requires a note saying what is blocking it. The tool warns when more than one task
is `in_progress`, when nothing is `in_progress` while work remains, or when a `blocked` task
has no note.

The list is re-rendered into the system prompt on **every step**, not once per turn — a
`todo_write` on step one has to be visible to step two. It is saved with the session and
restored by `-c` or `/resume`.

`/todos` shows it. The panel above the input shows it live.

## Sessions

Every turn autosaves, debounced 400 ms so a long tool loop does not hit the disk each step.

```json
{
  "id": "0193ab2c-…",
  "createdAt": "…", "updatedAt": "…",
  "cwd": "/home/you/project",
  "provider": "openai", "model": "gpt-5",
  "title": "why does the pagination test fail?",
  "inputTokens": 48210, "outputTokens": 3105,
  "costUsd": 0.0913,
  "notebook": { "todos": [ … ] },
  "messages": [ … ]
}
```

```bash
shiro -c                  # newest session for this directory
shiro -r 0193ab2c         # by id or unique prefix
```

```
/sessions   list the last 15
/resume <id>
/save       write now instead of waiting for the debounce
```

A corrupt session file is skipped rather than crashing the list.

## Compaction

Two mechanisms.

**Automatic**, at roughly 120k estimated tokens: `pruneMessages` strips reasoning and older
tool calls from what goes on the wire. Local history is untouched, so the transcript on your
screen stays complete. The turn reports it:

```
context compacted: 192 messages pruned to 15 on the wire
```

**Manual**, `/compact`: the model writes a summary — goal, files touched, decisions, commands
and outcomes, what remains — and it replaces the transcript entirely.

### The pruning repair

`pruneMessages({ reasoning: 'all' })` strips a reasoning item and keeps the message item from
the same response. The OpenAI responses API treats the message as a dependent of that
reasoning item and rejects the request:

```
400 Item 'msg_…' of type 'message' was provided without its required 'reasoning' item: 'rs_…'
```

The two carry different ids, so they cannot be matched by id. What links them is the
assistant message they arrived in — one message is one response. `src/prune.ts` drops the
dependent parts of any turn whose reasoning was removed. That costs nothing, because pruning
was already discarding those turns.

## Prompt history

Per-directory, capped at 200, deduplicated against the previous entry. Up and down in the
input walk it; down past the newest restores what you were typing.

Stored at `~/.shiro-neko/history/<hash>.json`, where the hash is a SHA-256 prefix of the
project path.