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.
Figures verified against source and the live graph on 2026-08-01 (commit ee31264), and re-verified on 2026-09-22. 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). 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/>468 nodes, 1,268 edges<br/>13 curated + 5 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<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: 468 nodes and 1,268 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 |
| Decision-memory record types | 3 + Project registry | schema.py |
| Allowed edge types | 24 (14 declared, 3 derived, 7 record) | writ/graph/db/_common.py |
| Retrieval stages | 5 (filter, BM25, vector, graph, rank) | writ/retrieval/pipeline.py |
| Injection channels | 3, composed by /prompt-bundle | writ/server/routes/query.py |
| Integrity checks | 7 clusters | writ/graph/integrity/ |
| Embedding model | all-MiniLM-L6-v2, ONNX on CPU, 384-dim | DEFAULT_EMBEDDING_MODEL in writ/retrieval/pipeline.py; encoder in writ/retrieval/embeddings.py |
| Code covered by this site | ~9,000 lines | writ/retrieval, writ/graph, export, compression |