Detailed Analysis
A developer working with AI coding agents — likely Claude — has published a practical solution to one of the most persistent frustrations in agentic software development: the systematic loss of context, intent, and accumulated insight between sessions. The core problem the author identifies is what they call "context rot" — the phenomenon where both the AI agent and the human developer lose track of the nuanced reasoning, edge cases, and implicit decisions that were understood during the original coding session but vanish by the next day. The solution they built, hosted at a public GitHub repository called `agents-remember.md`, establishes a "shadow doc tree" that mirrors the project's source file structure exactly. For every source file — for example, `src/Backend/UserController.php` — there is a corresponding markdown companion at a parallel path, such as `onboarding/src/Backend/UserController.md`. The companion document is automatically opened alongside the source file whenever an agent reads the code, requiring no search, no vector embeddings, and no RAG pipeline.
The system is deliberately structured around three interaction modes — a lightweight chat mode for simple tasks, a task-file mode for medium complexity work, and a full phased workflow for high-stakes changes like migrations or cross-repository edits. All three modes share a consistent discipline: the agent checks for drift between the companion doc and the current code state before planning, seeks explicit human approval before writing any code, and updates the companion document only after approved changes. This approval-gated update cycle is central to the design's integrity — companion files are not auto-generated or speculatively written, but are authored at the moment of maximum shared understanding between the developer and the agent, capturing intent while it is still live and accurate.
The author makes a distinction that cuts to the heart of current AI tooling limitations: semantic search and RAG systems require the user to have at least a vague idea of what they are looking for, making them unsuitable for recovering forgotten reasoning or undocumented invariants. The shadow doc approach sidesteps retrieval entirely by co-locating documentation with code through deterministic path derivation — the doc is always exactly where the code is, structurally speaking. This eliminates the "you can't look up what you don't know exists" problem that plagues knowledge bases and embedding-based systems. The author also notes an unexpected personal benefit: the companion files serve as rapid re-entry points for the human developer returning to unfamiliar code after weeks or months away, reconstructing intent that would otherwise require laborious code tracing.
The proposal connects directly to a broader challenge in the AI development ecosystem around persistent memory and agentic continuity. Anthropic has explored related territory through its contextual retrieval research and the memory tool available to Claude-based agents, but these operate at a system or session level rather than the file-by-file granularity this developer is targeting. The fine-grained, human-curated, version-controlled nature of the shadow doc tree represents a different philosophy — one that treats documentation as infrastructure rather than afterthought, and that keeps knowledge legible to both humans and machines without abstracting it into opaque vector stores. The author explicitly values markdown's openness: anyone on a team can read and contribute, meaning that knowledge deposited by one developer and their agent becomes immediately accessible to all other developers and their agents working in the same repository.
The post surfaces a tension that is becoming increasingly relevant as agentic coding tools mature: the gap between what an AI agent can do within a single context window and what it needs to do reliably across sessions and team members. The author's framing — "capture it all when me and the agent still know what's going on" — is a candid acknowledgment that current large language models, including Claude, have no persistent memory of prior sessions by default, and that the burden of continuity falls on the human and the systems they build around the model. The shadow doc tree is a low-tech, high-discipline answer to that gap, and its viability for team onboarding and collaborative agentic workflows positions it as a pattern worth broader examination in the developer community actively experimenting with AI-assisted software engineering.
Read original article →