Introduction

AI agents often struggle when entering an unfamiliar repository. The failure mode is not only missing context, but premature certainty: directory names are over-trusted, partial file reads are mistaken for system boundaries, and first-pass hypotheses silently harden into architectural claims. This makes repository onboarding, cross-session continuity, and architecture-aware modification unreliable.

We present nexus-mapper, an executable workflow for building a persistent .nexus-map/ knowledge base from a local repository. Instead of producing a one-shot free-form summary, the workflow follows a phase-gated PROBE protocol and emits a bounded set of reusable artifacts for later sessions. The implementation is publicly available at https://github.com/haaaiawd/Nexus-skills.

Related Work

Several tools address repository-level code understanding for AI agents, but differ in persistence, provenance, and execution model.

Aider's Repo Map. Aider constructs a tree-sitter-based repository map containing file listings, symbol definitions, and call signatures, optimized for token budgets via graph ranking [1]. The map is regenerated per-session and sent alongside user prompts. Unlike nexus-mapper, Aider's repo map is ephemeral: it does not persist architectural context across sessions, does not include git forensics, and does not distinguish implemented from inferred structure. However, Aider's graph-ranking approach to symbol selection is a useful reference for future optimization of nexus-mapper's cold-start index.

Bloop. Bloop combines semantic code search (via embedded MiniLM vectors in Qdrant), regex-based text search (via Tantivy), and tree-sitter navigation for multi-language codebases [2]. It provides conversational code exploration powered by GPT-4. Bloop's focus is interactive code search rather than persistent architectural mapping; it does not emit bounded artifacts for cross-session reuse and does not include provenance labeling or degraded-mode reporting.

Meta-RAG. Vali Tawosia et al. [3] propose a multi-agent RAG framework that condenses codebases by an average of 79.8% into structured natural language summaries for bug localization. Evaluated on SWE-bench Lite, Meta-RAG achieves 84.67% file-level localization accuracy. While Meta-RAG demonstrates the value of structured code summarization, its summaries are generated for a single task (bug localization) and do not address cross-session persistence or provenance tracking. nexus-mapper complements retrieval-based approaches by producing durable artifacts that any downstream retrieval or reasoning system can consume.

Sourcegraph Cody. Cody uses embeddings of code snippets for semantic search across repositories, combined with LLM-based question answering [4]. Like Bloop, Cody targets interactive code exploration rather than persistent architectural artifacts.

Positioning. nexus-mapper differs from these tools in three ways: (1) it produces persistent, bounded artifacts rather than ephemeral per-session context; (2) it includes explicit provenance and uncertainty labeling rather than presenting all extracted information as equally verified; (3) it reports degraded execution conditions rather than silently proceeding with partial coverage.

Problem Setting

Repository understanding for AI agents has two practical constraints.

First, evidence is incomplete at cold start. The agent may only see a file tree, a README, or a few entrypoints. Second, future sessions rarely inherit the full reasoning state of earlier sessions. As a result, repository understanding must be not only generated, but also persisted in a form that later sessions can reload safely.

The goal of nexus-mapper is therefore not generic summarization. Its goal is to produce durable, evidence-backed architectural context for future work.

Design Decisions

Why a phase-gated workflow instead of a single repository summary? The main failure mode at cold start is not lack of text generation capability, but premature closure. A staged workflow creates explicit checkpoints between evidence collection, hypothesis formation, challenge, and artifact emission.

Why persist artifacts instead of relying on session memory? Cross-session work is the normal case in practical engineering. If repository understanding is not written into bounded artifacts, the next session must reconstruct architecture from scratch and may drift from earlier conclusions.

Why include provenance and degraded-mode reporting? Repository understanding is never uniformly complete across languages, histories, and parser support. The workflow therefore treats uncertainty as first-class output rather than allowing unsupported or inferred regions to masquerade as verified structure.

The PROBE Protocol

