Theourgia -- a block-graph storage engine for LLM agents

Core features

A Living Graph Engine for Human-Agent Symbiosis

To get past these limits, the system stops organizing content by files. Blocks now store both documentation and actual source code files. The underlying store still projects onto standard files when needed, but a file boundary no longer decides what is read, what is written, or what is run. Instead, we rebuilt how engineering knowledge and code are structured, assembled, tested, and computed across seven core mechanisms.

A Minimal Query Surface for Agents

We built a compact interface strictly for machine economics and token budgets, stripping out rendering markup entirely. Core verbs like outline, search, refs, and batch answer in dense S-expressions, one item per line. An agent can see the exact token footprint of what it is about to read before reading it—and there is no second, pretty-printed output mode to parse.

$ theourgia outline --depth 1
- 8pniyrtk.j  Home
- 8pniyrtk.k  Why not markdown
- 8pniyrtk.l  Model

$ theourgia search "stale-baseline"
(hit "8pniyrtk.2l" 4 "refusal, stale-baseline, commit, example, answer")
(hit "8pniyrtk.1b" 1 "A refused commit does not simply say no. It answers stale-baseline, and it names")

One Unified Graph Across Docs and Source Code

The wall between the code repository and the document store is a filesystem accident, not a property of the work itself. Here, blocks hold both Markdown documentation and source code files—everything engineering produces lives in one unified graph. A design section, a full source file, a Scheme macro, a Python function, and an architectural decision record are all equal blocks, each with its own stable ID and each independently addressable. Edges are typed and directed: a requirement points to the code that meets it, the code points to the test that checks it, and the test points back to the discussion that decided it.

A name is a block

In a Scheme library block this is literal rather than a metaphor. A definition is a block, and evaluating an expression against that library is evaluating the definitions those blocks hold -- so a name resolves to its definition block, log <id> gives that definition's history, and an explicit edge ties it to the design that motivated it. The same three questions about one name -- what it is, how it got that way, why it exists -- are three reads rather than three searches.

Other languages, more modestly

Source in other languages goes in as text blocks cut at top-level regions, with names extracted as well as the language table allows. They are blocks like any other: addressable, linkable, with their own history. What they do not get is the resolution above -- a name in Python source is not a binding the store can follow to a block.

The store, the block and the log, in full ->

Global Backlinks at Near-Zero Cost

The graph changes how an agent—or a human—hunts for context, and what that hunt costs. A single refs query answers the whole picture at once: which design mentions this function? which prose block refers to it? Meanwhile, log hands back the block's exact history, and search pinpoints the answering block so the agent reads only that block instead of the entire file around it.

$ theourgia link koou2buo.2 implements koou2buo.1
$ theourgia insert --under root --title "Mentions by id" \
    --text "See [[koou2buo.1]] for the reasoning."

$ theourgia refs koou2buo.1
(ok (items (ref (from "koou2buo.2") (rel implements) (via link))
           (ref (from "koou2buo.4") (rel ref) (via md))))

Measured across 56 questions over 20 real engineering documents: searching and reading the target block costs 15% of the tokens required to read the full document each time; browsing the outline before reading costs 20%. The outline of an entire corpus takes up just 6% of its raw Markdown size.

Route	Tokens, 56 questions	Share
Read the whole document for each question	232,478	100%
outline, then read the block that answers	46,410	20%
search, then read the block that answers	34,917	15%

What refs resolves, exactly Measured, because this is easy to over-claim. A mention resolves by id: a block whose text contains [[koou2buo.1]] shows up as (ref (from ...) (rel ref) (via md)). A mention by title does not -- a block written with [[The design]] did not appear in refs for the block titled The design. An explicit edge shows up as (ref (from ...) (rel implements) (via link)) under whatever relation name it was given. So renaming a block leaves explicit edges and id mentions intact, because both are by id; what does not survive a rename is a reference that was only ever a name.

Deterministic Context Assembly

An agent's real bottleneck isn't I/O speed—it's whether the tens of thousands of bytes entering its context window are actually right and complete. Today, agents assemble context by intuition: run a search, read a few blocks, feel like it's enough, and start coding. If they miss a premise or follow a superseded ruling, the mistake only surfaces after the work is done. We turn "gathering materials" from an agent's heuristic into a deterministic store verb—and make the store accountable for its choices.

It works in two layers:

In-Memory Datalog Queries (query): The store's reduced in-memory state is treated as a set of logical facts: blocks, their types, validity, and versions; block fields; parent-child trees; library definitions; verification records; task premises; and typed edges (depends, uses, implements, supersedes, refutes). Over these facts sits a fixed set of Datalog-style rules built right into the core. Evaluation runs purely in memory—no disk writes, no log scanning, and no user code execution. Agents can directly ask for dependency chains, blast radiuses, unresolved rulings, expired verifications, or the single authoritative definition of a name in scope without walking the graph by hand.
Budget-Bounded Context Compilation (context): Given a task block (carrying its premises, goals, and deliverables) and a strict token budget, context selects and categorizes the exact working set: Constraints (Must-Read) include the task's premises and their dependency closure, unresolved rulings in the subtree, and the unique, live, authoritative definition for every symbol the task touches within its scope. Evidence, Counterexamples, Background, and Stale Verifications fill the remaining token budget greedily in a documented order. Explicit Exclusions list every block left out due to budget limits alongside the exact reason it missed the cut.

Human-Agent Symbiosis in the IDE

The store isn't just for the automated half; it is a shared semantic layer where humans and agents work on the exact same code blocks, prose blocks, edges, and history. For humans, that means an IDE, not a CLI. Because people edit real files projected by the store, the Language Server works natively with zero loss of IntelliSense—while the extension maps every save back to the blocks it touched and adds what only the graph knows:

