Alexandria is the coding harness underneath nearly everything else on this site.

It keeps AI coding sessions oriented across a machine with many projects, thousands of relevant files, several incompatible working surfaces, and a hard context limit. A new session needs to know which documents matter, what each one is for, whether the map still matches disk, and what the previous session was doing—without beginning every conversation by pasting the entire workshop into the prompt.

The harness has three named layers:

· Alexandria is the catalog: one useful description for every managed file.

· MCP is the local serve surface: tools that let a session inspect the catalog and fetch only the references it needs.

· Relay is the file mailbox between two coding seats that otherwise have no push channel.

They are one system. The catalog makes the map cheap. MCP makes it selective. Relay carries work across the process boundary.

Context is RAM

The operating assumption is that a model’s context window behaves more like memory on an embedded target than like a notebook with inconvenient pagination. It is finite, budgeted, and expensive to fill with anything that is not the current job.

I run context-full and end early: boot, work, leave a handoff, stop. A fresh session should be able to recover the live frame quickly enough that replacing a tired context is cheaper than dragging it forward.

The naive solution is a file tree. On this machine that would expose more than three thousand reachable paths with no explanation of which one is the live specification, which is a superseded report, and which only shares an attractive filename. Opening enough files to learn the tree spends the budget the tree was meant to preserve.

Alexandria pays for comprehension once, when a file changes. At read time the session receives compact one-line descriptions and opens only the few documents required for the work. A recurring token cost in the scarce resource becomes a one-time local compute cost in the cheap resource.

The library is disposable; the books are not

The name comes from the Library.

Each managed root has a manifest describing files inside the serve boundary. That manifest is a derived cache, not a second source of truth. Disk is canonical. Delete the catalog and the system rebuilds it from the stacks.

Freshness is based on the content hash, not modification time. Timestamps move when a file is copied, restored, or touched. They can claim change where none occurred and miss meaningfully different bytes after a bad restore. The write path and the read-time verifier use the same streamed SHA-256 helper, so they cannot quietly disagree about what counts as the file.

The watcher is the promise that the map stays current. Read-time hash verification is the proof. If the watcher died during a reboot, the next session asking for the tree should discover drift instead of receiving a confident description of a world that no longer exists.

Manifests, route hints, heartbeat state, and log trims are written atomically. No reader should ever observe half a catalog.

Filer: watch the useful three percent

The first recursive watcher monitored nearly everything beneath each project root. Roughly ninety-eight percent of that population was junk for the harness: dependencies, caches, build output, archives, and boundaries the coding sessions should not cross. The watcher livelocked and became effectively deaf.

The current Filer applies ignore and serve boundaries before it installs directory watches. In the August 31, 2026 census, the configured roots contained 117,992 files. Sessions could reach 3,251. Of those, 2,711 were the right type to describe and 2,703 already had a one-line account. Alexandria does not “index 117,992 files.” It intentionally ignores about 97.2% of them.

The daemon responds to content changes, validates the file is stable, and either describes it deterministically or summons a one-shot coding agent to read that file and return one line. The describing intelligence is dismissed after the file. It does not remain resident long enough to build a private mythology about the project.

Failure is cause-specific: timeout, launch failure, empty output, unparseable output, model error, invalid line. An earlier version collapsed those into one generic failure and left files stuck for a week with the diagnostic evidence destroyed at the moment it mattered.

Rate caps make runaway structurally impossible. A merely capped file does not consume a failure attempt. Three genuine failures retire the item from automatic retry and put it on the visible operator surface.

Pruning in both directions

Early catalogs only appended. Files that disappeared from disk remained in the index as ghosts. Files that moved outside the serve boundary remained described even though no session could fetch them.

The current system prunes both directions.

Targeted delete handling rechecks absence because a move-with-overwrite looks like delete-then-create at one path; a naive handler can erase a live entry inside that window. A startup sweep catches files deleted while the daemon was down and files still present on disk that have moved outside the boundary without producing a filesystem event.

