Skip to content
Tony Nguyen

Case study · Context infrastructure for coding agents

Mortise: Building a Local Context Engine for Coding Agents

A coding agent needs the few parts of a repository that matter to its task, with proof of where each came from. Mortise finds them on the developer’s machine, without a model in the loop, and hands them over as a small, budgeted packet that also says what it left out.

Role
Solo personal projectDesign, build and evaluation
Period
2026
Status
v0.1.0, unreleased, built from source. Verified on Apple Silicon macOS
Stack
Rust · SQLite FTS5 · Tree‑sitter · MCP (stdio) · Tauri + TypeScript
All work

When a coding agent starts a task, it usually spends the first several steps finding its way around the repository. It searches, opens files and rereads them. Mortise does that step for the agent, on the developer’s machine. It finds the code most relevant to the task and hands it over as a short, ranked context packet that fits a token budget. Every excerpt is tagged with its file, line range and Git state, and the packet lists what it left out.

I built Mortise on my own in 2026, with AI coding agents (Claude, Codex and Cursor) helping throughout the implementation. It plugs into Claude Code and Codex through their hooks and a local MCP server, the standard way agents call outside tools. It also carries work state between agent sessions, which is where the project began (§1), but this article is about the retrieval engine underneath.

Mortise’s strongest results are on correctness. Across its test suite, it never handed an agent code it wasn’t allowed to see, and when asked for a specific function or name, it ranked the right one first every time. Open-ended, plain-English questions are where I’m focusing next, along with filtering out outdated documents, which slipped through in four cases. The current test set is small and purpose-built, so the next step is measuring on larger codebases. Whether packets change how agents work is a separate question, and my first small experiments haven’t shown a clear effect yet. §5 has the numbers, §6 what the failures taught me and §7 what I’m testing next.

01The context problem

I started Mortise because of handoffs. I kept hitting usage limits on GPT and Claude in the middle of a task, and each time I wrote a handoff document so the next session could pick up where the last one stopped. The same thing happened whenever a better model came out. Switching to it meant writing another onboarding document and trusting that the new agent had understood the context and workflow of the old one. I wanted to switch agents, harnesses or models and keep going without that step, ideally with less context and at lower cost.

Teams have a larger version of the same problem. On a hackathon team, each person’s agent needs to know what the others changed. Today that means pulling, re-explaining the new state to the agent, or passing around a write-up of what everyone did so the agents don’t overlap.

Carrying work state between sessions is one half of Mortise. The other half, and the subject of this article, is retrieval. Whichever agent picks up the work still has to find the code that matters.

An agent dropped into an unfamiliar repository has a task description and a shell. It finds context the way a person would: it searches for words it guesses are relevant and opens what comes back. Each step costs a tool call, tokens and time, and the guesses are often wrong. A task says “exporting part of a table to HTML gives the wrong output”; the code that answers it is organised under names the agent has not seen yet.

Handing the agent more text does not fix this, for three reasons.

  • A context window is finite, and an answer can be too large to reach the model at all. In one case in §6 a client wrote a 112 KB answer to a file instead of showing it.
  • A list that has been silently truncated reads as complete, so the agent treats “not shown” as “not there”.
  • Code changes under the agent. The working tree differs from the last commit and files move, so a span is only useful if the agent can tell which version of the file it came from.

So I kept the problem narrow. Given a task, Mortise should return the few pieces of code most likely to matter and fit them into a token budget. Each piece should point to an exact file, line range and Git state, and anything that did not fit should be listed rather than silently dropped.

02Design requirements

Six requirements shaped the design. Each tradeoff in §4 serves one of them.
Latency
Cheap enough to call at the start of every task. That rules out a model call on the query path: retrieval runs in-process against a local index and should take milliseconds.
Relevance
Exact names come first: when a query names a function or type, its definition should lead. A prose query should still find the code it describes, and when nothing relevant exists the engine should be able to return nothing.
Local-first and private
Code and history stay on the machine, in one folder only the user can read. There is no account, server or telemetry, and the query path makes no network calls. Workspace membership, private notes and time bounds are enforced before anything is ranked.
Token budget
Every packet fits a budget the caller sets, counted in estimated tokens rather than with a model’s tokenizer. Code goes in as whole chunks or excerpts and is never summarised or paraphrased.
Determinism
The same index and request produce byte-identical packets. Nothing in routing, ranking or packing calls a model, so a change in output always traces back to a change in the input or the code.
Provenance and stated omissions
Each span carries its repository-relative path, line range, a hash of the bytes read, and the commit and branch observed when they were read. Anything left out is listed with a reason.

