OpenLore (formerly spec-gen)

spec-gen · clay-good/spec-gen · ★ 137 · last commit 2026-05-26

Give AI agents persistent architectural orientation by reverse-engineering OpenSpec living specs from code and exposing the graph via 45 MCP tools, reducing per-session orientation cost from 30k tokens to 1k.

Best whenContext decay is a behavioral navigation problem — where the agent goes (cross-module trajectory) determines architectural confidence, not what it remembers.

Skip ifRe-reading same files every session, LLM inventing architectural assumptions after long sessions

vs seeds

openspec(living specs), but openlore is uniquely a reverse-engineering (archaeology) framework — it extracts specs from existing…

Primitive shape 54 total

Skills 7 Hooks 2 MCP tools 45

Summary

spec-gen (OpenLore) — Summary

spec-gen has been renamed to OpenLore (npm install -g openlore, CLI binary openlore). It is a TypeScript/Node.js CLI tool that turns any codebase into a persistent architectural knowledge graph backed by OpenSpec living specifications. Three independent layers: (1) static analysis builds a call graph, cluster map, and McCabe complexity index into .openlore/analysis/CODEBASE.md; (2) spec layer generates LLM-backed OpenSpec living specs, drift detection, and ADR gates; (3) agent runtime exposes 45 MCP tools (including orient()) that replace exploratory file reads with targeted graph queries. The Epistemic Lease tracks session context decay — when an agent cross-module trajectory degrades architectural confidence, escalating signals force orient() re-calls. Ships 7 skills for Claude Code integration plus an AGENTS.md "code archaeologist" persona. Claimed 430µs p50 orient() against a 15k-node TypeScript codebase.

Differs from seeds: Closest to ccmemory (persistent memory via MCP) and spec-driver (living specs + skills), but openlore is uniquely a code-archaeology framework — it reverse-engineers specifications from existing code rather than writing specs for new code. The Epistemic Lease (cross-module trajectory model for architectural confidence decay) and orient() as a file-read replacement are novel. Unlike ccmemory (Neo4j graph), openlore uses SQLite with label-propagation community detection. Unlike taskmaster-ai (task management MCP), openlore's 45 tools focus entirely on structural orientation and drift awareness.

Overview

spec-gen (OpenLore) — Overview

Origin

GitHub: clay-good/spec-gen (137 stars, 19 forks, MIT, TypeScript). Published to npm as openlore. Renamed from spec-gen to openlore per README. Active as of 2026-05-26.

Philosophy

From README:

"Persistent architectural memory and structural cognition for AI coding agents."

"AI agents are powerful but amnesiac. 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 often burns 15,000–50,000 tokens per orientation pass, before a single line of useful code is written."

The core principle: "Archaeology over Creativity"

"Extract truth from code, don't invent features. Evidence-based: Every requirement traces back to actual implementation."

The Epistemic Lease:

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

Key Claims

orient() runs in ~430µs p50 against a 15k-node codebase (TypeScript compiler, ~79k edges)
Reduces orientation cost from ~30,000 exploratory tokens to ~1,000 targeted tokens
Pre-commit drift detection in milliseconds without API key
Incremental call graph updates on file save via --watch-auto

Antipatterns Named

Re-reading same files every session
LLM hallucinating architectural assumptions after long sessions
Architecture drift between code and specs
"Dependency hallucinations" that compound silently

Architecture

spec-gen (OpenLore) — Architecture

Distribution

Type: npm package + MCP server
Package: openlore on npm
Binary: openlore
Language: TypeScript (Node.js)
License: MIT

Install

npm install -g openlore
# or from source:
git clone https://github.com/clay-good/openlore
cd openlore && npm install && npm run build && npm link
# or via Nix:
nix run github:clay-good/openlore -- analyze

Three Layers

Layer	API Key?	Purpose
Static Analysis	No	Call graph, clusters, McCabe CC, CODEBASE.md
Spec Layer	Yes (for generation)	LLM living specs, drift, ADR
Agent Runtime	No	45 MCP tools, orient(), graph queries

Directory Tree (project after init)

