OpenLore: Deterministic, local-first memory and guardrails for AI coding agents

Notifications You must be signed in to change notification settings

Fork 33

Star 221

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

1,466 Commits

1,466 Commits

.claude/commands

.claude/commands

.github

.github

.planning/codebase

.planning/codebase

docs

docs

examples

examples

openspec

openspec

packaging/homebrew

packaging/homebrew

schemas

schemas

scripts

scripts

skills

skills

src

src

stubs/tree-sitter-cli-stub

stubs/tree-sitter-cli-stub

.gitignore

.gitignore

.npmrc

.npmrc

.nvmrc

.nvmrc

.prettierrc

.prettierrc

AGENTS.md

AGENTS.md

CHANGELOG.md

CHANGELOG.md

CLAUDE.md

CLAUDE.md

CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

README.md

README.md

SECURITY.md

SECURITY.md

eslint.config.js

eslint.config.js

flake.lock

flake.lock

flake.nix

flake.nix

package-lock.json

package-lock.json

package.json

package.json

tsconfig.json

tsconfig.json

vitest.config.ts

vitest.config.ts

vitest.integration.config.ts

vitest.integration.config.ts

Repository files navigation

Deterministic, local-first memory and guardrails for AI coding agents — with no LLM in the hot path.

One call tells your agent the code a task touches; one gate tells it what's unsafe to change.

Grounded in static analysis. No API key. Same answer every time.

A real, unedited recording — the published openlore on a fresh clone of ripgrep. install wires your agent and indexes the repo live — 235 files, 2,978 functions, 4,329 call edges in 14 seconds, no API key → orient returns the code a task touches → review catches a signature change that left 39 callers stale → prove projects the payoff. Re-record it yourself: docs/openlore-demo.tape.

Install · What you get · Benchmarks · Governance · How it works · vs. Alternatives · Docs · Community

Full table of contents

Start here: Install in one command · What you get · Is OpenLore for you? · See it in action · 5-Minute Quickstart · What it costs to adopt

Evaluate it: Value Scorecard (wins and losses) · OpenLore vs. Alternatives · Known Limitations · We dogfood our own governance

Understand it: How It Works · Governance · Core Features · Languages & IaC · Federation, Interop & PR review

Use it: Agent Cheat Sheet · Claude Code Skill · Requirements · Documentation · Development · Community

AI coding agents are powerful but amnesiac and ungoverned. Every task starts by re-reading the same files to rediscover structure; every long session quietly drifts toward confident-but-stale assumptions; and nothing tells the agent when a change is about to break a contract, cross an architectural boundary, or open a path into sensitive code.

OpenLore fixes both halves. It runs a one-time static analysis of your codebase and keeps a navigable knowledge graph — call structure, types, tests, decisions, IaC, and spec drift — incrementally fresh as you edit. Agents query it through MCP tools (or the CLI) to start every task already oriented, and to certify a change before it lands. 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 instead of served a confident guess.

Install in one command

npm install -g openlore && openlore install

That one command auto-detects your agent (Claude Code, Cursor, Cline, Continue, AGENTS.md), wires it to call orient() automatically, registers the MCP server, and builds the index — no API key, no config, no questions asked. Then ask your agent:

orient("add a payment method")

…and it begins the task already knowing the relevant functions, their callers, the matching specs, the tests, and the risk of changing each one — in a single call. Full setup, variants, and verification: 5-Minute Quickstart.

Zero config, everything discoverable. Core value needs no keys. To see every opt-in capability — embeddings, covering surfaces, the commit gate, the spec store, and more — whether each is active, and the one command to turn it on, run openlore features.

What you get

OpenLore does two things for an agent, both deterministic and local — it remembers your architecture so every task starts oriented, and it governs what the agent changes before the change lands.

🧠 Memory — start every task already oriented

Persistent architectural memory — orient() once; agents stop re-deriving the system from dozens of file reads, across sessions. Anchored notes and decisions survive refactors: a renamed or moved symbol carries its memory forward at the next analyze (with carriedAcross provenance) instead of orphaning it.

One-call orientation — orient(task) returns the relevant functions, their callers, matching spec sections, and insertion-point candidates in a single call. ~430µs p50 on a 15k-node graph.

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 & dead-code — "I changed parseConfig() — which tests should I run?" by backward call-graph reachability; cross-language mark-and-sweep finds what's dead, confidence-tagged, never deletion authority.

Context-freshness tracking (Epistemic Lease) — an agent is told when a cached fact has gone stale (context aged, repo moved) instead of acting on a confident guess.

🛡️ Governance — guardrails on what the agent changes

Change-impact certificate — change_impact_certificate flags when a diff newly opens a path into a sensitive boundary you declared (reachable after the change but not before) — differential, deterministic, no LLM.

Breaking-change verdict — certify_public_surface classifies every changed export breaking / non-breaking / potentially-breaking over a diff and names the in-repo consumers each break hits; conservative by construction, never silently "safe".