03From request to packet

Mortise has two paths. Indexing runs when a repository is refreshed; the query path runs on every request and is the part an agent waits for. Fig. 1 follows one request and shows what each stage leaves out.

Indexing, on refresh

Git working tree → Tree-sitter chunker (splits at definitions) → local SQLite index of full-text rows and symbol sites.

Request: the agent’s task text and a token budget.

  1. 1Scope

    Membership, private notes and time bounds, enforced inside every channel’s query.

    Leaves out: out of scope (not a member, someone’s private note, or outside the time bounds). Never becomes a candidate, so nothing can rank it back in.

  2. 2Retrieve

    Full-text (BM25), identifier and symbol-site channels; dense only by opt-in.

    Leaves out: unhelpful names (too common in the index, or absent from it). Recorded in the query plan.

  3. 3Fuse + rank

    Weighted RRF over ranks only, one candidate per code chunk.

    Leaves out: below the cut (ranked past the candidate limit). Counted in the trace.

  4. 4Pack

    Keeps rank order and fits spans first-fit into the token budget, without paraphrase.

    Leaves out: not packed (duplicate, no provenance, or over budget). Listed in the packet with a reason.

  5. 5Packet → agent

    Spans in rank order, each with its path, line range and Git state.

    Carries the omissions list: each skipped span with rank, reason, path, lines, size.

All on the developer’s machine; no network calls on the query path.

Fig. 1How a request becomes a context packet, and what each stage leaves out. Everything shown runs on the developer’s machine. The dashed boxes are what each stage removes and where that is reported, so nothing disappears silently. The blue box is what the agent receives.
Read Fig. 1 as text
  1. Indexing runs when the repository is refreshed, not per request: Mortise reads the Git working tree, splits files into chunks at definition boundaries with Tree-sitter, and stores full-text rows and symbol sites in a local SQLite index.
  2. A request (the agent’s task text and an optional token budget) is first scoped: workspace membership, private notes and time bounds are enforced inside every channel’s query. Out-of-scope evidence never becomes a candidate.
  3. Candidate retrieval runs several channels over the index: full-text (BM25), exact identifier and symbol sites; a dense channel exists only as an opt-in experiment. Names that are too common or absent from the index are dropped from the exact-match channels and reported in the query plan.
  4. Fusion merges the channels’ rankings with weighted reciprocal rank fusion, one candidate per code chunk, with deterministic tie-breaks. Candidates below the cut are counted in the trace.
  5. Packing walks the ranked list in order and fits whole chunks or excerpts into the token budget. Anything not packed is listed in the packet with a reason.
  6. The packet goes back to the agent: spans in rank order, each with its path, line range and the Git state it was read from, plus the list of omissions. Everything in the figure runs on the developer’s machine, and the query path makes no network calls.

Indexing. A scan reads the working tree’s current bytes through read-only Git commands and splits each file into chunks. For Rust, TypeScript, JavaScript and Python, Tree-sitter places chunk boundaries at definitions and records symbol sites: where each name is defined and where it is used. Other text files are chunked as text. A file is searchable as soon as its transaction commits.

Scope. The store can hold more than one workspace, and some notes are private to their author, so the first stage is authorization: active membership, then visibility, then any time bounds. These conditions are repeated inside every channel’s SQL query rather than applied once afterwards, so no later stage can bring excluded evidence back.

