How I built a 2,048-byte receipt for every turn my desktop AI companion takes: 20 tools, 20 files, 0 arguments
How I built a 2,048-byte receipt for every turn my desktop AI companion takes: 20 tools, 20 files, 0 arguments Ankita AI is the desktop AI assistant I build — a little companion, a lot more possible — by Krish Verma. I
How I built a 2,048-byte receipt for every turn my desktop AI companion takes: 20 tools, 20 files, 0 arguments
Ankita AI is the desktop AI assistant I build — a little companion, a lot more possible — by Krish Verma. It does real work while I'm away: edits files, runs commands, answers in my voice. The problem is what I come back to. The conversation transcript is pages long, and "what did you actually change?" shouldn't require re-reading all of it. So every turn now leaves a receipt: a bounded record of what it did, stored next to the transcript, in the repo and on the website.
The receipt lives in src/memory/turn-audit.mjs, and its first design choice is what it refuses to record. The file header says it plainly: the journal stores the conversation; the audit stores only evidence of work — tool names and touched paths. No arguments, no output, no commands. A receipt is a "what changed" line, not a transcript, and the moment it starts carrying command text it stops being a receipt and becomes a second journal with worse provenance.
The shape: 20 tools, 20 files, 2,048 bytes
A fresh audit is created at the start of every turn in src/core/agent.mjs, with the caps taken from config: projectAuditMaxTools and projectAuditMaxFiles, both defaulting to 20 and hard-capped at 100. The byte bound is fixed at 2,048 — AUDIT_MAX_BYTES — and individual paths are cut at 200 characters.
Two functions feed it. noteToolUse runs on every tool call, in both runToolCall and runMcpToolCall, and it dedupes: the same tool called five times is recorded once. Past 20 distinct tools it stops recording and increments a dropped counter instead of growing. noteFileEffects runs only when a tool result comes back, and only when the result doesn't start with Error: — a failed write is not a change, and the audit refuses to claim otherwise.
Which tools count as file effects is decided in one place, src/core/tool-effects.mjs, so the audit and the desktop's workspace watcher agree on what a change is. The list is short: write_file, edit_file, edit_lines, apply_patch, move_file, delete_file, restore_file — plus image_generate and image_download, which write into the workspace but get recorded as "changed" with no paths, because their paths are generated artifacts rather than project source.
Paths are extracted without ever looking at the arguments as data. move_file records both ends. apply_patch parses the diff headers — rename from/rename to lines and +++/--- lines — to recover the files a patch touched. Everything else takes the path argument. Each path is then made workspace-relative when it lives inside the workspace, absolute when it doesn't, because a relative path is the useful form and an absolute one is the only honest form outside it.
Where the receipt lands
At the end of the turn, finishTurnAudit freezes the record. If the JSON is over 2,048 bytes it pops files first, then tools, until it fits — and every pop increments dropped, so the receipt says how much evidence it threw away. The finished audit is attached to the journal entry (sessions.mjs stores it as entry.audit), and handed to project maintenance.
That last step is the whole point. maintainTurn in src/memory/project-maintenance.mjs is deterministic and costs zero model calls: if the audit says the turn changed something, it appends one work-log line to the project — the termination reason, a file count, and up to five paths, like model_answer · 3 file(s) · src/a.js, src/b.js, docs/c.md. The project view then shows what actually happened, turn by turn, without anyone re-reading a transcript. And if anything in that bookkeeping fails, the failure is swallowed into a return value — a turn must never break because the bookkeeping did.
The whole thing is switchable. PROJECT_WORK_CAPTURE=false turns the audit off entirely and the journal goes back to being a plain transcript. The caps are env-tunable (PROJECT_AUDIT_MAX_TOOLS, PROJECT_AUDIT_MAX_FILES), but never above 100 — a receipt that can grow without bound is a log file with a nicer name.
The honest limits
Six tests in test/memory/turn-audit.test.mjs pin the behaviour: tools capped and deduped, file-effect tools marking a turn changed, paths relative and deduped, moves and patches recorded without arguments, the byte bound holding under many long paths, and a null audit still producing a stable shape. What the tests can't pin is the hole I know is there: run_command and git can rewrite files without naming them. The audit cannot record paths for them — the desktop still refreshes the file tree when they run, because WORKSPACE_EFFECT_TOOLS includes them, but the work log can't say which file changed. The receipt is evidence of tool calls, not proof of intent: a tool can report success while doing nothing, and the audit will faithfully record the nothing.
Tell me I'm wrong: a receipt that can't see run_command rewrites is a receipt that lies by omission. Should the audit record the command text so the hole is at least visible, or is quoting an untrusted shell string into a permanent project record worse than saying nothing at all?
Krish Verma, creator of Ankita AI — a personal AI companion for the desktop. The code is open source at github.com/akyourowngames/A.N.K.I.T.A, and the project lives at ankita-sable.vercel.app.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.