A developer has rolled out a three-layer code-base map that lets AI coding agents retain a sense of place across sessions.
Why AI agents need a map
Chat-based coding assistants build a mental model of a repository only while the prompt window stays open. When the context window closes, the model evaporates, forcing the agent to rediscover symbols, imports and file relationships from scratch. That back-and-forth wastes compute cycles and makes the agent less helpful when a developer hops between files or returns to a project after a break.
The three layers that make up the map
- Structural layer – a catalog of symbols, function calls and import statements. It answers the static question “what calls what.”
- Temporal layer – git-derived signals such as file churn rates and ownership histories. It shows which parts of the code change most often and who tends to touch them.
- Behavioral layer – the real-world usage pattern extracted from an agent’s own edit and navigation history. It reveals which files are actually opened together during a coding session, exposing “true neighbors” that static analysis misses.
The behavioral layer carries the most weight because it reflects how developers (and agents) truly work, not just how the code is wired.
Two ways to feed the map to the agent
- Ambient Path – a concise summary injected into every interaction. It gives the agent an immediate “you are in X module, these symbols are nearby” snapshot without any extra calls.
- Deep Path – on-demand query tools the agent can invoke when it needs richer detail, such as a list of files that frequently change together or a timeline of recent ownership.
Separating ambient from deep information keeps the routine prompt light while still offering depth when required.
Design rules that keep the system lean
- Skip heavyweight language servers. The map relies on shallow parsing rather than full type inference. The goal isn’t to out-engine mature static analyzers but to complement them with behavioral insight.
- Contain the graph per project. The system does not stitch a global dependency graph across repositories. This containment reduces memory footprints and speeds up updates.
- Reuse the existing memory store. File-change logs come from the agent’s own memory of tool calls, avoiding duplicate storage and keeping the data source consistent.
Building the map in practice
- Collect structural data with a quick pass over source files, extracting symbols and import lines.
- Pull temporal metrics from the git history of the repository, noting which files see the most commits and who authored them.
- Harvest behavioral signals by logging the agent’s file-open, edit and navigation actions during real coding sessions. These logs become the basis for the “co-occurrence” matrix that defines behavioral neighbors.
- Populate the Ambient Path with a short, ordered list of the most relevant symbols and files for the current task.
- Expose the Deep Path as a set of lightweight query functions (e.g., “list files edited together in recent sessions”).
Fast hooks capture each edit as it happens; slower background sweeps recompute churn stats. Together they keep the map fresh without bogging down the developer’s workflow.
Lessons learned on the road
- Split ambient from on-demand. Keeping the always-present summary tiny prevents token bloat, while richer queries stay optional.
- Prioritize context by task. Ordering the ambient symbols according to the current edit focus yields more useful suggestions.
- Refresh aggressively but intelligently. Quick hooks capture high-frequency changes; periodic scans handle low-frequency churn and ownership shifts.
- Shallow parsing wins for speed. Deep type analysis adds latency without delivering the behavioral insight that drives the map’s advantage.
Takeaway: By layering static structure, git-derived history and real-world usage into a compact, two-tier access model, developers can give AI coding agents a durable map of the codebase. Keeping the always-present summary tiny prevents token bloat.