.openlore/
  analysis/
    CODEBASE.md         # ~600-token structural digest
    graph.sqlite        # SQLite call graph (FTS5 index)
  specs/                # Generated OpenSpec living specs
    overview/spec.md
    {domain}/spec.md
    architecture/spec.md
  config.json           # Configuration

openspec/               # OpenSpec directory (for spec generation)
  config.yaml
  specs/
    overview/spec.md
    {domain}/spec.md

Project Structure (source)

src/
  cli/
    commands/           # 15 CLI subcommands
    tui-approval.ts     # TUI for drift approval
  core/
    analyzer/           # Static analysis + call graph
    decisions/          # ADR management
    digest/             # CODEBASE.md generation
    drift/              # Spec drift detection
    generator/          # LLM spec generation (6 stages)
    services/           # Epistemic Lease, telemetry
    test-generator/     # Test generation from specs
    verifier/           # Spec verification

skills/                 # Claude Code integration (7 skills)
  openlore-analyze-codebase.md
  openlore-execute-refactor.md
  openlore-implement-feature.md
  openlore-plan-refactor.md
  claude-openlore.md
  openspec-skill.md
  story-to-change.md

AGENTS.md               # "Code archaeologist" agent persona

Required Runtime

Node.js 18+
Optional: LLM API key for spec generation (OpenAI compatible)

Components

spec-gen (OpenLore) — Components

CLI Subcommands (15)

Command	API Key?	Purpose
`openlore analyze`	No	Build call graph, clusters, CODEBASE.md
`openlore generate`	Yes	Generate living OpenSpec specs
`openlore drift`	No	Detect spec/code drift
`openlore decisions`	Yes (for consolidation)	Manage ADRs
`openlore mcp`	No	Start MCP server (45 tools)
`openlore view`	No	View architecture in browser
`openlore init`	No	Initialize .openlore directory
`openlore verify`	No	Verify spec completeness
`openlore run`	Yes	Full pipeline
`openlore doctor`	No	Diagnose setup issues
`openlore setup`	No	Interactive setup
`openlore refresh-stories`	Yes	Refresh user stories in specs
`openlore audit`	No	Audit spec quality
`openlore test`	No	Run spec-based tests
`openlore digest`	No	Generate CODEBASE.md only
`openlore telemetry`	No	Configure telemetry

MCP Tools (45)

Key tools:

orient(query) — Primary entry point; replaces 10+ file reads with 1 graph query
analyze_codebase — Full structural analysis
get_architecture_overview — Architecture summary
get_call_graph — Function call graph
detect_changes — Risk-score changed functions (centrality × change type)
record_decision — Record architectural decision before writing code
39+ tools for BFS traversal, semantic search, drift awareness, cluster navigation

Skills (7 for Claude Code)

Skill	Purpose
`openlore-analyze-codebase`	MCP-driven codebase analysis
`openlore-implement-feature`	Feature implementation with orient context
`openlore-execute-refactor`	Refactor with graph awareness
`openlore-plan-refactor`	Plan refactor using call graph
`claude-openlore`	General openlore operations
`openspec-skill`	OpenSpec workflow
`story-to-change`	Convert user story to code change

Epistemic Lease System

The agent runtime tracks session context decay via 4 triggers:

Time elapsed since orient()
Git hash divergence from orient baseline
Weighted cognitive load accumulation
Cross-module file access breadth

Escalation levels (4):

Level	Signal
Degraded	Advisory appended
Stale	Procedural block prepended
Stale [Elevated]	Risk-framing with consequences
Stale [Critical]	Imperative: `STOP. Call orient().`

Pre-Commit Hook

openlore drift as a pre-commit hook:

Detects: Gap (code changed, spec not updated), Uncovered (new file), Stale (deleted ref), ADR gap
In milliseconds, no API key required

Prompts

spec-gen (OpenLore) — Prompts

Excerpt 1: AGENTS.md — Code Archaeologist Persona

Technique: Named role + evidence-based constraint + no-early-stop mandate.

## Agent Role

You are a "code archaeologist" — your job is to reverse-engineer OpenSpec specifications from existing codebases. You document what code ACTUALLY does, not what you imagine it should do.

