Typed links and the catalog

A steampunk-styled person holding a glowing holographic map in a flooded industrial building

Post 2 of the Nexus series: the graph that sits next to the vector store.

Revised August 2026: the storage substrate has moved since this post first ran (PostgreSQL and pgvector everywhere; ChromaDB and SQLite retired). Transcripts, numbers, and internals below are re-run against the current system.


The catalog

In Xanadu did Kubla Khan / A stately pleasure-dome decree…

The Nexus catalog is a metadata layer that sits alongside the vector store, tracks every indexed document, and carries typed links between them. It’s what turns the flat vector store from Nexus by Example into a navigable graph. The thesis of this post: the graph itself is just a substrate. What makes it useful is being able to walk it with an LLM doing real semantic work at every hop. The links are the rails. The model is the engine.

A vector collection is a big bag of chunks. Each chunk is a little piece of a document with an embedding attached. Very good at “find me chunks near this query in vector space.” Not so good at “find me the document this chunk came from,” “what cites this paper,” or “what RDR governs this module.”

The catalog fills in that second class of questions. Three layers:

  1. Documents. One row per indexed source file: title, author, year, content type, file path, collection membership, chunk count, index time, source mtime. Nothing exotic. It’s an index-card system for the bag of chunks.
  2. Typed links between documents. Edges like cites, implements, implements-heuristic, supersedes, relates, comments. Each link records a named relationship from one document to another, along with a created_by field that says which tool or person wrote it.
  3. Topic assignments. HDBSCAN clusters over chunk embeddings, labeled by Claude Haiku, joined back to the catalog so each chunk carries a “what is this about” tag and each topic carries a human-readable name. Where links are declared, topics are discovered, but both end up as catalog metadata you can filter, scope, and traverse against.

Documents, links, and topic assignments all live in one Postgres database owned by the storage service. The client speaks HTTP to that service and never SQL.

That is not what this post said when it first ran, and the change is worth stating rather than quietly editing. The original design kept the source of truth in JSONL files on disk, commit-friendly and git-trackable, with a disposable SQLite and FTS5 cache on top for fast queries. It was pleasant to reason about. It did not survive more than one process writing at once, which stopped being an edge case the moment a CLI, an MCP server, and a tree of agents all touched the same catalog in the same session. nx catalog init, setup, sync and pull still exist as commands, and all four now do nothing but tell you the service owns the catalog.

Here’s the current state of mine:

$ nx catalog stats
Owners:    72
Documents: 19323
Links:     2813
Chunks:    279998
By type:
  blog_post    1
  code         15425
  design_note  1
  knowledge    421
  markdown     1
  paper        107
  pdf          5
  prose        3084
  rdr          278
By link type:
  cites        126
  comments     6
  extends      3
  implements   2519
  implements-heuristic 2
  relates      151
  same-as      3
  supersedes   3

When this post first ran, that link count was 16651, and 15490 of those were implements-heuristic: machine-generated edges from code to RDR based on module-name overlap. I said at the time that I would come back to why the distinction between heuristic and curated matters. It resolved itself, in the least graceful way available. The heuristic edges turned out to be a flood rather than a corpus: graph traversal was ignoring the flag that was supposed to exclude them, so every default walk was pushing past fifteen thousand guesses to reach a few hundred facts. The generator that produced them is now demoted to nx catalog suggest-links, which shows you what it would propose and writes nothing. Two of those edges survive, and I have left them alone as a fossil.

So the graph lost 83% of its edges while its document count grew by two thirds, and it is better for it. The curated implements edges more than doubled over the same period.

I want to be careful about what that number means, because I got it wrong myself before measuring. Fewer links here is not the residue of a cleanup I performed. It is the natural ceiling of the mechanism: these generators link a code file only when some RDR or prose document names its path in text, and most code files are never named in prose. Running every generator over the entire corpus today adds 133 links. Not thousands. The graph is small because the honest edges are few, not because I have been neglecting it.

If you want to follow along, Post 00: Installing Nexus is the install + first-tour walkthrough. Once you have indexed a repo you’ll have a catalog of your own, and nx catalog gives you every command below.

One thing to be clear about before the transcripts start, because it would otherwise waste your time. Every identifier in this post is local to my install. 1.1.838 is a document in my store, 1.3 is my Delos checkout, and the counts are my corpus on the day I re-ran them. None of it is a shared dataset you can query. Your 1.1 will be whatever repo you indexed first, and your numbers will be your own. What transfers is the shape: an address with a prefix you can scope by, a typed edge with a provenance stamp, a count you can check against your own tree. Read the tumblers as placeholders and the commands as real.

