Lore

Your code knows what. Lore knows why.
L'or de vos decisions techniques.

The Problem

You're 50 commits in. Six months later, someone asks: "Why did we build it this way?"

Git blame shows who changed what and when. But not why. The reasoning is gone — buried in a Slack thread, a PR comment, or the memory of a developer who left three months ago.

Every codebase has an invisible layer of decisions that code alone can't convey. And every day that passes, more of that knowledge evaporates.

The Solution

Three questions. Ninety seconds. Done.

$ git commit -m "feat: add JWT auth middleware"
  [1/3] Type [feature]:
  [2/3] What [add JWT auth middleware]:
  [3/3] Why? Because stateless auth scales better than sessions
  Captured  feature-add-jwt-auth-middleware-2026-03-16.md

Lore hooks into your Git workflow and asks 3 questions after every commit — Type, What, Why. The answers become a Markdown file living in your repo, searchable, versionable, portable. No wiki. No SaaS. No friction.

Installation

# Homebrew (macOS / Linux)
brew install GreyCoderK/lore/lore

# Snap (Linux)
sudo snap install lore --classic

# Chocolatey (Windows)
choco install lore

# Go (any platform)
go install github.com/greycoderk/lore@latest

# Pre-built binaries (macOS / Linux)
curl -sSL https://github.com/GreyCoderK/lore/releases/latest/download/install.sh | sh

Or download from GitHub Releases — binaries for macOS, Linux, and Windows.

Quickstart (5 minutes)

# 1. Initialize Lore in your project
lore init
# Creates .lore/ directory and installs the post-commit hook

# 2. Make a commit — Lore asks 3 questions automatically
git add . && git commit -m "Add rate limiting"
# → Type? feature
# → What? Add rate limiting (pre-filled from commit)
# → Why? API was getting hammered, 10K req/min from one client

# 3. See your captured decision
lore show
# → Displays the Markdown document with the full context

# 4. Check your documentation health
lore status
# → Shows coverage, pending commits, corpus stats

# Bonus: document a past commit retroactively
lore new --commit abc1234

How Lore Compares

Lore is also complementary to ADRs — it captures the daily why that feeds into bigger architectural decisions.

Commands

How It Works

The Documentation Flow

1. Type — What kind of change? (feature, bugfix, decision, refactor, note)
2. What — Pre-filled from your commit message. Press Enter to confirm.
3. Why — The one question that matters. Why this approach?

If all 3 answers come in under 3 seconds, Lore enters express mode and skips optional questions.

Contextual Detection

• Merge commits — Skipped automatically
• Rebase — Deferred to pending
• Cherry-pick with doc — Skipped
• Amend — Updates existing document
• Non-TTY (IDE, CI) — Deferred with OS notification (VS Code, dialog)
• Ctrl+C — Partial answers saved to pending

Document Format

---
type: decision
date: 2026-03-16
status: published
commit: abc1234567890abcdef
generated_by: hook
---
# JWT Auth Middleware

## Why
Stateless authentication scales better than server-side sessions...

## Alternatives Considered
Session-based auth with Redis...

## Impact
Users can now authenticate without server-side state...

Configuration

# .lorerc
language: "en"           # "en" or "fr" — bilingual UI
ai:
  provider: ""            # "anthropic", "openai", "ollama", or "" (zero-API)
hooks:
  post_commit: true
templates:
  dir: .lore/templates

Architecture (for contributors)

cmd/           → Cobra commands (CLI entry points)
internal/
  domain/      → Interfaces, types, DTOs (no dependencies)
  config/      → Configuration cascade (.lorerc → .lorerc.local → env)
  git/         → Git adapter (hooks, log, diff)
  storage/     → Document storage, front matter, index, doctor
  workflow/    → Reactive (hook) and proactive (lore new) flows
  generator/   → Document generation pipeline
  angela/      → AI-assisted documentation logic
  ai/          → AI provider implementations
  i18n/        → Bilingual message catalogs (EN/FR)
  ui/          → Terminal UI (colors, progress, lists)
.lore/
  docs/        → Documentation corpus (Markdown)
  pending/     → Interrupted/deferred commits
  store.db     → LKS index (SQLite, reconstructible)

Principles: Markdown is source of truth. Zero implicit network calls. Atomic writes. stderr for humans, stdout for machines.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

For security vulnerabilities, see SECURITY.md.

Community

• GitHub Issues — Bugs & feature requests
• GitHub Discussions — Q&A, ideas, show & tell
• SUPPORT.md — Where to get help
• CODE_OF_CONDUCT.md — Community guidelines

Sponsor

If Lore helps you capture better decisions, consider sponsoring the project.

Third-Party Notices

License

AGPL-3.0 — see LICENSE. Commercial license available — see LICENSING.md.