## Core Principles

1. **Archaeology over Creativity**: Extract truth from code, don't invent features
2. **Evidence-based**: Every requirement traces back to actual implementation
3. **OpenSpec-native**: Output follows OpenSpec conventions exactly
4. **Never stop early**: Do not say "Task completed", "Done", or "Finished" without having re-read the original request and verified every part of it is addressed.

Excerpt 2: openlore-analyze-codebase skill (from `skills/openlore-analyze-codebase.md`)

Technique: Step-by-step MCP tool orchestration with progressive disclosure of results.

## When to use this skill

Trigger this skill whenever the user asks to **analyze a codebase** with openlore, with phrasings like:
- "analyze my project / my code"
- "give me a code quality report"
- explicit command `/openlore-analyze-codebase`

This skill is **read-only** — it modifies no files. It produces a report and suggests next steps.

## Step 2 — Run static analysis

```xml
<use_mcp_tool>
  <server_name>openlore</server_name>
  <tool_name>analyze_codebase</tool_name>
  <arguments>{"directory": "$DIRECTORY"}</arguments>
</use_mcp_tool>

Present a concise summary:

Top 3 clusters by file count
Global entry points — public-facing roots
Critical hub functions (high fan-in — touch with care)


## Excerpt 3: Epistemic Lease Signal Levels (from README)

**Technique**: Graduated escalation signals — progressive urgency to resist warning blindness.

Level	Trigger	Signal style
Degraded	load ≥ 30, age ≥ 15min, or cross-module density ≥ 0.15	Advisory signal appended
Stale	load ≥ 60, age ≥ 30min, git hash divergence, or density ≥ 0.30	Procedural block prepended: what NOT to do
Stale [Elevated]	load ≥ 85 or age ≥ 45min	Risk-framing: names downstream consequences
Stale [Critical]	load ≥ 110 or age ≥ 60min	Imperative: STOP. Call orient(). — minimal, hardest to skim

Cross-module density = switches_in_last_15_calls / 15


## Excerpt 4: orient() Response Format

**Technique**: Structured context injection replacing file reads with targeted graph results.

```json
{
  "functions": [
    {
      "name": "processPayment",
      "file": "src/payments/processor.ts",
      "risk": "medium",
      "fanIn": 4,
      "callers": ["handleCheckout", "retryFailedCharge"],
      "callType": "direct"
    }
  ],
  "specDomains": ["payments — §CardValidation, §PaymentFlow"],
  "insertionPoints": ["src/payments/processor.ts:87 — after existing charge logic"],
  "callPath": "POST /charge → handleCheckout → processPayment → validateCard → stripeClient.charge"
}

Uniqueness

spec-gen (OpenLore) — Uniqueness

Differs from Seeds

Most similar to ccmemory (persistent architectural memory via MCP) and spec-driver (living specs + quality gates), but openlore's orientation is fundamentally different: it is a reverse-engineering tool (archaeology) not a forward-engineering harness. ccmemory stores memories the developer feeds it; openlore extracts architectural truth from code via static analysis. The Epistemic Lease (cross-module trajectory model for context decay) is novel — no seed tracks where the agent navigated as a proxy for architectural confidence. Unlike ccmemory (Neo4j), openlore uses SQLite with label-propagation community detection. The orient() tool (single call replacing 10+ file reads) and its benchmark claims (~430µs, 1-3k tokens) are unique. The 6-stage LLM spec generation pipeline (survey → extract → service → API → synthesize → ADR enrich) is more structured than any seed's spec workflow.

Positioning

Category: Architectural memory + spec reverse-engineering tool
Target user: Engineers joining brownfield codebases, or maintaining large systems where context reconstruction is expensive
Key differentiator: orient() as a token-efficient file-read replacement backed by a persistent call graph

Observable Failure Modes

npm rename confusion: The README prominently notes "spec-gen has been renamed to openlore" — users who find the repo via the old name may be confused by the package name change
API key for generation: Layer 2 (spec generation) requires an LLM API key; advertised as optional but significantly reduces value without it
Static analysis accuracy: Call graph from static analysis may miss dynamic dispatch, monkey-patching, or reflection-heavy code patterns
Epistemic Lease is advisory-only: Signals never block — agents can ignore them. Effectiveness depends on the agent responding to escalating warnings
Pre-commit hook blocking: The drift pre-commit hook could block valid commits if specs lag behind code in fast-moving development; requires conscious spec maintenance

