/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 |