OpenLore

openlore

[!NOTE] spec-gen has been renamed to OpenLore. The npm package is now openlore and the CLI command is openlore. Existing projects: rename your .spec-gen/ directory to .openlore/ and reinstall (npm i -g openlore). See docs/RENAME-TO-OPENLORE.md for the full migration checklist.

Persistent architectural memory and structural cognition for AI coding agents.

openlore turns any evolving codebase into a navigable knowledge graph backed by OpenSpec living specifications. It maintains persistent architectural context across agent sessions: graph structure, specs, decisions, drift state, and semantic retrieval — so agents start each task already oriented instead of re-discovering the system from file reads.

---

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.

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/. 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.

MCP (no API key)

47 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 — one call replaces 10+ file reads. detect_changes risk-scores changed functions using call graph centrality × change type multiplier. See 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.

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.

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.

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. Every MCP tool response carries a freshness signal when the agent's architectural context has degraded or expired. Decay is triggered by any of: time elapsed since orient(), git hash divergence from the orient baseline, weighted cognitive load accumulation (heavier tools count more), or cross-module file access breadth.

The signal escalates through three levels to resist warning blindness:

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). When already stale, a heavy architectural tool (weight ≥ 8) or density burst (≥ 0.60) triggers immediate escalation to Stale [Critical].

When fresh, injection is zero-overhead. Calling orient() resets the tracker. Unlike governance systems, the lease never blocks — it modulates the agent's confidence in its own cached reasoning rather than constraining its actions.

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::<id> 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.

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.

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.

---