OpenLore

Deterministic, Local-First Memory and Guardrails for AI Coding Agents

OpenLore is a runtime defense system designed to address two critical limitations of AI coding agents: their lack of persistent memory and their absence of governance mechanisms. Unlike traditional approaches that rely on large language models (LLMs) in the hot path, OpenLore operates deterministically and locally, ensuring consistent, repeatable outputs without external dependencies. It achieves this by performing a one-time static analysis of a codebase, constructing a live knowledge graph that captures call structures, types, tests, architectural decisions, and Infrastructure-as-Code (IaC). This graph serves as a queryable resource for AI agents, enabling them to start tasks with pre-oriented context and validate changes before execution.

The system eliminates the need for API keys, external model calls, or configuration overhead. Installation is streamlined to a single command, which auto-detects the AI agent in use (e.g., Claude Code, Cursor, Cline, Continue, Pi) and integrates OpenLore seamlessly. The agent then queries the knowledge graph via a single orient() call, receiving structured data about relevant functions, their callers, associated tests, and potential risks—all derived from the graph without model inference.

OpenLore’s design ensures reproducibility: the same query always returns the same grounded answer, and agents are explicitly notified when cached data becomes stale. This deterministic behavior contrasts sharply with LLM-driven approaches, which may produce inconsistent or outdated results.

How It Works

OpenLore functions through two core mechanisms: memory and governance. The memory component provides agents with pre-computed, structured knowledge about the codebase, while the governance component enforces guardrails to prevent unsafe or unintended changes.

Memory: Oriented Task Execution

• Single-Call Orientation: The orient(task) function returns a comprehensive snapshot of the code relevant to a task, including functions, callers, specifications, tests, and insertion points. For example, querying orient("add a payment method") immediately surfaces the affected functions, their dependencies, and risk assessments without manual file traversal.
• Unified Knowledge Graph: The system consolidates application code, Infrastructure-as-Code (IaC), and architectural decisions into a single graph. This allows agents to query across disparate layers—such as linking a code change to its deployment configuration—without siloed analysis.
• Staleness Detection: Agents are alerted when cached data no longer reflects the current state of the repository, preventing decisions based on outdated assumptions. This is achieved through explicit checks against the live graph rather than relying on model confidence scores.

Governance: Enforcing Safe Changes

• Unlike LLM-based tools, OpenLore never silently assumes a change is safe.
• Boundary Protection: The changeimpactcertificate command flags when a modification introduces new paths into declared boundaries (e.g., sensitive modules or restricted APIs).
• Claim Verification: The verifyclaim function evaluates assertions made by agents (e.g., "X is deprecated" or "Y is safe to modify") by cross-referencing them with the knowledge graph. Results are categorized as confirmed, refuted, or unverifiable, accompanied by citations from the graph.
• By default, enforcement is advisory, requiring explicit configuration for strict blocking.

OpenLore’s governance features are designed to be opt-in and configurable. Commands like openlore features allow users to enable or disable capabilities (e.g., embeddings, commit gates) with a single command, ensuring flexibility without sacrificing determinism.

Use Cases

OpenLore is particularly effective in scenarios where AI agents operate on complex, large, or niche codebases—environments where exploratory overhead and governance risks are costly. Its utility is quantified through benchmarks measuring round-trip reductions, correctness, and cost efficiency across different repository sizes and task types.

Target Environments

• Large or Unfamiliar Codebases: Repositories exceeding the cognitive capacity of both developers and models benefit from OpenLore’s pre-computed graph. For instance, a repository with 3,000 files (e.g., Django) sees a 7% cost reduction and 26% fewer round-trips for deep trace tasks compared to unassisted agents.
• Private or Niche Code: Proprietary or domain-specific codebases, which LLMs are unlikely to have encountered, gain structured context through OpenLore’s local analysis. This mitigates hallucinations and ensures decisions are grounded in actual code.
• Long-Lived Sessions: In extended development sessions, stale assumptions accumulate without OpenLore’s staleness detection. The system warns agents when cached data diverges from the current state, maintaining accuracy over time.
• Polyglot or IaC-Heavy Repositories: OpenLore’s unified graph integrates multiple languages and deployment configurations (e.g., Terraform, Kubernetes manifests). This enables cross-layer queries, such as tracing a code change to its deployment impact.
• The commit gate and boundary checks prevent catastrophic errors before they propagate.

Benchmark Insights

OpenLore’s efficacy is validated through controlled benchmarks comparing agent performance with and without the system.

• Deep Trace Tasks in Large Repositories: Agents using OpenLore achieve a 26% reduction in round-trips for complex, multi-hop queries (e.g., "How does X flow through Y?"). Cost savings range from 7% to 21%, scaling with repository size. For example, the excalidraw repository (640 files) reduced round-trips from 25 to 16, while django (3,000 files) saw a 7% cost improvement.
• In such cases, the system’s orientation tax (additional queries) can outweigh benefits, though this is task-dependent. Users are advised to run openlore prove --estimate to project potential overhead before adoption.
• Correctness Preservation: Across all scenarios, OpenLore maintains 100% correctness while reducing agent round-trips.

