Lore: Repurposing Git Commit Messages as a Structured Knowledge Protocol for AI Coding Agents

This paper introduces Lore, a lightweight, infrastructure-free protocol that transforms standard Git commit messages into structured decision records containing reasoning, constraints, and agent directives to preserve institutional knowledge for AI coding agents.

The Gist

Imagine you walk into a massive, ancient library. The shelves are packed with books (the code), but if you pick one up, the pages only show the final story. They don't tell you why the author chose that plot twist, what other endings they considered, or why they decided the hero should wear a hat instead of a helmet.

Over time, the library becomes a "legacy" mess: the books work, but nobody knows the logic behind them. If a new writer (or an AI) tries to fix a story, they have to guess the original intent, often making mistakes because the "why" is missing.

This paper, titled Lore, proposes a simple but powerful fix for this problem in the world of software and AI.

The Problem: The "Decision Shadow"

The author calls the missing information the Decision Shadow.

• What we have: A record of what changed (e.g., "I fixed the login button").
• What we lost: The why (e.g., "I fixed the button because the old one crashed when users clicked it twice, but we couldn't use a faster solution because of security rules").

Right now, when AI agents write code, they are great at generating the "what," but they are terrible at remembering the "why" for the next person. They leave the library with the same missing context, making the problem worse.

The Solution: Lore (The "Time-Travel Note")

The author suggests we stop treating the Git Commit Message (the note attached to every code change) as just a simple label. Instead, we should turn it into a structured decision record.

Think of a Git Commit Message like a time capsule or a sticky note left on a specific page of a book.

• Current State: The note says, "Fixed the typo."
• Lore State: The note says, "Fixed the typo. Why: The old spelling confused the search engine. Rejected: We thought about changing the whole word, but that would break old links. Warning: Don't change this back, or the search will break again."

How It Works (The Magic Trick)

The genius of this idea is that it doesn't require building a new, expensive database or a complex new system. It uses a feature that already exists in every software project called Git Trailers.

Imagine these trailers as standardized tags at the bottom of your note:

• Constraint: (The rules we had to follow)
• Rejected: (The ideas we tried and said "no" to)
• Directive: (Instructions for the future: "Don't touch this!")
• Confidence: (How sure we are this is right)