Tumblers

A catalog entry is a single indexed document (one source file, one PDF, one stored knowledge entry) with its chunks living below it in the vector store and its links living above. You don’t create entries by hand. Every indexing pathway registers them as it goes: nx index repo registers each classified file it walks, nx index pdf registers the paper, the MCP store_put tool registers whatever an agent writes into the knowledge store. The catalog row gets filled out as a side effect of the work you were already doing.

Each entry has an address. Those addresses are tumblers: hierarchical, dotted, variable-depth. A tumbler looks like 1.653.63 or 1.1.838. The leading 1 is the store; every nexus deployment is its own store, and the whole address space hangs off it. The plan is for 1 to come to mean local: this nexus, this machine. Other values will identify other nexus instances once federation arrives, so an address like 7.17.14 would point at owner 17, document 14 over in some remote store you’re talking to. Today every nexus just sees its own data and runs as store 1; the segment is reserved headroom. The middle segment identifies an owner under that store (usually a git repo, sometimes a curator account), and the trailing segment identifies a document within the owner’s namespace.

Owners get their numbering the first time something under them is registered. The first repo I indexed got owner number 1 (so prefix 1.1), the second got 1.2, my papers curator account got 1.9 when I started indexing PDFs that didn’t belong to any repo. Within an owner, document numbers are allocated sequentially as entries arrive, so 1.3.7 is the seventh thing the catalog ever saw under Delos, in registration order, not topical order. There’s no central authority handing out numbers; each store computes max(existing) + 1 against its own catalog when a new entry shows up.

I picked tumblers over opaque UUIDs for two reasons. The first is room to grow. Today’s 1.1.838 is the truncated form (store, owner, document), with the rest of Nelson’s scheme (versions, intra-document spans, link element type) sitting at implicit zeros that the catalog doesn’t bother to store yet. As nexus learns what semantics it actually needs, those segments come back online without renumbering anything that’s already in the catalog. A UUID is a sealed string; a tumbler is a tree I can extend.

The second reason is that the addresses already carry meaning and can be chunked. A UUID does the identification job fine; a tumbler does that job and hands me its neighborhood for free. 1.1.838 is the same owner as 1.1.839 and lives in the same tree as everything under 1.1, and I can ask questions in those terms without joining anything.

They also compose. You can ask “give me every entry under 1.3” and get the whole Delos neighborhood, not just one document. That’s subtree-query, and it’s what makes the catalog useful as a second index rather than just a graph.

$ nx catalog owners
1.1      repo       nexus
1.2      repo       ART
1.3      repo       Delos
1.4      repo       BFDB
1.5      repo       Kramer
1.6      repo       claude-code
1.7      repo       scheme-evolution-research
1.8      repo       mempalace
1.9      repo       ext-apps
1.10     curator    nexus

Repos and curators both live in the same address space. From there:

$ nx catalog list --owner 1.3 -n 8
1.3.1000     code       ByzantineDetectorBlsEnhancementsTest.java
1.3.1001     code       Phase1B3Health.java
1.3.1002     code       Phase1B3HealthProvider.java
1.3.1003     code       Phase1B3HealthTest.java
1.3.1004     code       CHOAMTransitionRecorder.java
1.3.1005     code       GenesisTransition.java
1.3.1006     code       CHOAMTransitionRecorderTest.java
1.3.1007     code       KeyRegistrationServiceImpl.java

  Next page: --offset 8

That’s eight of several thousand entries under Delos. It is also a fair illustration of something I did not expect when I first wrote this post. The original run of this listing showed curated titles: “Technical Debt Remediation”, “Subdomain Lifecycle API”. Today it shows filenames. I accumulated those titles by hand over a couple of years; the catalog they lived in has been rebuilt since. What you get from indexing is what indexing can derive from a file, which is the filename. The graph and its metadata are only as rich as the mechanism that produces them, and re-registering a corpus does not restore what a person once typed. If I want to scope a search or a traversal to “all of Delos and nothing else,” the tumbler prefix gives me that scope in a single predicate, no join required.

