memtrace-codebase-exploration

name

memtrace-codebase-exploration

description

Map an indexed source-code repo into a structured overview — scale, communities, central symbols, execution flows, API surface, recent activity. Use when the user wants to explore, understand, onboard to, map, or get an overview of an indexed source-code repo, architecture, modules, or major flows. Do not use Glob, find, tree, rg, or manual file browsing as the first exploration path; Memtrace provides structured graph briefing. Do NOT use for change history / what-changed questions — use memtrace-evolution.

Overview

Full codebase exploration workflow — from indexing through architectural understanding. Chains indexing, graph algorithms, community detection, and temporal analysis into a structured onboarding experience. Use this when someone is new to a codebase and needs to build a mental model.

Steps

1. Index the codebase

Call list_indexed_repositories first. If the repo is already indexed, skip to step 2.

Otherwise, call index_directory with the project path, then poll check_job_status until completion.

Success criteria: Repo appears in list_indexed_repositories with non-zero node/edge counts.

2. Get the lay of the land

Call get_repository_stats to understand scale:

• How many functions, classes, methods, interfaces?
• How many relationships (calls, imports, extends)?
• How many communities and processes were detected?

Report these numbers to the user — they set expectations for the codebase's size and complexity.

3. Map the architecture (communities)

Call list_communities to see how the codebase naturally clusters into logical modules.

Decision: If >10 communities, summarize the top 5–7 by size and let the user ask about specific ones.

Each community represents a cohesive module — these are the "areas" of the codebase.

4. Find the most important symbols

Call find_central_symbols — PageRank over CALLS/REFERENCES edges (no method param):

{ "repo_id": "<repo>", "limit": 15 }

These are the symbols that the rest of the codebase depends on most heavily. They form the "skeleton" of the architecture.

5. Find architectural bottlenecks

Call find_bridge_symbols to identify chokepoints — symbols that connect otherwise-separate parts of the codebase.

Decision: If bridge symbols overlap heavily with central symbols, flag them as critical infrastructure — high importance AND single point of failure.

6. Map execution flows

Call list_processes to discover entry points:

• HTTP handlers (API endpoints)
• Background jobs
• CLI commands
• Event handlers

This shows HOW the code is actually used at runtime, not just how it's structured.

7. Map the API surface (if applicable)

Call find_api_endpoints to list all HTTP routes.

Decision: If multiple repos are indexed, also call get_api_topology to map service-to-service dependencies.

8. Recent activity

Call get_evolution to see recent activity:

{ "repo_id": "<repo>", "from": "30d ago", "mode": "overview" }

Check totals.episode_count and episode boundaries. For file/symbol hotspots, switch to compound:

{ "repo_id": "<repo>", "from": "30d ago", "mode": "compound" }

Review top_changed_files and top_touched_symbols.

9. Complexity hotspots

Call find_most_complex_functions:

{ "repo_id": "<repo>", "top_n": 10 }

Full parameter spec for every Memtrace tool: references/mcp-parameters.md (bundled at the memtrace-skills plugin root).

Report Synthesis

Synthesize findings into a structured overview:

1. Scale — languages, total symbols, total relationships
2. Architecture — main communities/modules and what they do
3. Critical Infrastructure — central symbols and bridge points
4. Execution Flows — how the code is entered and used
5. API Surface — endpoints and service dependencies
6. Recent Activity — what's been changing in the last 30 days
7. Technical Debt — complexity hotspots and potential dead code

Output

The deliverable is the 7-part overview above. Skeleton (one headline per part):

1. Scale — 2 languages, 4,812 symbols, 19,344 relationships
2. Architecture — 12 communities; top 5: auth, indexing, api, ui, billing
3. Critical Infrastructure — EngineHandle::open (central AND bridge — flag it)
4. Execution Flows — 14 processes: 9 HTTP handlers, 3 CLI commands, 2 jobs
5. API Surface — 42 endpoints; 2 cross-repo service dependencies
6. Recent Activity — 31 episodes in 30d; hottest file per top_changed_files
7. Technical Debt — top-10 complex functions, highest complexity first

Common Mistakes

Mistake	Reality
Skipping indexing and using file-based grep	The knowledge graph provides structural understanding that grep cannot — callers, callees, communities, processes
Reporting raw numbers without interpretation	"450 functions across 12 communities" means nothing; describe what each community does
Only looking at code structure	Execution flows (processes) show how the code is actually used — always include them
Ignoring temporal context	Recent evolution shows where active development is happening — this is where the user will likely need to work