Tensegrity

Post 0 of the Nexus series: the conceptual companion to Installing Nexus. Code is knowledge work, and the agent team needs the same knowledge as the developer to do its job.

---

As I write this, my catalog holds just over 19K documents across 72 projects. The inventory includes the source files from every repo I have open, the papers those repos are based upon, the design records explaining why each is designed and implemented the way it is. This includes the notes I wrote to myself months ago that I would not otherwise find again. When I ask a question inside any one of those repos, the agent working with me can reach all of this information as a peer.

Nexus provides a common pool of curated, dynamically evolving knowledge. The rest of this post is how this is accomplished and why I even bothered.

The problem isn’t simply that I cannot find my files. It is that every agent session starts from nothing. I explain the same architectural decision for the fourth time. An agent proposes a design we rejected in March, for reasons recorded in a document it has never seen. I paste the same three paragraphs of context into a new conversation because that is faster than explaining where they live. None of that is a model capability problem. The knowledge exists; it is just not accessible to the participants from where the work takes place.

And so in Nexus the developer and the agents read and write the same store. Not a context window one refills by hand, and not a file I have to remember to attach. There is one knowledge base, spanning every local project at once, that both parties query directly.

---

Nexus borrows its architectural shape from the familiar computer memory hierarchy: registers, cache, RAM, disk; each tuned to a different lifetime and access pattern. Three tiers do the same work here. T1 is scratch, alive for one session and shared across every agent in it. T2 holds project state: decisions, plans, corrections that outlive the session. T3 is permanent knowledge across every project the catalog tracks. All three live in PostgreSQL, with pgvector for the embeddings. Agents cooperate by reading and writing the same tiers rather than by talking to each other, which means no agent needs to know another exists.

What goes in is whatever the work is already producing. Decisions live in research-design records and function as the active interface between the agents and people driving the system. Prior art lives in papers and other project repos. Architecture lives in long-form designs, plans and post-mortems. The work lives in planning documents, analysis, design and ultimately tracked and pursued with bead chains. Corrections from past sessions live on as standing rules. Curating an evolving design means keeping all of that reachable, which was true before agentic coding and is extremely hard to ignore now: I can reconstruct context from memory and a fresh agent instance cannot do the same.

Of course, none of the underlying ideas in Nexus are new. Software engineering as knowledge work has a well-established foundation; document management, hypertext and link-graph navigation, decision-record practice: each has decades of literature behind it. What changed is that embedding models, agents that coordinate through structured calls, and vector databases that run on a laptop all got good enough at roughly the same time. Composing them end to end used to take a team of librarians and infrastructure engineers. Now it takes one developer and a weekend, repeated for a year.

The surface

What the developer, the team, and the LLM agents do on Nexus (repeatedly, in any combination, often interleaved) collapses to five activities:

• Gather. A question lands and Nexus returns the right slice of the corpus: source files, decision records, prior art, plan templates, contributing notes, post-mortems. Tens of thousands of chunks across half a dozen indexed projects narrow to the hundred or so that actually apply. Filtering is Nexus’s job, not the developer’s.
• Hypothesize. A working idea is scratched into session memory before it is fully formed. The agent team picks it up, looks for evidence and contradictions, brings it back sharpened or replaced. The conversation acquires structure without form-filling.
• Track facts. From any document, typed edges show what depends on it and what it depends on: cites to prior art, implements to source files, supersedes to the older version of a decision the newer one replaces. Provenance is one hop away, not five searches and a guess.
• Synthesize new ones. Research findings, design rationales, post-mortems, plan templates: each is written back the moment it crystallizes. The next session reads it on first call. New facts join the same graph everything else lives on.
• Integrate. The catalog densifies, the plan library learns, RDRs supersede prior RDRs, the topic taxonomy reshapes itself. The store evolves with the project. Nothing has to be migrated, re-explained, or rebuilt.

These five are not solo activities. The developer initiates them; the agent team carries them out alongside; Nexus keeps the state visible to both. Everything else in this post (and most of the rest of the series) is what makes the five activities usable in practice.