All of that is about location: where in some catalog’s organization a document sits. The other identifier nexus uses is the opposite shape. Every chunk also gets a SHA-256 of its text (twice a UUID’s length, locally computed, identical everywhere the same content appears). It’s content-addressed and indifferent to organization: the same paragraph indexed in three different repos under three different tumblers hashes to the same string in all three. Tumblers organize. Chunk hashes identify. The two answer different questions, and the rest of the post leans on both.

The name, in case you’re curious, is from Ted Nelson’s Xanadu project. There a tumbler is the hierarchical identifier of a document, or of a span within one. Nelson’s chapter on the subject in Literary Machines is called “Tumbling Through the Docuverse,” which is a better title than anything I am going to come up with for the rest of this post. Nexus borrows the concept because Nelson got this part right, and it’s a shame it never made it into the mainstream web.

Typed links

A link in Nexus is an edge between two tumblers with a type and a creator. The type is just a string. Nexus ships with eight built-in types I added because I knew I’d need them early; anything else that any agent or tool wants to mint is allowed. Six of those eight show up in my catalog today:

  • cites: paper A cites paper B. Populated by the bib enricher on nx enrich, matching Semantic Scholar paperId references against the IDs it already has in the catalog. Only fires when both ends are enriched.
  • implements: this RDR implements that code file. Populated by a filepath extractor that scans RDR prose for src/... paths and matches them against registered code entries by path.
  • implements-heuristic: the weaker version of the same idea. Populated at index-time by module-name overlap between a code file and an RDR title. Useful as a hint, not as truth.
  • supersedes: this document replaces that one. Rarely set automatically; mostly hand-added when I retire an RDR in favor of a new one.
  • relates: the catch-all for “these are connected but I don’t want to claim more than that.”
  • comments: an annotation attached to a document rather than a claim about it. Six of these, all agent-written.

The remaining two built-ins, quotes and formalizes, sit unused. They are there because I expect to want them, not because anything writes them today.

The more interesting entries are the two in my catalog that Nexus never shipped at all. extends and same-as each have three edges, minted by agents that wanted a relationship the built-in list did not offer. Nobody added them to a schema and nobody asked me. That is the argument for keeping the type an open string, and it is the only part of this section I did not have to write on purpose.

The thing worth naming, though, is that nothing rests on the specific list. Adding a new type is just nx catalog link --type my-new-type FROM TO. No schema migration, no enum to update, nothing to deploy. If a research agent wants to record disagrees-with between two papers, it can. If a code-review subagent wants to record obsoletes-after-refactor from a test to a module, it can. The link type is open vocabulary, the same way a folksonomy is open vocabulary, and I expect the catalog’s working set to grow over time as agents and workflows mint relationships specific to whatever they’re doing. Queries downstream can then ask for those types by name and get a useful answer.

Each link also carries a created_by field. Auto-generators show up as bib_enricher, filepath_extractor, index_hook, auto-linker, and so on; agent-authored links come back with whichever skill or subagent was in charge when they were written. That’s how I can ask “show me every link the bib enricher created across the whole catalog” and get a clean answer, without having to diff timestamps by hand.

The heuristic-vs-curated distinction matters most during traversal. implements-heuristic links are guesses based on surface features, and I treat them as hints: starting points for a human or agent to confirm. implements links are precise: they came from an actual src/... path parsed out of RDR content, which existed on disk at the time of indexing. When I’m walking the graph to answer a question like “what decided this module’s shape?”, I prefer curated over heuristic, and the type field lets me filter accordingly.

Here are the four supersedes links currently in my catalog, as an example of what curated decision-history looks like:

$ nx catalog links --type supersedes
1.14.6 → 1.12.34 (supersedes) by deep-research-synthesizer
1.11.366 → 1.11.360 (supersedes) by session-2026-07-28-critique
1.11.367 → 1.11.360 (supersedes) by session-2026-07-28-final

Three edges, each with a provenance stamp. The first was written by the deep-research-synthesizer subagent; the second and third by two different passes of the same session on 2026-07-28, one a critique and one a final, both retiring the same earlier draft. That’s the level of attribution I want on every link in the graph. Not because I’m going to audit most of them, but because when a link turns out to be wrong, I want to know what wrote it and when.

Spans that outlive chunking

Citations in Nexus don’t point to passage numbers. Passage numbers lie: re-chunk a document with a new chunker and every passage-number citation becomes wrong. Instead, citations point to a SHA-256 of the exact chunk text. That’s a chash: span.