Candidate retrieval. The router picks channels from the shape of the query. Full-text search (SQLite FTS5, scored with BM25) always runs. An identifier channel runs when a token looks like code (snake_case, camelCase, letters mixed with digits) and favours likely declarations. A symbol channel looks up Tree-sitter sites, and wording such as “where is X defined” or “callers of X” decides whether definitions or uses lead. Smaller channels handle time ranges, authors and requests for the current version; the last only re-orders candidates and never adds any. A dense embedding channel is off unless the caller opts in (§4.6).

Fusion and ranking. Each channel returns its own ranked list, and reciprocal rank fusion (RRF) merges the lists using ranks alone:

score(c) = Σ  w(ch) / (k + rank_ch(c)),   k = 60
          over the channels ch that returned candidate c

k = 60 is the constant from the paper that introduced RRF (Cormack, Clarke and Büttcher, 2009). Each channel has a weight, and the exact-match channels count for more than full-text matching. A candidate that several channels agree on outranks one that a single channel ranked highly. Ties break on stable keys, so the order is total and repeatable.

The packer then fits the ranked list into the budget (§4.4). The engine does not resolve types, build a call graph or rank with a learned model. Its symbol data is syntactic, so two methods with the same name in different classes stay ambiguous.

04Engineering tradeoffs

The decisions that mattered most, each with the option I did not take and what the choice costs.

4.1Latency over relevance: no model on the query path

The usual way to improve relevance is to put a model in the loop: rewrite the query with an LLM, or rerank candidates with a cross-encoder. Both add tens to hundreds of milliseconds and make output depend on a model’s version and sampling. I kept the query path to index lookups and arithmetic. The cost is that a query worded differently from the code can miss (§4.6 covers the attempt to close that gap). In return the retriever answers in milliseconds and every decision it makes can be explained.

Retrieval tracing provides the explanation: the query plan, each candidate’s rank and score in every channel, and the packer’s decision for each. It is off by default. Turned on, it adds 0.49 ms at p50 and 0.37 ms at p95, measured over 200 runs on a small local workspace and including hashing, serialization and the file write.

4.2Local-first

Everything Mortise stores lives in one folder only the user can read. The MCP server is a child process the agent client starts and talks to over standard input and output; it opens no port, and its context tool is read-only. Network requests come only from commands that name them, such as downloading the optional embedding model or sharing to GitHub or Slack, and the MCP server makes none. The cost is that nothing is shared: each machine builds its own index, and there is no server to absorb a slow first scan.

4.3Candidate retrieval separate from ranking

Splitting the work into cheap, wide candidate channels and a separate fusion step lets each channel do one thing. BM25 scores, identifier matches and symbol-site counts are on unrelated scales. Calibrating them against each other would be a tuning project of its own, redone whenever a channel changed. RRF needs no calibration because it uses only ranks.

The harder question was what counts as one candidate. Fusion originally merged hits per evidence record, which in practice meant per file version. Several chunks of one file collapsed into a single candidate, and the chunk shown was whichever channel reported first. A review of the design before I built the symbol channel showed the consequence: a symbol hit would earn rank for one function while the packet displayed another part of the file. I changed fusion to one candidate per code chunk. A chunk that three channels find is one candidate, and two chunks of the same file compete separately.

4.4Context selection under a budget, with stated omissions

The packer is deliberately not a second ranker. It walks the fused list in order and keeps what fits:

  1. skip a duplicate of a span already included;
  2. skip anything without provenance or text, rather than send it unattributed;
  3. stop admitting items at an item limit;
  4. include the span if it fits the remaining budget; otherwise record it as over budget and keep going.

The last rule is first-fit, so one large span near the top cannot starve smaller ones below it. Leftover budget upgrades excerpts to whole chunks without adding, dropping or moving anything. Budgets are estimated conservatively from byte length, not with a model’s tokenizer. Every skipped span goes into the omissions list with its rank, reason, path, line range and estimated size, so an agent can tell “dropped for budget” from “not found”.

My first design scored each span’s utility against its size and packed greedily. I built only the part that cannot reorder anything, because a packer that re-scores candidates is a second ranking system that the trace would also have to explain. The cost is that packing does not account for redundancy between spans.

4.5Indexing and refresh

