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.
6.2 KiB
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, notnpm 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.
{
"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": [ … ]
}
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.