📜

Lore

Keeper of the Chronicle

The spellbook for your codebase: chronicle decisions, context, and lessons your AI companions can actually read.

✦ What is Lore?

AI coding tools are stateless. They do not remember why you chose PostgreSQL over SQLite, which safety rules cannot be bypassed, or what tradeoffs already shaped this codebase.

Lore fixes that. It is a local AI memory system for software projects. You capture knowledge once as plain files alongside your code, then export it into instruction files your tools can read automatically.

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

LOCAL YAML STORE CHRONICLE FIRST NO CLOUD SYNC TOOL-AGNOSTIC

⚜ The Three Artefacts

Spell

A single piece of knowledge: a decision, a fact, a hard-won lesson, or a preference worth preserving.

Tome

A named collection of spells. Default tomes include decisions, facts, preferences, and summaries.

Relic

A raw artifact saved as-is for later distillation. Use relics when things are moving too fast to curate carefully in the moment.

✧ How the Magic Flows

Your decisions, facts and lessons ↓ lore add / lore relic .lore/ (plain YAML) ↓ lore export CHRONICLE.md ← full project memory ↓ referenced by lean adapters Copilot · Claude · Cursor · AGENTS · prompts ↓ Every AI tool reads your repo context

✶ First Invocation

Start with onboarding. Lore walks through store setup, your first memory entry, and export flow in one guided ritual.

lore onboard

1. Initialize the spellbook with a project description and local 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 semantic search later with lore setup semantic if you want dense embeddings.

Requirements: Python 3.10+. Dense vector search is optional. Lore falls back to TF-IDF when needed.

⌘ Start Here

Install Setup instructions for PyPI, local development, and semantic search extras.

Core Concepts Understand spells, tomes, relics, and the chronicle model.

CLI Reference Learn the primary commands for capture, search, and export.

FAQ Short answers to common questions about storage, AI tools, and workflow.

🜏 Incantations

Install via pip

pip install lore-book

Local development

pip install -e .

Cast your first spells

lore add decisions "Use PostgreSQL for row-level locking" lore add facts "Auth service is the sole issuer of JWTs" lore export

📖 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>

✦ Source Repository ⚜ PyPI Package

— ✦ — ✦ — ✦ —