A refresh has to be cheap enough to run before a query. A scan uses the hashes Git already keeps to skip unchanged files without opening them. Chunk identity is a content hash, so moved code keeps its identity and a one-line edit re-derives only the chunks it touched. Deletions apply only when a scan completes, so a failed scan deactivates nothing.

I measured this once, in August 2026, on a synthetic repository of 1,000 Markdown files (~900 KB), with a release build on an Apple Silicon MacBook Pro. A refresh with nothing changed took 201 ms and read 0 bytes of file content; after a one-file edit it took 219 ms and read 865 bytes. The cold scan took 25.2 s, almost all of it waiting on fsync, because each file’s version, chunks and search rows commit in one transaction so a crash cannot leave a half-indexed file. A cold scan happens once per repository, so I chose durability over bulk-load speed. The files are Markdown, so this says nothing about Tree-sitter parsing cost.

4.6Why dense retrieval stayed experimental

To catch queries worded differently from the code, I added an optional dense channel: a small open-source embedding model (quantized bge-small-en-v1.5, 384 dimensions, 64 MB) run locally from hash-verified files, with an exact similarity scan over the candidates the caller may see. It raised recall (§5.3), but at first it broke abstention. On the suite’s eight questions that have no answer, the default engine returns nothing for two; with dense on, it returned something for all eight, because similarity always finds a nearest neighbour. A plain minimum similarity could not fix that: false matches scored 0.655–0.745 and relevant results 0.610–0.806, so any cut-off that removed the first also removed the second.

In September I added a guarded hybrid mode with a stricter rule for admitting results that only the dense channel found. On the full suite it kept the hybrid recall and brought abstention back to the default’s level. I still left the default lexical, for three reasons. I designed the guard after looking at individual benchmark queries, so its numbers are tuning results rather than held-out evidence. Dense retrieval costs a model install and about 11 ms more at p50. And the exact scan reached 289 ms at p95 for 50,000 chunks (release build, M1 Max), so a larger repository would need an approximate index past roughly 10–20k chunks. Both hybrid modes are opt-in and labelled experimental.

05Evaluation

I evaluate two things separately: whether the retriever behaves correctly on a known corpus, and whether agents do better with it. The first is well instrumented. The second is barely measured, and what has been measured shows no effect.

5.1Method: a small, adversarial benchmark

The benchmark, MortiseBench, builds a synthetic project from fixed inputs: two workspaces; five users, including one from the other workspace and one whose access was revoked; 25 sources of TypeScript-like code, SQL, configuration and design documents, with version history and one private note; and 75 queries, each labelled with expected, acceptable and forbidden results. The queries range from prose questions and exact identifiers to access checks, stale documents and questions with no answer. Every query runs through the same entry point the CLI and MCP server use and is scored on which evidence comes back, not on generated text.

One repetition runs on every build, locally and in CI, and fails it if any unauthorized evidence reaches the candidate set (checked before the output limit, not just in the top ten), if any candidate breaks a time bound, if a stale version outranks the current one, or if exact-identifier ranking falls below a fixed floor. Nothing gates symbol ranking or abstention.

Three metrics recur below. Recall@5 is the share of a query’s expected results that appear in the top five. Mean reciprocal rank (MRR) averages 1/rank of the first expected result, so 1.00 means it always came first. Abstention is returning nothing when nothing relevant exists.

Its limits: I wrote the corpus and the original labels, so queries may share wording with the code they target, which flatters lexical retrieval; labels are per file, so the right file with the wrong passage still counts; and 81 chunks is far too small for latency or quality claims about real repositories.

5.2The default engine

Table 1: Default engine on MortiseBench
MeasureResultQueries
Unauthorized evidence in the candidate set0all 75
Time-bound violations0all 75
Stale version ranked above the current one02
Forbidden results returned (a superseded document)4all 75
Exact-identifier MRR1.003
Symbol lookup MRR1.003
MRR, prose questions0.4138
MRR, held-out prose questions0.319
MRR, all queries with an answer0.5963
Abstention on questions with no answer2 of 88
Latency, p50 · p95 (debug build)1.30 ms · 2.02 ms75
Table 1Default engine on MortiseBench. Last recorded run, 17 October 2026: one repetition of an unoptimized debug build on an Apple M1 Max, warm and in-process, 81 indexed chunks. Latency varies with machine load: across about 110 recorded runs of this gate, p95 was mostly 1.8–3.5 ms and reached 26–67 ms while the machine was busy. An optimized build with 3 repetitions (13 September 2026) gave p50 0.54 ms and p95 1.97 ms.

