PageRank repo-map as the zero-config structural context floor

PageRank repo map as an opt in structural layer

Problem

Recall here is memory centric plus semantic and lexical over memory strings. It has no structural view of the codebase: which files define the symbols the current task touches, ranked by dependency weight. Semantic search over memory strings cannot answer what owns authenticate and who calls it. That is a graph question and there is no code graph. Every session rediscovers project structure through reads and greps.

Aider's RepoMap is the proven shape: tree-sitter tags per file, file level dependency graph, PageRank seeded from chat files and mentioned identifiers, token budgeted symbol map injected as context. Fully deterministic, zero LLM calls, mtime cached.

Scope: opt in, never core

A structural map is a retrieval aid, and this repo already has a working retrieval stack. Putting parsing and invalidation on the hot path for every user would tax people who never call it. So core gets nothing new. The map is an opt in provider behind a flag, artifact gated, absent by default like the reranker. Grammars are explicit and listed (Rust, TS, Python first). An unlisted language means no symbols for that file, never a hard failure. Cache is mtime plus hash per file, never a global rebuild. Rank is hand rolled (~30 lines), no petgraph.

Measured prototype

I built the prototype outside core and ran it on three repos here, budget 2000 tokens:

jcode: 1350 files, 32,874 symbols, 40,114 edges, 4.57s cold, map 1998 tokens / 8.7KB.
websearch: 46 files, 421 symbols, 201 edges, 0.11s cold, map 2000 tokens / 9.1KB.
codesearch: 29 files, 226 symbols, 69 edges, 0.08s cold, map 1236 tokens / 5.5KB.

Warm cache on jcode: 4.06s cold down to 0.066s warm, about 61x, cache 2.9MB. That confirms the invalidation concern is real (cold parse dominates) and that per file invalidation makes the steady state effectively free.

What this says about default on: cold cost is parse bound and linear in files, 4.6s per 1350 files on one core. That is why this cannot be default on. The 2000 token map covers all parsed files in rank order, a usable stub at a fixed budget. Prototype script: bench/repomap_proto.py on my fork, run with python3 repomap_proto.py <repo>....

Why this shape

Structural queries beat semantic search on code (identifiers, ownership, call edges). The map covers the orthogonal axis to memory recall. Deterministic and local first: no model, no service, no migration. File granularity first, per symbol rank is the possible refinement if files prove too coarse. It complements the rerank work (#1228): rerank sharpens memory recall, the map sharpens orientation.

Limits

Structural only: the map knows what calls what, never why the code exists. Intent stays with memories and the sidecar. Parse failures warn instead of silently dropping: a file that fails parsing is listed as unparsed in the footer. Three grammars to start, more languages are mechanical follow up.

Start with the measured prototype at bench/repomap_proto.py and run it with python3 repomap_proto.py to compare cold and warm behavior. Then trace the existing retrieval providers and reranker integration to define the opt-in boundary. Done means an artifact-gated map with Rust, TypeScript, and Python grammars, per-file mtime/hash caching, deterministic ranking, and an unparsed-file footer.