The Repo Is the Context

We kept watching the same thing happen.

An agent would open a repo and start hunting. It would search for something it couldn't find, read files it had no reason to open, and slowly reconstruct a mental model of the codebase one expensive token at a time. Then the session would end. The next agent would arrive with no memory of the last one and do the whole thing over again: the same searches, the same dead ends, the same files opened for no reason.

At some point the framing flipped for us. We started by treating the context window as the place where understanding lives and then we moved on and tried using plans and specs, but plans and specs quickly go stale. But the understanding the agent was reaching for was already sitting in the repository, in the folder structure, the file names, docstrings and comments, and what we'd chosen to surface and what we'd buried. The repo itself acts like an extended context. Every decision we make about how code is organized has a downstream effect on whether an agent can find its way around it. We just weren't designing for that reader.

Lexibrary is our attempt to take that idea seriously. It is open source, it is early, and we want to be clear up front about what it is and isn't: a contribution, not an answer - something we hope helps anyone experimenting with AI engineering get closer to one.

The obvious objection arrives before you finish that last paragraph: agents already have grep and file search, and there's a whole industry doing retrieval-augmented generation over source code. Why not throw better retrieval at the raw files and be done with it?

We think retrieval is a complement, not a competitor - and we built Lexibrary because we kept noticing where retrieval alone runs out of road. RAG works well on a clean, well-understood codebase. It works less well as repos get bigger and older, and it degrades fastest under the exact condition that is becoming the norm: codebases increasingly written by agents. Each agent tends to solve a problem its own way. Without a shared structure to build into, those individual solutions accrete into spaghetti, and retrieval over a mess returns a mess. The repository gets harder to understand precisely as more of it gets written.

So the problem we're actually chasing isn't only today's token waste. It's entropy over time. We wanted a structure that agents build as they build the code, a layer that stays legible to the next agent instead of decaying with every change. Think of Lexibrary less as a replacement for RAG and more as a newer relative of it: a stepping stone toward a future where agents can work in a codebase over the long run without leaving it messier than they found it.

Lexibrary reads your source and produces a .lexibrary/ directory of structured knowledge that lives alongside the code, in plain Markdown and YAML, version-controlled, backed by local SQLite indexes, with no external infrastructure to run. The pieces that matter:

• Design files. A generated, human-readable summary for each source file - what it does, its interface skeleton, links to related concepts. The distilled context an agent needs before it opens the file, so often it doesn't have to.
• Two graphs. A file-level link graph (who imports what) and a sub-file symbol graph (which functions call which, what inherits from what, which classes compose which, what an enum's members actually are). Where retrieval gives you fuzzy similarity, these give you exact edges; lexi trace walks a call chain instead of guessing at one.
• A memory that survives the session. A built-in Stack Q&A records solved problems and the approaches that failed, so the next agent doesn't re-walk a dead end. Lightweight "I was here" breadcrumbs hand off unfinished work between sessions. This is the part that directly answers the thing that started it all - agents with no memory of each other.
• A human/machine split in who owns what. The generator captures structure; people (and agents) layer intent on top as durable rationale. Change detection is built so that regenerating the structure when code changes never silently clobbers the intent someone wrote by hand. Getting that boundary right was genuinely fiddly, and it's the kind of thing we'd want a careful engineer to notice.

The agent gets its own, smaller CLI. There are two command-line surfaces: lexictl for maintainers, and a deliberately lean lexi for agents that exposes only the commands an agent needs while coding. This is partly about focus, but it's also context economy taken to its logical end. A sprawling CLI is itself a tax; the moment an agent runs --help, all that surface area floods its context window. A tool whose entire purpose is to stop agents from wasting context has no business wasting it. So the agent's surface is small on purpose.

The hardest problem was verbosity. Too much information curdles into noise. But too little is also noise: context that lacks enough signal to actually help is just waste wearing a different name. Every design file lives on that knife's edge, and most of our hard engineering went into staying on it. It shows in the unglamorous parts of the changelog: a filter that drops generic, hedging warnings that carry no real signal; a hard cap of three tags per file; prompt work that forces a specific invariant or symbol instead of a vague summary. Calibrating signal against noise isn't only the product's purpose. It was the discipline we had to practice to build it.

At the time of writing, Lexibrary is currently at version 0.7.0, roughly three and a half months of work, a couple hundred test suites, and a tool we use on our own repos every day, including on itself. It is also early, and we'd rather tell you the edges than paper over them. It is Python-centric today; TypeScript and React support is recent and still maturing, and other repo shapes will need work. We've seen anecdotal improvement using it on our own code. We have not yet run formal evaluations. The entropy argument above is a reasoned bet from people living with the tool, not a benchmarked result - and we think knowing that difference is itself part of doing this well.

Right now, Lexibrary meets us where we are: messy repositories organized by humans, for humans, that nobody is going to refactor for the benefit of a machine. It's a legibility layer for the world as it exists. But the further we go, the more we suspect the real shift is upstream: that in an agent era the repository becomes a context-engineering surface you design on purpose, with agent needs treated as a first-class concern rather than an afterthought. Lexibrary is the first artifact of that suspicion.

We don't think we've found the answer. We think we've found a useful step along the road while the rest of us figure it out. The code is open if you want to take a look.