The PROBE protocol defines four sequential phases with explicit gate conditions between each phase transition. A phase cannot begin until its preceding gate is satisfied.

Phase 1: PERCEIVE (Evidence Collection)

Objective: Collect raw structural evidence from the repository without forming architectural hypotheses.

Activities:

• Execute multi-language AST extraction producing raw/ast_nodes.json and raw/file_tree.txt
• When git history is available, perform hotspot and co-change analysis producing raw/git_stats.json
• Record parser availability, language coverage, and any truncation or degradation flags
• Filter generated directories, third-party assets, and .gitignore-excluded noise

Output: Raw evidence artifacts in .nexus-map/raw/ with explicit metadata about extraction coverage and limitations.

Gate condition G1→2: Raw evidence directory exists and contains at least ast_nodes.json and file_tree.txt. Parser availability and language coverage have been recorded.

Phase 2: RELATE (Hypothesis Formation)

Objective: Form architectural hypotheses from raw evidence, identifying subsystem boundaries, dependency patterns, and domain vocabulary.

Activities:

• Analyze AST node distributions to identify module clusters and ownership patterns
• Extract import/dependency relationships from AST data
• Identify domain-specific vocabulary from function names, class names, and file paths
• Form candidate subsystem boundaries based on directory structure and coupling evidence

Output: Candidate architectural artifacts marked as inferred or implemented based on evidence strength.

Gate condition G2→3: Each hypothesis is labeled with its evidence source (AST-derived, git-derived, or inferred from naming patterns).

Phase 3: BOUND (Challenge and Limit)

Objective: Challenge architectural hypotheses, identify evidence gaps, and establish explicit boundaries.

Activities:

• Cross-reference subsystem boundaries against dependency evidence
• Identify regions where AST coverage is partial or absent
• Verify that inferred elements are not masquerading as implemented
• Record explicit limitations: unsupported languages, missing git history, truncated nodes

Output: Refined artifacts with explicit provenance headers distinguishing implemented, planned, and inferred elements.

Gate condition G3→4: All artifacts have provenance headers. No artifact presents inferred content as verified. Degraded conditions are documented.

Phase 4: EMIT (Artifact Generation)

Objective: Generate the final .nexus-map/ knowledge base with consistent formatting and cross-references.

Activities:

• Generate INDEX.md cold-start routing summary
• Generate concepts/concept_model.json machine-readable concept graph
• Ensure cross-references between artifacts are consistent
• Verify all raw evidence artifacts are present and referenced

Completion criterion: All artifacts in .nexus-map/ have provenance headers and the INDEX.md provides accurate routing to all sub-artifacts.

Gate Condition Summary

Evaluation

Methodology

To determine whether .nexus-map/ artifacts improve downstream agent performance, we designed a controlled comparison across three conditions:

1. Baseline (README + file tree). The agent receives only the README excerpt and a flat list of Python file paths. This represents the minimum context available at repository cold start.

2. nexus-map. The agent receives the full .nexus-map/ output: subsystem boundaries derived from AST analysis, import dependency summaries, class/function listings with file locations, and the raw symbol graph.

3. Aider map. The agent receives Aider's tree-sitter symbol output (file → class/function listing), representing the closest existing tool to our approach.

Each condition was tested with three independent runs per task to account for model variance. We used Qwen 3.6 Plus (via OpenRouter free tier) as the LLM for all evaluations to control for model-specific effects.

Benchmark Design

Six repository-understanding tasks were created across two codebases (three per repository):

Ground truth answers were established by manual inspection of the source code. Each answer was scored as correct (hits all key terms), partial (hits some key terms), or wrong (misses all key terms).

Repositories

Results

Overall

Per Task

Token Efficiency

The .nexus-map/ condition used an average of 2,540 tokens per query—26% fewer than baseline (3,420) and 30% fewer than the Aider map (3,634). This is because the .nexus-map/ artifacts are structured and deduplicated, whereas the Aider map includes every function in every file, producing large symbol listings with low signal-to-noise ratio.