I rely most on the zero counts, because they are structural: scope is enforced inside every channel’s query, and the benchmark checks that the code still does so. Determinism is covered by tests that compile identical input twice and compare the bytes. Everything else is weaker. A forbidden result is one the labels say must not appear for that query, which is a different check from access or time bounds; all four are the same superseded design document, and the stale-version gate only checks that it never outranks the current one. Perfect identifier and symbol scores on three queries each show that routing works on clean lookups, not much more. Ranking on prose questions is mediocre, and abstention is poor.

Latency on 81 chunks is a regression signal, not a claim about real repositories, and I have no percentile for a real codebase. The only real-repository timings are single readings on Mortise’s own repository (about 2,571 chunks) in August 2026: 2 ms for the slowest symbol query, and about 67 ms for a full command-line search, most of it process start and opening the database.

5.3The optional dense channel

Before tuning the dense channel I wrote down the rule for keeping it. Keep it if held-out recall@5 reaches .70 and MRR .50 with every hard gate and resource limit met. Keep it experimentally if recall@5 improves by at least .15 with the hard gates intact but something else misses. Reject it if the gain is under .10. I chose the model and fusion weights on development queries only, froze the configuration, and ran it unchanged on three held-out sets. I wrote all three sets myself with an AI coding agent and froze them before any retrieval run, so they are held out from tuning but not independent of me.

  • Default (lexical · identifier · symbol)
  • Dense only (ablation)
  • Default + dense (experimental)
Fig. 2Default vs default + dense on three frozen query sets. Frozen configuration, recorded August 2026, on the synthetic benchmark corpus. The vertical rule is the bar for a full keep. Dense only is an ablation for comparison, never a product mode.
Table 2Fig. 2 data: recall@5 and MRR by query set
Table 2: Fig. 2 data: recall@5 and MRR by query set
Query setQueriesDefault R@5 / MRRDense onlyDefault + dense
Original held-out set9.44 / .31.89 / .46.78 / .35
Second held-out set, same project20.50 / .41.85 / .74.75 / .60
Held-out set, second project12.58 / .40.75 / .56.92 / .58
Table 2Fig. 2 data: recall@5 and MRR by query set.

On the two newer sets the combined mode cleared both bars: recall@5 went from .50 to .75 on 20 queries and from .58 to .92 on 12, with no unauthorized results, no scope violations and exact-identifier MRR still 1.00. The original nine-query set missed the MRR bar (.35). Dense alone ranked a stale version above the current one in every such case of the 20-query run, since similarity has no notion of which version is current. With the abstention loss in §4.6, the verdict was “keep experimentally”.

A month later I re-ran the comparison on the full 75-query suite with an optimized build. Recall@5 rose from 0.681 to 0.853, abstention fell from 0.25 to 0.00, forbidden results went from 4 to 8, and p50 latency went from 0.54 ms to 11.4 ms. The guarded mode kept 0.853 with abstention back at 0.25 and forbidden results back at 4. On the 14 real agent queries from the experiment in §5.4, it put 11 of the 26 files the fixes needed in the top four results, against 8 for the default; a small sample, but the same direction.

What this shows

On small, frozen query sets written for this project, adding dense retrieval raised recall without breaking exact-identifier lookup or any access or scope gate.

What this does not show

Quality on a real codebase. The sets have 9 to 20 queries, so one query moves recall by .05 to .11; I wrote them; labels are per file; and the corpus has under a hundred chunks.

5.4Agent outcomes

