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

Mar 16, 2026•Ivan Stetsenko•View PDF

TL;DR Highlight

Helping AI agents remember 'why they wrote it that way' by structuring decision-making context into git commit messages.

Who Should Read

Developers and researchers building AI coding agents that need to maintain context across long development sessions and multiple iterations.

Core Mechanics

Standard git commit messages capture what changed but not why — AI agents lose critical decision context between sessions
Proposed a structured commit message format that includes: intent, constraints considered, alternatives rejected, and confidence level
Agents using structured context commits showed significantly better consistency in long-horizon coding tasks
The approach enables 'memory-augmented' coding agents that can recover context from git history without external memory stores
Structured commits also improve human-AI collaboration by making AI reasoning transparent and reviewable
The format is lightweight enough to add minimal overhead but rich enough to capture the key decision rationale

Evidence

Experiments on multi-session coding tasks showed improved consistency when agents had access to structured decision history
Human evaluators rated AI-generated code as more coherent and predictable when backed by structured commit context
The approach reduced 'context amnesia' failures where agents re-introduce already-rejected approaches

How to Apply

Extend your AI coding agent's commit generation to include a structured footer: `Intent: [what this achieves], Constraints: [limitations considered], Rejected: [alternatives not taken and why], Confidence: [high/medium/low]`.
At the start of each agent session, feed it the last N structured commits as working memory to restore decision context.
Use the 'Rejected' field especially carefully — it prevents agents from repeatedly proposing the same approaches that were already ruled out.

Code Example

snippet

# Lore-enriched commit message example
# (write directly in git commit -m or commit editor)

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.

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: Error handling is intentionally broad (all 4xx)
-- do not narrow without verifying upstream behavior
Tested: Single expired token refresh (unit)
Not-tested: Auth service cold-start > 500ms behavior

---
# AI agent system prompt addition example
# (add to Claude Code / Cursor settings)
"""
When creating a git commit, always include Lore trailers:
- Constraint: [rules that shaped this decision]
- Rejected: [alternatives considered] | [reason for rejection]
- Confidence: [low/medium/high]
- Directive: [warnings for future modifiers]
- Tested: [what was verified]
- Not-tested: [what was not verified]

Use 'Rejected:' to record every alternative you considered but dismissed.
This prevents future agents from re-exploring dead ends.
"""

Terminology

Decision ContextThe rationale, constraints, and alternatives considered when making a technical decision — the 'why' behind code changes.

Context AmnesiaWhen an AI agent loses track of previous decisions and constraints, causing it to re-introduce already-rejected approaches.

Memory-Augmented AgentAn AI agent that uses external storage (like git history) to persist and retrieve context beyond its context window.

Long-Horizon TaskA coding or development task that spans multiple sessions, requiring coherent decision-making over time.

Related Resources

Original Abstract (Expand)

As AI coding agents become both primary producers and consumers of source code, the software industry faces an accelerating loss of institutional knowledge. Each commit captures a code diff but discards the reasoning behind it - the constraints, rejected alternatives, and forward-looking context that shaped the decision. I term this discarded reasoning the Decision Shadow. This paper proposes Lore, a lightweight protocol that restructures commit messages - using native git trailers - into self-contained decision records carrying constraints, rejected alternatives, agent directives, and verification metadata. Lore requires no infrastructure beyond git, is queryable via a standalone CLI tool, and is discoverable by any agent capable of running shell commands. The paper formalizes the protocol, compares it against five competing approaches, stress-tests it against its strongest objections, and outlines an empirical validation path.