Muhammad Zakir Ramadhan
2fa6ee247b
Tools, six built-in to fourteen: - read_many_files: up to 20 paths read concurrently, each with its own window. An unreadable path is reported in its own block instead of throwing. - multi_edit: several edits to one file, validated in memory first so a late failure cannot leave the file half-written. - list_dir: ignore-aware depth-limited tree. - git_status/diff/log/show/blame: read-only, spawned with a fixed argv rather than a shell string, which is what makes them safe to auto-approve. toolSets gates them. core is always on; edit-plus and git are optional. A disabled set reaches neither the wire nor the system prompt, since a prompt naming an absent tool teaches calls that cannot succeed. Interface: - Reasoning streams to a collapsed panel, ctrl-r expands, dropped when the turn ends: it is progress, not the answer. - The tool in flight is named from tool-input-start, before its arguments finish streaming, and cleared on its result. - Prompts typed mid-turn queue and drain in order. esc clears the queue as well as aborting. - @ opens a path picker fed by the ignore-aware walker. Prefix matches rank above substring matches, so @src/ means "under src/". The walk runs on the first @, not at startup. ctrl-c kills the command in flight and keeps the turn. The call throws rather than returning, so the model cannot read a killed command as one that ran and failed on its own terms. The kill takes the whole process tree: killing cmd /c alone left the real command holding both pipes open, so the read never returned and the interrupt did nothing for 19 seconds. Two pruning fixes: - A tool result whose tool call was pruned is now dropped with it. Pruning counts messages, so the cut landed between an assistant tool-call and the tool message answering it, producing 400 "No tool call found for function call output with call_id ...". The reverse pairing is left alone: a call awaiting its result is what a suspended approval looks like. - ignore.ts called statFs without importing it, so walk() crashed on the first symlink. 482 tests, up from 404. Docs synced across README, ROADMAP, TODO, and all of docs/: tool sets, the new tools, ctrl-c semantics, the tool-start event, and the two hand-maintained tool-name lists recorded as a known weakness.
181 lines
6.2 KiB
Markdown
181 lines
6.2 KiB
Markdown
# 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
|
|
|
|
Pruning breaks two provider invariants. `src/prune.ts` repairs both, and both were real 400s
|
|
before it did.
|
|
|
|
**A message without its reasoning item.** `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. `dropOrphanedItems` drops the
|
|
dependent parts of any turn whose reasoning was removed. That costs nothing, because pruning
|
|
was already discarding those turns.
|
|
|
|
**A tool result without its tool call.** `toolCalls: 'before-last-3-messages'` counts
|
|
*messages*, not pairs, so the cut can land between the assistant message holding a `tool-call`
|
|
and the `tool` message answering it:
|
|
|
|
```
|
|
400 No tool call found for function call output with call_id call_…
|
|
```
|
|
|
|
`dropOrphanedResults` drops any result whose call id no longer survives. The reverse is left
|
|
alone deliberately: a tool call still waiting for its result is what a suspended approval looks
|
|
like, and dropping it would break `/resume`.
|
|
|
|
## 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. While an `@` token is open
|
|
those keys move in the file picker instead.
|
|
|
|
Stored at `~/.shiro-neko/history/<hash>.json`, where the hash is a SHA-256 prefix of the
|
|
project path.
|
|
|
|
## The prompt queue
|
|
|
|
Not persisted, and deliberately so. A prompt typed during a turn lives in memory until the turn
|
|
ends, then runs. `esc` clears it along with aborting the turn, and quitting discards it — a
|
|
queued thought that fires on next launch, against a workspace that has since changed, is worse
|
|
than a lost one.
|