Above Every Definition, What Only the Graph Knows: A semantic lens sits right above each function: three design sections refer to this, two lessons learned, last changed by agent-b under request R, see test W3. Hovering reveals the design summary. While the language server tells you what a symbol is, the graph tells you why it is here, who depends on it, and what to read before changing it.
A Rename That Names the Docs It Left Behind: An editor rename writes back as one atomic change. Because block IDs never move, every edge from a design section, lesson, or test survives intact. One query for the old name then lists the exact prose paragraphs that haven't caught up—flagging stale documentation by name instead of hoping somebody notices.
An Agent's Draft, Reviewed with the Whole IDE: Each writer's scratchpad is its own indexed workspace root. You review an agent's unfinished code change alongside its design, references, and live diagnostics rather than squinting at a flat text diff—and the agent sees those exact same IDE diagnostics and test results on its draft before committing.
Precision Test Runs: With call hierarchies stored as graph edges, knowing which tests must rerun is a single graph walk from the changed block: only the tests that guard it, and the tests that guard its callers, get executed.

Zero-Conflict Concurrent Workspaces & Isolated Execution

Multiple agents and humans can edit and test the exact same code or documentation block simultaneously without locking up the store or stepping on each other's runtime state.

Isolated Scratchpads: Every human and agent operates under a writer id—from which block IDs are minted, so every block carries its author's identity for life. Calling write places a proposed code or prose change into the writer's private scratchpad, invisible to the log and to everyone else. The main tree stays untouched until someone commits.
Concurrent Execution and Testing in Dedicated Environments: A scratchpad is not a dead text buffer. Code modified concurrently inside a scratchpad runs and tests inside its own dedicated, isolated environment. Ten agents can explore ten competing implementations of the same module at the same time—compiling, executing, and running test suites in parallel within their own scratchpad environments—verifying that their changes actually work before ever touching the main tree.
Baseline Optimistic Locking: commit installs a writer's verified drafts into the store as one atomic change, serialized by the store process so races are cleanly decided rather than interleaved. When a commit declares the version it was based on and that baseline has moved, the store never silently overwrites. Instead, it refuses the commit with stale-baseline—handing back the version the draft was made against, the current version, and the records applied since (including the winner's content). The losing agent already holds everything it needs to merge the changes inside its scratchpad, rerun its tests, and commit again.

$ theourgia commit <block> --writer w1

(error stale-baseline
  (block "s9av8p0w.1")
  (based-on "fb580a74...")
  (now "904e0323...")
  (since (("s9av8p0w" . 3)
          (<the record that landed>)
          (set "s9av8p0w.1" src "w2 version")))
  (usage (commit (<block> ...) ("--writer" <name>)
                 ("--working-version" <block>=<version>))))

About that example That answer was taken from a run, not written by hand: two writers took a draft of one block from the same baseline, the second committed, and the first was refused. The two hashes are shortened here to fit the page, and the record in the middle of since is stood in for by a description of it; everything else is as the store answered.

A Lisp Machine: A Living Knowledge Base

The store is not just where knowledge and code are kept; it is a runtime they execute in.

In-Block Sandboxed Evaluation: When a block holds Scheme code, the system acts as a modern Lisp machine. Both agent-generated and human-typed code evaluate in place against the R6RS libraries and definitions held in the store. Every evaluation runs inside an isolated child process with strict wall-clock, memory, and output quotas, returning standard output cleanly in its own response field.
Evaluate at Any Point in History: Because the store's state is a deterministic reduction of the log, you can evaluate code at any historical cut. You aren't just diffing old source text—you are executing the old behavior as the system stood at that moment, with the exact historical coordinate returned so the run can always be reproduced.

$ theourgia eval --under <library> '(f)'
(ok (values ("second version")) (working-view #f (("koou2buo" . 8))) ...)

$ theourgia eval --under <library> '(f)' --cut '(("koou2buo" . 7))'
(ok (values ("committed")) (working-view #f (("koou2buo" . 7))) ...)

The definition was changed between the two calls. The second asks for the earlier cut and gets the behaviour that was there then.

Measured

Numbers, and where they came from

387blocks written into one store by five agents at the same time, with 0 refusals

5.7xless context for one real question: outline plus one block, against reading the file

113/113documents exported back byte-for-byte identical after being imported

6%of a corpus's markdown tokens is the size of its entire outline

1 msto read a block through the daemon

How the numbers were taken Every figure on this site comes from one of two measured runs: 157 files of a real agent memory written by five concurrent agents, and 113 documents converted and then queried. Four things are worth knowing before quoting them. The token counts use cl100k_base, which is OpenAI's tokenizer, not Claude's and not a billing unit; calibrated once against real context growth it ran about 9% low. How much a query saves tracks the size of the block that happens to answer it, not anything theourgia does: in the bucket where the answering block is most of the document the median query still cost 95.2% of reading the whole thing. Small documents have little to give either -- under about a thousand tokens the median was 38.5%, and one README's outline alone came to 67.6% of the document it summarised. And roughly 40% of queries made without knowing what is in the store fall back to reading the outline first.

Start

A store is a directory

# a store is a directory
theourgia init

# one block answers one question
theourgia insert --under root --title "Why the retry is three deep" \
  --keywords "retry, supervisor, worker, timeout" \
  --text "..."

# find it again without reading the store
theourgia search "retry supervisor"
theourgia read <id>

# what is under this block?
theourgia outline --depth 1

Theourgia is R6RS Scheme and builds with Chez Scheme against Igropyr. build.ss compiles every library in the tree into a directory of objects; the client, the MCP shell and the sandbox worker are the scripts beside them. There is no package to install and no daemon to configure: point the client at a directory and it starts what it needs.