OpenLore
A local-first, deterministic intelligence graph that eliminates repetitive file reads for AI coding agents
tracks context freshness, and unifies code, infrastructure, and architectural decisions
into a single, safety-gated governance runtime.
Onboard a 7,066-file repo once, then replace "grep 75 files and hope" with one deterministic call that returns the exact blast radius.
---
AI coding agents are powerful but amnesiac: every task starts by re-reading the same files to rediscover structure, and every long session quietly drifts toward confident-but-stale assumptions. OpenLore runs a **one-time static analysis** of your codebase and keeps a navigable knowledge graph β call structure, types, tests, decisions, and spec drift β incrementally fresh as you edit. Agents query it through **MCP tools** (or the CLI) to start every task already oriented. It is **deterministic and local-first** β no LLM in the hot path β so the same question returns the same grounded answer, and an agent is *told when a fact has gone stale* rather than served a confident guess.
### What you get
- π§ **Persistent architectural memory** β `orient()` once; agents stop re-deriving the system from dozens of file reads, across sessions.
- β‘ **Deterministic & local-first** β pure static analysis, no API key, no network, same answer every time. `orient()` runs in **~430Β΅s p50** on a 15k-node graph.
- π **One-call orientation** β `orient(task)` returns the relevant functions, their callers, matching spec sections, and insertion-point candidates in a single call.
- πΈοΈ **One unified graph** β application code, **Infrastructure-as-Code**, and **architectural decisions** all project onto the same node/edge primitives, so a single traversal answers questions that span all three.
- π§ͺ **Test-impact selection** β "I changed `parseConfig()` β which tests should I run?" answered by backward call-graph reachability.
- β οΈ **Dead-code & reachability** β cross-language mark-and-sweep over **18 languages**, confidence-tagged, never deletion authority.
- π§ **Context-freshness tracking (Epistemic Lease)** β every response carries a factual freshness note when your cached context ages or the repo moves.
- π‘οΈ **Safety-gated governance** β architectural decisions recorded, gated at commit, and synced into living specs; spec/code **drift detected in milliseconds**, no API key.
- π **Benchmarked & honest** β **β26% agent round-trips** on deep traces in large repos; we publish the losses next to the wins and every claim traces to a command you can run.
Quickstart Β· Benchmarks Β· How it works Β· Features Β· vs. Alternatives Β· Docs
> **New here?** `npm install -g openlore && openlore install` β one command detects your agent, wires it up, and builds the index. No API key. Jump to the [5-Minute Quickstart](#5-minute-quickstart).
> Migrating from `spec-gen`? The package is now [`openlore`](https://www.npmjs.com/package/openlore) and the command is `openlore` β see [docs/RENAME-TO-OPENLORE.md](docs/RENAME-TO-OPENLORE.md) for the short checklist (rename `.spec-gen/` β `.openlore/`, reinstall).
---
## Value Scorecard β does it pay for itself?
OpenLore only earns its place if an agent **with** it reaches a correct answer for less total cost than the same agent **without** it. We measure that inequality and publish it β wins **and** losses. Numbers are from the Spec 14 agent benchmark (`claude -p`, sonnet, N=4 medians, pinned SHAs, `--strict-mcp-config` isolating each arm), measured **2026-06-01**.
| Scenario (task Γ repo) | Cost Ξ | Round-trips Ξ | Correctness | Verdict |
|---|---|---|---|---|
| **Large/unfamiliar repo Β· deep "how does X flow through Y"** *(its target)* | **β7% to β21%** | **β26%** | 100% = 100% | β
helps β and the win grows with repo size |
| Small/familiar repo Β· shallow "who calls X" | **task-dependent** *(Round 1: +43%)* | **+38%** | 100% = 100% | β often adds overhead β measure with `openlore prove` |
> **Re-confirmed live 2026-06-03 (N=2):** the deep-task win **reproduces** β okhttp **β13%, identical to the table below**. The small/familiar case is **task-dependent, not a flat loss**: same repo class, opposite outcomes (chalk **β32%** win vs express **+59%** loss) β the cost there is a sometimes-redundant `orient` round-trip, not tool-schema bytes, so a leaner surface doesn't close it. Don't guess from our repos β run **`openlore prove`** on yours.
Deep-trace detail β the win scales with codebase size (cost Ξ; round-trips WITHOUT β WITH):
| Repo (size) | Cost Ξ | Round-trips |
|---|---|---|
| excalidraw (~640 files) | **β21%** | 25 β 16 |
| tokio (~790 files) | **β21%** | 17 β 13 |
| okhttp | **β13%** | 13 β 11 |
| django (~3k files) | **β7%** | 21 β 15 |
| gin (110 files, smallest) | +4% *(βeven)* | 10 β 9 |
**When OpenLore helps β and when it doesn't:**
- **Helps:** large, unfamiliar, or private codebases the model hasn't memorized; deep multi-hop questions; long sessions where re-reading an ever-growing context compounds. The most consistent, hardest-to-game signal is **round-trips: β26%, fewer on every deep task.**
- **Doesn't (yet):** small, famous repos already in the model's weights answered by a shallow query β there's no orientation tax to remove, so the MCP tool surface is pure overhead.
**Reproduce it:** `npm run bench:agent` (needs an API key for the agent arm). Full methodology, per-task numbers, and caveats: [docs/AGENT-BENCHMARKS.md](docs/AGENT-BENCHMARKS.md). Plumbing latency (orient ~430Β΅s p50) is separate and real: [scripts/BENCHMARKS.md](scripts/BENCHMARKS.md).
> **Honesty contract.** We never publish a savings number the benchmark didn't produce; we always show the loss cases next to the wins; the scorecard is date-stamped and re-measured after each optimization phase. Every public token claim traces to a command you can run in this repo β if it doesn't reproduce, treat it as marketing and call it out.
---
## Why It Exists
The amnesia is structural, not incidental. On every new task:
- They re-read the same source files to understand structure
- They forget architectural decisions made two sessions ago
- They have no link between specs and code β drift is invisible
- File-by-file navigation costs round-trips and fresh tokens that grow with repo size β on deep traces in large repos the WITHOUT baseline runs **17β25 tool-calls** to reach an answer; openlore cuts that **β26%** (see the [Value Scorecard](#value-scorecard--does-it-pay-for-itself) for the measured numbers, and where it does *not* help)
- In long sessions, they drift from authoritative retrieval toward internally cached reasoning β producing subtly wrong architectural assumptions that compound silently until a refactor breaks
openlore closes this loop. Run a full analysis once, then keep the graph incrementally updated as the codebase evolves. Even greenfield projects become cognitively "brownfield" after only a few agent sessions β architectural context fragments, decisions disappear, and agents repeatedly reconstruct the same understanding from scratch.
openlore persists that context continuously: structure, specs, decisions, drift state, and graph relationships remain queryable across sessions.
---
## How It Works
Three layers, each usable independently:
| Layer | What it does | API key? |
|-------|-------------|----------|
| **1. Static Analysis** | Call graph, clusters, McCabe CC, external deps β `CODEBASE.md` digest | No |
| **2. Spec Layer** | LLM-generated living specs, ADRs, drift detection, decision gates | For generation |
| **3. Agent Runtime** | 60 MCP tools β `orient()`, semantic search, graph expansion | No |
You can use layer 1 alone to give agents structural context. Add layer 2 for semantic intent and architectural governance through OpenSpec-compatible living specifications. Layer 3 keeps that context continuously accessible through graph-native MCP tools once `openlore mcp` is running.
---
## openlore vs. Alternatives
| | Cursor / Claude Code | Sourcegraph | openlore |
|---|---|---|---|
| Graph-aware MCP context | β file-based reads | Partial | β call graph + clusters |
| Spec drift detection | β | β | β milliseconds, no API |
| Architectural decision gates | β | β | β pre-commit hook |
| Offline structural analysis | β | β | β |
| Token-efficient orient() | β | β | β β7%ββ21% cost, β26% round-trips on deep tasks β |
| Living spec generation | β | β | β |
| Persistent cross-session architectural memory | β | Partial | β |
β **Measured, and it depends on the task** (full numbers in the [Value Scorecard](#value-scorecard--does-it-pay-for-itself) above). The Spec 14 agent benchmark (`npm run bench:agent`, WITH vs
WITHOUT openlore, `claude -p`, N=4 medians) gives a two-tier result:
- **Small, familiar repos + shallow "who-calls-X" queries:** openlore *adds*
~43% cost β the model already knows the code, so there's no orientation to save.
- **Larger codebases + deep "how does X flow through Y" questions (its target):**
with the lean `--preset navigation` tool surface, openlore is a **net win β
β7% cost and β26% tool-calls at N=4, scaling with repo size (up to β21% on
~640β790-file repos)**, at 100% answer correctness in both arms.
So the headline savings hold where openlore is designed to help, not on toy
queries. Full results, methodology, and honest caveats:
[docs/AGENT-BENCHMARKS.md](docs/AGENT-BENCHMARKS.md). The plumbing latency (orient
~430Β΅s p50) is separate and real β see [scripts/BENCHMARKS.md](scripts/BENCHMARKS.md).
| Long-session confidence decay (Epistemic Lease) | β | β | β |
Traditional coding agents reconstruct architecture from repeated file reads every session. openlore persists it as a queryable graph.
---
## 5-Minute Quickstart
> **One command, no API key needed:**
```bash
npm install -g openlore
cd /path/to/your-project
openlore install # detect your agent, wire it up, AND build the index
```
That single command:
1. **Auto-detects** which agent surfaces are present (Claude Code, Cursor, Cline, Continue, AGENTS.md) and wires each one to call `orient()` β no manual `CLAUDE.md` editing.
2. **Registers the MCP server** so it starts automatically when your agent launches (you don't run `openlore mcp` yourself).
3. **Builds the index** (`init` + `analyze` β a keyword/BM25 graph, no network needed) so `orient()` returns real results in your very first session β no separate `analyze` step.
```bash
openlore install --no-analyze # wire surfaces only; build the index later
openlore install --dry-run # preview every change without writing
```
See [docs/install.md](docs/install.md). The MCP server keeps the index fresh as you edit (file watcher on by default β large build dirs like `target/`, `node_modules/`, `dist/` are pruned automatically; disable entirely with `openlore mcp --no-watch-auto`).
Then ask your agent: **`orient("add a new payment method")`**
That single call returns the relevant functions, their call neighbours, matching spec sections, and insertion-point candidates β preserving architectural continuity across sessions instead of forcing the agent to repeatedly reconstruct context from raw file reads. The Spec 14 benchmark ([docs/AGENT-BENCHMARKS.md](docs/AGENT-BENCHMARKS.md)) measures this directly: on deep "how does X flow through Y" questions in larger codebases, openlore (with `--preset navigation`) cuts cost ~7% and tool-calls ~26% at N=4 (more on bigger repos); on small/familiar repos with shallow queries it adds overhead instead. Net: it pays off in its target arena, not on toy queries.
**Full pipeline** (specs + decisions β optional and additive):
```bash
openlore generate # generate living specs (requires API key)
openlore drift # detect spec/code drift
openlore decisions # manage architectural decisions
```
Install from source
```bash
git clone https://github.com/clay-good/openlore
cd openlore
npm install && npm run build && npm link
```
Nix / NixOS
```bash
nix run github:clay-good/openlore -- analyze
nix shell github:clay-good/openlore
```
System flake:
```nix
environment.systemPackages = [ openlore.packages.x86_64-linux.default ];
```
---
## See It In Action
Example: orient("add a payment method")
```json
{
"functions": [
{
"name": "processPayment",
"file": "src/payments/processor.ts",
"risk": "medium",
"fanIn": 4,
"callers": ["handleCheckout", "retryFailedCharge"],
"callType": "direct"
},
{
"name": "validateCard",
"file": "src/payments/validator.ts",
"risk": "low",
"fanIn": 1,
"testedBy": [{ "name": "validateCard.test.ts", "confidence": "called" }]
}
],
"specDomains": ["payments β Β§CardValidation, Β§PaymentFlow"],
"insertionPoints": [
"src/payments/processor.ts:87 β after existing charge logic"
],
"callPath": "POST /charge β handleCheckout β processPayment β validateCard β stripeClient.charge"
}
```
One graph query replaces most exploratory file reads. The agent knows exactly where to look and what risks to consider.
---
## Agent Cheat Sheet
The full surface is 60 tools, but day-to-day work needs a handful. Reach for the right one by situation:
| Situation | Tool |
|-----------|------|
| Starting any task | `orient(task)` β functions, callers, specs, insertion points in one call |
| Shallow "who calls X / where is Y?" | `orient(task, lean:true)` (CLI `orient --lean`) β navigation core only, ~40% smaller and skips the enrichment compute (Spec 27) |
| "Which file/function handles X?" | `search_code` |
| Call topology across many files | `get_subgraph` / `analyze_impact` |
| "What's the blast radius if I change this?" | `analyze_impact` β risk score + up/downstream chain + **governing decisions** |
| "What decisions constrain this code?" | `analyze_impact` / `get_subgraph` β `governingDecisions` (Spec 16) |
| Planning where to add a feature | `suggest_insertion_points` |
| "How does request X reach function Y?" | `trace_execution_path` |
| "I changed X β which tests should I run?" | `select_tests` β backward reachability to the reaching tests + paths (Spec 19) |
| "What's dead / what dies if I delete X?" | `find_dead_code` β cross-language reachability, confidence-tagged candidates (Spec 20) |
| "What's the blast radius of my whole diff before I commit?" | `blast_radius` β one advisory briefing: callers/layers, tests to run, anchored memories/decisions that will drift, stale specs (CLI `openlore blast-radius`) |
| "What changed structurally / whose callers are now stale?" | `structural_diff` β graph diff, stale callers, rename flags (Spec 21) |
| "What changes together with this / what's volatile?" | `get_change_coupling` β co-change + churn from git history (Spec 22) |
| "May I add this import here / what breaks the architecture?" | `check_architecture` β pre-edit verdict against declared rules (Spec 23) |
| Recording an architectural choice | `record_decision` **before** writing the code |
| Reading / checking a spec | `get_spec` Β· `search_specs` Β· `check_spec_drift` |
| Ranking what changed by risk | `detect_changes` |
Everything else (read a file, grep, list files) uses your native tools. Full reference: [docs/mcp-tools.md](docs/mcp-tools.md).
---
## Use OpenLore as a Claude Code Skill
OpenLore ships a canonical [Claude Code Skill](https://docs.claude.com/en/docs/claude-code/skills) at [`skills/openlore-orient/`](skills/openlore-orient/). Install it once and Claude Code will automatically call `orient()` at the start of every task β no `CLAUDE.md` editing required.
```sh
# From the OpenLore repo root:
npm run skill:install-local # β ~/.claude/skills/openlore-orient/
# Or copy into a single project's .claude/skills/:
cp -R skills/openlore-orient /path/to/your-project/.claude/skills/
```
The skill bundle ships a `SKILL.md` manifest, POSIX + PowerShell wrappers, a worked example, and a redacted real `orient()` JSON output so the model knows the response shape. See [`skills/openlore-orient/README.md`](skills/openlore-orient/README.md) for details.
### What's in `skills/` β and what actually installs
The `skills/` directory holds more than just `openlore-orient/`. Here's the map so nothing looks like a missing install step:
| Path | What it is | How it installs |
|---|---|---|
| [`skills/openlore-orient/`](skills/openlore-orient/) | The **canonical** Claude Code skill β the one we recommend everyone install. | `npm run skill:install-local`, or `cp -R` into a project's `.claude/skills/` |
| The 8 workflow skills (brainstorm, plan-refactor, execute-refactor, write-tests, review-changes, debug, implement-story, analyze-codebase) | Multi-agent **workflow** skills for Claude Code / OpenCode / Mistral Vibe. | `openlore setup` (sources them from [`examples/`](examples/) into `.claude/`, `.opencode/`, or `.vibe/`) |
| Loose top-level `skills/*.md` (e.g. `claude-openlore.md`, `openlore-plan-refactor.md`) | **Reference prompt templates** β copy-paste starting points, not auto-installed by any command. | Manual copy if you want them |
If you only install one thing, install `openlore-orient`. The workflow skills are opt-in via `openlore setup`; the loose `.md` files are just reference material.
---
## Core Features
**Analyze** (no API key)
Continuously maintains a structural representation of your codebase using pure static analysis. Builds a full call graph persisted to SQLite, runs label-propagation community detection to cluster tightly coupled functions, computes McCabe cyclomatic complexity for every function, and extracts DB schemas, HTTP routes, UI components, middleware chains, and environment variables. Outputs `.openlore/analysis/CODEBASE.md` β a ~600-token structural digest that compresses the equivalent of tens of thousands of exploratory tokens into a small, queryable summary.
With `--watch-auto`, the call graph updates incrementally on every file save: changed file and its direct callers are re-parsed and the graph is atomically swapped. Orient and BFS queries remain live between full analyze runs.
**Generate** (API key required)
Sends the analysis to an LLM in 6 structured stages: project survey β entity extraction β service analysis β API extraction β architecture synthesis β ADR enrichment. Produces `openspec/specs/` living specifications in RFC 2119 format with Given/When/Then scenarios.
**Drift** (no API key)
Compares git changes against spec mappings in milliseconds. Detects: Gap (code changed, spec not updated), Uncovered (new file, no spec), Stale (spec references deleted files), ADR gap (code changed in an ADR-referenced domain). Installs as a pre-commit hook.
**Install** (no API key)
`openlore install` auto-wires the popular agent surfaces (Claude Code, Cursor, Cline, Continue, AGENTS.md) so they call `orient()` automatically β no `CLAUDE.md` editing required. Each integration uses a fingerprinted managed block so re-runs are idempotent and hand-edits are detected. `--dry-run` previews diffs; `--uninstall` cleanly removes everything. See [docs/install.md](docs/install.md).
**Preflight** (no API key)
`openlore preflight` is a CI staleness gate: any pull request that edits files in the graph fails the check until the graph is refreshed. Drop-in templates for GitHub Actions, GitLab CI, and generic shell live in [`examples/ci/`](examples/ci/). Weighted scoring surfaces hubs first so a one-line leaf edit doesn't fail the same way a refactor of a top-of-stack module does. See [docs/preflight.md](docs/preflight.md).
**MCP** (no API key)
60 graph-native tools exposed over stdio. Together they act as a persistent architectural runtime for coding agents: orientation, graph traversal, semantic retrieval, drift awareness, decision context, and structural risk analysis.
`orient()` is the main entry point β it collapses the discovery loop into one call (measured: **β26% round-trips** on deep traces; see the [Value Scorecard](#value-scorecard--does-it-pay-for-itself)). `detect_changes` risk-scores changed functions using call graph centrality Γ change type multiplier. Every tool call runs the same guards β input validation against its schema (bad args β JSON-RPC `-32602`), a per-tool timeout, a deterministic output-size cap, and normalized error codes β and the surface carries complete MCP `annotations`. See [docs/mcp-tools.md](docs/mcp-tools.md).
`orient()` runs in **~430Β΅s p50** against a 15k-node codebase (TypeScript compiler, ~79k edges). Full benchmark results: [scripts/BENCHMARKS.md](scripts/BENCHMARKS.md).
**Test impact selection** (no API key, Spec 19)
`select_tests` answers "I changed `parseConfig()` β which tests should I run?" by walking the call graph **backward** from the change to every test that transitively reaches it (via `calls` + `tested_by` + inheritance edges), returning each test with its reaching path. This is static, call-graph-based regression test selection (RTS) β established CS β served to the agent at edit time instead of to CI after the fact. grep can't do it (the reach is through indirect calls); the model is slow and guesses; a deterministic graph does it instantly. It is an honest **over-approximate prioritizer** ("run these first"), not a sound replacement for the full suite β the response states its posture, coverage, and caveats (dynamic dispatch / DI can under-select). Inputs: a symbol set or a git diff. Deterministic and offline. See [docs/test-impact-selection.md](docs/test-impact-selection.md).
**Reachability & dead-code** (no API key, Spec 20)
`find_dead_code` runs cross-language mark-and-sweep over the call graph: reachability from roots (tests, imported symbols, route handlers, `main`), candidate-dead = the unreached remainder, and "what becomes dead if I delete X?" = the set reachable only through X. Prior art (knip, ts-prune) is TS/JS-only; this rides the unified tree-sitter graph across 15+ languages. Results are **confidence-tagged candidates, never deletion authority** β dynamic dispatch, DI, framework routing, and externally-consumed exports cause false positives, stated in the response. A conservative module-level liveness signal keeps high-confidence candidates trustworthy (it cut them from ~470 to ~35 on a real repo). See [docs/reachability-dead-code.md](docs/reachability-dead-code.md).
**Structural change analysis** (no API key, Spec 21)
`structural_diff` is a graph diff β the structural complement to `git diff`. Between two states (working tree vs a ref, or two refs) it reports functions and edges added/removed, signature changes, and the existing callers in *other* files now **stale** because a callee's signature moved under them. A review/refactor agent gets "this removed `gamma`, changed `alpha`'s signature, and 5 of its callers are now stale" instead of "these 40 lines changed". Only the changed files are re-parsed (old via `git show`, new via the working tree), so it is cheap and never mutates the canonical graph; rename/move ambiguity is flagged, not guessed. See [docs/structural-diff.md](docs/structural-diff.md).
**Change-coupling & volatility** (no API key, Spec 22)
`get_change_coupling` mines two facts from local git history that the call graph structurally cannot see: **co-change coupling** ("these files almost always change together" β the *invisible* coupling with no import or call edge) and **volatility/churn** ("this file changed 23 times" β a risk flag). Prior art (CodeScene) puts it well: change coupling "isnβt possible to calculate from code alone β it is mined from git." Surfaced additively in `orient` as caution signals. Support/confidence thresholds and a bulk-commit filter keep it honest; it is an **advisory signal, correlation not causation**. Local, deterministic, no network (reuses the Spec 18 git ingestion). See [docs/change-coupling.md](docs/change-coupling.md).
**Architecture invariant guardrails** (no API key, Spec 23)
`check_architecture` turns an architectural rule from a post-hoc CI failure into a **pre-write** guardrail. A repo declares constraints β `layers`, `forbidden`, `allowedOnly` β in `.openlore/architecture.json` (or via an `Invariant:` marker on a synced ADR, so a recorded decision *carries* its invariant), and the tool answers, before the agent writes the import, *"may a file under A import B?"* with a deterministic verdict + the governing rule + why, plus a full violation scan. Prior art (ArchUnit, dependency-cruiser, import-linter) enforces architecture in CI *after* the code is written and per-language; OpenLore's contributions are **cross-language** rules over the unified dependency graph and **agent-facing, pre-edit** evaluation (reusing the same `classifyLayerEdge` primitive that powers `CODEBASE.md`'s layer report). Opt-in and fully inert until rules are declared; never LLM-inferred; complements, not replaces, CI linters. See [docs/architecture-invariants.md](docs/architecture-invariants.md).
**Epistemic Lease** (no API key)
> **Core principle**: EpistemicLease models architectural drift as a behavioral navigation phenomenon rather than a semantic understanding problem. Context decay is driven by where the agent goes (cross-module trajectory), not what it knows.
As a session grows longer, agents naturally shift from authoritative graph retrieval toward internally cached reasoning. This is useful for fluency but dangerous for architectural correctness β cross-module assumptions go stale, dependency hallucinations accumulate, and delegation prompts embed incorrect repository understanding that cannot easily be corrected downstream.
The Epistemic Lease models this decay explicitly. Once your cached context ages or the repository moves since your last `orient()`, every MCP tool response carries a brief, **factual freshness note** β minutes since `orient()`, the cognitive-load score, modules touched, and whether the repo has new commits β phrased as information you can act on, *not* a command (it closes with "Informational signal; you decide whether to act on it"). Decay is driven by time elapsed since `orient()`, weighted cognitive load (heavier tools count more), and cross-module access breadth. A repo that has moved since `orient()` β very often your own commits β is surfaced as a fact and nudges the note to *degraded*; it never expires your model, because committing well-understood work is the most-informed action in a session.
The note has two states, with a load-driven detail line so it stays skimmable without resorting to coercion:
| Level | Trigger | Note |
|---|---|---|
| Degraded | load β₯ 30, age β₯ 15min, density β₯ 0.15, or repo moved since `orient()` | One-line factual note appended |
| Stale | load β₯ 60, age β₯ 30min, or density β₯ 0.30 | One-line factual note prepended; severity (a short "a fair amount / a lot of analysis has accumulated" detail) is driven by accumulated cognitive load (β₯ 85 / β₯ 110), **not** the wall clock |
Cross-module density is computed as a sliding-window trajectory model: `switches_in_last_15_calls / 15`. The fixed denominator prevents false positives during session warmup. Each module switch adds +5 cognitive debt; a high-density window adds +15; a burst (density β₯ 0.60) adds +20. A 5s dampening window prevents back-and-forth from double-counting.
An oscillation coefficient (`repeated_bigram_transitions / total_transitions`) separately distinguishes confusion loops (AβBβAβB scores 1.0) from genuine exploration (AβBβCβD scores 0.0). Severity within *stale* is driven by accumulated cognitive load, not the wall clock β so an idle-but-oriented session never escalates on time alone; once stale, a heavy architectural tool (weight β₯ 8) or density burst (β₯ 0.60) is a genuine activity burst that raises the note to its highest detail.
When fresh, injection is zero-overhead. Calling `orient()` resets the tracker. The lease never blocks and never commands β it surfaces neutral facts and leaves the decision to the agent, the same facts-not-coercion principle as the rest of OpenLore (decision `8e95746d`).
**Decisions** (API key for consolidation)
Agents call `record_decision` before writing code. Consolidation runs immediately in the background. At commit time, a pre-commit hook gates the commit until all verified decisions are reviewed and written back as requirements in `spec.md` files. Decisions are classified by scope (`local / component / cross-domain / system`); only `cross-domain` and `system` decisions produce ADR files, keeping the decision log signal-dense.
Decisions are also **first-class graph nodes**. At analyze time the active decision store is projected β the same parserβprojector split that puts Infrastructure-as-Code on the graph β into `decision::` nodes joined to the files they govern by `affects` edges. The relationship is stored, not recomputed: `analyze_impact` and `get_subgraph` return the governing decisions of a symbol and its blast radius as typed neighbors (`nodeType: "decision"`), and `orient` reports which relevant files each decision governs. This turns "what architectural decisions constrain this code, and what does changing it implicate?" into a deterministic graph query β the join no code-navigation competitor offers. The JSON store stays authoritative; the projection is derived and rebuilt on every analyze. See [docs/specs/openlore-spec-16-decisions-as-graph-nodes.md](docs/specs/openlore-spec-16-decisions-as-graph-nodes.md).
**Provenance** (no API key, local-only)
Reads the local `.git` history (and local `gh` if present) to project `authored_by` (file β person) and `changed_in_pr` (file β PR) edges onto the graph, so `orient` answers "last changed by X in PR #N" β provenance grep cannot surface. **No OAuth, no cloud connector, nothing is ever uploaded**: the git-only path needs no network, and `gh` is an optional enrichment that degrades gracefully when absent or unauthenticated. Bounded (last-touch + top-N recent authors + recent PRs per file) so the graph never bloats; deterministic for a fixed git state. The same local history feeds the change-coupling instrument (Spec 22). See [docs/provenance.md](docs/provenance.md).
**Telemetry** (opt-in, no API key)
Cognitive telemetry for empirical measurement of EpistemicLease behavior. Gated by `OPENLORE_TELEMETRY=1` β disabled by default. Writes append-only JSONL to `.openlore/telemetry/` per domain. Agent identity is captured from the MCP `initialize` handshake, enabling per-agent behavioral comparison.
```
.openlore/telemetry/
mcp.jsonl # every tool call: latency, errors, agent name
orient.jsonl # orient quality: function/file/insertion_point counts
cache.jsonl # readCachedContext hit/miss
epistemic-lease.jsonl # state transitions: degraded, stale, depth escalation
```
Analyze with `openlore telemetry`:
```
openlore telemetry [directory] # summary: latency, cache hit rate, obstinacy index
openlore telemetry --live # stream events in real time as they occur
```
Key metrics: **obstinacy index** (tool calls after stale before orient β measures whether agents act on warnings), **recovery efficiency** (staleβorient latency), **trajectory dynamics** (avg cross-module density, burst frequency). These turn EpistemicLease from a tuning-by-intuition system into an empirically measurable one.
---
## Architecture
OpenSpec provides semantic intent and workflow structure. openlore maintains the evolving implementation as a continuously queryable architectural graph for agents.
```mermaid
flowchart TD
Code[Codebase] --> Analyze[openlore analyze
tree-sitter Β· pure static analysis]
Analyze --> DB[(SQLite graph store
.openlore/analysis/call-graph.db)]
Analyze --> Digest[CODEBASE.md
~600-token structural digest]
subgraph shared["Projected onto shared node + edge primitives"]
direction LR
CodeNodes[functions + call edges]
Iac[IaC resources + references]
Dec[decisions + affects edges]
end
Analyze --> CodeNodes
Analyze --> Iac
Analyze -. active decision store .-> Dec
CodeNodes --> DB
Iac --> DB
Dec --> DB
DB --> MCP[60 MCP tools
orient Β· BFS Β· search Β· analyze_impact]
MCP --> Agent((Coding Agent))
Code -. optional, API key .-> Gen[openlore generate]
Gen --> Specs[openspec/specs/*.md
RFC 2119 living specs]
Code --> Drift[openlore drift
spec/code drift, ms, no API]
Agent -. record_decision .-> Gate[decisions pre-commit gate]
Gate --> Specs
```
The graph and the OpenSpec spec layer are co-equal: the graph makes orientation fast, the specs make it semantically grounded. Drift detection and decision gates connect both. Crucially, application code, Infrastructure-as-Code, and architectural **decisions** all project onto one shared set of node/edge primitives β so a single traversal answers questions that span all three. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full pipeline diagram.
**Decisions on the graph** (Spec 16) β a decision becomes a node joined to the files it governs by `affects` edges, so impact analysis returns governance as a neighbor:
```mermaid
flowchart LR
D["decision::c6d1ad07
North-star substrate"]:::dec
D -- affects --> F1[src/cli/export/scip.ts]
D -- affects --> F2[src/core/analyzer/iac/project.ts]
F1 -- calls --> G[exportScip]
classDef dec fill:#6f42c1,stroke:#4b2e83,color:#fff
```
---
## Design Decisions
OpenLore dogfoods its own decision system. These ADRs were recorded with `record_decision`, gated at commit, and synced into `openspec/specs/` β and (per Spec 16) are now projected onto the graph itself. They are the load-bearing constraints behind the architecture above:
| Decision | Rationale | Where |
|----------|-----------|-------|
| **North star is a deterministic structural context substrate** | Local-first plumbing (like tree-sitter/SCIP/LSP) that agents build on; every feature must make the coding-agent case more useful and stay grounded in static analysis, not LLM guessing | [ADR-0001](openspec/decisions/adr-0001-north-star-is-a-deterministic-structural-context-s.md) |
| **IaC resources project onto the existing graph primitives** | One projector maps infrastructure onto `FunctionNode`/`CallEdge` so every MCP tool works on IaC with zero new tooling | `analyzer` spec Β· `src/core/analyzer/iac/project.ts` |
| **Decisions project onto the graph the same way** | A parserβprojector split turns the decision store into `decision::` nodes + `affects` edges β governance becomes a deterministic graph join | `analyzer` spec Β· `src/core/decisions/project.ts` (Spec 16) |
| **EdgeStore uses SCHEMA_VERSION rebuild-on-bump, not migrations** | The graph is fully derivable from source, so a schema change drops and rebuilds β no migration code, no drift | `analyzer` spec Β· `src/core/services/edge-store.ts` |
| **BM25 keyword retrieval is the zero-network floor** | `orient`/`search_code` work with no API key or embedding server; dense embeddings are an optional upgrade, never a requirement | `analyzer` spec Β· Spec 06 |
| **SCIP is a one-way export, not a round-trip format** | The SQLite graph stays canonical; SCIP exports only the subset it can model, avoiding a lossy bidirectional contract | `cli` spec Β· `src/cli/export/scip.ts` |
| **MCP exposes a curated `navigation` preset, not all 60 tools** | A lean graph-traversal surface is what wins the Spec 14 agent benchmark; the full set stays available opt-in | `cli` spec Β· Spec 14 |
| **The `tools/list` prefix is trimmed losslessly + bounded by a guard, not byte-shaved** | Spec 28 measured it: MCP has no server-side schema deferral and the lossless byte-lever is ~2%; the real levers are the client (deferred schemas) and tool count, so we trim safely, guard against bloat, and report the limit | `cli` spec Β· Spec 28 |
| **Lean orientation skips enrichment compute, not just its payload** | `orient --lean` returns the navigation core for shallow lookups and skips the work behind the dropped blocks (extra embedding search, manifest/git reads); the rich default is unchanged | `cli` spec Β· Spec 27 |
| **Decision consolidation is serialized with a cross-process file lock** | Concurrent `record_decision` calls were losing drafts; a lock makes consolidation safe and every commit instant | `cli` spec Β· Spec 15 |
This table is not aspirational documentation β it is the live decision log the pre-commit gate enforces and Spec 16 makes queryable. See [docs/governance-dogfooding.md](docs/governance-dogfooding.md).
---
## Interop
OpenLore exports [SCIP](https://github.com/sourcegraph/scip) (Source Code Intelligence Protocol). Plug it into Sourcegraph code nav, GitHub stack graphs, Glean importers, or any SCIP-aware tool:
```bash
openlore analyze # build the graph (if you haven't already)
openlore export scip # writes ./index.scip
```
The SQLite graph stays canonical; SCIP is a one-way export of the subset SCIP can model (functions β symbols, call edges β occurrences). See [docs/scip-export.md](docs/scip-export.md) for what is and isn't exported and how to consume it.
---
## Federation (cross-repo)
The hardest agent-orientation questions cross repo boundaries: who calls `BillingService.refund`, where is event `X` consumed, how does data flow from service A to service B. OpenLore's answer is "SBOM-of-cognition" β every repo publishes a small, public, deterministic manifest describing what it exposes:
```bash
openlore manifest emit # writes ./.well-known/openlore.json
openlore manifest validate .well-known/openlore.json
```
The manifest captures the public API surface, HTTP routes, stats, dependencies, and spec state in a [versioned schema](schemas/openlore-manifest-v1.json). A future OpenLore federation index will read these manifests across many repos to answer cross-repo `orient()` questions, staying a thin merger rather than a giant analyzer. See [docs/federation.md](docs/federation.md).
A first deterministic slice of that index-of-indexes already ships. Each repo keeps its own independently-built `.openlore` index; a project-local registry references them and federated queries load only what they need β no merged graph is ever materialized:
```bash
openlore federation add ../billing-service --name billing # register a peer repo's index
openlore federation list # β indexed / β stale / β
unindexed
```
Once peers are registered, `analyze_impact`, `find_dead_code`, `select_tests`, and `find_path` take an opt-in `federation` flag and answer across the fleet β who consumes a published symbol, whether an export is dead *everywhere*, which consumer tests a change touches β always naming the repos consulted vs skipped, never guessing for an unindexed one. The capability is opt-in: `openlore mcp --preset federation`. See [docs/cli-reference.md](docs/cli-reference.md#federation-multi-repo).
---
## Documentation
| Topic | Doc |
|-------|-----|
| MCP tools reference (60 tools + parameters) | [docs/mcp-tools.md](docs/mcp-tools.md) |
| Agent setup (Claude Code, Cline, OpenCode, Vibeβ¦) | [docs/agent-setup.md](docs/agent-setup.md) |
| `openlore install` β auto-configure agent surfaces | [docs/install.md](docs/install.md) |
| LLM providers + embedding config | [docs/providers.md](docs/providers.md) |
| Drift detection in depth | [docs/drift-detection.md](docs/drift-detection.md) |
| Spec-driven tests + spec digest | [docs/spec-tests.md](docs/spec-tests.md) |
| CI/CD integration | [docs/ci-cd.md](docs/ci-cd.md) |
| Preflight CI staleness gate | [docs/preflight.md](docs/preflight.md) |
| SCIP export (Sourcegraph/Glean interop) | [docs/scip-export.md](docs/scip-export.md) |
| Cross-domain impact (code β infrastructure) | [docs/cross-domain-impact.md](docs/cross-domain-impact.md) |
| Local provenance (git/PR, no OAuth) | [docs/provenance.md](docs/provenance.md) |
| Test impact selection (which tests to run) | [docs/test-impact-selection.md](docs/test-impact-selection.md) |
| Reachability & dead-code analysis | [docs/reachability-dead-code.md](docs/reachability-dead-code.md) |
| Structural change analysis (graph diff) | [docs/structural-diff.md](docs/structural-diff.md) |
| Change-coupling & volatility (git-mined) | [docs/change-coupling.md](docs/change-coupling.md) |
| Architecture invariant guardrails (pre-edit) | [docs/architecture-invariants.md](docs/architecture-invariants.md) |
| Federation manifest (cross-repo) | [docs/federation.md](docs/federation.md) |
| CLI command reference | [docs/cli-reference.md](docs/cli-reference.md) |
| Interactive graph viewer | [docs/viewer.md](docs/viewer.md) |
| Analysis output files | [docs/output.md](docs/output.md) |
| Configuration reference | [docs/configuration.md](docs/configuration.md) |
| Programmatic API | [docs/api.md](docs/api.md) |
| Pipeline architecture | [docs/pipeline.md](docs/pipeline.md) |
| Internal design | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| Algorithms | [docs/ALGORITHMS.md](docs/ALGORITHMS.md) |
| Agentic workflows (BMAD, Vibe, GSD, spec-kit) | [docs/agentic-workflows.md](docs/agentic-workflows.md) |
| Troubleshooting | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) |
| Philosophy | [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) |
| Telemetry & cognitive metrics | [docs/telemetry.md](docs/telemetry.md) |
---
## Known Limitations
- **Incremental call graph updates are depth-1 only**: the MCP file watcher (`--watch-auto`, on by default) re-indexes signatures and edges on save for the changed file and its direct callers. Transitive callers (AβBβC, C changes, A stays stale) are only refreshed by the next `analyze --force`. For hub files with 100+ callerFiles, re-parse may take several seconds. The watcher prunes build/dependency directories (`target/`, `node_modules/`, `dist/`, `.venv/`, `vendor/`, β¦) so it stays light even on large repos; turn it off entirely with `openlore mcp --no-watch-auto`.
- **Static analysis only**: dynamic dispatch, runtime metaprogramming, and `eval`-based patterns are not captured in the call graph.
- **LLM spec quality varies**: generated specs reflect the model's understanding. Review sections covering complex business logic before treating them as authoritative.
- **Embedding is optional**: plain `openlore analyze` (no `--embed`, no `EMBED_*`) builds a keyword (BM25) search index out of the box, so `orient`, `search_code`, `suggest_insertion_points`, and `search_specs` work immediately. Configure an embedding endpoint (`EMBED_BASE_URL`/`EMBED_MODEL` or an `embedding` block in `.openlore/config.json`) to upgrade to hybrid dense+BM25 search, which is more accurate for semantic queries.
- **Large monorepos**: `openlore analyze` on large codebases may take several minutes. Graph storage itself has no practical limit β the pipeline (AST parsing, symbol extraction) is the bottleneck.
- **`node:sqlite` experimental warning on Node 22**: Node.js 22 prints `ExperimentalWarning: SQLite is an experimental feature` to stderr. The warning is gone on Node 24+. Suppress on Node 22 with `NODE_NO_WARNINGS=1 openlore analyze`.
---
## Requirements
- Node.js 22.5+
- API key for `generate`, `verify`, and `drift --use-llm`:
```bash
export ANTHROPIC_API_KEY=sk-ant-... # default provider
export OPENAI_API_KEY=sk-... # OpenAI
export GEMINI_API_KEY=... # Google Gemini
```
Or use a CLI-based provider (`claude-code`, `gemini-cli`, `mistral-vibe`, `cursor-agent`) β no API key, just the CLI on your PATH.
- `analyze`, `drift`, `mcp`, and `init` require no API key
**Languages supported**: TypeScript Β· JavaScript Β· Python Β· Go Β· Rust Β· Ruby Β· Java Β· C++ Β· Swift Β· C# Β· Kotlin Β· PHP Β· C Β· Scala Β· Dart Β· Lua Β· Elixir Β· Bash β call graphs ride the same node/edge primitives for every language. See [docs/languages.md](docs/languages.md) for per-language extraction limits and the `.h` C/C++ rule.
**Infrastructure-as-Code**: Terraform/HCL Β· Kubernetes Β· Helm Β· CloudFormation Β· Ansible Β· Pulumi Β· AWS CDK Β· CDKTF β IaC resources and their references are projected onto the same graph as application code, so `orient`, `search_code`, `get_subgraph`, and `analyze_impact` answer "what is the blast radius of changing this security group / ConfigMap / IAM role?" with zero new tooling. See [docs/iac.md](docs/iac.md).
**Cross-domain impact** (Spec 17): for embedded IaC (Pulumi/CDK/CDKTF), the code that provisions a resource is linked to it by a `references` edge, so `analyze_impact` traverses the codeβinfra boundary **end-to-end** β "what infrastructure does this handler reach?" and the reverse, "what code breaks if I change this resource?". Infra neighbors are surfaced as a typed, ecosystem-tagged `crossDomain` block, distinct from the code blast radius. A code-only navigator structurally cannot answer this. Reproducible example: [docs/cross-domain-impact.md](docs/cross-domain-impact.md).
---
## Development
```bash
npm install
npm run build
npm test # 2900+ unit tests
npm run typecheck
```
---
## Star History & Community
If OpenLore saves your agents from re-reading the same files, **star the repo** β it's the signal that tells us to keep building, and it helps other engineers find it.
- β **Star** to follow along: [github.com/clay-good/OpenLore](https://github.com/clay-good/OpenLore)
- π **Found a bug or have an idea?** Open an [issue](https://github.com/clay-good/OpenLore/issues).
- π€ **Want to contribute?** Start with [CONTRIBUTING.md](CONTRIBUTING.md) β the test suite, decision gate, and dogfooding loop are all documented.
- π¦ Install in one line: `npm install -g openlore && openlore install`
---
## Links
- [OpenSpec](https://github.com/Fission-AI/OpenSpec) β spec-driven development framework
- [AGENTS.md](AGENTS.md) β system prompt for direct LLM prompting
- [Examples](examples/) β BMAD, Vibe, GSD, drift-demo, spec-kit integrations