Trace: Building an Architectural Memory Engine for AI Coding Agents

AI coding agents such as Claude Code, Codex, and Cursor possess impressive code-generation capabilities, but they lack a fundamental attribute of human senior engineers: architectural memory. When launched in a large codebase, an agent starts with an empty context window. It greps blindly, reads partial file headers, guesses relationships, and frequently violates architectural layering—importing database models into UI controllers or breaking established design records.

I engineered Trace to solve this blindness. Trace is an open-source, deterministic architectural memory engine written in Rust and exposed over the Model Context Protocol (MCP). It equips agents with structured, instant, and persistent knowledge of an entire repository without consuming a single token of LLM context until requested.

1. One-Pass Tree-Sitter AST & Call-Graph Extraction

Many codebase indexing tools attempt to use embeddings and vector search for code understanding. However, vector similarity is fundamentally mismatched for precise code navigation: an agent searching for authenticate_user() needs the exact call site and callers, not semantically adjacent text.

Trace utilizes native tree-sitter grammars across 7 major programming languages (Rust, Python, TypeScript, JavaScript, Go, Java, and C/C++). In a single sequential pass, Trace extracts:

• Symbol Declarations: Structs, classes, functions, traits, enums, interfaces, and methods with exact byte spans.
• Call Graph Edges: Precise caller-to-callee relationships resolving cross-file invocations.
• Module Imports & Exports: ESM, CommonJS, crate paths, and package imports resolved relative to project roots.
• HTTP API Routes: Automated discovery of REST endpoints and handler bindings across Express, Axum, Actix, Gin, and FastAPI.

2. Scale & Incremental Cache Mechanics

Developer tooling must be imperceptible. If an indexer locks the CPU or takes minutes to boot, developers and agents will bypass it. Trace was designed in Rust with strict zero-cost abstractions:

Trace stores symbol and edge tables in an embedded SQLite database using WAL (Write-Ahead Logging) mode and memory-mapped pages. When a file is modified during an agent session, only the AST diff is re-parsed and merged in 60 milliseconds.

3. Fail-Closed Architectural Boundary Enforcement

The most dangerous failure mode of autonomous agents is "architectural erosion"—introducing circular dependencies, bypassing authentication middleware, or altering frozen core algorithms.

Trace introduces a declarative architectural rule engine defined in .trace/rules.toml:

# Enforce strict domain boundaries
[[rules]]
name = "isolated-domain-core"
description = "Domain core must never import external database adapters"
forbidden_imports = ["src/adapters/**", "src/infra/**"]
applies_to = ["src/domain/**"]
severity = "fail-closed"

[[rules]]
name = "frozen-crypto-primitives"
description = "Cryptographic handshakes cannot be modified by junior agents"
frozen_paths = ["src/crypto/**"]

Before an agent executes a plan, Trace evaluates the intended modifications against the rule graph. If a proposed file change violates a rule, Trace returns a hard config_error that blocks execution before code is written to disk.

4. Cross-Session Execution Recall & ADR Discovery

When an agent conversation ends, all working memory is lost. The next session starts from scratch. Trace solves this through Session Memory and automated Architectural Decision Record (ADR) indexing:

• Session Logs: Trace records an immutable session history of touched files, modified symbols, and rationale strings. New agent sessions can query trace_recent_sessions to immediately understand previous refactors.
• ADR Parser: Trace automatically indexes MADR and adr-tools Markdown documents, providing relevance-ranked retrieval when agents ask why a specific pattern or database was chosen.

5. Native MCP Protocol Interface

Trace runs as an unprivileged background daemon communicating with host agents via standard JSON-RPC 2.0 over stdio or local Unix domain sockets. It exposes 16 high-efficiency tools:

• trace_symbols: Instant symbol lookup with type signatures and documentation comments.
• trace_call_graph: Upstream and downstream caller inspection up to N depths.
• trace_check_rules: Fast architectural compliance verification.
• trace_adr_search: Full-text semantic ADR search.
• trace_session_recall: Past session discovery and file impact logs.

6. Conclusion: Engineering with Determinism

The future of AI engineering is not about generating code faster—it is about keeping code coherent, architecturally sound, and maintainable over decades. Trace provides the deterministic foundation that allows creative agents to operate safely within complex enterprise repositories.