The cross-domain reality

Taking the working catalog I keep across these projects as an example, a typical day moves through several kinds of indexed content, in no particular order:

• Code: 15,428 source files, AST-aware, language-classified, embedded for code-aware retrieval.
• Decision records (RDRs): 278 RDRs across the active projects, 201 of them in this one repo. Each RDR cites prior RDRs, links to its implementing code, and is tracked by a bead with a status.
• Research papers: 107 indexed papers (Xanadu, AgenticScholar, BFT-SMR, schema-evolution literature, ChromaDB internals, and others).
• Knowledge notes: 421 stored findings, post-mortems and long-form designs that knit cross-cutting concerns together.
• Prose: 3,084 documents covering contributing guides, READMEs, RDR templates, and blog drafts (this post included).
• Plans: 19 saved templates in the T2 plan library, alongside the bead graph that tracks ongoing work.
• Standing rules: 86 feedback notes that distill prior corrections into permanent guidance loaded at the start of every session.

Working on the code is not “look at the code.” It is navigating across all of these at once. A query like how does plan-match-first retrieval work pulls from RDR-078 (the decision), src/nexus/operators/dispatch.py (the implementation), the AgenticScholar paper (the prior art), and the test suite (the contract). A code review needs to know which design was being implemented, which alternatives were considered, and which requirements are in force. A plan template should know which paper its strategy came from. A critique should know whether a proposed change quietly supersedes a prior decision.

This is exactly what knowledge-management systems are usually for. The perhaps non-obvious bit (e.g. source-graph obviously knows) is that it is also what code work is, once you stop pretending the source tree is the whole picture.

Finding the signal

Storage and lookup is not the hard part. Organization is. A few indexed projects produce tens of thousands of chunks across code, prose, RDRs, papers, and the residue of failed experiments. Signal-to-noise drops as the corpus grows. Nexus layers a knowledge graph over the semantic store and uses it to filter aggressively, recovering signal as the corpus scales instead of losing it.

• Typed links knit decisions to code to research. A query that lands on RDR-078 can follow implements edges to the source files that satisfy it, cites edges to the papers that informed it, and supersedes edges to the prior RDR it replaces.
• Taxonomy assignments cluster topics across collections, so “membership churn in BFT systems” surfaces the relevant papers regardless of which corpus they were originally indexed under.
• Catalog metadata routes queries by author, content-type, subtree, or follow-link, pre-filtering the search space before any embedding work runs.
• The plan library learns which retrieval shapes work for which kinds of question, so paraphrases of what tradeoffs are called out across Arcaneum’s RDRs all land on the same operator chain.
• Plan DAGs (the multi-step operator chains covered in detail in Post 5) run as pipelines that search, cleanse, amplify, and winnow as they go. A single query can fan into retrieval, follow typed edges to related material, extract structured facts, rank by relevance, then summarize. Each step shrinks the working set and sharpens it; signal accumulates across the chain, noise does not.

The point is to surface the right slice on demand, not return everything that vaguely matches. A handle on the knowledge, structure to model it, tools to find what is needed when it is needed: that is what makes the cross-domain corpus useful instead of overwhelming.

The experience

The asymmetry between the developer and the agent is most easily seen on the agent’s side. An LLM agent has a finite context window and no privileged view of the codebase. To find anything, it has to read into context, and naive file-reading wastes most of its budget on material the question did not need. Without indexing, there is no good way to ask what code implements RDR-078: the agent walks the filesystem, opens files, scans for patterns, and burns context on material it then has to discard. The agent has to sip from the corpus, not gulp.

The developer has the same problem in slower motion. IDEs and LSPs offer real tools (go-to-definition, find-references, language-aware refactoring) but with their own friction: cold-start cost, language coverage, cross-repository limits. For prior art outside the open project (papers, RDRs from a sibling repo, a half-remembered design conversation), there is no LSP equivalent. Web search returns the wrong granularity; grep returns syntactic matches without meaning.

