Andre Lund

Audition the voice before you commission the work

2026-07-29T00:00:00+00:00

Part of my tooling generates long-form written content in a configured voice: an editorial identity that describes the audience, the register, the vocabulary, what the writer sounds like. The identity is prose in a config. And prose configs for tone have a nasty property: they are write-only. You describe the voice you want ("unhurried, curious, explains from first principles, never hypey"), the generator consumes it, and you learn whether your description worked only after paying for a full generation run and reading the result. If the register is off, you edit adjectives and pay again.

The feedback loop is the problem. Tuning a persona through full generations is like adjusting a recipe by catering a wedding each time. What I wanted was a taste: given this identity, say two lines in this voice, right now, for approximately nothing.

The smallest possible agent</h2>
The fix is a preview agent, and the design goal was to make it as close to free as an LLM call gets - because a preview you hesitate to run is a preview that does not get run. Everything about it is subtraction:

No tools. The agent cannot read files, browse, or search. Everything it needs - the identity text and an optional topic - is passed inline in the dispatch. This is not just cost control: an agent with no tools and fully inline context is reproducible. Same input, same class of output, nothing ambient to drift.</li>
A fast local model. Auditioning a register is narrow work; it needs fidelity to a style description, not reasoning depth. The call routes to the cheapest tier in my worker runtime - a small model running on my own machine. A measured audition costs about 500 tokens end to end, which on local hardware rounds to zero.</li>
A hard output schema. The agent must return two to six sample lines, each a sentence or two the voice would actually speak, and nothing else - no headings, no stage directions, no commentary about the voice. The schema is enforced at the call layer, so a malformed response retries rather than reaching the UI. A preview is a contract, not a chat.</li>
Ephemeral by construction. The route that serves it writes nothing: no database row, no artifact, no history. Preview output that persists becomes state - something to list, migrate, and clean up. The whole value of a preview is that it evaporates.</li>
A timeout and one retry. Ninety seconds, one attempt to recover, then fail visibly. A preview that hangs is worse than one that errors.</li> </ul>
The prompt side is one rule repeated three ways: match the identity's tone, register, and vocabulary precisely; each line must be a speakable line of prose on its own; do not perform meta-commentary. Sample lines that describe the voice instead of being the voice are the failure mode, and the instructions attack it directly.
The loop it creates</h2>
In the settings UI, next to the identity editor, there is a sample button. Type an optional topic, click, and a moment later: a handful of lines in the configured voice. Edit the identity, sample again. The tuning loop drops from "generate a full piece, read it, wince" to seconds per iteration.
Two UI decisions carry more weight than they look like they should:
The preview invalidates nothing. It is a plain fire-and-return call with no cache updates, because it changes no state. Wiring a preview into the app's data layer as if it were a mutation is a category error that makes every preview cost a refetch.
The empty state teaches. With no identity configured, the button does not disable silently; the endpoint refuses with "identity is unset" and the UI says so. A preview feature whose precondition is invisible reads as broken.
There is also a seam decision underneath: the route awaits the worker synchronously, bounded at two minutes, instead of returning a job id the client polls. Previews are interactive - the human is sitting there. The moment a preview needs a progress bar, it has failed at being a preview, so the API shape encodes the latency budget: if this cannot answer while the user watches, it should error, not stream status updates.
Why this is a pattern, not a feature</h2>
The general shape: when a system consumes a human-authored description and produces something expensive, insert the cheapest possible sampler between the two. The description-to-output gap is where confidence quietly dies - you wrote the config, you think it says what you mean, and the only verification on offer costs a full run.
Samplers earn their place when they are:

Instant enough to be reflexive. Seconds, not minutes. The moment sampling requires deciding whether it is worth it, iteration stops.</li>
Free enough to be guiltless. A local model or the cheapest API tier. The task is narrow by design; use the narrowest worker that does it.</li>
Constrained enough to be honest. Schema-forced output in the target format. A sampler that returns an essay about what it would do is theater.</li>
Stateless enough to be ignorable. No persistence, no history, no cleanup. Run it forty times; nothing accumulates.</li> </ol>
I now reach for this shape whenever a prose config drives generation: sample the persona before the piece, the summary style before the batch, the reviewer's severity before the review run. Each sampler is an afternoon of work, because subtraction is fast to build - the entire agent definition fits on one screen, and the worker runtime it rides on already existed.
The quiet lesson underneath is about model routing. The instinct is to send every task to the strongest model available. But a preview's job is to be representative and immediate, not maximal - and a small local model with a tight schema and inline context is more representative of "what will the configured voice sound like" than a frontier model improvising with more freedom. Match the worker to the narrowness of the task, and some tasks turn out to be nearly free.

Giving my agent a map of the codebase (drawn partly from its own footsteps)

