Lore · Demo & Overview

📜

# 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