Architecture & graph intelligence

Graph algorithms over the indexed AST graph: Louvain communities, PageRank-central symbols, bridge chokepoints, dependency paths, execution flows, and cross-repo API topology.

Every indexed repository becomes an AST knowledge graph, and Memtrace runs real graph algorithms over it — not heuristics. Louvain community detection, PageRank centrality, betweenness centrality, and shortest-path search all run against the same graph your MCP tools query, so the architecture picture you get is derived from the code itself, not from folder names or file counts.

Overview#

These tools are grouped under one idea: understand the shape of a codebase before you touch it. list_communities finds the logical modules, find_central_symbols and find_bridge_symbols find the load-bearing and chokepoint code, find_dependency_path traces how two symbols connect, get_codebase_briefing composes a structural summary, and list_processes / get_process_flow reconstruct execution flows end to end. All of these are billable graph-query MCP tools.

Communities (Louvain)#

list_communities lists Louvain community clusters detected in a repository — groups of tightly-coupled symbols that frequently call each other. Communities naturally correspond to bounded contexts, services, subsystems, or modules, even if the code doesn't explicitly label them that way. Use it to understand a codebase's high-level architecture without reading any code, then drill into a specific community with find_code or find_symbol to explore its contents.

Communities respect a minimum size (default 3) and a result cap (default 50) so a small, incidental cluster of two helper functions doesn't crowd out the modules that actually matter.

Central symbols & bridge symbols#

find_central_symbols runs PageRank over the full knowledge graph and filters to the requested repo, branch, and symbol kinds (falling back to in-degree centrality if the full computation is unavailable). A higher score means more transitive callers and dependents — these are load-bearing symbols that deserve extra care during refactoring, because changes to them carry the highest blast radius. Run this at the start of a refactoring session to see which functions to be most careful about.

find_bridge_symbols runs normalized betweenness centrality to find architectural chokepoints — symbols that sit on many paths between otherwise disconnected parts of the codebase. Bridge symbols are the highest-risk refactoring targets precisely because changing them can cascade through subsystems that look unrelated. A symbol with a high bridge score but low PageRank is often a hidden architectural dependency nobody documented — the kind of code a first-time reader would never guess matters.

Dependency paths#

find_dependency_path finds the shortest call/dependency path between two symbols — "how does X connect to Y?" or "what's the chain from the HTTP handler down to the database query?" Use it when you know both endpoints but not the route between them. edge_type defaults to a traversal over CALLS, REFERENCES, IMPORTS, and INSTANTIATES edges together; narrow it to calls or imports alone when you want a specific kind of connection.

Codebase briefing#

get_codebase_briefing composes a structural briefing for an indexed repository: scale, modules, endpoint coverage, high-risk symbols, dead-code candidates, and suggested next graph queries, in a single call. Use it at the start of an agent session, before reading any files — detail_level: "summary" (the default) keeps it short; "full" includes more modules and risk entries.

Processes & execution flows#

Processes are BFS-traced call chains from entry points — the major user-facing flows in a codebase: HTTP route handlers, background jobs, CLI commands, event handlers, init sequences. list_processes gives a high-level map of "what the code actually does," showing each process's entry point, step count, and the communities it crosses (intra-community vs. cross-community). get_process_flow then traces one named process step by step — function name, file path, line number, and community membership for every hop — answering "what happens end to end when X is triggered?"

API topology & cross-repo linking#

find_api_endpoints lists the HTTP endpoints a service exposes, detected automatically during indexing from frameworks including Express, Encore, NestJS, Axum, FastAPI, Flask, Gin, and Spring Boot — handler function, HTTP method, path template, and which other services call each endpoint. find_api_calls lists the outbound HTTP calls a service makes, detected from fetch, axios, callTypedAPI, useSWR, useQuery, reqwest, and similar client patterns, including the raw URL or path template (env-var base URLs like ${PAYMENT_SERVICE_URL}/charge resolve too).

get_api_topology returns the full cross-repo HTTP call topology — which services call which others, with matched route pairs and confidence scores — across every indexed repository at once, with no repo_id required. Filter by min_confidence (default 0.7) or a specific repo to zoom in, and set include_external to true to also show calls to third-party APIs.

$ memtrace index /path/to/frontend
$ memtrace index /path/to/payments-service
# then, over MCP:
# link_repositories(from_repo="frontend", to_repo="payments-service", reason="checkout calls payments")

get_service_diagram renders the same topology as a Mermaid graph LR diagram — services as nodes, external third-party APIs styled with dashed borders. It returns null until at least one indexed service has HTTP endpoints or calls to show; render the returned string in any Mermaid viewer, or view the same picture live in the dashboard's Topology tab.

Relationships & blast radius#

analyze_relationships traverses typed AST edges from a symbol: find_callers, find_callees, class_hierarchy, overrides, imports, exporters, and type_usages. get_impact computes the transitive blast radius of modifying a symbol — affected symbols grouped by depth, an overall risk rating (Low / Medium / High / Critical), and the affected files and processes — in either the upstream (who calls this) or downstream (what does this call) direction.

Pre-flight check#

preflight_check is the single call to run before editing any symbol you didn't just write. It bundles blast radius (who depends on it, which process flows it sits in), co-change partners (files that historically change together with it), complexity, 30-day churn, and a generated checklist of verification steps — one call instead of four. The checklist tells you what to re-verify after the edit; co-change partners are files you likely need to update in the same change.

Related pages: code quality & review for dead code and complexity, and the knowledge graph for how the graph itself is built.