Because these are just text tags, any AI agent or human can read them instantly using a simple command line tool (like a search engine for the library's notes).

Why This is a Big Deal

The paper compares Lore to other solutions:

1. vs. Architecture Decision Records (ADRs): ADRs are like separate, heavy encyclopedias kept in a different room. They often get out of sync with the books. Lore is a note inside the book, so it can never get lost or outdated.
2. vs. AI Summaries: Current AI tools just summarize what changed. Lore captures the reasoning that was never in the code to begin with.
3. vs. Heavy Infrastructure: Some ideas suggest building massive "knowledge graphs" (complex digital brains). Lore is like using a pencil and paper instead of building a supercomputer. It's free, instant, and works everywhere.

The "Agent" Advantage

The paper argues that this is perfect for the future of AI coding.

• Humans are busy and often forget to write these notes.
• AI Agents are tireless. They can automatically generate these rich, structured notes every time they write code.
• Future Agents can read these notes to understand the "rules of the game" before they start working, preventing them from making the same mistakes the previous agent made.

The Bottom Line

Lore is a proposal to stop throwing away the "brain" of the software development process. By turning simple text notes into structured, machine-readable instructions, we create a self-healing library of knowledge.

It turns the software history from a silent movie (where you only see the action) into a documentary with commentary, ensuring that the "Decision Shadows" are finally illuminated, so that both humans and AI can build better software, faster, without losing their minds.

Technical Summary

Based on the paper "Lore: Repurposing Git Commit Messages as a Structured Knowledge Protocol for AI Coding Agents" by Ivan Stetsenko (March 2026), here is a detailed technical summary.

1. Problem Statement: The "Decision Shadow"

The paper identifies a critical bottleneck in the era of AI-assisted software development: the loss of institutional knowledge known as the Decision Shadow.

• The Phenomenon: Every code commit captures the diff (what changed) but discards the reasoning (why it changed). This includes constraints, rejected alternatives, trade-off evaluations, and forward-looking context.
• The Consequence: As AI agents become primary producers and consumers of code, they lack the "tacit knowledge" required to understand the structural rationale behind existing code. This leads to "legacy code" where the code functions but its logic is opaque.
• Current Limitations: Existing solutions like Architecture Decision Records (ADRs) are too high-level (missing implementation details) and suffer from synchronization drift. Code Digital Twins and Knowledge Graphs are too heavyweight and require significant infrastructure. AI-generated commit messages currently only summarize the diff (what changed) rather than the intent (why it changed).

2. Methodology: The Lore Protocol

The author proposes Lore, a lightweight protocol that repurposes the existing Git commit message into a structured, machine-parseable decision record.

Core Architecture

• Mechanism: Lore utilizes Git Trailers, a native Git feature for key-value pairs in commit messages. This requires no new infrastructure, databases, or servers.
• The "Lore Atom": A commit is redefined as an atomic unit of institutional knowledge. It is immutably bound to the specific code change, ensuring the knowledge never drifts out of sync.
• Format Structure:
  1. Intent Line: Describes why the change was made (not just what).
  2. Body: Narrative context.
  3. Trailers (Structured Metadata): Machine-readable key-value pairs containing specific decision data.

Trailer Vocabulary (Key Metadata Fields)

The protocol defines specific trailers to capture decision context:

• Constraint: Rules that shaped the decision (e.g., "Auth service does not support token introspection").
• Rejected: Alternatives evaluated and dismissed, with reasons (preventing future agents from re-exploring dead ends).
• Confidence: Author's assessment (low, medium, high).
• Scope-risk: Blast radius of the change (narrow, moderate, wide).
• Reversibility: Whether the change is clean, requires migration, or is irreversible.
• Directive: Forward-looking instructions for future modifiers (e.g., "Do not narrow without verifying upstream").
• Tested / Not-tested: Verification status and gaps.
• Related: References to related commits by hash.

Tooling and Agent Interaction

• CLI Tool: A standalone command-line interface (lore) allows agents to query the history.
  • Discovery: Agents run lore context <path> to load decision history.
  • Filtering: Agents use lore rejected <path> to avoid previously discarded solutions.
  • Validation: lore validate checks for format compliance.
• Agent Workflow: Agents discover the protocol via the CLI, harvest constraints before modifying code, and serialize their own decision context into Lore atoms upon committing. No special agent SDK is required; only shell command execution is needed.

3. Key Contributions

1. Protocol Definition: The first formal proposal to use the commit message itself as a structured, machine-parseable channel for inter-agent communication across time.
2. Zero-Infrastructure Solution: Unlike competing approaches (Knowledge Graphs, Digital Twins), Lore leverages existing Git infrastructure, making it universally deployable.
3. Granularity Shift: Moves knowledge capture from the architectural level (ADRs) to the implementation level, capturing the specific "why" behind individual functions and modules.
4. Agent-Centric Design: The protocol is designed specifically for AI agents to consume and produce, shifting the burden of documentation from human typing to agent serialization.

4. Results and Validation Strategy

• Comparative Analysis: The paper argues Lore outperforms ADRs (better synchronization), Code Comments (immutable history), and AI-generated summaries (adds new info, not just rephrasing).
• Proposed Empirical Validation: The author outlines a 6-month study comparing two teams on the same project:
  • Control: Uses conventional commits.
  • Experimental: Uses Lore.
  • Metrics: Agent task success rate, time-to-correct-solution, rate of re-proposing rejected approaches, and review cycles.
• Stress Testing: The paper addresses potential objections:
  • Overhead: Minimal for agents (who already hold context); mitigated by lore validate.
  • Context Windows: Lore compresses raw transcripts into structured data, making it more efficient than feeding full chat logs.
  • Trust: While it doesn't solve trust, it makes the quality of decisions auditable.

5. Significance

• Solving the "Why" Gap: Lore addresses the fundamental limitation of current AI coding tools: they can see what code exists but cannot reliably reconstruct why it exists.
• Institutional Memory Preservation: By treating commits as immutable decision records, Lore creates a "knowledge flywheel" where the project's intelligence compounds over time, preventing the accumulation of "legacy code" that is functional but unintelligible.
• Scalability: Because it relies on standard Git, Lore is immediately applicable to any existing repository without the cost of migrating to new platforms or building complex backend systems.
• Paradigm Shift: It redefines the commit message from a human-readable label into a structured data interface for AI agents, enabling autonomous agents to reason about code evolution with the same depth as human developers.

In conclusion, Lore proposes a minimalist, high-impact solution to the AI coding knowledge gap by transforming the ubiquitous Git commit message into a robust, structured protocol for preserving and transmitting the "Decision Shadow."