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

Lor e: Repurposing Git Commit Messages as a Structur ed Knowledge Pr otocol f or AI Coding Agents Iv an Stetsenko Independent Resear c her dev .ivan.stetsenko@gmail.com March 2026 Abstract As AI coding agents become both primary producers and consumers of source code, the software industry faces an accelerating loss of institutional kno wledge. Each commit captures a code diff but discards the reasoning behind it—the constraints, rejected alternati ves, and forward-looking conte xt that shaped the decision. I term this discarded reasoning the Decision Shadow . Prior work has identified this tacit knowledge gap as a critical bottleneck for AI-assisted de v elopment [ 1 , 2 ] and has proposed hea vyweight infrastructure to address it, including kno wledge graphs [ 1 ], version-controlled agent memory systems [ 3 ], and separate Architecture Decision Records [ 4 ]. This paper argues that the solution already exists in ev ery software project: the git commit message. I propose Lore , a lightweight protocol that restructures commit messages—using nativ e git trailers—into self-contained decision records carrying constraints, rejected alternativ es, agent directi ves, and v erification 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. This paper formalizes the protocol, compares it against fi ve competing approaches, stress-tests it against its strongest objections, and outlines an empirical v alidation path. T o the best of my knowledge, Lore is the first proposal to repurpose the commit message itself as a structured, machine-parseable knowledge channel optimized for inter -agent communication across time. 1 Introduction 1.1 The Decision Shadow Every commit in a software project is the visible output of an invisible process. A developer (or AI agent) encounters a problem, considers sev eral possible approaches, ev aluates the tradeof fs, selects one, and implements it. The commit captures exactly one artifact from this process: the final dif f. Ev erything else—the problem definition, the alternati ves considered, the reasons for rejection, the constraints that shaped the decision, the confidence le vel, the kno wn weaknesses—e v aporates. I call this lost context the Decision Shadow : the unrecorded reasoning behind why the code looks the way it does at an y gi ven point. Over time, Decision Shado ws accumulate. Each one is individually small. Collecti vely , they produce what the industry calls “legac y code”—code that functions but whose structural rationale is lost. Peng and W ang [ 1 ] describe this phenomenon as “tacit knowledge” that “often li ves in de v eloper experience or informal artif acts rather than in code” and observ e that 1 “current [AI] assistants cannot reliably retrie ve or reconstruct this kno wledge on demand. ” 1.2 The Commit Message as It Exists T oday The Con v entional Commits specification [ 5 ], the closest approximation to an industry stan- dard, encodes a message as type(scope): short description . This tells you what happened ( fix(auth): handle expired token refresh ) but is nearly useless for understanding why the code ev olved the w ay it did. The problem is structural, not motiv ational. The format was designed for a world where humans were the only consumers of commit history , the diff w as the primary artif act, and deep context li ved in people’ s heads—transmitted orally through standups, pull request re vie ws, and hallway con versations. All three assumptions are collapsing. 1.3 Why This Matters No w T wo shifts make the Decision Shado w problem urgent. Shift 1: AI agents ar e now primary code consumers. T ools such as Claude Code [ 6 ], GitHub Copilot [ 7 ], and Cursor [ 8 ] attempt to reconstruct intent and constraints from existing code when tasked with modifications. The code tells them what exists; tests tell them what should be true; the commit history should tell them why —b ut in practice, messages like refactor: clean up utils transmit near-zero signal. Shift 2: AI agents ar e now primary code pr oducers. When an agent generates a commit, the message it writes is typically a summary of the diff—a lossy compression of information already present. Research from GitClear analyzing 153 million changed lines of code found that AI coding tools are introducing code faster than ever while raising concerns about long-term maintainability [ 9 ]. No decision context is added to commits. The knowledge destruction problem is accelerating . The compound result: codebases are growing faster than ev er while the ratio of recorded institutional kno wledge to code volume is decreasing. 2 Related W ork 2.1 Architectur e Decision Records Architecture Decision Records (ADRs), popularized by Nygard [ 4 ] in 2011, capture high- le vel architectural decisions as standalone documents. The format typically includes a title, context, decision, and consequences. ADRs hav e gained adoption in go vernment [ 10 ] and enterprise settings [ 11 ], and tools such as Log4brains [ 12 ] provide management and publication infrastructure. ADRs operate at the architectural granularity—e xplaining choices such as “why we chose PostgreSQL ov er MongoDB”—but do not capture implementation-le vel decisions: why a particular function handles errors the way it does, what alternati ves were considered for a specific module’ s retry logic, or what constraints shaped a data v alidation approach. These implementation decisions are far more numerous than architectural decisions and are the ones most commonly lost. Furthermore, ADRs suffer from a synchronization problem: as separate files, they must be manually maintained alongside an e volving codebase and routinely go stale [ 10 ]. Lore addresses the complementary granularity—implementation decisions—and eliminates the synchronization problem by embedding kno wledge directly 2 in the commit, which is immutable and atomically bound to the code change. 2.2 Code Digital T win Peng and W ang [ 1 ] propose the Code Digital T win, a “li ving knowledge infrastructure that couples a physical layer of software artifacts with a conceptual layer that encodes system intent and ev olution. ” Their diagnosis of the problem aligns strongly with the one presented here: tacit kno wledge including “architectural rationales, design trade-of fs, and historical context” is critical for AI-assisted de velopment, and “capability gains alone do not eliminate the need for structured, version-a ware conte xt that preserves why the system is the way it is. ” Ho we ver , their proposed solution is architecturally heavyweight: a multi-layered infras- tructure in volving kno wledge graphs, bidirectional traceable links between code artifacts and conceptual models, and continuous automated extraction pipelines. While this may be appropriate for large enterprise systems such as the Linux kernel (their motiv ating example), it represents significant infrastructure in vestment that most projects cannot undertake. Lore identifies the same problem but proposes a radically lighter -weight treatment: enriching an artifact e very project already has (commit messages) using a mechanism git already supports (trailers), queryable through a tool e very agent already kno ws how to use (a CLI). 2.3 Git Context Controller The Git Context Controller (GCC) [ 3 ] proposes a structured conte xt management frame work for AI agents, using git-inspired operations (COMMIT , BRANCH, MERGE, CONTEXT) ov er a .GCC/ directory to or ganize agent memory as a v ersioned file system. The authors report state-of-the-art results on the SWE-Bench benchmark when agents are equipped with GCC. GCC and Lore address different aspects of the agent context problem. GCC is an intra- session memory management system: it helps an agent or ganize its o wn working memory during a task, with checkpointing and branching to support exploration. Lore is an inter- session knowledge transfer mechanism: it encodes decision context into the permanent project history so that futur e agents (or humans) benefit from it. GCC manages the agent’ s scratchpad; Lore manages the project’ s institutional memory . The two are complementary— an agent could use GCC during a task and produce a Lore-enriched commit at the end. 2.4 AI Code Attribution and Pr ovenance The git-ai project [ 13 ] tracks which lines of code were written by AI agents, linking e very AI-authored line to the agent, model, and original prompt transcripts. Their /ask skill allo ws agents to query the original intent and requirements behind code they are modifying, providing what the authors describe as access to “the wh y” rather than just “what the code does. ” Git-ai preserves the raw transcript —the full con versation between human and agent. Lore preserves the distilled knowledge —the constraints, rejected alternativ es, and directiv es extracted from that con versation. These are related but distinct: the transcript is the raw material, Lore is the refined product. A transcript for a single feature might be thousands of tokens of back-and-forth; the corresponding Lore commit is a dozen structured trailers. For consumption by future agents operating under context windo w constraints, the compression from transcript to structured kno wledge is critical. 3 2.5 AI-Generated Commit Messages A large ecosystem of tools—including aicommits [ 14 ], W indsurf ’ s built-in feature [ 15 ], and Cursor’ s commit generation [ 8 ]—use AI to automatically generate commit messages from dif fs. These tools impro ve consistency and sa ve de veloper time, b ut they fundamentally oper - ate as better labelers of dif fs: they describe what changed, not why . As one practitioner noted, while AI handles “consistency and technical summa ries” well, it cannot capture “the ‘why’ behind our changes—the business conte xt, user feedback, or strategic decisions” [ 16 ]. Lore proposes a categorically dif ferent kind of information in commits—not a better description of the dif f, but kno wledge that was ne ver in the dif f at all. 3 The Lore Pr otocol 3.1 Core Thesis A commit should not be a label on a diff. It should be the atomic unit of institutional knowl- edge in a software project—the smallest self-contained record of a decision, permanently and immutably bound to the code change that enacted it. I call this unit a Lore atom . Its defining properties: Atomic binding. The knowledge is permanently fused to the exact code change it describes. Unlike documentation, wikis, ADRs, or chat threads, it cannot drift out of sync—the commit and its message are a single immutable object. T emporal immutability . Once committed, the Lore atom exists permanently in the project history . It forms an append-only log of decisions—a stronger guarantee than any documenta- tion system provides. Universal availability . Every git-based project already has this channel. There is zero infrastructure cost. The distrib ution mechanism (clone, fetch, pull) is already solved. Natural granularity . Commits are already scoped to logical units of work. The Lore atom inherits this scoping for free. 3.2 F ormat: Git T railers Lore uses git trailers—a nativ e git feature for structured key-v alue data in commit messages. This choice is deliberate: no custom parsing is required, the format is queryable through standard git commands ( git log -trailer= ), and it is supported by e very git tool in existence. A Lore-enriched commit takes the follo wing form (Figure 1 ): The intent line (first line) describes why the change was made, not what changed. The body provides narrative context. The trailers carry machine-parseable decision context. The trailer vocab ulary is shown in T able 1 . Every trailer is optional. The format is additiv e and extensible: unkno wn keys are ignored, and teams can introduce domain-specific trailers without breaking compatibility . 3.3 The CLI: Querying and A uthoring Lore While raw Lore trailers are readable in any git log output, a CLI tool provides ef ficient, scoped querying (Figure 2 ): 4 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 Figure 1: Example of a Lore-enriched commit message. T able 1: Lore trailer v ocab ulary . T railer Semantics Constraint: Rules that shaped this decision and may still be activ e Rejected: Alternativ es ev aluated and dismissed, with reasons Confidence: Author’ s assessment: low , medium , high Scope-risk: Blast radius: narrow , moderate , wide Reversibility: clean , migration-needed , irreversible Directive: Forward-looking instructions for future modifiers Tested: What was verified and ho w Not-tested: What was not v erified and why Related: Reference to related commits by hash 3.4 Agent Consumption Model When an AI coding agent enters a Lore-enabled project, the consumption workflow unfolds through discov erable CLI interactions: Discovery . The agent encounters a .lore config file or Lore-formatted commits in git log , and runs lore -help to understand the av ailable commands. Constraint harvest. Before modifying any file, the agent runs lore context to load the full decision history into its working conte xt. Anti-pattern filtering . Rejected: trailers prev ent the agent from re-exploring dead ends. Directi ve absor ption. Directive: trailers function as messages from pre vious authors to future modifiers—permanent, searchable institutional kno wledge. T emporal r easoning. The lore stale command surfaces constraints that may be out- dated, enabling a self-healing kno wledge base. Knowledge serialization. The agent formats its own commit as a Lore atom, serializing decision context it already holds rather than discarding it. 5 $ lore --help Lore -- Query and author institutional knowledge from git history Query commands: lore context Full lore summary for a code region lore constraints Active constraints shaping this code lore rejected Previously rejected alternatives lore directives Forward-looking warnings lore coverage Test coverage map lore stale [--older-than] Flag outdated assumptions Authoring commands: lore commit Interactive commit builder lore commit --from-json Commit from structured input lore validate Check recent commits for lore format Figure 2: Lore CLI interface. The critical property is that zero special agent support is requir ed —only the ability to run shell commands and read text output. 4 Analysis: Why Not Something Else? vs. ADRs. Complementary , not competing. ADRs capture architectural decisions; Lore captures implementation decisions. ADRs are separate files subject to synchronization decay; Lore atoms are immutably bound to code changes. vs. Code Comments. Comments are mutable, routinely inaccurate, and cannot capture trajectory . Lore preserves the full ordered history of decisions. vs. AI-Generated Diff Summaries. Diff summaries [ 14 , 15 ] re-encode information already in the dif f. Lore adds information that was never in the diff : rejected alternati ves, external constraints, confidence assessments, and forward-looking warnings. vs. RA G Over External Sources. Chat-based RA G suffers from low signal-to-noise, no atomic binding, and ephemeral access. Lore in verts all three. vs. Code Digital T win. The Code Digital T win [ 1 ] prescribes hea vyweight infrastructure. Lore offers near -zero infrastructure cost for the vast majority of projects that cannot justify a full kno wledge layer . 5 Critical Examination Overhead objection. Lore is situated in the AI agent era. Agents already hold decision context and can serialize it at commit time; the ov erhead is revie w , not authoring. Residual risk: rubber -stamped lo w-quality atoms require lore validate checks. Context window objection. No context windo w expansion recov ers information never written do wn. Rejected alternati ves and e xternal constraints exist only in the author’ s mind at commit time. Concession: Lore’ s value is primarily inter -session and inter-agent. T rust and gaming. Structured format makes quality measurable and auditable. Concession: 6 Lore does not solve the trust problem; it mak es trust auditable. Granularity mismatch. The Related: trailer supports commit chains. Concession: ADRs [ 4 ] remain better for cross-cutting architectural decisions. 6 Architectur e Lore has e xactly tw o layers. Layer A is the commit format—git trailers in standard messages, requiring zero tooling. Layer B is the CLI tool—providing efficient querying and authoring. The CLI is optional; the format is sufficient. No servers, no index files, no databases. Additional tools can be built on top without becoming part of the core protocol. 7 Adoption Path and V alidation Lore degrades gracefully: best experience with the CLI, fallback via nativ e git log -trailer= , and no worse than today in con ventional repos. The adoption curve is agent- first: AI agents produce Lore commits with zero friction. Con ventional Commits [ 5 ] took years because humans had to type them; Lore shifts the burden to agent configuration. Pr oposed empirical validation: T wo teams, same project, six months. One uses Lore; one uses con ventional commits. Measured outcomes: agent task success rate, time-to-correct- solution, rate of re-proposing rejected approaches, and re vie w cycles before mer ge. 8 Conclusion This paper has argued that the git commit message is critically underutilized as a knowledge channel. I ha ve proposed Lore, a protocol that repurposes commit messages into structured decision records using native git trailers, queryable through a CLI that any AI agent can discov er and use. The core insight is that e very commit already produces institutional knowledge that is currently discarded. Lore asks agents and dev elopers to serialize this knowledge rather than thro w it away . The ov erhead is minimal; the infrastructure requirement is zero; and the v alue compounds o ver time through a kno wledge flywheel that con ventional commits cannot produce. T o the best of my knowledge, no prior work has proposed the commit message itself as the vehicle for structured, machine-parseable decision context optimized for AI agent consumption. Lore operates at the simplest possible layer . This minimalism is a feature, not a limitation. Every codebase has lore. Most of it is lost. The protocol proposed here is a first step toward changing that. Disclosure of AI-Assisted T ools The author used AI-assisted tools during the research and writing process for this paper . Specifically , Claude (Anthropic, claude-opus-4-6) was used as an interactive research collab- orator for brainstorming the core thesis, iterating on protocol design decisions, conducting structured literature re view , and drafting and refining text. Google NotebookLM was used for organizing and synthesizing research materials. All intellectual contributions—including the identification of the Decision Shado w problem, the Lore protocol design, the choice of 7 git trailers as the implementation mechanism, the CLI-first architecture, and the comparative analysis against competing approaches—originated from the author’ s o wn reasoning, with AI tools serving as instruments for exploration, articulation, and refinement. The author re vie wed, edited, and takes full responsibility for all content in this paper . References [1] X. Peng and C. W ang, “Code Digital T win: Empowering LLMs with T acit Knowledge for Complex Softw are De velopment, ” arXiv preprint , 2025. [2] V . T erragni, A. V ella, P . Roop, and K. Blincoe, “The Future of AI-Driven Software Engineering, ” ACM T rans. Softw . Eng. Methodol. , 2025. [3] “Git Context Controller: Manage the Context of LLM-based Agents like Git, ” arXiv pr eprint arXiv:2508.00031 , 2025. [4] M. Nygard, “Documenting Architecture Decisions, ” Novem- ber 2011. https://cognitect.com/blog/2011/11/15/ documenting- architecture- decisions [5] “Con ventional Commits Specification v1.0.0. ” https://www. conventionalcommits.org/ [6] Anthropic, “Claude Code, ” 2025. https://docs.anthropic.com/en/docs/ agents- and- tools/claude- code/overview [7] GitHub, “GitHub Copilot, ” 2025. https://github.com/features/copilot [8] Anysphere, “Cursor: The AI Code Editor, ” 2025. https://cursor.com [9] B. Harding, “Coding on Copilot: 2023 Data Suggests Downward Pressure on Code Quality , ” GitClear , 2024. [10] 18F (U.S. General Services Administration), “ Architecture Decision Records: Helpful no w , in v aluable later , ” July 2021. [11] D. Haylock, “The Importance of Architecture Decision Records (ADRs), ” Medium , March 2025. [12] T . V aill, “Log4brains: ADR management and publication tool. ” https://github. com/thomvaill/log4brains [13] A. Cunniffe, “Git AI: A Git extension for tracking AI-generated code, ” 2025. https: //usegitai.com [14] H. Nasser , “aicommits: A CLI that writes your git commit messages with AI. ” https: //github.com/Nutlope/aicommits [15] W indsurf, “ AI Commit Messages, ” 2025. https://docs.windsurf.com/ windsurf/ai- commit- message [16] C. Lawson, “Git Commit: When AI Met Human Insight, ” V ersent T ech Blog , September 2024. 8