Fuller packets, same agent. The one experiment that varied Mortise’s packets compared two builds that differed in a single feature: whether leftover budget upgrades excerpts to whole chunks (§4.4). It used 7 bug-fix tasks in a private Swift app of mine, one pair per task, with Claude Code and Opus 5 in both arms. The arms were identical apart from the binary, alternated in order, ran in fresh clones and were scored by deterministic hidden tests, with no model judge. Correctness never separated the arms. The main measure was how often agents reopened files the packet had already given them; with fuller packets it was lower in 3 pairs and higher in 4, so I found no effect. The traces show why. The extra whole chunks went to the top-ranked items, which for bug-report queries were mostly views and tests: only 3 of 29 whole chunks were files the fix needed, and agents opened the files the snippets named. Separately, 2 of 14 agent queries got empty packets (§6.2).

With and without Mortise. Earlier, in August 2026, I ran four judged pairs on two of those tasks. One arm could call Mortise and the other could not, each in its own fresh clone; the agents and the blind judge were all Opus 5. Both arms passed the hidden tests in all four pairs. The judge called three ties and preferred the run without Mortise in the fourth (98 to 87) because of how the fix was structured. In two pairs the packet contained none of the files the task needed (§6.1), and Swift is outside the languages the symbol channel parses.

What these results show

Mortise did not cost correctness in any pair of either experiment.

What they do not show

That Mortise makes agents cheaper, faster or more correct. Eleven pairs on seven tasks in one app I wrote, one pair per task in the main experiment, and a judge from the same model family as the agents are enough to find failure modes, not to estimate an effect.

06Failure modes and lessons

Each of these surfaced in a real agent run, not on the benchmark, and each changed the design.

6.1The agent’s query led with its own app name

In two of the paired runs the agent’s query began with the name of the app it was working on. The name was CamelCase, so the router treated it as an identifier, and it appeared in about 73% of the repository’s chunks. Because exact-match channels are weighted above full-text matching, it pulled in an arbitrary slice of the repository and buried the channels that did discriminate: none of the four answering files reached the packet, and the agent discarded it and grepped. Replaying one of those queries offline without the app name brought back three of the four.

What changed. Before routing, each identifier-shaped term is now counted against the index. A term that matches most of the indexed chunks is dropped from the identifier and symbol channels, kept in the full-text query, and reported in the query plan as too common.

6.2Guessed names returned empty packets

Two real agent queries came back empty: a fifty-word bug report naming a class that did not exist, and a forty-five-word one with six guessed names, two of them real. A query with identifier-shaped tokens never fell back to full-text matching, so a wrong guess meant no answer at all.

What changed. The router now records which names are absent from the index. If some are present, it routes on those. If all are absent and the query is long enough to be a task description, it runs full-text matching on the words. A short query whose names are all absent still returns nothing, because “no such symbol” is the right answer.

6.3A packet too large to reach the model

On real agent runs in September 2026, a 6,000-token packet of 20 items, sent both as text and as structured JSON, was 67 KB on the wire, and a 12,000-token one was 112 KB. The client wrote the larger one to a file instead of showing it to the model. The packer’s token count was not the cost the client saw.

What changed. The default answer is now the rendered text alone, with structured JSON available on request, and every trace records the serialized size of the response so this risk is visible per call.

Two practices came out of these. I check a query term against the index before trusting its shape, because a CamelCase word can be the app’s own name. And I measure the bytes a client receives, not the tokens the packer estimated.

07What’s open

The evidence supports a narrow claim: correct, fast, explainable retrieval on a small synthetic corpus. These are the questions it leaves open, and what I plan to test next.
  • Ranking for bug-report queries. The packet experiment showed that the budget follows the ranking, and the ranking put views and tests above the files the fixes needed. That is the first thing I would work on.
  • Latency on real repositories. I would measure end-to-end tool latency (p50, p95 and p99), cold and warm, on codebases of 10,000 chunks or more; nothing on this page was measured at that scale.
  • Better labels. Relevance would be labelled per chunk rather than per file, with query sets written and judged by someone other than me.
  • Dense retrieval at scale. The guarded mode would need confirming on queries it was not designed against, and the exact scan would need an approximate index before 10,000–20,000 chunks.
  • Agent experiments large enough to estimate an effect, on more than one codebase and with more than one pair per task.