Benchmarks are reproducible and transparent. The openlore prove command generates a scorecard comparing performance with and without OpenLore, including token costs and round-trip metrics. Results are published alongside losses to ensure honesty by construction.

Key Features and Capabilities

• Uncovered searches avoid presenting ranked lists, while weak matches omit editing advice.
• Index Staleness and Health Checks: Commands like openlore status and doctor provide visibility into the index’s health, including retrieval mode, build time, and staleness.
• Spec-to-Evidence Tracing: Audits can link scenarios to reachable tests, flagging gaps where observable outcomes are absent.
• Change-Oriented Analysis: Tools like changeimpactcertificate focus on symbols that actually changed, reducing noise in busy files. The doctor command identifies oversized analysis corpora before builds, while fingerprint budget reports pinpoint paths consuming computational resources.
• Users can configure tool surfaces via .openlore/config.json to balance performance and functionality.
• Governance Portability: Public-surface checks generate stable finding codes and recommend SemVer bumps.

Recent releases (e.g., v3.3.0, v3.2.0) have introduced incremental improvements:

• Governance features now support intentional breaking changes with justifications.
• v3.1.1 (2026-09-09): Optimized first-run performance, fixed Windows compatibility issues, and reduced redundant work in serving paths.

OpenLore’s design prioritizes determinism, local execution, and integration with existing toolchains. By eliminating LLM dependencies in the hot path, it reduces latency, improves accuracy, and enables reproducible workflows for AI-assisted development.

Real-World Example: Orienting an Agent

A practical demonstration of OpenLore’s capabilities involves orienting an agent to add a flag to an unfamiliar command. Without OpenLore, the agent might:

• Guess a function name via grep, open the wrong file layer, and repeat the process across multiple files.
• The agent issues orient("add a --since flag to the blast-radius command"), receiving a single response containing:
• Relevant files (src/cli/commands/blast-radius.ts, src/core/services/mcp-handlers/blast-radius.ts).
• Functions (computeBlastRadius), their signatures, and callers (handleBlastRadius, computeImpactCertificate, etc.).
• The agent immediately knows where to modify the code, which tests to run, and which consumers would break—all derived from the graph without file exploration.
• Before committing, the agent uses certifypublicsurface to confirm that no critical consumers are affected, ensuring a safe change.

The system’s output is purely derived from the graph, eliminating model hallucinations or incomplete inferences.

Technical Underpinnings

• Static Analysis Engine: Performs one-time analysis of the repository to build a knowledge graph. This includes parsing code, resolving call structures, and indexing tests and specifications.
• Knowledge Graph: A directed graph representing code entities (functions, classes), their relationships (calls, dependencies), and metadata (tests, decisions). The graph is updated incrementally as the repository evolves.
• Query Interface: Provides commands like orient(), certifypublicsurface, and verifyclaim to interact with the graph.
• Governance Layer: Enforces rules through commands like openlore enforce and changeimpactcertificate. It integrates with version control systems to block or flag unsafe changes.
• Platform Compatibility: Supports TypeScript, Dart, Elixir, and other languages via tree-sitter grammars. It operates on Windows, Linux, and macOS, with POSIX-compliant path handling across platforms.

OpenLore’s architecture ensures that all operations are local and deterministic. There are no external API calls during runtime, and all data is derived from the repository’s current state.

Evaluation and Transparency

OpenLore’s claims are validated through rigorous benchmarks and public methodologies.

• Honesty Contract: All published savings numbers are derived from measurable benchmarks. Losses are reported alongside wins to provide a balanced view. For example, the Spec 14 agent benchmark (2026-06-01) compared Claude Sonnet’s performance with and without OpenLore across 4 median runs.
• Reproducible Metrics: The openlore prove command generates scorecards comparing round-trip counts, token costs, and correctness.
• Task-Specific Insights: Benchmarks distinguish between deep trace tasks (where OpenLore excels) and shallow queries (where overhead may occur). For instance, excalidraw (640 files) saw a 21% cost reduction, while gin (110 files) experienced negligible impact.
• Platform and Language Support: OpenLore’s benchmarks include polyglot repositories and IaC-heavy setups, demonstrating its applicability beyond monolithic codebases. Recent updates (e.g., Dart/Elixir support) expand its utility for multi-language projects.

The project maintains transparency through public documentation, including:

• Methodology: Detailed in docs/AGENT-BENCHMARKS.md, outlining benchmark setup, metrics, and reproducibility steps.
• Changelogs: Release notes (e.g., v3.3.0, v3.2.0) document incremental improvements, bug fixes, and new features with version-specific details.
• Command Reference: A full table of governance commands and their capabilities is available in the Governance section of the documentation.

Sources

• github.comhttps://github.com/clay-good/OpenLore