One graph, four planes, five-stage retrieval
Writ stores engineering knowledge in a Neo4j graph and injects the right rule at the right moment. This site maps the retrieval and graph systems from source code: a full system map below, and four chapters that each zoom into one subsystem. Every diagram opens fullscreen with zoom and pan.
Read from source at commit 0c75b01 on 2026-07-15; figures re-verified against source and the live graph on 2026-08-01 (commit ee31264). Scope: writ/retrieval, writ/graph, writ/export.py, writ/compression, and the daemon endpoints that serve them. Every claim is anchored to file:line.- This page gives the whole system in one map. Blocks in the map are clickable and jump to their chapter.
- Chapters 1 to 4 each answer one question: what is stored, how a query is ranked, how rules reach the agent, and how graph and source stay honest.
- The Explorer page renders the real graph: every node and edge from Neo4j, interactive.
- Diagram convention: the dark green rounded block is where the flow starts (START or INPUT); orange blocks are outcomes; numbered steps show reading order.
- Diagrams are large on purpose. Click any diagram to open it fullscreen; scroll to zoom, drag to pan.
0.1The whole system on one map
Four planes. Storage: Neo4j is the canonical store; the bible/ markdown corpus is its human-editable, git-tracked mirror. Indexes: the daemon pre-warms every search structure into memory at startup, so the per-query path touches no database at all (writ/retrieval/pipeline.py:14). Serving: four retrieval endpoints plus a graph explorer. Maintenance: offline tools validate, compress, and export the graph back to markdown.
flowchart LR
BIBLE[("bible/ markdown corpus<br/>git-tracked source at rest")]
NEO[("Neo4j knowledge graph<br/>464 nodes, 731 edges<br/>13 curated + 4 record node types")]
IDX["In-memory search indexes<br/>BM25 + vector + adjacency<br/>pre-warmed, no DB on the query path"]
DAEMON["FastAPI daemon<br/>3 injection channels<br/>+ graph explorer"]
CLIENT(["START: a prompt arrives<br/>Claude Code hook or writ CLI"])
TOOLS["Offline tools<br/>writ validate (32 checks)<br/>writ compress, export"]
CLIENT -->|"1: request"| DAEMON
DAEMON -->|"2: rules injected into the turn"| CLIENT
IDX -->|"serves"| DAEMON
NEO -->|"loaded once at startup"| IDX
BIBLE -->|"ingest"| NEO
NEO -->|"export"| BIBLE
TOOLS ---|"read + repair"| NEO
classDef entry fill:#0B5E55,stroke:#083F39,color:#FFFFFF,font-weight:bold
classDef hub fill:#DCE9E5,stroke:#0B5E55,stroke-width:2px
class CLIENT entry
class NEO hub
click NEO "data-model.html" "Chapter 1: Graph data model"
click IDX "retrieval-pipeline.html" "Chapter 2: Retrieval pipeline"
click DAEMON "injection-channels.html" "Chapter 3: Injection channels"
click BIBLE "corpus-roundtrip.html" "Chapter 4: Corpus round-trip"
click TOOLS "corpus-roundtrip.html" "Chapter 4: Corpus round-trip"
0.2The chapters, plus a live explorer
Graph data model
13 curated node types plus decision-memory records, 24 edge types in three groups, composite per-project identity, and the provenance lifecycle that gates how knowledge becomes canon.
Open chapter 1 Chapter 2Retrieval pipeline
The five-stage hybrid ranker: BM25 plus vector search merged by reciprocal rank, a graph-aware second pass, exact fusion weights, and the token-budget response modes.
Open chapter 2 Chapter 3Injection channels
How rules reach the agent: the ranked broad query, the unranked always-on obligations, and the deterministic methodology channel, composed by one warm endpoint.
Open chapter 3 Chapter 4Corpus round-trip and integrity
Markdown to graph and back: ingest with one shared edge derivation, reconcile pruning with provenance exemptions, deterministic compression, and 32 integrity checks.
Open chapter 4 ExplorerThe graph itself
The live corpus from Neo4j, complete: 464 nodes and 731 edges, force-directed with edge-layer presets, search, and per-node inspection. Hand-authored edges render on top so they never drown under the derived layers.
Open the explorer0.3The system at a glance
| Dimension | Value | Anchor |
|---|---|---|
| Curated node types | 13 | writ/graph/schema.py:112-140 |
| Decision-memory record types | 3 + Project registry | schema.py:577-628 |
| Allowed edge types | 24 (14 declared, 3 derived, 7 record) | writ/graph/db/_common.py:32-64 |
| Retrieval stages | 5 (filter, BM25, vector, graph, rank) | writ/retrieval/pipeline.py:1-16 |
| Injection channels | 3, composed by /prompt-bundle | writ/server/routes/query.py:165 |
| Integrity checks | 32 across 7 clusters | writ/graph/integrity/ |
| Embedding model | all-MiniLM-L6-v2, ONNX on CPU, 384-dim | writ/retrieval/embeddings.py:70 |
| Code covered by this site | ~9,000 lines | writ/retrieval, writ/graph, export, compression |