01 · CODEBRO
CodeBro
engineering context & memory layer
Verified facts, persistent decisions, and structural impact analysis for AI coding agents. Not context stuffing — structured intelligence that survives session boundaries.
02
What it is.
CodeBro is a local engineering intelligence layer that runs alongside AI coding agents. It maintains a verified fact store — symbols, modules, tests, dependencies — built from scanning the workspace, plus a persistent engineering memory store for decisions and constraints recorded across sessions.
It has three core interfaces: engineering_facts for
querying what exists in the codebase, engineering_memory
for retrieving recorded decisions and context, and
impact_analyze for understanding what changing a
symbol or file would touch. Each is an MCP tool the agent calls
directly — no prompt injection, no context window stuffing.
There's also a guarded mutation API (apply_change and
apply_changes) that validates edits against the
current workspace state before applying them, with automatic
rollback on failure.
03
Why I built it.
I run AI coding agents on my projects every day. The single biggest quality problem I hit was context fragility — agents would forget what they'd already established, re-scan files I'd already indexed, and make decisions that contradicted prior work simply because the session had no memory.
Most agents solve this by stuffing everything into the prompt. That works until the project is non-trivial, then the context window becomes the bottleneck and quality degrades. I wanted something that gave agents verified, structured facts on demand — the same way a senior engineer references a mental model rather than re-reading the entire codebase.
The memory layer was the second half of the problem. Every time an agent makes a decision — architecture choice, constraint, convention — that knowledge should persist. Not in a diff, not in a comment, but in a store the agent can query reliably across sessions.
04
How it works.
Workspace scan
On first access (or after mutations that signal reindex), the engine walks the workspace and extracts symbols, modules, packages, and dependencies into a structured fact record.
Fact indexing
Each fact gets a stable ID and a kind label (symbol, module, test, build_target, dependency, relationship, reference, diagnostic, architecture_rule). Provenance is recorded — where the fact came from.
Memory persistence
Engineering memories (decisions, constraints, context notes) are stored with confidence scores, tags, and optional expiry. They outlive sessions and can be queried by keyword relevance.
Query and mutation
Agents call MCP tools to read facts, search memory, or analyze impact. Changes go through the guarded change engine, which validates old-text matches and rolls back on failure.
The whole system is lightweight: a set of JSON files under
.codebro/, no external database, no external service.
The reindex command rebuilds facts.json from scratch;
memory entries accumulate unless explicitly deleted.
05
Data and structure.
Fact kinds
Facts are categorised by kind: workspace,
module, package,
symbol, test,
build_target, dependency,
relationship, reference,
diagnostic, architecture_rule,
language, framework, and
entry_point.
Each fact includes a location (file path, line range), a provenance source, and optional metadata. Symbols resolve to definitions and usages; relationships capture call graphs and import edges.
Memory entries
Engineering memories carry a stable key, a value (the recorded text), a confidence score (0.0–1.0), optional tags for filtering, and an optional expiry in seconds.
Confidence matters: facts from the index are high-trust; memories recorded by agents are medium-to-low trust and explicitly tagged as agent-recorded context, not verified engineering truth.
The delete_memory tool requires
confirm=true — there's no accidental deletion.
06
Automation and tooling.
The change engine is the most structured piece.
apply_change handles single-file edits;
apply_changes wraps multiple edits in an atomic
transaction — either all land or the workspace rolls back to its
prior state. Both refuse stale or ambiguous edits, preventing
drift between what the agent thinks the file looks like and what
it actually looks like.
The reindex tool triggers a full workspace
re-scan, regenerating facts.json from scratch. This
is the recommended action after any source change when the
engine signals needs_reindex=true.
The update_identity tool records high-trust project
declarations — goals, constraints, decisions, roadmap items —
into .codebro/project_identity.json. This is how
the workspace learns its own context over time.
Key tool behaviors
- engineering_facts — returns actual fact records with locations, not raw ids. Empty results mean no index exists yet, not that the symbol doesn't exist.
- engineering_memory — resolves relevant entries by keyword; returned with confidence scores so agents know what to trust.
- impact_analyze — returns directed relationship edges (with bounded BFS depth) showing what would structurally change if a target is modified.
- repository_health — returns structured exit code, status (healthy/warn/error), and per-check results for the workspace.
07
Research and experiments.
The A/B comparison ran the same prompt on the CodeBro repository itself with and without the CodeBro MCP server registered. The prompt asked for total symbol, test, and module counts plus three example symbol ids. Ground truth comes from the facts store.
With CodeBro the agent returned exact numbers —
10,514 symbols, 3,602 tests, 351 modules — from a single
workspace_context call. Without CodeBro it under-counted
dramatically (4,227 symbols, 2,799 tests) and invented symbol
ids that matched the format but were not real. For whole-project
factual questions, the facts store is materially better than
grep — it answers exactly where an agent cannot cheaply.
08
What I'm figuring out.
The reindex strategy is still evolving. Full scans are reliable but expensive on large workspaces. I'm exploring whether a delta-based approach (only re-scan changed files) is correct, or whether a periodic full reindex is simpler and more robust.
Impact analysis depth is already configurable per-query (0–5), and transitive relationships are returned at depth ≥ 2. The open question is whether the default depth should be higher for larger repos, or whether a separate mode for deeper traversal would be clearer for agents that need it.
And the relationship between engineering memory and project identity isn't fully resolved yet. Memories are agent-recorded and low-to-medium trust; identity declarations are high-trust and project-level. The boundary between "this is a decision the agent made" and "this is a project constraint" needs clearer semantics.
09