Architecture invariants, pre-edit — check_architecture answers "may a file under A import B?" against your declared layer/forbidden rules before the import is written — cross-language.

Grounded claims, not guesses — verify_claim returns a deterministic confirmed / refuted / unverifiable verdict with a citation receipt before an agent asserts "X is dead" or "Y is safe to change".

One commit gate — openlore enforce resolves every governance finding through your enforcement.policy and blocks only on what you class blocking (advisory by default, no API key). Decisions are recorded, gated, and synced into living specs; spec/code drift detected in milliseconds.

📊 Honest by construction — −26% agent round-trips on deep traces in large repos, with the losses published next to the wins; every public claim traces to a command you can run. Pure static analysis: no API key, no network, same answer every time.

Is OpenLore for you?

The fastest way to evaluate a tool is to find out quickly that it isn't for you. So:

✅ Strong fit A codebase big enough that you can't hold it in your head — and neither can the model. Private or niche code the model never memorized. Long agent sessions where stale assumptions compound. Polyglot repos, or code plus the IaC that deploys it. Anywhere "the agent changed something it shouldn't have" is a real cost, not a hypothetical.

🤔 Try it, but measure Mid-size repos and mixed workloads. The orientation win scales with size and depth, so run openlore prove --estimate (seconds, no API key) before you commit to it.

❌ Probably not yet A small repo the model already knows, answering shallow questions like "who calls parseArgs" — your agent's built-in search is cheaper, and we publish the measurement that says so. Also: if you want something to perform the refactor, OpenLore is the wrong layer — it locates and certifies, it never edits your code.

One idea, if you only read one line of this README: an agent's expensive failure mode isn't ignorance — it's confidence. A model that doesn't know a function exists will go look. A model that "knows" a stale fact will confidently build on it, and you pay for that at review time. OpenLore is built so the agent can be told "that fact is stale" and "this change opens a path you said was sensitive" — deterministically, from the graph, with no second model in the loop guessing about the first.

See it in action

The same task, twice. Ask an agent to add a flag to a command it has never seen:

Without OpenLore With OpenLore

Opening move grep a guessed name → open a file → wrong layer → open three more orient("add a --since flag to the blast-radius command")

What it learns file contents, one at a time, in whatever order it guessed the functions, their callers, the matching spec sections, and the ranked insertion points — in one call

What it misses the five callers living in files it never opened every caller the graph can see — statically resolvable ones, at least; dynamic dispatch is still nobody's friend

Before it commits "looks right to me" blast_radius → tests to run; certify_public_surface → the consumers this signature change breaks, by name

The measured effect of that shape change on deep, multi-hop tasks: 25 → 16 round-trips on excalidraw, −26% aggregate. It is not magic — it is the difference between rediscovering structure per task and querying it. Full numbers, including where this doesn't pay off, in the Value Scorecard.

orient("add a --since flag to the blast-radius command") — one query replaces most exploratory file reads

Real output — openlore orient --json "add a --since flag to the blast-radius command", run on this repo (abridged: fields elided, caller lists flattened to names):

{ "relevantFiles": ["src/cli/commands/blast-radius.ts", "src/core/services/mcp-handlers/blast-radius.ts"], "relevantFunctions": [ { "name": "computeBlastRadius", "filePath": "src/core/services/mcp-handlers/blast-radius.ts", "signature": "async function computeBlastRadius(input: BlastRadiusInput): Promise", "fanIn": 5, "isHub": true, "language": "TypeScript" } ], "callPaths": [ { "function": "computeBlastRadius", "callers": ["handleBlastRadius", "computeImpactCertificate", "runBlastRadiusCli", "composeReview", "collectGovernanceFindings"] } ], "landmarks": [ { "name": "runBlastRadiusCli", "hops": 1, "signals": [{ "label": "orchestrator", "evidence": { "fanOut": 11 } }, { "label": "volatile", "evidence": { "level": "medium", "commits": 6, "coChangedWith": 5 } }] } ], "insertionPoints": [ { "rank": 2, "name": "computeBlastRadius", "role": "hub", "strategy": "cross_cutting_hook", "reason": "computeBlastRadius is called by 5 functions -- adding logic here affects the entire callsite surface." } ], "suggestedTools": ["record_decision", "analyze_impact", "get_subgraph", "check_spec_drift"] }

The agent knows exactly where to look, what it touches, and what's risky to touch — before reading a single file. Every field is computed from the graph; nothing is inferred by a model.

Gate a risky change before it lands — deterministic, in CI or a pre-commit hook

openlore impact-certificate --base main # does my diff open a new path into a declared sensitive boundary? openlore certify-public-surface --base main # did I break a consumer's public API contract? openlore blast-radius # callers/layers touched, tests to run, specs & decisions that drift openlore enforce --hook # one gate; blocks only on findings you've classed blocking

No LLM, no API key — the same grounded answer every run. Advisory by default; you opt into blocking per finding.

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 a

[truncated for AI cost control]