The Repository Context Layer: A Git-Native Architecture for Persistent Agent Context

Download the paper (PDF, 6 pages) · Specification repository · Reference implementation

Abstract

AI coding agents now perform multi-step engineering work, yet every session begins without the operating knowledge that shapes a codebase: the decisions taken, the alternatives rejected, the constraints discovered during execution. Existing mechanisms (documentation, architecture decision records, retrieval-augmented generation, IDE memories, agent instruction files) each address a fragment of the problem; none provides a store that is versioned with the code, consulted by contract, and writable by agents under human review. This paper formalizes the Repository Context Layer (RCL), an architecture pattern in which a repository carries its own agent-facing context through a defined consult–execute–update–commit lifecycle. We separate the pattern into four independent layers: the architecture, a deterministic discovery specification, a minimal file format (context.md), and implementations. We give branch, merge, and rollback semantics inherited from Git, analyze the contested design choices (single file versus many, append-only semantics, conflict handling, hierarchy, and the limits of agent self-modification), and report on Metatron, a reference implementation. We argue that repository context should be treated as a first-class, versioned artifact of software projects, alongside code, tests, and documentation.

Cite

Kerbel, P., & Kerbel, M. (2026). The Repository Context Layer: A Git-Native
Architecture for Persistent Agent Context. Preprint v0.1.
https://pavelkerbel.com/papers/repository-context-layer/

Companion artifacts: the Repository Context Layer manifesto and minimal specification, and Metatron, the reference implementation discussed in Section 9.