# Lore (rac-core)

> Lore stores your team's requirements, decisions, designs, and roadmaps as typed Markdown in your repo and serves them read-only to coding agents over MCP, so agents cite your decisions instead of violating them.

Lore is an open-source tool built on RAC — Requirements as Code — that keeps your team's recorded knowledge as typed Markdown in your Git repository and serves it deterministically to coding agents like Claude Code, Cursor, and Claude Desktop over MCP. It is published under the Apache License 2.0 and installable via `pip install rac-core`. The project is early and actively evolving, with the MCP server shipping as of the latest release.

## What It Is

Lore solves a specific problem in AI-assisted development: coding agents repeatedly re-introduce approaches the team already rejected, rebuild things that were deliberately removed, or ignore decisions that were written down but never made machine-readable. Lore stores requirements, decisions, designs, roadmaps, and prompts as typed Markdown artifacts with YAML frontmatter in your repo, validates them in CI, and exposes them to agents through a read-only MCP server. The agent calls Lore, finds the relevant decision, cites it by ID, and proposes a compliant change — instead of reintroducing what was ruled out. There is no AI in the core: retrieval is deterministic and reproducible, not similarity-ranked.

## How the Architecture Works

The system has three layers working together:

- **Typed Markdown artifacts** — every requirement, decision, design, roadmap, or prompt is plain Markdown with a small frontmatter envelope; the engine classifies and validates each artifact against a per-type schema.
- **Write-time enforcement** — `rac validate` and `rac gate` reject malformed artifacts, broken or ambiguous links, and references to superseded decisions in CI, before bad knowledge lands in the repo.
- **Read-only MCP server** — the server exposes four tools (`get_artifact`, `search_artifacts`, `get_related`, `get_summary`) and cannot create, modify, or delete files; the trust boundary is human PR review.

The engine makes no LLM calls and no network calls. Telemetry is opt-in twice over: local recording requires an explicit flag and never includes arguments or repository content; remote sharing is a separate explicit consent step.

## Where It Fits in the Stack

The project documentation positions Lore as complementary to, not competing with, spec-driven development (SDD) tools like GitHub Spec Kit or OpenSpec. SDD tools manage the change cycle — proposal, design, tasks, implementation — treating requirements as ephemeral inputs. Lore manages the durable corpus those changes draw on: requirements and decisions that persist across changes and are served to the agent over MCP. Similarly, Lore composes with fuzzy retrieval (RAG, agent memory): recall fuzzily in a vector store, then verify the exact current decision in Lore.

Lore also relates to Google's Open Knowledge Format (OKF). OKF standardizes the carrier — a Git tree of Markdown with YAML frontmatter — and is permissive at read time. RAC adds write-time enforcement that OKF leaves to the consumer. `rac export --okf` emits a conformant OKF bundle, so the two compose rather than compete.

## CLI and Export Capabilities

The `rac` CLI covers the full artifact lifecycle:

- `rac quickstart` — scaffold identity and a first artifact
- `rac new decision adr.md` — mint a typed artifact with a generated ID
- `rac validate rac/` — check every artifact in a directory
- `rac inspect`, `rac review`, `rac gate` — inspect, review, and enforce the merge gate
- `rac export --html` — generate the Portal, a self-contained single HTML file of the whole corpus for stakeholders
- `rac export --okf` — emit a conformant OKF bundle
- `rac export --documents` — JSONL for memory/RAG backends
- `rac export --graph` — the typed decision graph for graph backends

The Python API (`rac.__all__`) is also a public surface for programmatic access.

## Update: Release 2026.06.5 — The "Rename" Release

The latest release, version 2026.06.5 (published 2026-06-27), is described as the "rename" release. The package ships on PyPI as `rac-core`, the CLI as `rac`, and the MCP server identity as `lore`. Optional install extras add DOCX/HTML import (`[ingest]`), PDF/PPTX/XLSX import (`[ingest-all]`), and a terminal Explorer (`[explorer]`). The project dogfoods its own tooling: Lore's planning corpus under `rac/` is validated by RAC in CI, so any rule that breaks the tool's own artifacts fails the build.

## Features
- Read-only MCP server exposing get_artifact, search_artifacts, get_related, get_summary tools
- Typed Markdown artifacts with YAML frontmatter for requirements, decisions, designs, roadmaps, and prompts
- Deterministic, reproducible retrieval — no AI, no embeddings, no RAG in the core
- Write-time enforcement via rac validate and rac gate in CI
- Referential integrity and status-consistency checks across artifacts
- Portal export: self-contained single HTML file of the entire corpus
- OKF-conformant bundle export (rac export --okf)
- JSONL export for memory/RAG backends and graph export for graph backends
- Python API (rac.__all__) for programmatic access
- rac-import agent skill for converting existing decision docs into valid artifacts
- Optional DOCX, HTML, PDF, PPTX, XLSX ingest via install extras
- Terminal Explorer (rac explorer) via optional install extra
- Opt-in telemetry with enterprise lockout support
- Dogfoods its own corpus validated in CI

## Integrations
Claude Code, Cursor, Claude Desktop, MCP (Model Context Protocol), GitHub Actions (CI), OKF (Open Knowledge Format), PyPI, uv

## Platforms
CLI, API

## Pricing
Open Source

## Version
2026.06.5

## Links
- Website: https://itsthelore.github.io/rac-core/
- Documentation: https://itsthelore.github.io/rac-core/
- Repository: https://github.com/itsthelore/rac-core
- EveryDev.ai: https://www.everydev.ai/tools/lore-rac-core