Skip to content
RationaleDocumentation

Factual architecture

How Git, Codebase Memory, the canon, the context compiler, MCP, local activity, and the Control Room fit together.

How Rationale is wiredAgents and the CLI reach the pipeline. The pipeline reads Codebase Memory, Git and the canon, compiles the packet, records local traces and sends candidates to the capture gate, which writes Records. The Control Room only reads.COMPILECANDIDATESMCP TOOLSREVISIONWRITESTRACESPROVIDERCodebase Memorywhere · how it connectsGITGitwhat · whenRECORDSCanon.rationale/ · whyMODULEContext compilercontext · retrievalMODULEPipelineprepare · finalizeMODULECapture gatecanon · storageBOUNDARYMCP server · CLImcp::server · mainLOCALActivity.rationale-local/READ-ONLYControl Roomui · 127.0.0.1
Call between modulesReadWrites Records to the canonEdges from Codebase Memory's call graph of this repository, revision 4be2ecd.

Components

Module Responsibility
pipeline Orchestrates prepare, explain, health, and finalize.
providers A normalized structural model; the Codebase Memory adapter speaks only its public MCP tools. A fixture provider backs deterministic tests.
context + retrieval Select the structural neighborhood, derive relationship state, and compile the packet under a token ceiling.
canon + storage The capture gate, provenance, authority, supersession, conflicts, migration, and atomic YAML writes under a lock.
relationships Explanations of relationships and their derived state.
operations + activity Operation snapshots and the per-session activity stream (ADR-0017).
mcp::server Newline-delimited JSON-RPC over stdio: five tools, six prompts.
ui A std-only localhost HTTP server with REST views and Server-Sent Events.
agents + prompts + skill_bundle Convergent, reversible agent registration; the protocol and shortcuts from one source; the embedded rationale skill written file by file with a hash.
doctor Canon integrity checks and guided repair.

Canonical versus derived

YAML under .rationale/ is the only authority. The SQLite search cache, operation snapshots, and activity can be rebuilt or deleted. No component reads a provider’s private storage (constraint.no-provider-internal-access).

Boundaries that hold

  • The provider informs, the canon decides. Absence of an edge is not proof.
  • Agents write memory, people own authority: pinning, unpinning, and replacing a pinned rule are human acts with declared authority.
  • The Control Room observes and never writes; the MCP server is the only agent boundary.
  • Local traces stay local and minimal: identifiers and a one-line intent.

Where to read more

The repository keeps the conceptual architecture, a factual code map in docs/architecture/, and the ADRs in docs/adr/ with their approval status.