context-graph-engine (repo-index)
Deterministic Syntactic Indexer & Context Pipeline for Coding Agents
Diagramas
Deterministic Context Pipeline (repo-index)
Project Overview
An agent asked to work on an unfamiliar repository spends most of its budget just discovering what exists: listing directories, firing glob and grep calls, and re-reading the same files on every new session. context-graph-engine (repo-index) eliminates that waste by computing the repository's structure once, 100% deterministically — using only the Go standard library, with zero LLMs, zero embeddings, and zero network calls.
What it extracts in practice: filesystem metadata (size, mode, symlinks, scope), Git state (branch, HEAD, remotes with credentials stripped), Clojure namespaces (requires, aliases, refers, public vars, reader conditionals), Go packages (module path from go.mod, imports, exported symbols), dependencies (deps.edn / package.json), dev/CI commands, and security surfaces. Every derived fact carries exact provenance (source, source_type, line, analyzer, version, confidence, rule), guaranteeing byte-identical output across runs.
Real production example (CA-097 on craft-agents): when running a full architectural review with 4 CGE profiles (architecture, cognition, backend-fabric, locomotion), repo-index compiled an 83,377-byte Turn-0 envelope while Glob/Grep/find/rg were blocked. The agent navigated straight to mapped contracts via Read, achieved a 93.59% cache hit rate (5.95M of 6.36M input tokens read from cache), avoided autocompaction (peaking at 408K / 1M tokens), and cut equivalent cost from ~$53.18 to $9.99 (~81% savings) while delivering a 552-line report in 9m23s.
Architecture & Implementation
The pipeline strictly separates four layers that never mix: (1) Index (scan): pure observation of what exists with provenance (facts.json + graph.json); (2) Navigation (navigate): what is relevant to a declarative task profile (architecture, dependencies, testing, security, migration, or custom .ai-factory/navigation/tasks.json), without LLMs; (3) Pack (pack): physical context planning under token budgets (--budget-soft / --budget-hard) and stable ordering; (4) Agent (envelope): final text handed over at Turn 0.
Real CLI usage:
repo-index scan . --output .ai-factory/index
repo-index verify .ai-factory/index --repo . # returns OK | STALE_INDEX | INDEX_INVALID
repo-index pack .ai-factory/index --task architecture --budget-soft 24000 --format envelope
Security & 3-Layer Artifact Protection: sensitive paths (.env, keys, credentials) are never opened at any layer — they travel strictly as metadata with content_read: false. Generated facts and benchmark baselines are read-only for agents across three independent layers: filesystem permissions (0444 artifacts / 0555 index dir), a PreToolUse hook denying writes with exit code 5 (WRITE_DENIED protected_artifact), and explicit project deny rules.