Nexus closes the asymmetry by giving developer and agent the same access. Semantic search across code, prose, RDRs, and papers, by intent rather than exact strings. Typed-edge traversal across all of those: find what implements this, what cites it, what supersedes the older version. Symbol-aware navigation and AST-aware chunking for the structural precision LSPs already do well, layered alongside the semantic side rather than competing with it. The agent sips precisely from the slice that matters; the developer skips the mechanical scavenger hunt and gets to the question they were trying to answer.

The agent team

The LLM agents that help with the work are not solo assistants. They are a team, and their roles map to the five activities. Six agents do most of the lifting on this project: deep-research-synthesizer (gather and synthesize from papers and prior decisions), strategic-planner (turn intent into phased execution), plan-auditor (test the plan against the live codebase), developer (implement with TDD discipline), code-review-expert (critique the implementation), and substantive-critic (argue with the design at the gate).

The team is dispatched through skills, not summoned one at a time. Across 2,308 recorded sessions, 820 Agent dispatches were logged; roughly 2.6 of those are critique-or-review for every generation dispatch. The team does not produce first drafts. It argues over them.

The agents do not coordinate with each other in plain English. They leave state in the store (a hypothesis in T1 scratch, a finding in T2, a linked document in T3) and the next agent picks it up from there. The store is how the agents talk to each other; the conversation is how the developer talks to the whole arrangement.

The tiers, briefly

The three storage tiers carry the five activities (gather, hypothesize, track, synthesize, integrate) across different time horizons. Different lifetimes, one cooperation rule: every agent and the developer read from and write to the same store.

• T1 is within-session coordination state: the working hypothesis, the active context, the operator’s intermediate output. Lasts as long as the conversation does.
• T2 is project-scoped persistent state: standing rules, plan templates, research findings against open RDRs, relevance logs.
• T3 is cross-project semantic memory: code, prose, RDRs, papers, knowledge entries, architecture docs. The catalog and its typed links live here; semantic search runs against it.

The shape is intentional. T1 being ephemeral is what makes within-session coordination cheap: agents write freely, knowing the scratch disappears with the session. T2 being project-scoped is what keeps standing rules and plan templates persistent without polluting the cross-project semantic index. T3 being long-lived is what lets a paper indexed for one project answer a question on the next. Each tier is tuned for the work it carries.

Installing Nexus showed the CLI for these tiers (nx scratch, nx memory, nx store). The agent team’s MCP calls reach the same store from the other side. The five activities work because both interfaces land at the same place: nothing is passed between agents in chat messages; everything is left in the store for the next reader to pick up.

A vector store on its own returns documents. With the catalog, the typed-link graph, and the plan library on top, you get the right document at the right point in the work, not just a list of matches.

What the rest of this series does

The series opens up Nexus one piece at a time, each piece tied back to how it gets used in actual work:

• Post 00: Installing Nexus: the install walkthrough and short tour, the practical companion to this post.
• Post 1: Nexus, by example: a worked session against the Delos corpus showing the moving parts cooperating on a real research question.
• Post 2: Typed links and the catalog: the graph that knits the corpora together.
• Post 3: Decisions as indexed data: RDRs as first-class graph nodes, not static markdown.
• Post 4: Plans, not replanning: the plan library as a growing asset, not a maintenance burden.
• Post 5: Operators as building blocks: the DAG primitives that compose into reusable analytical flows.
• Post 6: The substrate, measured (forthcoming): what 2,300+ sessions show the system actually doing.

Each piece in the series exists because real work would otherwise drop something on the floor: a decision uncited by code, a paper unlinked from a plan, a critique that runs without knowing which prior critique it is contradicting, a rule the agent team has to relearn every session.

Up next

Post 1: Nexus, by example: a session through the Delos corpus, with the agent team and the knowledge tiers visible at every step.

Previous in the series

Post 00: Installing Nexus: the install walkthrough that put Nexus on your machine.