When nx_answer grounds a claim in evidence, the citation comes back looking like chash:94a0aead8d13eddf.... To resolve a span later, I look up the hash in the catalog’s chunk index. Three outcomes:

  1. The hash still exists somewhere, possibly under a different chunk ID because of a re-index. Span resolves.
  2. The hash doesn’t exist anymore. The chunk text literally changed. Span fails loudly, not silently, which is the important part.
  3. The hash was never in the catalog. Span was invalid from the start.

It’s content addressing applied to the smallest meaningful unit of a knowledge base. Re-index freely; citations survive as long as the source text does. And when the source text changes, the citation doesn’t quietly end up pointing to a chunk that kind of looks similar but says something different. It breaks cleanly, and I go figure out what happened.

Nelson was getting at this in 1981. Literary Machines describes a “Prismatic Document” whose links “may be refractively followed from a point or span in one version to corresponding places in any other version.” Forty-five years later, hashing each chunk and storing the hash as the citation feels like a small, cheap version of the same idea. He had something more ambitious in mind, but it’s the right shape.

An old graph, a new walker

Almost none of the graph side of this is original. Typed-edge ontologies, RDF, the semantic web, property graphs; before them, frame-based knowledge representation, Sowa’s conceptual graphs, Cyc. Encoding meaning as nodes and labeled edges has been worked on steadily since the 1970s, and the underlying ideas go back further still. The catalog’s link table is a small, prosaic descendant of all that work. The vector store side has the same lineage (different family, same age) and the same well-understood ceilings. Nexus inherits both halves and tries to add as little as it can get away with on top.

What’s new is what you can do along a path now. In the nx_answer demo from Nexus by Example, the six-step plan included a traverse step that walked the catalog graph and an extract step that read what the walk found and pulled out the relevant claims. Both of those are LLM operators: claude_dispatch calls into a fresh Claude subprocess that takes the previous step’s output as input and produces the next step’s input. Static query still gets you adjacency, the same as it always did; what’s added is that the graph can also be walked, with a model standing at every node deciding what to do with what it sees.

That changes what a traversal can do. You can summarize at every hop, rank, compare, refuse to continue if the evidence doesn’t hold up, branch into a sub-question, or escalate to a human. None of those moves are new ideas individually; what’s new is composing them at every node of a graph walk because the cost of asking a model “what’s important here?” finally collapsed. Operators as building blocks covers the operators in detail, and Plans, not replanning the plans that orchestrate them. For now, just hold the picture: when I show a traversal below, the catalog isn’t merely listing adjacent nodes; an operator can also stand at every node and do something with what it sees there.

A walk

Picking a single Nexus RDR and walking its neighborhood:

$ nx catalog show 1.1.838
Tumbler:    1.1.838
Title:      rdr-096-uri-source-identity.md
Type:       rdr
File:       docs/rdr/rdr-096-uri-source-identity.md
URI:        file:///Users/hal.hildebrand/git/nexus/docs/rdr/rdr-096-uri-source-identity.md
Collection: rdr__1-1__voyage-context-3__v1
Chunks:     64
$ nx catalog links 1.1.838 --direction out --type implements
1.1.838 → 1.1.122 (implements) by filepath_extractor
1.1.838 → 1.1.21 (implements) by filepath_extractor
1.1.838 → 1.1.52 (implements) by filepath_extractor
1.1.838 → 1.1.526 (implements) by filepath_extractor
1.1.838 → 1.1.56 (implements) by filepath_extractor
1.1.838 → 1.1.7 (implements) by filepath_extractor

Six rows, and six is the whole answer. When this post first ran the same query returned 133 rows for nine real targets, the rest being duplicate edges minted on every re-index. Those duplicates are gone.

The from-side is RDR-096, the decision about how a document’s source_uri gets its identity. The to-side tumblers don’t tell a reader much by themselves. Resolving each through nx catalog show translates them into the files the RDR names:

Tumbler File
1.1.7 src/nexus/db/t3.py
1.1.21 src/nexus/commands/enrich.py
1.1.52 src/nexus/aspect_extractor.py
1.1.56 src/nexus/aspect_worker.py
1.1.122 src/nexus/aspect_readers.py
1.1.526 src/nexus/doc/citations.py

Six production modules: the implementation footprint of one decision about identity, every path machine-extracted by filepath_extractor from src/... strings the RDR itself names.

