Theourgia

Blocks, not files

Files were the wrong unit. Blocks hold documentation and source code alike. The store still projects onto plain files when something needs them, but a file boundary no longer decides what is read, what is written, or what is run. The machinery comes in seven parts.

A Minimal Query Surface for Agents

We built a compact interface for token budgets, and stripped out the rendering markup. Core verbs like outline, search, refs, and batch answer in dense S-expressions, one item per line. An agent can see the 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, so you can walk from a requirement to the code that meets it, to the test that checks it, back to the discussion that decided it.

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? log gives you the block's full history, and search lands on the one block that answers—so the agent reads that block, not the whole 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.

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 show its work.

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 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 why it missed the cut.

Humans and Agents 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 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 without losing 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 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 the 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>))))

A Lisp Machine: A Living Knowledge Base

The store keeps knowledge and code — and runs them, too.

• 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're not diffing old source text. You're running the old behavior, as the system stood then, with the 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.

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