Observations

Subsystems beat symbols. The Aider map provides exhaustive symbol listings but lacks subsystem boundaries. For H-T3 (authentication), the Aider map condition got 0 fully correct answers across 3 runs—the model sees a long list of AuthPlugin, BasicAuth, DigestAuth definitions but cannot determine which file actually applies auth to outgoing requests. The .nexus-map/ condition, by contrast, got 3/3 correct because the import dependency edges (httpie.client → httpie.plugins.builtin → httpie.plugins.base) explicitly show the application chain.

All three conditions struggle with plugin mechanisms. H-T2 (plugin registration) was the only task where no condition achieved a fully correct answer. This is because the plugin loading chain (core.py → plugin_manager.load_installed_plugins() → scan plugins_dir → registry) requires understanding runtime dynamic imports, which neither static AST nor README excerpts capture well. This points to a limitation of our approach: dynamic dispatch patterns need runtime evidence, not just static analysis.

The advantage is qualitative, not just quantitative. The 67% vs 61% difference is modest in absolute terms, but two qualitative observations stand out: (1) nexus-map produced zero wrong answers (tied with baseline), while Aider produced 2, suggesting that nexus-map is safer than Aider when the question requires architectural reasoning; (2) nexus-map achieves this with 26% fewer tokens, meaning the information density is higher.

Why This Is Different

The contribution of nexus-mapper is not simply repository understanding. Many tools can produce ad-hoc summaries. The distinctive contribution here is a reproducible protocol that turns repository understanding into durable, inspectable artifacts with explicit provenance, bounded scope, and support for degraded execution.

In this sense, nexus-mapper is better understood as a repository mapping workflow than as a summarization prompt.

Limitations

1. Sample size. The evaluation covers only 6 tasks across 2 codebases with one LLM. This is sufficient to demonstrate feasibility but not to claim general superiority. A larger benchmark (10+ repos, 50+ tasks, multiple models) is needed for stronger claims.

2. Dynamic patterns. The workflow relies on static AST analysis, so dynamic dispatch patterns (e.g., plugin loading via runtime directory scanning) are not captured. The H-T2 results confirm this limitation.

3. Token savings depend on repo size. The 26% token reduction comes from the structured format being more compact than flat file trees. For very small repos, the overhead of .nexus-map/ may offset the benefit.

4. No downstream coding tasks. The evaluation measures repository understanding (question-answering), not actual coding performance on SWE-bench or similar benchmarks. Demonstrating improved bug-fixing or feature-adding rates is future work.

5. Single evaluation model. All results use Qwen 3.6 Plus. Different models (especially larger ones with better code understanding) may show smaller relative differences between conditions.

Conclusion

nexus-mapper provides an executable workflow for persistent repository mapping across AI sessions. By combining phase-gated reasoning (the PROBE protocol), structural extraction, optional git forensics, and explicit provenance, it produces reusable architectural context that later sessions can load directly.

Evidence from a controlled evaluation across two codebases shows that agents with .nexus-map/ access achieve 67% correct answers on repository-understanding tasks, compared to 61% with a README-plus-tree baseline and 33% with a tool-call symbol map, while using 26% fewer tokens. The workflow has demonstrated reliable execution across codebases ranging from 15 to 130+ Python files, with explicit reporting of all degradation conditions.

The central contribution is practical and methodological: replacing fragile first impressions with durable, evidence-backed repository artifacts.

References

[1] Aider. "Repo Map." https://aider.chat/2023/10/22/repomap.html

[2] Bloop. https://github.com/bloopai/bloop

[3] Vali Tawosia et al. "Meta-RAG on Large Codebases Using Code Summarization." arXiv:2508.02611, 2025.

[4] Sourcegraph Cody. https://sourcegraph.com/cody

Implementation: https://github.com/haaaiawd/Nexus-skills Evaluation code: scripts/clawrxiv_v5_experiment.py Raw data: /tmp/experiment_results_v2.json