Novel Patterns

Epistemic Lease: Mathematical model of session architectural confidence decay based on cross-module trajectory — unique in the corpus
orient() as file-read replacement: Graph-native context injection vs file-based reads — token efficiency claim is quantified
Oscillation coefficient: Detects confusion loops (A→B→A→B) vs exploration (A→B→C→D) as separate signals
Decision scope classification: only cross-domain and system decisions produce ADR files — prevents ADR noise pollution

Workflow

spec-gen (OpenLore) — Workflow

Primary Workflow

Minimum (No API Key)

openlore analyze    # Build call graph → CODEBASE.md
openlore mcp        # Start MCP server
→ orient("add a payment method")  # Replaces file reads

Full Pipeline (API Key Required)

openlore analyze    # Static analysis → CODEBASE.md
openlore generate   # LLM → living specs in openspec/specs/
openlore drift      # Detect spec/code drift
openlore decisions  # Manage ADRs
openlore mcp        # Start MCP server

Spec Generation (6 Stages)

LLM-driven spec generation uses staged prompting:

Project survey
Entity extraction
Service analysis
API extraction
Architecture synthesis
ADR enrichment

Output: openspec/specs/{domain}/spec.md files in RFC 2119 format with Given/When/Then scenarios.

Decision Gate (Pre-Code ADR)

record_decision() → agent calls before writing code
→ Consolidation runs immediately in background
→ Pre-commit hook gates commit until decisions are reviewed
→ Written back as requirements in spec.md files

