Introduction

Lore Protocol is a convention for embedding decision context into git commit messages using standard git trailers. It captures why code decisions were made — constraints, rejected alternatives, confidence levels, forward-looking directives — so that AI agents and future developers never lose context.

The Problem

Every codebase accumulates decisions:

• Why was this library chosen over alternatives?
• Why was this approach rejected?
• What constraints shaped the current design?
• What should future modifiers be careful about?

These decisions live in Slack threads, closed PRs, meeting notes, and engineers’ heads. When people move on, the context leaves with them. Code review catches the what, but the why decays silently.

AI agents amplify this problem. They operate across sessions with no memory of prior reasoning. Without access to decision context, they:

• Re-explore approaches that were already rejected
• Violate constraints they were never told about
• Overwrite intentional design choices with “improvements”
• Produce working code that breaks architectural invariants

The Solution

Lore Protocol stores decision context in the one artifact that is already immutable, versioned, and universally available: the git commit message.

Prevent silent session drops during long-running operations

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

The Lore CLI then provides commands to query this context:

# What constraints apply to this file?
lore constraints src/auth/interceptor.ts

# What approaches were already rejected?
lore rejected src/auth/interceptor.ts

# Why does this specific line exist?
lore why src/auth/interceptor.ts:47

# What knowledge might be outdated?
lore stale src/auth/

Design Principles

1. Git-native — Uses standard git trailers. No external database, no server, no SaaS.
2. Agent-first — JSON stdin/stdout for programmatic use. Human-readable text as the default.
3. Append-only lifecycle — Decisions are never mutated. Outdated decisions are retired through Supersedes: chains.
4. Survives git operations — Stable Lore-id references survive rebase, cherry-pick, and amend.
5. Zero adoption cost — Works with any language, any framework, any CI/CD. Just commit messages.

Research

Lore Protocol is described in the paper “Lore Protocol: Embedding Decision Context in Git History for AI Agent Consumption” (arXiv:2603.15566, March 2026).

This documentation reflects the Revised Specification v1.0, which resolves 14 design challenges identified after the paper’s publication.

Current Status

The protocol specification is complete. The CLI tool is under active development. Follow progress on GitHub.