GitHub - itsthelore/rac-core: Give your coding agent the decisions your team already made — so it stops re-doing things you ruled out, treating product knowledg
Lore
[](https://github.com/itsthelore/rac-core#lore)!Image 1: Lore — agents that know why. Deterministic. Read-only. No RAG, no guessing.
Quickstart · How it compares · How it works · Docs · CLI · Changelog
> **Give your coding agent the decisions your team already made — so it stops re-doing things you ruled out.**
Lore keeps your team's recorded knowledge — requirements, decisions, designs, roadmaps, and prompts — as typed Markdown in your repo and serves it **read-only** to Claude Code, Cursor, and Claude Desktop over MCP, so the agent cites your decisions instead of violating them. No RAG, no embeddings, no model call to decide what's relevant — retrieval is deterministic and reproducible. It is built on **RAC — Requirements as Code**, the open-source engine underneath; the package, CLI, and MCP server ship under the `rac` name.
How it compares
[](https://github.com/itsthelore/rac-core#how-it-compares)
Lore isn't a search index or a memory tool — it's the **deterministic system of record** an agent grounds against. Fuzzy retrieval (RAG, agent memory) is good at finding _what's near_ a loose question; Lore is good at returning the _exact, current_ decision and declining the ones you've superseded. They compose well — recall fuzzily, then verify in Lore.
| | Lore | Fuzzy retrieval (RAG / agent memory) | | --- | --- | --- | | Good at | the exact, current decision | finding what's _near_ a question | | Retrieval | deterministic, reproducible | similarity-ranked, varies by run | | Role | source of truth, read-only | a fast index or working copy | | In CI | enforced (`rac validate` / `rac gate`) | not its job |
Quickstart
[](https://github.com/itsthelore/rac-core#quickstart) 1. **Install** the engine:
pip install rac-core 2. **Scaffold** identity and your first artifact:
rac quickstart 3. **Connect your agent** (Claude Code, from your repo root):
claude mcp add lore -- rac mcp 4. **Enforce** in CI so bad knowledge never lands:
rac validate rac/ && rac gate rac/
Install
[](https://github.com/itsthelore/rac-core#install) | Command | Gets you | | --- | --- | | `pip install rac-core` | the `rac` CLI + the `lore` MCP server | | `pip install 'rac-core[ingest]'` | + DOCX / HTML import | | `pip install 'rac-core[ingest-all]'` | + PDF / PPTX / XLSX import | | `pip install 'rac-core[explorer]'` | + the terminal Explorer (`rac explorer`) |
Requires Python 3.11+. `uv tool install rac-core` also works.
How it works
[](https://github.com/itsthelore/rac-core#how-it-works)
- **Typed Markdown, in your repo.** Every artifact is plain Markdown with a tiny frontmatter envelope; the engine classifies it deterministically and validates it against a per-type schema.
- **Read-only at serve time.** The MCP server only ever reads; the trust boundary is human PR review, and the agent cannot mutate the store.
- **Enforced at write time.**`rac validate` and `rac gate` reject malformed artifacts, broken or ambiguous links, and references to superseded decisions — in CI, before the knowledge lands.
- **Air-gapped by design.** The engine makes no LLM calls and no network calls; the only egress is a consent-gated, content-free usage ping that is off by default, and regulated installs can prove it stays off with `rac telemetry off --enterprise` (security posture, ADR-086).
Connect your agent
[](https://github.com/itsthelore/rac-core#connect-your-agent) Claude Code (from your repo root):
claude mcp add lore -- rac mcp
Claude Desktop / Cursor (`mcpServers` in the client config):
{ "mcpServers": { "lore": { "command": "rac", "args": ["mcp", "--root", "/absolute/path/to/your/repo"] } } }
Author and enforce artifacts
[](https://github.com/itsthelore/rac-core#author-and-enforce-artifacts)
rac quickstart # set up identity + scaffold your first artifact rac new decision adr.md # scaffold a typed artifact (mints the id) rac validate rac/ # check every artifact in a directory rac inspect requirement.md # see its type and completeness rac review rac/ # full repository review, worst problems first rac gate rac/ # the merge gate: validate + relationships + review
Import an existing decision
[](https://github.com/itsthelore/rac-core#import-an-existing-decision) Already have decisions in Confluence, Notion, or loose Markdown? The `rac-import` agent skill turns **one** existing document into **one** valid artifact, with a human-review step before anything is written:
rac skill install rac-import
Then ask your agent, in plain language: _"import this decision doc into Lore."_ It drafts from **only** what your document says, shows you the proposed type, title, and relationships to confirm, scaffolds with `rac new`, and closes on `rac validate`. For multi-format or bulk conversion, use the `rac-ingest` skill.
Export the corpus
[](https://github.com/itsthelore/rac-core#export-the-corpus)
rac export rac/ --html --out lore.html # the Portal: the whole graph, one file rac export rac/ --okf # a conformant Open Knowledge Format bundle rac export rac/ --documents # JSONL for memory/RAG backends rac export rac/ --graph # the typed decision graph for graph backends
The `--documents` and `--graph` modes feed external memory, RAG, and graph tools so an agent can recall fuzzily there and then **verify in Lore** — see the CLI reference. The connectors themselves live in the separate `lore-connectors` companion.
Python API
[](https://github.com/itsthelore/rac-core#python-api) The engine is a library too; its public surface is `rac.__all__`.
from rac import parse_file, classify, find_artifacts
art = parse_file("rac/decisions/adr-001-markdown-first.md") print(classify(art).type) # -> "decision"
result = find_artifacts("rac/", "caching") # returns a SearchResult for hit in result.matches: print(hit.id, hit.title)
How it relates to OKF
[](https://github.com/itsthelore/rac-core#how-it-relates-to-okf)
Google's Open Knowledge Format (OKF) standardises the _carrier_ — a Git tree of Markdown with YAML front matter — and is deliberately permissive. RAC writes that same carrier and adds what OKF leaves to the consumer: **write-time enforcement** in CI. `rac validate` and `rac relationships --validate` reject malformed artifacts, broken links, and references to superseded decisions, deterministically, before the knowledge lands. `rac export --okf` turns any RAC repo into a conformant OKF bundle — so the two compose rather than compete.
Who it's for
[](https://github.com/itsthelore/rac-core#who-its-for)
- **Teams running coding agents heavily** (Claude Code, Cursor) tired of the agent ignoring decisions the team already made.
- **Teams who already write ADRs** and want those decisions to actually shape what the agent does.
- **Anyone who wants the _why_ behind their software versioned alongside the code.**
Documentation
[](https://github.com/itsthelore/rac-core#documentation) **Full documentation: https://itsthelore.github.io/rac-core/**
- Quickstart — install and author your first artifact
- MCP server — tools, client configuration, examples
- CLI reference — every command, flag, and exit code
Origin
[](https://github.com/itsthelore/rac-core#origin)
Lore is the product surface of **RAC — Requirements as Code**, the open-source engine underneath; the package, CLI, and MCP server ship under the `rac` name, and `lore` is the server identity and brand. Wayfinder, the deterministic prompt-complexity router, began as a `route` experiment inside RAC and was split into its own tool — routing is a runtime concern, not a knowledge one.
Repository layout
[](https://github.com/itsthelore/rac-core#repository-layout)
``` rac-core/ src/rac/ the engine: CLI, core, services, output, the in-process MCP server (rac mcp), and bundled skills, templates, and git hooks rac/ the dogfood corpus — requirements, decisions, designs, roadmaps, and prompts that govern the project itself tests/ per-service batteries plus core / cli / artifacts coverage (ADR-027) docs/ the documentation site (MkDocs) examples/ the grounding demo, woven into the corpus and the test fixtures rac-localview/ the Portal / graph viewer, vendored into the engine ```
Test
[](https://github.com/itsthelore/rac-core#test)
pip install -e .[dev] python -m pytest
`ruff check`, `ruff format --check`, and `mypy src/` run in CI alongside the per-service batteries (ADR-027).
Project status
[](https://github.com/itsthelore/rac-core#project-status) Lore is early and evolving quickly. The MCP server ships today. Contributions, ideas, and experiments welcome — see CONTRIBUTING.md.
License
[](https://github.com/itsthelore/rac-core#license) Apache License 2.0.