Lore Protocol
Your codebase remembers what changed.
Make it remember why.
Lore Protocol embeds decision context — constraints, rejected alternatives, confidence, directives — into git commit messages as standard trailers. So AI agents and future developers never lose the reasoning behind the code.
A commit message that actually works
Standard commits say what changed. Lore commits capture the full decision context — queryable by humans and machines.
$ git log —oneline
e4f2a1b fix: handle token expiry in auth interceptor
a1c9d3e refactor: clean up session management
7b2f8c4 feat: add retry logic to auth flow
// Why was the TTL not extended?
// What constraints shaped this?
// What was tried and rejected?
// … no one knows anymore.
$ lore context src/auth/interceptor.ts
── a7f3b2c1 (2026-03-15) ──────────
Constraint: Auth service does not support introspection
Constraint: Must not add latency to non-expired paths
Rejected: Extend TTL to 24h | security policy violation
Rejected: Background refresh | race condition
Directive: [until:auth-v3] Error handling is broad (all 4xx)
Confidence: high Scope-risk: narrow
Pure git. No infrastructure.
Lore uses standard git trailers — the same mechanism git itself uses. No database, no server, no vendor lock-in. Your decision history lives where your code lives.
The auth service returns inconsistent status codes on token
expiry, so the interceptor catches all 4xx responses and
triggers an inline refresh.
Lore-id:a7f3b2c1
Constraint:Auth service does not support token introspection
Constraint:Must not add latency to non-expired-token paths
Rejected:Extend token TTL to 24h | security policy violation
Rejected:Background refresh on timer | race condition
Confidence:high
Scope-risk:narrow
Reversibility:clean
Directive:[until:auth-v3] Error handling is intentionally broad (all 4xx)
Tested:Single expired token refresh (unit)
Not-tested:Auth service cold-start > 500ms behavior
Everything you need, nothing you don’t
Survives rebase
Stable 8-character Lore-ids live in the commit message, not the hash. Rebase, cherry-pick, amend — all references stay valid. No hash-dependent linking that breaks on the most common git operation.
Agent-first authoring
Default input is JSON via stdin — designed for AI agent pipelines. Structured JSON output with —json. Interactive mode via -i for humans. Both paths produce the same result.
Decision lifecycle
Constraints are never mutated. When a decision is outdated, a new commit Supersedes: the old one. Queries automatically filter retired decisions. Use —all to see the full history.
Multi-signal staleness
Time-based expiry isn’t enough. lore stale combines five signals: age, code drift, low confidence, expired [until:…] hints, and orphaned dependency chains.
Line-level context
lore why src/auth/interceptor.ts:47 — combines git blame with Lore trailers to answer the most natural question: why does this specific line exist?
CI/CD validation
lore validate —since main checks protocol compliance with defined exit codes. Errors fail the pipeline, warnings are your call. Add one line to your CI config.
Query decisions like you query code
16 commands covering setup, queries, authoring, and maintenance. Every command supports —json for agent consumption.
The specification is complete.
The CLI is being built.
Lore Protocol is described in a published paper (arXiv:2603.15566, March 2026). The revised specification resolves 14 design challenges and is ready for implementation.
# Coming soon
npm install -g @lore-protocol/cli
lore init
Created .lore/config.toml with protocol version 1.0