Trace

Architectural Memory Engine — fast AST indexer + ADR graph + agent session recovery via MCP

Key Facts & Overview

Trace is an architectural memory engine for AI coding agents, served over the Model Context Protocol. It gives agents structured, always-fresh knowledge of a codebase — symbols, call graph, imports and HTTP routes — plus the project's architectural rules, its decision records, and a memory of what earlier agent sessions did. Everything is deterministic and offline: no API keys, no network, no LLM inside.

›Scale: 17s cold index on 23K files (1.3M symbols, 1.8M call edges), 1s warm restart, 60ms incremental refresh.
›Fails closed: malformed rules file blocks every plan with a clear config_error.
›Path confinement: every path argument is confined to the project root, including through symlinks.
›Daemon auto-revive: if it dies mid-session, the shim fails in-flight requests, respawns, and reconnects.
›Agent discovery + config editing built in: trace setup writes the MCP config for Claude Code, Codex, OpenCode, and Cursor automatically.

Core Architectural Features

One-pass tree-sitter extraction: symbols, imports, call graph, HTTP routes

7 languages: Rust, Python, TypeScript/TSX, JavaScript/JSX, Go, Java

Incremental + persistent: SQLite cache, only re-parses changed files

Import resolution across crates, packages, modules, and ESM paths

Architectural rules: forbidden/required imports, frozen paths, fail-closed

ADR engine: parses adr-tools and MADR records, relevance-ranked search

Execution memory: session log with touched files and reasons

MCP server: JSON-RPC 2.0 over stdio with 16 tools

Per-project daemon with Unix socket IPC; auto-revive on crash

CI integration: trace check --strict in GitHub Actions or pre-commit

Installation

curl -fsSL https://raw.githubusercontent.com/ayoubzulfiqar/trace/main/install.sh | sh

# Build from source
git clone https://github.com/ayoubzulfiqar/trace.git
cd trace
cargo build --release

# Install via Cargo (Linux/macOS)
cargo install --locked trace

Usage

# After install, register with your agent
trace setup

# Check what trace sees in a project
cd ~/code/my-app && trace status

# Run architectural rules in CI
trace check --strict

# Force a clean rebuild
trace scan --reset

# Install as a systemd service (optional)
trace service install

Resources & Repositories

GitHub ↗Docs ↗Install Script ↗