📜

L · O · R · E

The Spellbook for Your Codebase

Chronicle decisions, context, and lessons your AI companions can actually read.

LOCAL YAML STORE NO CLOUD SYNC NO API KEYS TOOL-AGNOSTIC PLAIN FILES · DIFFABLE

✦   PRESS  →   OR   SPACEBAR   TO ADVANCE   ✦

1

The Problem

AI tools are stateless — context evaporates

Without Lore

  • Re-explain architecture every session
  • AI suggests choices you already ruled out
  • Security rules repeated in every prompt
  • New team members start from zero context
  • Decisions exist only in someone's head

With Lore

  • Decisions captured once as plain YAML
  • AI reads your chronicle at session start
  • Security preamble in every export
  • New devs inherit full project memory
  • Context travels with the code in git
Rule of thumb: If you've explained something to an AI twice, it belongs in lore.
2

How the Magic Flows

One source of truth → every AI tool

lore add / lore relic
↓captured as YAML
.lore/  plain files · git-tracked
↓lore export
CHRONICLE.md — full memory
↓referenced by lean adapters
Copilot
Claude
Cursor
AGENTS
Gemini
Cline

Key principle

Two-layer architecture:

  • CHRONICLE.md — one full source of truth, committable
  • Lean adapter files — tiny, tool-specific, reference the chronicle

Token overhead per session stays minimal. Only the chronicle grows; adapters stay small.

3

Install

One command · Python 3.10+

# stable release from PyPI
$

# or local dev install
$

Batteries included

  • TF-IDF search — works immediately
  • All AI adapter file exports
  • Git hook integration
  • Trust scoring from git signals

Optional extras

  • Dense vector search (sentence-transformers)
  • Run the guided wizard:
$ lore setup semantic
4

First Run — Onboard

A guided ritual for new projects

$ lore onboard

📜 L · O · R · E
An Onboarding Chronicle

I. Forge the Store
II. Inscribe a Law (security)
III. Record a Memory
IV. Publish the Chronicle

✓ Sanctum forged at ./lore/
✓ Security covenant inscribed
✓ Memory sealed into decisions
✓ Chronicle published
  • I
    Forge the Store
    Creates .lore/, adds it to .gitignore
  • II
    Inscribe a Law
    Security preamble, OWASP rules, custom edicts
  • III
    Record a Memory
    Choose category, write content, optional tags
  • IV
    Publish the Chronicle
    Writes CHRONICLE.md + all adapter files
5

Spells — Adding Memories

Capture once · retrieve semantically

# interactive walkthrough
$ lore add

# or inline — scriptable and CI-friendly
$ lore add decisions "Use PostgreSQL — need JSONB and row-level locking"
$ lore add facts "Auth service is the sole issuer of JWTs — never bypass it"
$ lore add preferences "Always use type hints" --tags style,python
$ lore add summaries "v2.4 dropped the v1 API endpoints entirely"

# list and manage
$ lore list
$ lore list decisions
$ lore remove a1b2c3d4

Default Tomes

  • decisions — why choices were made
  • facts — constraints & rules
  • preferences — style & conventions
  • summaries — change history

Custom tomes: add to categories in .lore/config.yaml

6

Semantic Search

Find what you know — conceptually

$ lore search "why did we choose postgres"

── 3 results ──────────────────────────────────────────────

[0.94] decisions · a1b2c3d4
Use PostgreSQL — need JSONB and row-level locking

[0.71] decisions · e5f6a7b8
Evaluated SQLite and MySQL; rejected due to concurrency limits

[0.58] facts · c9d0e1f2
Production DB is Aurora PostgreSQL 15 — never run raw DDL in flights
TF-IDF — works out of the box with no extras.
Dense vectors — run lore setup semantic to enable sentence-transformers.
7

Relics — Capture Now, Curate Later

Raw artifacts → distilled spells

# capture — many input sources
$ lore relic capture --git-diff --title "Pre-deploy changes"
$ lore relic capture --file session-notes.md
$ lore relic capture --clipboard --title "Auth Slack thread"
$ lore relic capture --git-log 5 --title "Sprint wrap-up"
✓ Relic a3f1b2c4 stored (2,847 chars)

# later — distill into spells
$ lore relic distill a3f1b2c4

─── Spell #1 ──────────────────────────────
✦ Inscription: We chose CQRS to separate read/write models
✦ Tome [decisions]:
✓ Spell b9c0d1e2 sealed into decisions

When to use relics

  • Mid-sprint, no time to curate
  • Copying from Confluence/Slack
  • Post-incident notes
  • Architecture review transcripts
  • Long git diffs to review later

Each spell links back to its source relic for full provenance.

8

Export — Publish the Chronicle

One command · all AI tools in sync

$ lore export

✓ CHRONICLE.md
✓ .github/copilot-instructions.md
✓ AGENTS.md
✓ CLAUDE.md
✓ .cursor/rules/memory.md
✓ .github/prompts/lore.prompt.md
✓ .windsurfrules
✓ GEMINI.md
✓ .clinerules
✓ CONVENTIONS.md

10 files written atomically

Adapter files

Copilot Claude Cursor Codex Windsurf Gemini Cline Aider

CHRONICLE.md is committable. Adapter files are gitignored by default.

/lore trigger: In GitHub Copilot Chat, type /lore to load your full chronicle into context on demand.
9

Trust Scoring

Not all memories are equal

# score all memories from git metadata
$ lore trust refresh

✓ a1b2c3d4 decisions score=87 (author: trusted, 3 touches)
✓ e5f6a7b8 facts score=72 (recency boost)
~ c9d0e1f2 facts score=31 (tag: needs-review)

# explain one score
$ lore trust explain a1b2c3d4

author_weight 40 (trusted author)
activity_bonus 25 (committed 3×)
recency_bonus 22 (last touched 4d ago)
total 87

Tune trust thresholds

# .lore/config.yaml
trust:
default_score: 50
chronicle_min_score: 60
trusted_authors:
- "Alice"

Only entries at or above chronicle_min_score appear in exports.

10

Store Scope & Isolation

Control which directory inherits which store

/workspace/
├── projectA/ # has .lore/
│ ├── .lore/ # scope: auto (default)
│ └── sub/ ✓ inherits projectA's store
├── projectB/ # has .lore/ with scope: local
│ ├── .lore/ # scope: local
│ └── sub/ ✗ no store visible — lore exits cleanly
# pin a store to its own directory only
$ lore config scope local

# explicit root for scripts / CI
$ LORE_ROOT=/projectA lore search "…"

Scope values

  • auto — walk up to parent store (default, backward-compatible)
  • local — store is private to its own directory
◈

Live Demo

Commands to walk through

# ① health check
$ lore doctor

# ② add a memory live
$ lore add decisions "…"

# ③ search immediately
$ lore search "…"

# ④ export & inspect
$ lore export
$ cat CHRONICLE.md

# ⑤ capture a relic
$ lore relic capture --git-diff
$ lore relic distill <id>

Good demo memories

  • "We use Postgres for JSONB + row locking"
  • "Never skip JWT validation in auth layer"
  • "All API responses must be paginated"
Tip: Run lore ui for the interactive terminal browser — great for visual demos.
✦

All Context. No Repetition.

Record knowledge once. Every AI session inherits it. Every team member starts with full context.

Install

$ pip install lore-book

Start

$ lore onboard

Explore

$ lore ui
✦ GitHub ⚜ PyPI 📜 Docs