Architecture & Design Philosophy
The meta-level story — how the vault models itself as a weighted DAG, and the recursive self-improvement loop that makes the system better over time.
The Core Model: A Weighted DAG
The vault is a directed acyclic graph where every reference points strictly upward. Saves are leaf nodes. Topics synthesize saves. Connections link topics across domains. Projects consume connections. BFS navigation with YAML-first scoring gates expensive full reads — the system stays fast at 6K+ saves by never reading everything at once.
Recursive Self-Improvement Loop
The vault improves its own outputs using its own infrastructure. After each /orchestrate run, a quality measurement agent scores the enriched saves. A calibrated judge cascade estimates fabrication risk and quality. Prompt improvements triggered by low-scoring runs are re-measured on the next run — closing the feedback cycle automatically.
Orchestration Patterns
N agents dispatched in one message; results merged by controller. Wall-clock = slowest single agent, not sum of all.
Item A reaches stage 3 while item B is still in stage 1. No synchronization barrier; no wasted idle time.
Each agent works in a fresh git worktree. Cherry-pick to main when done — no merge conflicts.
Keep spawning finder agents until K consecutive rounds return nothing new. Terminates naturally without a fixed count.
Spec-pass agent checks "does it match the plan?" Quality-pass agent checks "is it correct?" Two independent gates before any merge.
Token budget controls fleet size dynamically. Cost is a first-class variable, not an afterthought.
73 Architecture Decision Records
Architecture Decision Records (ADRs) document key technical choices: the problem context, every option considered, a decision matrix, and the final rationale. In the Research Vault, 73 ADRs capture decisions like "append-only logs over mutable files," "cherry-pick over full merge," and "BFS/YAML-first navigation over brute-force search." Each ADR is a first-class artifact that future sessions — human or AI — can read to understand the system without re-litigating past decisions.
| ADR | Decision | Why |
|---|---|---|
| #11 — Append-only logs | One file per entry + derived index.md |
Concurrent agents can write without conflicts; entries are permanent artifacts, not mutable state |
| #28 — Cherry-pick merge | Cherry-pick feature commits to main | Vault backup commits create file-location conflicts on full merge |
| #46 — BFS/YAML-first | Read frontmatter before full bodies | Scales to 6K+ saves; L1 filter eliminates 80–90% of reads before they happen |
What This Demonstrates
Software engineering fundamentals applied at real scale: data modeling (a typed, weighted DAG with strict reference direction), test coverage (985 tests across agent behavior, pipeline invariants, and script correctness), and systematic decision-making (73 Architecture Decision Records, each with a problem statement, options analysis, and decision matrix).
AI engineering discipline, not just AI usage: a custom agent framework built on Claude Code, observable pipelines (append-only telemetry logs, quality scoring, cost tracking per run), and a recursive self-improvement loop that closes the feedback cycle automatically.
The vault is not a prototype. It runs every day, processes real content, and improves its own quality over time. That’s the difference between “built a thing with AI” and “built a reliable system that uses AI.”