I did not choose this example to make a point, and then it made one anyway. The night before I wrote this, a daemon on this machine died silently because one of those exact files, aspect_readers.py, computed a document’s source_uri by resolving a relative path against the process’s current directory, and something deleted that directory. The fix landed in aspect_readers.py, aspect_extractor.py and aspect_worker.py. Three of the six files above, named by an RDR written months earlier about precisely that question, linked by a generator that did nothing cleverer than read the RDR’s own prose for path-shaped strings.

That is the whole argument for typed links in one accident. The graph did not predict the bug. It did something more modest and more useful: it already knew which files answer to which decision, so the blast radius of a question about identity was a query rather than an afternoon.

That listing above is the boring view: just adjacency, the kind of output any graph database from 1995 could give you. Six edges, all typed implements, all created by the same extractor. Nothing in that output tells me whether any of them is true.

So I put a summarize operator at each of the six nodes and asked it one question: how does this specific file participate in RDR-096’s decision, and if it does not, say so plainly rather than manufacturing a connection. One dispatch per node, six in total. Compressed to their verdicts:

Target What the operator found
aspect_readers.py The single derivation point. uri_for() at line 88 is where the decision actually lives.
aspect_extractor.py The sole surviving going-forward writer; stamps every record by delegating to uri_for rather than composing a URI itself.
aspect_worker.py Enforces the no-null-row contract on the queue-drain side. Added, unasked: the worker still keys its queue and logs on source_path, not source_uri.
commands/enrich.py The CLI consumer. Added, unasked: _source_uri_host_key is a later addition under a different bead, adjacent to this decision rather than part of it.
db/t3.py “Participates only weakly, and on the read side.” No source_uri, no URI derivation, no scheme handling in its 1,845 lines. The live path does not traverse it at all any more.
doc/citations.py “Only as cited prior art, not as an implementation site.” Holds the chash: grammar that RDR-096 names as precedent. Not modified by the decision.

Two of the six edges did not survive contact with the model. db/t3.py and doc/citations.py are both real, both machine-extracted from paths the RDR genuinely names, and neither implements anything. One is a test-only read path the production code stopped using; the other is a citation the RDR makes to prior art. The filepath extractor cannot tell “this RDR names this file” from “this file implements this RDR”, because from the text those look identical. The operator standing at the node can, and it volunteered scope caveats on two of the four that did survive.

That is the difference between the two views, and it is not that one is prettier. Adjacency told me six files implement this decision. The walk told me four do, with qualifications on two of those, and handed me the line numbers to check every claim. The graph proposes; the model disposes. Neither half is much use alone: without the edges there is nothing to walk, and without the model at each hop I would have believed all six.

Two structural things worth noting before moving on:

  1. The graph no longer has mixed curation, and that is the resolution of the question this post opened with. implements links are precise, extracted from paths the RDR itself names. implements-heuristic guesses are gone. Originally I described a traversal that would trust the graph differently at different depths, deciding per hop whether to follow an edge or stop and ask. That was the right instinct applied to the wrong remedy. The guesses were not worth the machinery required to distrust them carefully. Deleting them was cheaper and left a smaller graph that can be trusted uniformly.
  2. Traversal by type is cheap. --type implements doesn’t scan every edge; it prunes in Postgres using the index on link type. That matters when the graph has 15k+ edges and a plan wants to walk it without budget overruns.

A flat vector search over the same RDR corpus finds me chunks that mention the same tokens, which is useful but different. Traversal finds me chunks that participate in the same named relationship. And animating that traversal with an LLM at every hop turns “list of related things” into “structured argument about what the relationship means.” When I ask “what code did RDR-010 influence?”, that’s what I actually want.

Going deeper

This post is the overview; the repo carries the reference docs. The Nexus pieces this post leaned on:

What’s next

Decisions as indexed data puts the typed-link discipline to work on decision records specifically: RDRs and beads as first-class graph nodes, walked on Nexus’s own RDR corpus (which is where most of the curated links in this post came from). If you liked the walk above, the next post is a longer version of it with an actual decision arc telling a coherent story.

If you want to follow along, Post 00: Installing Nexus is the install + first-tour walkthrough.



4 responses to “Typed links and the catalog”

  1. […] Typed links and the catalog. Tumblers, content-addressed spans, the typed link graph. Traversal demos on Delos. […]

  2. […] the last post, Typed links and the catalog introduced the catalog as a metadata layer that tracks indexed documents and the typed edges […]

  3. […] Post 2: Typed links and the catalog: the graph that knits the corpora together. […]

  4. […] Post 2: Typed links and the catalog: the graph that knits the corpora together. […]

Leave a Reply