Introducing Lore Protocol

Mar 20, 2026

Ivan Stetsenko

Creator of Lore Protocol

Every codebase accumulates decisions. Why was this library chosen? Why was that approach rejected? What constraints shaped the current design? These decisions live in Slack threads, closed PRs, meeting notes, and people’s heads. When they leave, the context leaves with them.

AI agents make this worse. They operate across sessions with no memory of prior reasoning. They re-explore approaches that were already evaluated and dismissed. They violate constraints they were never told about.

The Insight

The git commit message is the one artifact that is already:

Immutable — once committed, it doesn’t change
Versioned — tracked alongside the code it describes
Universally available — every developer and CI tool has access

Yet commit messages are underutilized. Most capture what changed, not why.

What Lore Protocol Does

Lore Protocol defines a set of git trailers — structured key-value pairs appended to commit messages — that capture decision context:

Prevent silent session drops during long-running operations

Lore-id: a7f3b2c1
Constraint: Auth service does not support token introspection
Rejected: Extend token TTL to 24h | security policy violation
Confidence: high
Scope-risk: narrow
Directive: [until:auth-v3] Error handling is intentionally broad (all 4xx)

The Lore CLI then lets you query this context:

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

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

# What approaches were already tried and rejected?
lore rejected src/auth/

Key Design Decisions

Stable identity over commit hashes. Every Lore-enriched commit carries a Lore-id — an 8-character hex identifier stored in the message itself. Unlike commit hashes, Lore-ids survive rebase, cherry-pick, and amend.

Typed relationships. Atoms can Supersede previous decisions, Depend-on other atoms, or be Related. This enables automatic lifecycle management — superseded constraints are filtered from queries by default.

Agent-first authoring. The lore commit command accepts JSON from stdin by default, designed for AI agent workflows. Interactive mode is available via -i for human authors.

Multi-signal staleness detection. lore stale doesn’t just check age — it combines five signals: time, code drift, low confidence, expired directive hints, and orphaned dependencies.

The Research

The protocol design is described in “Lore Protocol: Embedding Decision Context in Git History for AI Agent Consumption”, published March 2026. The paper covers the motivation, protocol design, and evaluation.

After publication, we identified 14 design challenges that the paper’s interface left unresolved — ambiguous path resolution, missing lifecycle management, unspecified output formats, and more. The Revised Specification v1.0 resolves all 14 and serves as the implementation blueprint for the CLI tool.

What’s Next

The CLI tool is under active development. We’re building it in the open. Star the GitHub repository to follow progress.

We’d love feedback on the protocol design. If you’re building AI-assisted developer tools or thinking about decision preservation, read the spec and let us know what you think.