The first measured sweep removed 122 phantom entries—95 genuinely gone and 27 boundary-pruned—in about a second and without spending a model call.

Librarian: selective context, verified at the door

The Librarian is a local Python MCP server registered with the desktop coding environment. It is read-only.

A session can request an annotated tree, fetch a document or one section, boot from a configured set, or re-anchor against files whose hashes changed since the session began. The universal floor is deliberately small and section-addressed. An unknown session fingerprint fails loud and returns the full floor rather than pretending it knows what the caller has already seen.

Serve and maintenance are separate process planes. The Filer, router, and dashboard share one lifecycle. Desktop-owned Librarian processes share another. Restarting the dashboard should not be narrated as restarting the thing serving a live session.

That boundary matters operationally. One mixed-version incident survived a normal desktop shutdown because orphaned serve processes remained. The dashboard now reports the live fleet’s own version rather than parsing version text from files on disk. On August 31 it observed twelve Librarian processes, all agreeing on version 2.22.

Router: automation stops at uncertainty

New documents arrive in a drop folder. The Router classifies them against configured destinations and learned hints.

When it is confident, it files the document. When it is not, it asks. The human correction is not merely a manual move; it becomes a teaching event. The system stores both an exact file signature and a coarser type/project hint. A later correction can overwrite a stale hint in both directions, so the router can unlearn as well as learn.

The dashboard calls the same routing functions as the daemon. A second classifier inside the UI would be architectural drift, even if both implementations were locally correct.

This is one of Alexandria’s governing habits: automation stops where certainty stops, and correction changes the machine rather than creating an exception only a person remembers.

Relay: a mailbox, not simulated telepathy

Two coding seats on this machine cannot send messages directly to one another. One works against local disk. The other occupies a cloud-shaped environment that cannot be pushed into. The early instinct was to automate the gap with hooks, couriers, and an overwatch board.

That machinery was built, tested, and deleted.

Relay is intentionally simpler. Each project arc has folders for messages going to each seat and an archive for what has been read. The filename identifies the author. The folder identifies the recipient. Sequence gaps are harmless; duplicate sequence numbers are forbidden because they destroy message identity.

A person or a session moves the files. Nothing silently speaks on another agent’s behalf. #relay means check the mailbox now; it does not grant the mailbox authority over the work.

The deleted Observatory matters. A dashboard that attempted to show both sessions on one screen created a second culture of session stamps and snapshots around a problem the mailbox already solved. Its ports are retired. If they answer, that is an incident, not a feature returning.

The dashboard refuses a headline number

Alexandria’s local dashboard exists to catch the catalog lying.

It separates total files, reachable files, describable files, described files, pending work, and given-up work. On August 31 the catalog reported 18 configured groups, 14 watched groups, 5 pending items, and 5 retired after repeated failure. Two drifted descriptions meant the identity did not collapse to a clean 100%—and the board showed the mismatch rather than rounding it into a green badge.

That is not an aesthetic preference. A healthy-looking line once survived a ten-hour outage because the graph was hardcoded. Activity masqueraded as health. The replacement measures correctness: whether the process is live, whether hashes agree, whether pending items have a named reason, and whether the count’s numerator and denominator describe the same population.

Dogfooded infrastructure

Alexandria is live and used every day across the projects it catalogs. The sessions that modify the harness boot through it, fetch its own references, route its own handoffs, and use its dashboard to catch the map drifting from the files.

That recursion is the proof that matters. The system is not a concept for how AI-assisted development might retain context. It carries the context of the sessions that keep building it.

The open work is equally explicit. Session fingerprints are still in memory; persistence beyond the first re-anchor phase is unbuilt. A handful of descriptions remain pending or retired. A validated one-line description can still be wrong about a byte-identical but semantically different document, and at least one such error remains visible rather than covered with a path-derived guess.

The catalog is useful because it is cheap to trust and cheap to destroy.

The files remain the truth.