2026-07-29T00:00:00+00:00

Watch a coding agent land in an unfamiliar repository and you will see it do what a new hire does on day one: grep for names, list directories, open files, and slowly assemble a mental model. Unlike the hire, the agent does this every session. The model it builds is discarded when the context window closes, and the next session pays for it again - in tokens, in latency, and in the wrong turns an incomplete picture produces.
My fix is a per-project code map: a queryable navigation layer each repository carries, rebuilt incrementally, that a new session receives a digest of before it reads a single file. The interesting part is not that it exists - static code intelligence is a mature field - but which three signals it fuses, because the third one is something most tooling cannot see at all.
Three signals, one map</h2>
Structure is the conventional axis: symbols, calls, and imports parsed with tree-sitter across whatever languages the repo mixes. This is deliberately the shallow version of static analysis. Dedicated tools do deep type resolution far better than I ever will, and competing with them head-on would be a losing use of my time. Syntactic edges are good enough for navigation, and the edge table records where each edge came from, so a deeper per-language analyzer can add resolved edges later without a redesign.
Temporal comes from git: churn, ownership, and co-change - which files historically change in the same commits. Parsed from plain git log</code> output; no library dependency, and the repo's whole history is sitting there with nothing better to do.
Behavioral is the differentiator. My memory system already records every tool call an agent makes - every read, edit, and write, tagged with project and session. Rolled up, that log yields a co-touch matrix: which files did agents actually work on together, in real sessions. Editing weighs more than reading in the rollup, because changing two files together is stronger evidence of coupling than looking at them.
The distinction between the axes matters in practice. The call graph tells you A depends on B - true, and sometimes useless, because half of a codebase depends on B. The behavioral signal tells you that in the last thirty sessions, every time A changed, B and C changed too. Those are A's de facto neighbors: the set you should have open when you touch it. Static tools cannot compute this because they never see the work. Git co-change approximates it but only at commit granularity, after the fact, and only for changes - a session that read four files to safely edit a fifth leaves no trace in git at all. The agent's own footsteps are the only place this signal exists.
Cheap at session start, deep on demand</h2> The map is consumed two ways, and the split is deliberate. The cheap path is a small rendered digest injected into every session's context at start: the subsystems, a few key files each, one line of purpose, ordered by community detection over the fused graph. On my main project right now that is 913 files folded into 33 communities. One refinement earns its keep daily: the digest's sections are reordered by relevance to the branch's current task, which the session-start machinery already knows from the pointer file described in the previous post. A session opening a branch about upload quality-control sees the QC subsystem first, not an alphabetical list. The deep path is a set of query tools the agent calls mid-session: neighborhood (structural plus behavioral neighbors of a file), hotspots (churn-weighted risk), and why - which is my favorite, because it joins the map to the documentation standard from the previous post. Ask why a file exists and the answer includes the architecture decision records that cite it, alongside its callers. The decision trail and the call graph hang off the same index, so "what is this" and "why is it like this" are one query apart. The two paths exist because they have different economics. The lay-of-the- land question benefits from being ambient - answered before the agent knows to ask, at zero query cost. Graph traversals cannot be pre-rendered into prose without exploding; they stay behind tools. Pure-filesystem and pure-query designs both lose to the split. Staying fresh without a daemon</h2> A navigation layer that drifts from the code is worse than none - an agent routed by a stale call graph mis-navigates confidently. The freshness model is a pattern I now reuse everywhere: lifecycle events catch the common case; a scheduled sweep guarantees convergence. When an agent edits a file, a post-edit hook re-parses just that file and updates its rows - sub-second with tree-sitter, and it keeps the index honest about the thing most likely to be queried next: the code the agent just changed. But hooks are best-effort by nature. They miss hand edits made outside a session, deletions, rebases. So a periodic full reindex sweeps up whatever the hooks missed. Neither mechanism alone is sound: the hook without the sweep accumulates drift forever; the sweep without the hook means the map is wrong precisely about the current session's work. Together they give eventual consistency with a fast path where it matters. The digest itself is recomputed on the slow cadence, not per-edit - which subsystems exist and what matters most is stable week to week, and the one expensive step (an LLM naming the communities) is not worth paying per keystroke. What I deliberately did not build</h2> Three rejections shaped the design more than the features did: No language servers, no deep type inference. Spinning up N language servers across every watched project is operationally heavy, and it competes with mature tools on their home turf. The behavioral signal is the moat; syntactic structure is scaffolding for it. The v2 path (per- language deepening adapters) is recorded, provenance-tagged, and unbuilt.</li> No global cross-project graph. Each project's map is self-contained and lives with the project's own data. A cross-project query ("which repos use this pattern") has no consumer yet, and speculative generality would tax every tool signature. When a real consumer shows up, a thin aggregator can be added over the per-project stores.</li> No separate behavior log. The co-touch matrix is a rollup over the event log the memory system already keeps. A dedicated tracking store would duplicate data, lose the joins with session decisions, and double the surface I have to keep redaction-clean.</li> </ul> What transfers</h2> Your agent's work history is a first-class code signal. If you run agents against a repo and log their tool calls, you are sitting on coupling data no static analyzer can derive. The rollup is a SQL view, not a research project.</li> Split ambient from on-demand. A small always-injected digest for orientation, tools for depth. Neither substitutes for the other, and the digest is only trustworthy if something recomputes it.</li> Order context by the current task. The same digest reads twice as well when the relevant subsystem comes first. You usually already know the task; use it.</li> Freshness = fast best-effort path + guaranteed slow sweep. Any derived index maintained only by event hooks is quietly wrong; any maintained only by batch is wrong about right now.</li> Route around mature tools, not through them. Tree-sitter-shallow plus a unique signal beats competing with twenty years of type-inference engineering on their terms.</li> </ul> This is the fourth post about the same small stack, and the pattern holds: the memory system logs the footsteps, the presence layer keeps parallel sessions legible, the docs standard preserves the why, and the code map fuses all three into the thing an agent actually needs on arrival - a sense of place.
Documentation my agents can trust (and why it made me faster too) 2026-07-29T00:00:00+00:00 The two posts before this one describe work finished weeks earlier: a retrieval bug with twenty measured queries, a presence layer with its design alternatives. I wrote each in an afternoon, and I reconstructed nothing. Every number, every rejected option, every reason was already written down, in a predictable place, in a form I could trust had not drifted since. That is not diligence. Left to my own habits I document like everyone else: enthusiastically at the start, then never again. The reason the records exist is that my projects follow a documentation standard designed for a reader with less context than any human: a coding agent landing cold. It turns out that optimizing docs for that reader makes them dramatically better for the human too - future-me is also a reader landing cold, just with more overconfidence. The failure mode: nobody can tell what is true</h2> Before standardizing, I surveyed my own repos. The evidence was embarrassing in a specific, countable way: Architecture decision records that only ever grew. One ADR had accumulated nine dated amendment sections and roughly 390 lines. Another was over 500. Reading one meant reading a journal and mentally replaying which parts still applied.</li> A monolithic build-plan file, plus a 960-line "shipped" ledger, with no in-progress state and two sources of truth for "done" that disagreed.</li> A "current task" note that was stale more often than not, because nothing ever forced it to be true.</li> </ul> For a human this is friction. For an agent it is poison: an agent reads the stale note and acts on it. The core question a repo has to answer - what is decided, what is to-do, what is done, what is in-flight - had no reliable answer anywhere. Decisions are immutable; change means supersede</h2> The cornerstone rule: an accepted decision record is never edited again. One decision per ADR, short. If the decision changes, you write a new ADR that supersedes the old one, and the old one's status flips to "superseded by NNNN" - a one-line metadata change, with the body untouched. Before adopting it I ran a research pass across the published field, with each claim adversarially verified, and this was the single strongest convergence: four independent primary sources (AWS's prescriptive guidance, adr-tools, log4brains, MADR) all name immutability-plus-supersession as the cure for exactly the append-only journal sprawl my repos exhibited. The deeper reason it works is trust, and trust is an agent requirement before it is a style preference. An agent quoting a mutable document has to wonder whether the text changed since the decision was made. An immutable record with an explicit supersession chain cannot lie about its history: if its status says accepted, the body means today what it meant the day it was accepted. That property is what let me lift design rationale into a blog post weeks later without re-verifying any of it against the code. One companion rule keeps the immutability honest: as-built reality does not live on the ADR. The ADR records the decision and carries one pointer line to the plan that implemented it. How the implementation actually went - the surprises, the deviations - lives in the plan. Without this split, the pressure to "just add a note" reintroduces the journal. Plans: stable task ids and a decision log</h2> Work items live as plan files in an active/</code> directory, moving to archive/</code> when done. The skeleton is boring on purpose: intent, approach, a task checklist, and a decision log. Two rules carry the weight: Task ids are stable forever. Tasks are T1</code>, T2</code>, ... assigned at creation and never renumbered. A split or reordered task gets a fresh id; an existing id never silently changes meaning. This sounds pedantic until you have commits, session notes, and a current-task pointer all referencing "T4" - renumbering would quietly repoint every one of them at different work. Stable ids are what let a task be checked off with a one-line "done, as built" note and trusted years later. Small decisions go in the plan's decision log, not new ADRs. The threshold: an ADR is for a decision that outlives one work item. Everything local - "we fold the panel by section, not per-fact, because..." - lands as a dated entry in the plan that needed it. This keeps ADRs rare and heavy while still capturing the reasoning that debugging (or blogging) later depends on. My measurement-traps post was essentially written from these entries; the traps were recorded as decision-log entries the day they bit. There is also a gate for honesty about ignorance: an unresolved question in a plan is written as an explicit [NEEDS CLARIFICATION: ...]</code> marker, and no task it gates may start while one remains. An agent that hits the marker asks instead of guessing. The alternative - the agent inventing an answer with full confidence - is how plausible-but-wrong work happens. One authoritative home per question</h2> The piece that killed the most staleness is a small table: every question a reader might ask has exactly one place whose answer counts. Question</th> Authoritative home</th></tr></thead> Why is it built this way?</td> ADRs</td></tr> What does it actually do?</td> The code</td></tr> What is to-do / done?</td> The plan's task checklist</td></tr> Who is working on what right now?</td> The ephemeral presence layer</td></tr> What is this branch about?</td> A one-line pointer file into the active plan</td></tr> </tbody></table> Two entries deserve comment. First, the code stays authoritative for what. The research pass surfaced the fashionable inverse - make the spec canonical and subordinate the code to it - and it failed adversarial verification outright. Docs own intent and rationale; behavior is what ships. Second, in-flight status is deliberately ephemeral. "Session A is working on T3" lives in the live presence registry from the previous post, never as a durable marker in the plan. A durable in-progress flag is precisely the thing that rots when a session dies mid-task - which is how my old current-task note became a professional liar. Durable files record what is true durably; live state lives somewhere that dies with the process. Discipline that is not enforced is decoration</h2> Everything above would decay in a month if it relied on my consistency, so it does not: New repos are scaffolded with the structure, templates, and glossary in their first commit, so the standard is the path of least resistance.</li> A lint runs over the machine-readable invariants: frontmatter status values, task-id uniqueness, archive moves, pointer files that reference plans that exist, an ADR's implemented-by path that still resolves.</li> The migration rule for old repos is forward-only: nothing is retroactively rewritten, but touching an old open item means first lifting it into a real plan. Old mess is contained, not laundered.</li> </ul> The lint matters more than it looks. It converts "we agreed to do this" into "the build tells you when you did not," which is the only form of agreement that survives contact with a busy week. What transfers</h2> Write for the reader with the least context. An agent landing cold is the honest proxy for future-you. If an agent can reconstruct what is decided, done, and open from your repo, so can any human.</li> Make records immutable and change explicit. A document that cannot have been quietly edited is the only kind either of you can quote without re-verifying.</li> Give every question exactly one authoritative home, and be honest about which axis is durable and which is ephemeral. Most staleness is a durable file claiming to know live state.</li> Stable ids beat tidy renumbering. Anything referenced from outside a document must never change meaning.</li> Enforce mechanically or watch it drift. Templates make compliance cheap; a lint makes drift loud.</li> </ul> The compounding effect surprised me. Each layer - the memory system, the presence layer, this standard - was built to solve its own local problem, and the posts about them exist because the layers also happen to document each other. The infrastructure that keeps my agents honest turned out to be the same infrastructure that lets me tell you about it. My agent system dreams at night, and that is where its memory comes from 2026-07-29T00:00:00+00:00 The first four posts in this series keep referring to durable facts my agents recall across sessions. None of those facts got there because an agent, mid-task, decided "this is worth remembering forever." Almost everything an agent thinks is memorable in the moment is noise a week later, and an agent given a direct write path to durable memory will fill it with confident junk. Instead, my system does what brains do: it consolidates offline. Twice a day, on a timer, a process wakes up, reads what happened since it last ran, and decides - slowly, with gates - what deserves to survive. I call it dreaming, and the name has turned out to be more than a joke: the design questions are genuinely sleep-shaped. What gets replayed? What gets promoted to long-term storage? What gets discarded? And what happens when the process misfires? The shape: a timer, not a daemon</h2> Dreaming is a one-shot process fired by a scheduler - a morning cycle for lighter work (recommendations, "what needs attention"), an evening cycle for the heavy memory-promotion pass. No resident daemon, no queue service. Each run is a fresh process that reads files, thinks, writes files, and exits. Everything in my stack is filesystem-first, and consolidation is no exception: if the machine is off, the cycle is skipped and the next one picks up the unprocessed range. Two operational rules matter more than the schedule: Exactly one machine dreams. My state syncs across machines, and two consolidators writing the same durable files would conflict endlessly. One machine owns dreaming; the others read the results. Single-writer is the cheapest concurrency model that exists, and choosing it here removed a whole category of merge problems before they happened. Every cycle has a hard token budget. The reflection step calls an LLM, and an unbounded loop over a busy day's events is an unbounded bill. A cycle gets a fixed input and output cap; hitting the cap mid-cycle means finish gating what you already produced, log the overrun, and let the next cycle continue from there. A runaway day costs a known maximum. The daily spend lands around one to three dollars, which I consider cheap for a memory that maintains itself. The pipeline: cluster, reflect, score, gate</h2> The evening pass runs the day's episodic events - tool calls, session summaries, captured thoughts - through a fixed sequence: Cluster. Events are embedded and grouped by density. A durable fact almost never comes from one event; it comes from the same theme surfacing across sessions.</li> Reflect. An LLM reads each cluster and proposes candidates: "these events support the fact that X." Each candidate carries the ids of the events supporting it, so provenance survives the whole trip.</li> Score. Candidates get a confidence score and pass structural checks: enough distinct supporting events, spread over enough time, not a restatement of something already known.</li> Judge. Two LLM-backed checks run against existing memory: does this contradict a stored fact, and is it a duplicate?</li> Promote or queue. High-confidence, well-corroborated candidates can be written to durable memory automatically. Everything else lands as a card in a review queue where I accept or reject with a keystroke, and applying accepted items produces a git commit - the memory file's history is an audit log.</li> </ol> The single most important design fact: the interesting engineering is entirely in steps 3 through 5. Generating candidates is easy; any LLM over any event log will happily propose memories. The system's quality is decided by what it refuses to write. Durable memory pollution compounds - a bad fact gets recalled, believed, cited, and built upon by dozens of future sessions - so the write gate is where the paranoia belongs. Concretely: auto-promotion requires both a confidence threshold and at least three supporting events. A candidate with two supporters can be judged genuinely durable by the reflector, and it still cannot enter memory unattended - it routes to the review queue instead. The rule is not "two events are not evidence"; it is "two events are not enough evidence to skip the human." Two failure stories worth their tuition</h2> The silent floor mismatch. For a while, the clustering stage was allowed to form two-event clusters, but the scoring stage silently dropped any candidate with fewer than three supporting events. Every two-event cluster the reflector judged durable was structurally discarded - not rejected with a reason, just gone. The pipeline looked healthy: cycles ran green, promotions happened, nothing errored. It was simply quieter than it should have been, and quiet is the hardest defect to notice. The fix lowered the score floor to match the cluster floor and moved the three-event rule to the auto-promote boundary, where it belongs: the candidate now survives to the review queue and the human sees it. The general lesson: when two stages of a pipeline disagree about a threshold, the disagreement does not error - it silently shrinks your output, and you will attribute the quietness to "slow week" for months. The judges that aborted the dream. The contradiction and duplicate judges originally propagated a hard LLM error - an outage, a quota blip - straight up, aborting the entire cycle and discarding all the clustering and reflection work before them. Meanwhile a garbled LLM response was handled gracefully with a conservative default. That asymmetry made no sense: the transient network error was more destructive than the corrupted answer. The policy now is uniform: any LLM-backed stage that fails hard degrades to its conservative default (no contradiction found, assume novel) and the cycle completes. For a nightly batch process, resilience beats strictness - a conservative default risks one duplicate card in a review queue; an abort discards a day. Consolidation grows skills, not just facts</h2> The part I did not plan and now value most: the same clustering that finds durable facts also finds recurring work. When the cycle notices the same kind of procedure performed across at least three instances on multiple days with no skill covering it, it proposes one - and above a confidence threshold it auto-writes a draft skill file. The draft is inert: invisible to every agent harness until I explicitly promote it. The human gate did not disappear; it moved from "write the draft" to "activate the draft," which is a cheaper place for me to pay attention. This is the sleep metaphor completing itself. Consolidation is not just deciding what to remember; it is noticing what you keep doing and turning it into ability. The facts feed recall, the skills feed behavior, and both come out of the same nightly replay of the day's events. What transfers</h2> Separate the write path from the work path. Agents mid-task are the worst judges of durability. Let them capture freely into an append-only log; let a slower, gated process decide what becomes permanent.</li> Put the engineering into refusal. Candidate generation is free; memory pollution compounds. Corroboration floors, contradiction checks, and a human queue for everything below the bar are the product.</li> Move human gates to the cheapest checkpoint; do not delete them. Auto-draft plus manual activate beats both manual-everything and full autonomy.</li> Batch processes should degrade, not abort. A conservative default wastes a little; a dead cycle wastes the day.</li> Audit your pipeline for silent disagreements. Two stages with inconsistent thresholds produce no error, only quiet. Count what enters and exits each stage, and alarm on structural drops.</li> Cap the spend structurally. A per-cycle token ceiling with graceful overrun turns "LLM loop over unbounded input" from a risk into a line item.</li> </ul> Every layer in this series feeds this one: the sessions write the events, the presence layer keeps them attributable, the docs standard records the decisions, the code map consumes the footsteps - and dreaming is the slow process at the bottom that turns a day of all of it into the few sentences worth keeping. How I measure whether my agent's memory works 2026-07-29T00:00:00+00:00 I run my coding agents on top of a personal memory system I built: durable facts live in a markdown file, an indexer embeds them with a local model (bge-m3), and a recall</code> command does semantic search over the result. Sessions query it constantly. It looked healthy for months. Then I asked it something I knew was in there: whether my system supports Windows. The fact existed, word for word, in the durable file. recall</code> returned zero hits from it. Not ranked low - absent. This post is the story of finding out why, and more usefully, the methods that made every step provable instead of plausible. If you are building agent memory, the specific bug will probably not be yours. The measurement traps will be. The bug: the text was never embedded</h2> My indexer chunked the memory file by markdown section. One section had grown to 904 tokens. The embedding library I use (fastembed) silently truncates input at a default of 512 tokens unless you override it, and nothing in my code did. Nothing upstream bounded chunk size either. So the encoder saw the first 1687 characters of a 3090-character section and threw away the rest - 45.4% of the text, containing three entire facts. No error, no warning, no log line. The stored vector simply did not contain their meaning. Retrieval was not failing to find them. There was nothing to find. The nasty property: this bug is monotone with growth. Every new fact appended to the section pushed more content past the cut. The memory system degraded because it was being used. Proving it causally, not correlationally</h2> "The section is long and recall is bad" is a correlation. Before touching any code I wanted the mechanism pinned, because my first diagnosis was wrong (more on that below). The probe that settled it: query text</th> distance to the stored chunk</th></tr></thead> the full 3090-char section</td> 0.0000</td></tr> only the first 1687 chars</td> 0.0000</td></tr> only the discarded 1403-char tail</td> 0.4247</td></tr> </tbody></table> The full section and its truncated prefix embed to the same vector - exact zero distance. The tail contributes nothing at all. That is not what dilution looks like; that is a step function. Correlating each fact's character offset with its self-retrieval distance gave a Spearman rho of +0.952: a cliff at the cut position, not a gradient. This mattered because my original hypothesis was centroid dilution - one embedding averaging over many facts, dominated by the numerous ones. Dilution suggests fixes like re-ranking or splitting long sections more finely. Truncation means data is missing from the index entirely, and no amount of ranking cleverness can retrieve a vector that was never computed. Wrong mechanism, wrong fix. The ten-minute probe was cheaper than shipping the wrong repair. The fix that looks right and the one that is</h2> The one-line fix exists: the model genuinely supports an 8192-token window, and a single .with_max_length(8192)</code> restores it. I rejected it for three reasons: It trades a proven defect for an unproven one - the multi-fact centroid I could now actually measure. Even on a five-fact section that fits the window completely, querying any single fact's verbatim text returned its section at distance 0.21-0.34, against a 0.0000 floor for whole-chunk self-queries. Bundling costs retrieval sharpness even without truncation.</li> Quadratic attention on a 16x sequence, paid on every indexed chunk, for the benefit of exactly one oversized section.</li> It leaves the granularity wrong. Citations, quality reports, and injection payloads all wanted to address individual facts and could not.</li> </ol> So the fix was to make the fact the unit of embedding: the indexer now parses the memory file's per-fact structure and emits one chunk per fact. Every fact is 58-335 tokens, comfortably inside any window. And separately - this is the part that prevents recurrence - the indexer now counts every chunk's tokens against the encoder's actual window and warns on offenders, and my health command reports the count. The window guard, not the window raise, is what stops this bug class from coming back. Four wiki documents are over the limit today; the detector names them, and that debt is visible instead of silent. Measuring the fix instead of arguing about it</h2> The design had one open risk I could not reason away: per-fact chunks might lose on broad queries ("what side projects am I working on"), where a big section chunk plausibly wins by covering more topics. I had accepted this as a trade-off in the design review. Instead of accepting it, I measured it. Two indexes over the identical corpus: arm A chunked by section (exactly reproducing the live store), arm B chunked by fact. Twenty queries against both - memory-directed ones, broad ones, and eight wiki-directed queries as a counter-direction check, because an improvement that comes from crowding out the rest of the corpus is not an improvement. The accepted trade-off inverted: Rank-1 distance was never worse: 12 of 12 memory-directed queries.</li> Memory facts present in a default top-5 rose from 9 to 27 across queries.</li> All six broad queries improved or tied. The flagship broad query went from one memory hit at d=0.4763 to three hits led by d=0.3537.</li> Four narrow probes went from zero memory chunks in the top 5 to rank 1.</li> The eight wiki queries kept rank 1 unchanged, all eight.</li> </ul> The section chunk's assumed advantage on broad queries never existed. It was an artifact of there being only two memory chunks in the index at all - of course one of them "won broad queries"; there was nothing else to return. This is my strongest argument for measuring over arguing: the risk I had formally accepted in a design document was not real. End to end, the six-probe acceptance set went from 0/6 correct to 6/6, and every one of the twelve facts now self-retrieves at exact d=0.0000 - which doubles as a standing proof that no fact is truncated anymore. The two ways my "before" measurement almost lied</h2> An honest before/after table requires the "before" arm to actually measure the old behavior. Mine silently stopped doing that twice, and both failures produced the same poisonous output: a table showing no change at all. Trap one: the old store was auto-upgraded by the new binary. My index store wipes and rebuilds itself when its schema version is outdated. The fix bumped the schema. So when I pointed the new binary at the preserved old store to get "before" numbers, the first query quietly rebuilt the entire store with per-fact chunking - converting my before-arm into a second after-arm. The before-arm has to be driven by the old binary, not just the old data. Trap two: the old binary overwrote the new one. I built that old binary from a git worktree, but with the build cache directory shared with the main checkout - which overwrote the release binary I was using for the "after" column. Both columns were now measuring pre-fix code. I caught it because of two smells: the after column exactly equaled the before column, and a known-good result I had measured minutes earlier had silently regressed. The rule I keep now: pin each arm to its own binary path, and assert the two binaries differ before trusting any comparison between them. "Before equals after, everywhere, exactly" is not a null result. It is an instrument failure. A third, related trap lives in the test suite. My mock embedder hashes the full input text with no truncation, so every truncation test passes against it - including on the broken code. The causal tests require the real encoder (a 558MB model download I keep out of CI), so CI instead pins the structural properties the fix guarantees: one chunk per fact, identity fields populated. The proof runs by hand at the gate; the regression guard runs on every commit; and I wrote down which is which, so a green CI run cannot be mistaken for the causal proof. What transfers</h2> None of this needed special tooling - a CLI, a scratch directory for each index, and discipline about what counts as evidence. The parts I would carry to any agent-memory system: Prove mechanism before choosing a fix. The cheap causal probe (full vs. prefix vs. tail) killed a wrong diagnosis that would have led to a plausible, useless repair.</li> Make missing data observable. The worst property of my bug was silence. The token-count guard turns the next occurrence into a warning with a filename in it. And "not measured" must render as not measured - my health check deliberately refuses to show a green tick when the data to judge is absent, because a green that certifies nothing is worse than no check.</li> Measure accepted risks; they may not exist. The broad-query trade-off survived a design review as a reasonable-sounding caveat. It did not survive twenty queries.</li> Distrust symmetric results. Identical before/after numbers mean your instrument broke, until proven otherwise.</li> Claim what you measured, nothing more. Everything above is one corpus of 129 chunks, one embedding model, twenty queries, on my machine. It generalizes as a method, not as numbers.</li> </ul> The whole investigation - diagnosis, fix, and both measurement arms - is recorded as an architecture decision record and a work plan in the project's docs, which is also why I can write this post months of context later without reconstructing anything from memory. But that discipline is a story for another post. Running parallel agent sessions without them stepping on each other 2026-07-29T00:00:00+00:00 I usually have several coding-agent sessions running at once. Sometimes on different projects, often on the same repo: one session deep in a refactor, one writing docs, one investigating a bug. Nothing about an agent harness makes this safe by default. The two failure modes show up fast: Corruption: two sessions write the same state file and one clobbers the other.</li> Collision: two sessions, blind to each other, pick up the same work or edit the same files, and you discover it at diff time.</li> </ol> These feel like one problem ("agents conflict") but they are structurally different, and in my memory system they got structurally different fixes. The corruption fix has no runtime component at all. The collision fix has no locks. This post is about both, and about the things I deliberately did not build. Corruption: solved by construction, not coordination</h2> Each of my agent sessions keeps working memory on disk: a scratchpad, a decision log, open questions. The naive layout - one set of files per project branch - dies immediately with two live sessions, and the classic answer is locking or serialized writes through a daemon. The layout that needs neither: every session writes only to its own directory, keyed by its session id. Subagents inherit the id with a suffix, so even a session's own workers cannot collide with their parent. No two writers ever touch the same file, not because a lock stops them, but because no shared file exists. At session start, a materialize step folds all sessions' entries into one read-only merged view, so a new session still reads everything that happened on the branch - stamped as historical reference, because a snapshot is stale by definition. There is exactly one exception, and it is load-bearing: a single current-task.md</code> per branch, shared by every session, last writer wins. That file answers "what is this branch about right now", which is only useful because it is shared. The design rule that fell out: share nothing by default, and when you do share, share one small file whose whole point is being the single meeting place. This solved corruption completely. It did nothing for collision - a session writing safely in its own directory can still cheerfully redo work another session finished an hour ago. Collision: sessions need to see each other</h2> The actual pain, once corruption was gone, was launching a second session into a repo blind. It did not know a first session existed, let alone what files it was touching. My fix is a presence layer: a machine-local registry of live sessions, maintained entirely by lifecycle hooks that were already firing on session start, tool use, and session end. Each record carries the branch, the files the session has touched, an optional one-line intent, and a freshness timestamp. When a new session starts, it gets a block injected into its context: 3 other session(s) live on this branch right now - avoid editing the same files: - 6679ade6 - touching channel.md, production-readiness.md (active 5m ago) - 30b9890c - touching audit.rs, audit.test.ts (active 52m ago) - c5e09075 - touching review-queue.md, CONTEXT.md (active 1h ago)</code></pre> That is most of the feature. The dominant collision case was never two sessions racing for a file at the same millisecond; it was me starting session B without remembering what session A was doing. Awareness at launch time, plus an on-demand "who else is here" query the agent can run mid-session, covers almost all of it. The part that took actual design care is trust. A presence registry is only useful if the agent can believe it: phantom peers - records of sessions that died without cleaning up - turn the block into noise the agent learns to ignore, and then the feature is worse than nothing. Session-end hooks are unreliable by nature (crashes, hard kills, dead batteries), so liveness is checked at read time against the OS: does the recorded pid exist, and does its process start-time match what the record captured? The second check matters more than it looks. Pids get reused; without the start-time match, a recycled pid makes a dead session read as alive forever, which is precisely the failure the layer exists to prevent. No locks, on purpose</h2> The instinctive design here is mutual exclusion: lock files a session is editing, deny the other session access. I rejected it, and the reasoning generalizes: The problem was awareness, not exclusion. Sessions were not fighting over files; they were ignorant of each other. Informing them fixes the actual failure. Blocking them fixes a different, mostly hypothetical one.</li> A lock is hostile to the human in the loop. These are my own parallel sessions. A hard lock means my repo tells me no when I ask a second session to touch a file the first one grazed an hour ago.</li> Advisory degrades gracefully; locks degrade catastrophically. A stale presence record wastes a warning line. A stale lock blocks work until someone hunts it down.</li> </ul> So the whole layer is advisory. It informs, it never blocks. Weeks in, I have not once wished for the lock. I also rejected the heavier alternative: a durable task queue where every session formally claims a task before touching anything. Queues answer "what is the status of this work" - a real question, but a different one. For live collision avoidance a claimed task is simultaneously too coarse ("someone is on the refactor" does not tell you which file they are editing right now) and too much ceremony (every session pays a claim step to defend against a rare event). Presence is finer and free: the hooks fire anyway. The human side: which session needs me</h2> Coordination between sessions is half the story. The other half is coordinating me. With four sessions across three projects, the expensive question stops being "are the agents colliding" and becomes "which one is waiting on my input while I stare at a different terminal". Presence records carry a state field for this: working</code> or waiting</code>. Turn boundaries drive it - submitting a prompt marks the session working, the agent finishing its turn marks it waiting. The subtlety is that tool activity alone cannot tell you this: a session that is thinking, or reading files, looks idle by every activity metric while genuinely busy. Only the turn boundary is truthful. A workbench view renders the sessions per project with a marker on whoever is waiting, and a backgrounded session going idle fires a notification. The effect on throughput is larger than the collision fix. Parallel sessions were already safe; this made them worth it, because agent idle time - finished, waiting, unnoticed - was where the parallelism actually leaked. What transfers</h2> The specifics are mine, but the shapes are portable to any multi-session agent setup: Partition state by writer; make shared files a deliberate exception. Corruption problems you solve by construction do not come back. Locks you add have to be right forever.</li> Inject awareness at start time. The dominant collision is launching blind, not racing. A cheap "who is here, touching what" block at session start beats sophisticated conflict detection you build later.</li> A registry nobody trusts is worse than none. Whatever your liveness story is, phantom entries are the death of an advisory system - the reader learns to ignore it. Verify liveness at read time, against a source that survives crashes.</li> Prefer advisory over blocking until proven otherwise. Especially when every session ultimately answers to one human.</li> Track waiting, not just working. If you run parallel sessions, the bottleneck quietly becomes your own attention. Surface it.</li> </ul> None of this needed a coordinator process, a message bus, or a database. It is a directory convention, a handful of JSON files in a cache directory, and hooks that were already firing. The boring infrastructure was the feature.