I wanted my coding agent to remember the codebase

AI coding agents may initially perform well on their first task, but they often encounter difficulties on subsequent attempts. They tend to reopen the same files, trace the same call chains, and overlook certain aspects that need modification. This repeated investigation can be costly, as it consumes more tokens and leaves room for incomplete patches to go unnoticed.

The goal was to provide the agent with a reusable map of the codebase, allowing for cheaper repeated investigation without compromising the safety of future product changes. However, the final outcome revealed that a saved code map only proved beneficial when the resulting patch was correct. If an index helped the agent find four files quickly but missed the crucial fifth file containing the contract, the saved tokens were essentially wasted, as they were replaced with rework.

This article aims to explore how this idea was tested and to determine when a saved code map adds value in day-to-day product work, as opposed to relying on current source and tests. The primary challenge that the agent repeatedly needed answers to was understanding the impact and implications of a small set of questions. Before making any changes, the agent needed to know why the answer mattered, what specific function, class, or endpoint was involved, and where this value or decision was spread throughout the codebase.

The visible user interface often only represents the final step in a more complex path that needs to be understood to avoid unforeseen consequences. The agent also needed to identify where the change would propagate and which tests would safeguard the modified behavior. A passing local check does not guarantee the overall behavior, so verifying the saved map's accuracy was essential.

Tools can answer these questions in various ways, such as leveraging language services used by an IDE or maintaining a parsed map of symbols, imports, calls, and tests. This parsed map is referred to as an index in this article, serving as navigational assistance rather than replacing the source of truth. While the promise of having an agent spend less time searching code and more time implementing changes is appealing, the success of this approach depends on maintaining quality or even improving it.

Throughout the testing process, a strict rule was maintained: a patch could only be considered successful if it satisfied the source-derived behavior contract and passed its focused tests. After failing intentionally to introduce a specific defect, the test had to fail again, confirming the test's ability to catch the introduced mistake.

An LLM was initially employed to judge which questions were worth investigating, but ultimately, source checks and deliberate modifications served as the final gate. To make the question testable, the researcher examined different methods for an agent to retain code context between questions, including ordinary source search, context packers, language-service bridges, graph indexes, and semantic search.

Each method had its specific role, and ranking them collectively could obscure more than it clarified. The investigation proceeded in three stages: the first stage compared various ways an agent might store code context between questions, analyzing candidates and potential failure points. The second stage focused on specific questions the agent could answer using different tools across multiple repositories and languages.

The third and most critical stage tested the impact of persistent context on the quality of completed changes. The first stage provided a comprehensive view of potential pitfalls, while the third stage measured the actual outcomes. Neither stage aimed to create a universal ranking or claim token savings, but instead sought to answer a practical question: which recurring questions could a tool effectively address within a given repository?

Despite these findings, several critical questions remain unanswered. Specifically, it is unclear whether the use of a saved code map ultimately reduces total work without compromising patch quality. The selection framework keeps track of candidate history, allowing for reproducibility by providing pinned revisions and raw records of the experiments.

This archive ensures that the article can explain the decision-making process without requiring readers to independently audit a tool catalogue. Ultimately, the experiment revealed that in certain specific cases, such as stopping an inactive signed-in user from resolving a department through a shared SQL helper or delivering accurate counts in desktop and mobile layouts, ordinary source navigation proved sufficient, with no added advantage from employing structured indexes.

However, in more complex situations, such as carrying a machine category through SQL, pagination, TypeScript contracts, and across two reader surfaces, a navigation index did not enhance reliability. In fact, many patches appeared plausible but were found to be incomplete, such as missing paginated fields, incorrect updates to closed vocabulary, or uncertainties left unresolved.