Lore

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

⚜ 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

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

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.

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

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

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

🜏 Incantations

Install on Windows with Scoop

Install on Windows (easy path)

Install from this repo on Windows

Install via Homebrew

Install via pip

Cast your first spells

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

☄ Hooks, Daemon, and Health

📖 Grimoire of Commands