A smaller, more useful memory for local AI coding agents.
AI coding agents are good at working with code. They are less good at remembering a whole codebase without repeatedly loading file trees, source dumps, terminal logs, and old conversation into context.
Spectra is an experiment in fixing that. It gives an agent two things: a visual map of the codebase and a small, durable record of what has already happened. The goal is simple: spend fewer tokens rediscovering context, and more of them doing the actual work.
Polyglot repository ──code adapters──▶ topology graph ──▶ PNG map + exact anchors
Agent lifecycle ──adapter hooks──▶ immutable ledger ──▶ bounded state context
Instead of dumping source up front, Spectra lets the model see the shape of the system, choose an exact path:start-end anchor, and read code once it knows what it is looking for.
Important
Spectra is an early prototype. The v0.3 registry retains the complete CodeGraph v1.3.0 language and extension surface with 39 adapters. The harness-neutral Ledger is verified for Codex, Claude Code, and Gemini CLI; Cursor support is intentionally partial because it can reinject continuity only at session start. See Project status before relying on it in production.
The agent support contract tracks topology and Ledger support separately so an MCP integration is never mistaken for lifecycle coverage.
Most code-context tools answer with source and explanation together. That can be useful, but it also means paying for the same code again when the conversation moves on. Spectra separates finding the right code from reading it:
- See the system first. Spectra turns the relevant part of the architecture into a deterministic 1536×1024 map.
- Read with a purpose. Every visual ID points back to an exact file and line range.
- Keep the answer small. Maps show 48 nodes by default and never more than 96.
- Stay current. The MCP server watches served projects in the background, and every map retains a synchronous refresh fallback.
- Remember outcomes, not noise. The Ledger keeps edits, test results, and blockers without saving full conversations or terminal output.
- Keep it local. Parsing, indexing, rendering, selection, and replay all happen on your machine.
| Evaluation | Result |
|---|---|
| Median provider-input reduction | 88.3% |
| Composite recall-proxy retention | 118.0% |
| Expected-anchor recall | 85.2% (CodeGraph: 68.5%) |
| Ledger median estimated-token reduction | 93.4% |
| Ledger fact retention | 100% |
| Maximum Ledger projection | 57 tokens |
These numbers come from nine frozen prompts across pinned ripgrep, Tokio, and rust-analyzer repositories using Grok 4.5. They are encouraging, but they are still prototype results—not a promise that every model and repository will behave the same way. The reproducible methodology, prompts, and limitations are documented in the benchmark protocol. Generated result artifacts stay local and are not committed.
Spectra does not have prebuilt binaries yet, but Cargo can install the tagged v0.3.0 release directly from GitHub:
- Rust 1.88 or newer
- At least one supported local agent: Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini CLI, Antigravity, or Kiro
- A repository containing at least one supported source language
Any MCP client can also run spectra serve --mcp manually.
cargo install --git https://github.com/rankupgames/Spectra.git --tag v0.3.0 --bin spectra --lockedspectra installIn a terminal, Spectra opens a short wizard that scans for supported agents, shows each capability tier, asks where to install, preflights conflicts, and confirms before writing. For unattended global installation of every detected target, use spectra install --yes. Restart any agents it reports. If Codex is among them, review the Spectra context ledger hook once; Codex keeps that trust decision in your hands.
Confirm the installation:
spectra statusExpected output:
Claude Code: MCP=current, Ledger hooks=current, Capability=topology+ledger
Codex: MCP=current, Ledger hooks=current, Capability=topology+ledger
Cursor: MCP=current, Ledger hooks=current, Capability=topology+ledger-partial
Gemini CLI: MCP=current, Ledger hooks=current, Capability=topology+ledger
Your output only lists the agents Spectra detected. Codex, Claude Code, and Gemini CLI have recorded-wire topology+ledger coverage. Cursor is visibly labeled topology+ledger-partial: it records lifecycle facts but can reinject context only at sessionStart, not before every prompt.
After that, there is nothing to babysit. The long-lived MCP process watches every project it serves, reconciles changes after a short debounce, and performs a startup catch-up before accepting requests. Maps still check for changes synchronously, so a degraded or unavailable watcher cannot silently return a stale topology. Concurrent MCP servers, CLI commands, and fallback hooks coordinate through a heartbeat-backed project lock. You do not need to run a separate daemon, remember a sync command, or initialize each repository by hand.
Ask your agent an architecture or navigation question, for example:
Use Spectra to map how request routing reaches persistence.
Or render a map directly:
spectra map "how does request routing reach persistence" --path /path/to/projectSpectra returns a PNG and compact semantic metadata:
N1=method impl Router::dispatch @ src/router.rs:18-47
N2=method impl Store::save @ src/store.rs:9-31
flow N1 -calls-> N2
nodes=42 truncated=false index=v4
From there, the agent can pick an anchor and open the part of the source that actually matters. MCP responses append watcher health as autosync=active|degraded pending=N; direct CLI maps omit that server-only line.
Normal use creates a project-local .spectra/ directory containing generated state:
.spectra/
├── index-v4.json incremental polyglot code index
├── ledger-v1.jsonl append-only context ledger
└── artifacts/ generated PNG and SVG maps
When the MCP server starts, Spectra registers a recursive filesystem watcher before its initial catch-up refresh. Supported source changes, directory changes, and ignore-rule changes are collected for two seconds and reconciled as one batch. Failed reconciliations retain their pending paths and retry; watcher setup failures are reported as degraded, retried on the next request, and backed by request-time refresh. Runtime writes under .spectra/ and internal Git activity do not trigger feedback loops.
Index reconciliation is serialized across processes. The lock records a unique owner, refreshes a heartbeat during long scans, recovers abandoned locks, and remains held until the matching RepositorySynced Ledger event is committed. This allows several agent MCP processes and Git hooks to share one project index without corrupting the cache or duplicating material sync events.
Whenever an agent asks for a map, Spectra:
- Traverses the repository while respecting
.gitignore. - Detects each supported file through the adapter registry, reuses unchanged fragments, and reparses changed files with the matching grammar.
- Resolves high-confidence structure and relationships.
- Marks uncertain calls as dashed boundaries instead of presenting guesses as facts.
- Selects and renders a query-focused subgraph.
- Records the synchronization and map outcome in the Ledger.
Provider adapters for Codex, Claude Code, Gemini CLI, and Cursor normalize supported authorization, edit, verification, completion, and blocker events into the same private boundary. Codex, Claude, and Gemini receive a short session-aware projection at their documented context hooks. Cursor records the same bounded facts but reinjects only at session start.
spectra install [--agent AGENT] [--location global|local] [--path REPO] [--yes] [--topology-only] [--dry-run] [--no-color]
spectra status [--agent AGENT] [--path REPO] [--json]
spectra uninstall [--agent AGENT] [--location global|local] [--path REPO] [--dry-run]
spectra init [PATH] [--force] [--json] [--no-color]
spectra sync [PATH] [--quiet]
spectra autosync install [PATH]
spectra autosync status [PATH]
spectra autosync remove [PATH]
spectra map <QUERY> [--path PATH] [--max-nodes 1..96] [--out DIR]
spectra serve --mcp
spectra lifecycle ingest
spectra hook [--agent codex|claude|gemini|cursor]
spectra init is an optional eager-indexing command for diagnostics and benchmarks. It reports index version, file/node/edge totals, database size, node kinds, languages, synchronization state, and elapsed time; --json emits the stable report. Home and filesystem roots require --force. spectra sync exposes the same reconciliation path used by the watcher and is intentionally quiet-capable for automation. Neither command is required during ordinary MCP use.
On filesystems where native recursive watching is unavailable or unreliable, spectra autosync install adds marked blocks to the repository's post-commit, post-merge, and post-checkout hooks. Each hook launches spectra sync --quiet in the background. Installation is idempotent, honors Git's resolved hooks directory, preserves existing hook bodies, and spectra autosync remove deletes only Spectra-owned blocks.
--agent auto is the default and configures every detected agent. --agent all attempts every adapter; agents that expose configuration only through their own CLI must already be installed. Non-interactive use requires an explicit --agent or --yes, so it never waits for wizard input. Verified local configuration is available for Codex, Claude Code, Gemini CLI, and Cursor.
The installer is idempotent and ownership-aware: it updates stale Spectra registrations, preserves unrelated settings and comments, writes configuration atomically, and refuses to overwrite or remove a foreign MCP entry named spectra.
Spectra keeps the default MCP surface to two complementary tools:
spectra_brief(query, projectPath?, tokenBudget?, detail?, source?)
spectra_map(query, projectPath?, maxNodes?)
Use spectra_brief as the first call when starting or resuming work. It combines bounded project-wide Ledger facts, synchronization health, ranked graph anchors, affected boundaries, and suggested next reads. Session state is included only when an exact {harness, sessionId} source is supplied. Compact mode defaults to 600 estimated tokens; detail=source substitutes bounded, line-numbered source windows and never creates an image or map artifact.
Use spectra_map when a visual architecture view is useful. Its response contains an image/png content block followed by compact anchor metadata and never includes source bodies. Legacy snake-case parameter spellings remain accepted by every tool.
Change impact, typed paths, and the full CodeGraph-parity query pack are available without rebuilding. Set SPECTRA_MCP_TOOLS=all, or provide a comma-separated short-name allowlist such as brief,map,changes,path,explore. The available opt-in tools are:
spectra_changes(projectPath?, base?, paths?, depth?, includeTests?, tokenBudget?)
spectra_path(from, to, fromFile?, toFile?, mode?, maxHops?, projectPath?)
spectra_explore(query, maxFiles?, projectPath?, tokenBudget?)
spectra_search(query, kind?, limit?, projectPath?)
spectra_callers(symbol, file?, limit?, projectPath?)
spectra_callees(symbol, file?, limit?, projectPath?)
spectra_impact(symbol, file?, depth?, projectPath?)
spectra_node(symbol?, file?, includeCode?, offset?, limit?, symbolsOnly?, line?, projectPath?)
spectra_status(projectPath?)
spectra_files(path?, pattern?, format?, includeMetadata?, maxDepth?, projectPath?)
Use spectra_changes for worktree-to-symbol impact and ranked test discovery; explicit paths work without Git. Use spectra_path for up to three deterministic directed execution or dependency paths with exact anchors. Use spectra_explore for a deeper bounded source-and-call-path read after brief identifies an anchor. The remaining tools provide focused symbol, relationship, file-tree, project inventory, and index-health queries. All support cross-project queries. Configuration values in YAML and properties files are withheld from source responses.
The final metadata line reports watcher health as autosync=active|degraded pending=N. Watch registration honors repository ignore rules so generated build trees do not consume native watcher resources; macOS also uses an ignore-aware source polling fallback if FSEvents misses a change. Set SPECTRA_WATCH_DEBOUNCE_MS to a value from 100 through 60000 to override the default 2000 ms debounce window for unusually bursty repositories.
Automatic configuration is recommended. For a manual setup, register an MCP server named spectra that runs:
/absolute/path/to/spectra serve --mcp
Equivalent Codex configuration:
[mcp_servers.spectra]
command = "/absolute/path/to/spectra"
args = ["serve", "--mcp"]The workspace is intentionally split into two small layers:
spectra-core: packed graph primitives, language-adapter extraction and resolution, deterministic selection and rendering, incremental indexing, and the State Machine Ledger.spectra: CLI commands, stdio MCP transport, watcher-backed automatic synchronization, multi-agent installation, harness-neutral lifecycle ingestion, private provider-hook translation, and benchmark runners.
The internal graph kernel is domain-neutral:
- contiguous
NodeIdandEdgeIdarrays - interned
AtomIdvalues - typed scalar attributes
- adjacency indexes and invariant validation
- code-specific
SourceSpandata kept in a separate sidecar
Every adapter maps parser-backed or structured extraction into the same graph vocabulary. The current v0.2 packs cover the complete CodeGraph v1.3.0 language surface, including structural symbols, imports, calls, inheritance, implementations, configuration references, templates, infrastructure blocks, and legacy execution edges where applicable. Web components additionally parse embedded JavaScript or TypeScript, connect template events to script handlers, resolve rendered components, and model SvelteKit, Nuxt, Astro, Razor, Drupal, and ArkUI routes. Native adapters connect Objective-C interfaces, protocols, implementations, and message sends, and distinguish CUDA and Metal entry-point kernels from ordinary functions. Structured adapters cover Terraform/OpenTofu, Nix, YAML, XML/MyBatis, properties, Twig, CFML queries, and COBOL/CICS. Ambiguous targets remain explicit uncertain boundaries. Rendering condenses cycles, layers nodes, clusters related code, routes typed edges, and emits deterministic SVG and PNG artifacts.
The adapter contract, functional acceptance bar, and CodeGraph parity matrix are tracked in Code adapters.
See the Ledger design and maintenance boundaries for the state-machine contract.
Spectra should not become another transcript database. It deliberately keeps less:
- Source bodies are excluded from topology responses.
- Prompts, assistant messages, patch bodies, and terminal output bodies are not written to the Ledger.
- Credential-shaped values are redacted before persistence.
- Hook retries use correlation IDs so immutable events are not duplicated.
- Index writers use an ownership-checked heartbeat lock across MCP, CLI, and Git-hook processes.
- Cross-process transactions serialize concurrent Ledger writers.
- Malformed or unsupported hook events fail open and cannot block the agent loop.
- The
.envfile and.spectra/runtime data are ignored by Git.
Provider hooks remain fail-open and record only their documented lifecycle surfaces. Spectra does not claim to intercept every OS process or terminal operation. Cursor's session-start-only reinjection remains an explicit partial capability.
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo build --release --workspaceThe benchmark protocol, frozen prompts, raw evaluation data, and replay fixtures live under benchmarks/.
Implemented:
- adapter-driven topology extraction and incremental indexing across all 39 CodeGraph v1.3.0 language families and dialect adapters
- CodeGraph-parity server framework routes plus React/Next, SwiftUI, React Native, Expo Module, and Fabric client/native bridges
- embedded JavaScript/TypeScript bridges, component rendering and event bindings, and conventional SvelteKit, Nuxt, and Astro page routes
- query-focused deterministic PNG and SVG rendering
- bounded MCP image and anchor responses
- the complete CodeGraph v1.3.0 MCP query capability set, with a one-tool default and allowlist-enabled explore/search/traversal/node/files/status tools
- automatic MCP installation for Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini CLI, Antigravity, and Kiro
- automatic lifecycle-hook installation for Codex, Claude Code, Gemini CLI, and Cursor
- append-only, per-session State Machine Ledger with replay, recovery, redaction, concurrency control, cross-harness project facts, and bounded projection
- stable harness-neutral
spectra lifecycle ingestJSON v1 protocol - deterministic, provider-backed, and recorded-hook regression suites
- pinned real-repository parity gates covering framework routes and multimodal topology quality
Not yet implemented:
- per-prompt Cursor context reinjection (the host currently exposes reliable reinjection only at session start)
- complete unified-shell interception
- packaged release binaries and automatic updater
- Tauri observability UI
- public graph-extension SDK
The v0.3 release hardens that CodeGraph-parity topology around a harness-neutral continuity protocol, verified provider adapters, project-local setup, and a richer terminal workflow. Packaged installers that do not require a Rust toolchain remain future work.
Spectra is young, and thoughtful help is welcome. Small, focused pull requests are much easier to review than sweeping rewrites. Please keep features modular, preserve deterministic output, and do not add source or terminal bodies to model-facing payloads. New dependencies need a quick maintenance and release-health check before they come in.
Before opening a pull request, run the full verification commands above and include regression evidence for changes affecting selection, rendering, indexing, installation, or the Ledger.
If Spectra saves you some tokens, time, or frustration, and you would like to help fund the next round of work, you can send a SOL donation here:
Network: Solana Mainnet
Asset: Native SOL
Recipient:
5bK9UNxJoaENxTYh2ZFMpuhuu8iA2MNfBoWGMzrshH96
Verify the address on Solana Explorer
If your wallet supports Solana Pay, this amount-free request lets you choose the donation amount:
solana:5bK9UNxJoaENxTYh2ZFMpuhuu8iA2MNfBoWGMzrshH96?label=Spectra&message=Support%20Spectra%20development
Caution
Send only native SOL on the Solana network. Always verify the entire recipient address in your wallet before confirming a transaction. Cryptocurrency transfers are irreversible.
No pressure, of course. Using the project, reporting a bug, or sharing a benchmark is valuable too. Thank you for helping Spectra grow in the open.
Spectra is available under the MIT License.