Only cross-domain and system scope decisions produce ADR files (local/component decisions are logged but don't create ADR files).

Phase to Artifact Map

Phase	Artifact
Static analysis	`.openlore/analysis/CODEBASE.md`, `graph.sqlite`
Spec generation	`openspec/specs/{domain}/spec.md`
Drift detection	Drift report (stdout)
ADR management	ADR files in spec.md
MCP runtime	Live graph queries via 45 tools

Approval Gates

Pre-commit hook: openlore drift blocks commit until spec drift is resolved
Decision gate: Pre-commit blocks until architectural decisions are reviewed
Drift TUI: Interactive terminal approval for drift items (tui-approval.ts)

Incremental Updates

With openlore analyze --watch-auto:

Changed file + direct callers are re-parsed on every file save
Call graph atomically swapped
orient() and BFS queries remain live between full analyze runs

Memory Context

spec-gen (OpenLore) — Memory & Context

State Storage

Type: SQLite (call graph, FTS5 index, decision log)
Persistence scope: Project (.openlore/ directory)
Search: Graph-native (BFS/DFS) + FTS5 full-text

State Files

Path	Purpose
`.openlore/analysis/graph.sqlite`	Call graph, clusters, McCabe CC, FTS5 index
`.openlore/analysis/CODEBASE.md`	~600-token structural digest
`openspec/specs/{domain}/spec.md`	Living OpenSpec specifications
`openspec/config.yaml`	Spec configuration

Epistemic Lease (Cross-Session Decay Tracking)

The Epistemic Lease tracks when an agent's architectural context has degraded:

Triggers: time since orient(), git hash divergence, cognitive load, cross-module access density
Decay metric: weighted cognitive load + cross-module trajectory (switching coefficient)
Oscillation detection: repeated_bigram_transitions / total_transitions detects confusion loops (A→B→A→B = 1.0) vs genuine exploration (A→B→C→D = 0.0)
Reset: calling orient() resets the tracker

The lease never blocks — it modulates agent confidence signals via metadata on MCP tool responses.

Context Injection

orient(query) replaces 10+ file reads with a single graph query returning:

Relevant functions + their callers/callees
Spec domain mappings
Insertion point candidates
Call paths from entry to implementation

Claimed: ~1-3k tokens vs 15-50k for file-by-file exploration.

Cross-Session Handoff

Yes — SQLite graph persists across sessions. openlore analyze --watch-auto keeps the graph incrementally updated on file save.

Compaction Handling

Indirect — the Epistemic Lease signals when context has degraded, prompting orient() re-call. No explicit pre-compact hook.

Telemetry

Opt-in telemetry pipeline (configurable via openlore telemetry). No API key required for telemetry.

Orchestration

spec-gen (OpenLore) — Orchestration

Multi-Agent: No

Single-agent focused. The MCP tools and skills are designed for one agent consuming graph context.

Orchestration Pattern: Sequential

Single agent queries graph → implements → records decision → commits (gated by pre-commit hook).

Isolation Mechanism: None

Works in-place. No worktree, no container.

Execution Mode: Interactive-loop + Event-driven

Interactive: agent calls openlore mcp tools during session
Event-driven: --watch-auto updates graph on file save; pre-commit hook gates on drift

Multi-Model: No

Model-agnostic. Any OpenAI-compatible API for spec generation. No model routing.

Consensus Mechanism: None

Prompt Chaining: Yes

analyze → CODEBASE.md → generate (uses CODEBASE.md) → living specs → drift (uses specs + code) → pre-commit gate. Each stage output feeds the next.

Auto-Validators

Pre-commit hook: openlore drift — detects Gap, Uncovered, Stale, ADR gap
Decision gate: pre-commit blocks until cross-domain/system decisions are reviewed
TDD: not enforced by framework

Git Automation

Pre-commit hooks (both drift detection and decision review). No auto-commit.

Cross-Tool Portability: Medium

7 skills are Claude Code-specific. MCP tools work with any MCP client. AGENTS.md persona works with any AI. CLI is tool-agnostic.

Token Efficiency Claim

orient() replaces exploratory file reads:

Claimed: 15,000-50,000 tokens (file-by-file) → ~1,000-3,000 tokens (orient())
Benchmark: 430µs p50 against 15k-node TypeScript compiler codebase
Pre-commit drift detection: milliseconds (no API key, no LLM)

Ui Cli Surface

spec-gen (OpenLore) — UI / CLI Surface

CLI Binary

Name: openlore
Package: openlore (npm)
Is thin wrapper: No — core analysis engine
Subcommands: 15 (analyze, generate, drift, decisions, mcp, view, init, verify, run, doctor, setup, refresh-stories, audit, test, digest, telemetry)

Local UI

View command: openlore view — opens architecture overview in browser (TUI or web)
TUI approval: tui-approval.ts — interactive terminal UI for reviewing drift items before commit
No dedicated web dashboard beyond the view command

IDE Integration

Claude Code: 7 skills in skills/ directory
MCP clients: All 45 tools accessible via openlore mcp (stdio protocol)
Pre-commit: Installable via openlore setup

MCP Configuration

{
  "mcpServers": {
    "openlore": {
      "command": "openlore",
      "args": ["mcp"]
    }
  }
}

Observability

openlore audit — Spec quality audit
openlore doctor — Setup diagnostics
detect_changes MCP tool — Risk-scores changed functions using call graph centrality × change type
Epistemic Lease signals — In-band confidence decay notifications on MCP responses
Opt-in telemetry via openlore telemetry

Performance

From README (benchmarked 2026-05-26):

orient() p50: ~430µs against 15k-node TypeScript codebase (~79k edges)
Pre-commit drift detection: milliseconds (no LLM)
Incremental graph update: changed file + direct callers only (not full re-analyze)

Related frameworks

same archetype · same primary tool · same memory type

Context Mode ★ 16k

A19 Token-efficient encoding

Keeps raw tool output data out of the context window via sandbox execution and SQLite+FTS5 session indexing, reducing context…

lean-ctx ★ 2.2k

A19 Token-efficient encoding

A full-session context runtime that compresses file reads (10 modes), shell output (60+ patterns), and session memory (CCP) to…

Nemp Memory ★ 101

A19 Token-efficient encoding

Persists AI agent context across sessions as 100%-local plain JSON files with zero dependencies, zero cloud, and agent identity…

CogniLayer v4 ★ 28

A19 Token-efficient encoding

Provides AI coding agents with typed semantic memory, tree-sitter code intelligence, and a multi-agent coordination protocol to…

cursor-coding-agent-os (Mugiwara555343) ★ 3

A19 Token-efficient encoding

Lean/Verbose dual-mode Agent OS fork for solo developers on token budgets.

rtk (Real Token Killer) ★ 55k

A19 Token-efficient encoding

Intercepts Claude Code's Bash tool calls at the PreToolUse hook and compresses verbose CLI output (git status, test runners,…

Distribution

Type: npm-package
License: MIT
Install: one-liner
Version: unknown (npm: openlore, renamed from spec-gen)

Surfaces

CLI binary: openlore
CLI subcmds: 15
Local UI: terminal-tui
Tech stack: Node.js, blessed/ink (TUI), browser view for architecture

Components

Commands: 0
Skills: 7
Subagents: 0
Hooks: 2
MCP servers: 1
MCP tools: 45
Scripts: 2
Templates: 4

Workflow

Phases: 5
Approval gates: 3
Spec format: markdown
Spec storage: per-feature-folder
Delta or full: delta-diff

Orchestration

Multi-agent: No
Pattern: sequential
Max concurrent: 1
Isolation: none
Consensus: none
Prompt chaining: Yes

Multi-model

Multi-model: No
BYOK: Yes
Modal: text

Execution

Mode: event-driven
Crash recovery: No
Compaction: Yes
Session handoff: Yes
Streaming: No

Memory

Type: sqlite
Persistence: project
Search: graph
State files: 3 files

Quality

TDD: No
TDD mechanism: none
Validators: 1
Self-review: none

Git / Observability

Auto commit: No
Auto PR: No
Auto merge: No
Worktree/feat: No
Audit log: Yes
Audit format: sqlite
Replay: No

Tools

Primary: claude-code
Targets: 2
Portability: medium

Signals

Stars: 137
Last commit: 2026-05-26
Maintainer: active
Quality score: 3.7/10

Summary

spec-gen (OpenLore) — Summary

Overview

spec-gen (OpenLore) — Overview

Origin

Philosophy

Key Claims

Antipatterns Named

Architecture

spec-gen (OpenLore) — Architecture

Distribution

Install

Three Layers

Directory Tree (project after init)

Project Structure (source)

Required Runtime

Components

spec-gen (OpenLore) — Components

CLI Subcommands (15)

MCP Tools (45)

Skills (7 for Claude Code)

Epistemic Lease System

Pre-Commit Hook

Prompts

spec-gen (OpenLore) — Prompts

Excerpt 1: AGENTS.md — Code Archaeologist Persona

Excerpt 2: openlore-analyze-codebase skill (from skills/openlore-analyze-codebase.md)

Uniqueness

spec-gen (OpenLore) — Uniqueness

Differs from Seeds

Positioning

Observable Failure Modes

Novel Patterns

Workflow

spec-gen (OpenLore) — Workflow

Primary Workflow

Minimum (No API Key)

Full Pipeline (API Key Required)

Spec Generation (6 Stages)

Decision Gate (Pre-Code ADR)

Phase to Artifact Map

Approval Gates

Incremental Updates

Memory Context

spec-gen (OpenLore) — Memory & Context

State Storage

State Files

Epistemic Lease (Cross-Session Decay Tracking)

Context Injection

Cross-Session Handoff

Compaction Handling

Telemetry

Orchestration

spec-gen (OpenLore) — Orchestration

Multi-Agent: No

Orchestration Pattern: Sequential

Isolation Mechanism: None

Execution Mode: Interactive-loop + Event-driven

Multi-Model: No

Consensus Mechanism: None

Prompt Chaining: Yes

Auto-Validators

Git Automation

Cross-Tool Portability: Medium

Token Efficiency Claim

Ui Cli Surface

spec-gen (OpenLore) — UI / CLI Surface

CLI Binary

Local UI

IDE Integration

MCP Configuration

Observability

Performance

Related frameworks

Excerpt 2: openlore-analyze-codebase skill (from `skills/openlore-analyze-codebase.md`)