Lore — The Spellbook for Your Codebase
Description: Local AI memory for software projects. Chronicle decisions and context your tools can actually read.

## ✦ What is Lore?

AI coding tools are stateless. They don't remember why you chose PostgreSQL over SQLite, that the auth layer must never bypass JWT validation, or that the frontend team deprecated the v1 API six months ago. You end up re-explaining the same context in every session.

Lore fixes that. It is a local AI memory system for software projects. You capture knowledge once as plain YAML alongside your code — then Lore publishes it as instruction files that GitHub Copilot, Claude, Cursor, Codex, and other AI tools read automatically.

By default, Lore exports `CHRONICLE.md` plus lean adapter files so the same project description, security preamble, and memory entry points stay consistent everywhere.

No external database. No API keys. No cloud sync. Everything lives in `.lore/` next to your code.

LOCAL YAML STORE CHRONICLE FIRST NO CLOUD SYNC TOOL-AGNOSTIC

## ⚜ The Three Artefacts

### Spell (a memory)

A single piece of knowledge: a decision, a fact, a hard-won lesson. Short, specific, retrievable by semantic search.

### Tome (a category)

A named collection of spells. Default tomes: decisions, facts, preferences, summaries. Add your own in `.lore/config.yaml`.

### Relic (a raw artifact)

A raw artifact saved as-is for later distillation — a pasted session log, a git diff, a Slack thread. It lands in `.lore/relics/` untouched until you're ready to extract spells from it.

## ✧ How the Magic Flows

Your decisions, facts & lessons ↓ lore add / lore relic .lore/ (plain YAML) ↓ lore export CHRONICLE.md ← full project memory (one source of truth) ↓ referenced by lean instruction files: copilot-instructions.md · AGENTS.md · CLAUDE.md .cursor/rules/memory.md · GEMINI.md · .clinerules ↓ on demand in Copilot Chat: /lore → reads CHRONICLE.md into context ↓ Every AI tool reads your repo context — without you repeating yourself

## ✶ First Invocation

New users should start with onboarding. Lore walks through the store layout, security policy, your first spell, and publishing in one guided ritual.

lore onboard

1. Initialize the spellbook with a project description and local store defaults.
2. Record real knowledge as decisions, facts, preferences, or summaries.
3. Export the chronicle so every supported AI tool inherits the same context.
4. Enable dense semantic search later with `lore setup semantic` if you want embeddings beyond TF-IDF fallback.

Requirements: Python 3.10+. Dense vector search is optional. If model loading fails, Lore falls back to TF-IDF so search still works.

## ⌘ Export Architecture

Lore uses a two-layer export model: one canonical chronicle, then thin instruction files that point back to it. That keeps token overhead low while preserving full project memory when needed.

CHRONICLE.md Complete project memory grouped by tome. This is the single source of truth.
.github/copilot-instructions.md Lean GitHub Copilot adapter with project summary, security preamble, and chronicle reference.
AGENTS.md and CLAUDE.md Small tool-specific adapters for Codex, agent frameworks, and Claude.
.github/prompts/lore.prompt.md Enables the `/lore` prompt in Copilot Chat to pull chronicle context on demand.
Cursor, Gemini, Cline, Windsurf, Aider Optional adapters you can keep enabled or disable through `.lore/config.yaml`.
Atomic exports Regeneration is all-or-nothing so a crash mid-write does not leave partial instruction files behind.
lore export
lore export --format chronicle
lore export --format prompt

## 🜂 The Scrying Glass

Lore ships a retro phosphor-green terminal browser — a full interactive TUI for browsing, searching, writing, and exporting your spellbook without leaving the command line.

lore ui

- Search — Semantic search across all spells as you type
- Browse — Navigate tomes and read entries in a split pane
- Add — Write new spells directly from the interface
- Export — Publish your Chronicle without leaving the TUI
- Live reload — Watches `.lore/` on disk and updates instantly

Open it in a split pane while you code — your full project memory, always one glance away.

## 🝮 Relics and Distillation

When things are moving too fast to curate, capture the raw artifact first. Relics preserve noisy context as-is, then let you distill the verified parts into proper spells later.

### Capture

Paste notes, import a file, snapshot a git diff, read from clipboard, or pipe in text from another tool.

lore relic capture
lore relic capture --git-diff --title "Pre-deploy changes"

### Distill

Walk the artifact spell by spell, choose the right tome, and keep a traceable link back to the source relic.

lore relic distill <id>

## 🜏 Incantations

### Install on Windows with Scoop

# Preferred once the Scoop bucket is published
scoop bucket add cptplastic https://github.com/CptPlastic/scoop-lore-book
scoop install lore-book

### Install on Windows (easy path)

# Use pipx for a clean CLI install
py -m pip install --user pipx
py -m pipx ensurepath
pipx install lore-book

### Install from this repo on Windows

powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1

### Install via Homebrew

# Bind the tap
brew tap cptplastic/lore-book
brew install lore-book

### Install via pip

python -m pip install lore-book

### Cast your first spells

# Record a decision
lore add decisions "Use PostgreSQL — we need JSONB and row-level locking"
# Record a fact
lore add facts "Auth service is the sole issuer of JWTs — never bypass it"
# Publish to all AI instruction files
lore export

## ⟁ Trust Model

Lore is designed for layered trust. The chronicle should be reviewed, reliable memory. Raw intake belongs in relics first.

- Shared trusted memory — Commit `CHRONICLE.md` when a fact or decision is reviewed and ready for everyone to inherit.
- Local working memory — Keep generated adapter files local by default so teams can share the chronicle without forcing every personal wrapper into git.
- Raw untrusted intake — Capture noisy sources with `lore relic capture`, then distill only verified points into spells.
- Confidence signals — Use tomes and tags like `verified`, `needs-review`, or `deprecated` to express trust clearly.
- Automated scoring — Recompute trust from git metadata with `lore trust refresh` and explain one score with `lore trust explain <id>`.

Add candidate memory. Validate against code, tests, and docs. Export the chronicle. Commit only what you want every collaborator and every agent to inherit.

## ☄ Hooks, Daemon, and Health

### Git Hooks

Install a post-commit hook that can extract knowledge from commits and regenerate all export files automatically.

lore hook install
lore extract --last 20

### Background Daemon

Watch `.lore/` for changes and export the moment the memory store changes.

lore awaken
lore awaken --background
lore slumber

### Health Check

Verify store readability, semantic search mode, endpoint reachability, and spell counts in one command.

lore doctor

### Release Smoke Test

Run a clean isolated CLI smoke test before publishing to catch packaging and command regressions.

./smoke.sh

## 📖 Grimoire of Commands

Store

`lore onboard`, `lore init`, `lore add`, `lore list`, `lore remove`

Search

`lore search <query>`, `lore index rebuild`, `lore setup semantic`

Relics

`lore relic capture`, `lore relic list`, `lore relic view`, `lore relic distill`

Publishing

`lore export`, `lore export --format prompt`, `lore config <key> <value>`

Trust and Security

`lore security`, `lore trust refresh`, `lore trust explain <id>`

Automation

`lore hook install`, `lore awaken`, `lore slumber`, `lore doctor`, `lore ui`

✦ Source Repository ⚜ PyPI Package 📜 Overview & Demo
— ✦ — ✦ — ✦ —