MCP tool reference
Every tool memtrace mcp registers, grouped by category, with what it returns, its key parameters, and whether it counts against your plan quota.
READ THIS FIRST
This page is the exhaustive reference — every tool, every parameter. For how the tools fit together (why a search tool hands off to a graph tool, why quota gating exists, how Cortex's sidecar relates to the main server), see MCP overview first.
memtrace mcp registers 75 tools across nine categories. 37 of them are billable — they consume your plan's query quota; the rest are indexing/watch lifecycle, fleet coordination, diagnostics, and plain metadata enumeration, which are never metered. The tables below don't mark billing status per row — see the closing callout for which categories are metered. On quota exhaustion a billable tool still returns a normal success result — the payload itself is a quota-error JSON object, not a protocol-level failure.
Indexing & watch#
Getting a repository into the graph, watching it for live changes, and tracking background jobs.
| Tool | Description | Key params |
|---|---|---|
index_directory | Index a local directory into the persistent code graph — parses every source file, resolves cross-file relationships, detects API endpoints/calls, runs community detection and process tracing, and embeds symbols for semantic search. Auto-detects multiple git repos inside a directory. Returns job_id(s) to poll. | path (required), repo_id, incremental, clear_existing, branch (default main), skip_embed, defer_replay |
list_indexed_repositories | List all indexed repositories with node/edge counts, branch, last-indexed time, and pending replay/enrichment status. Always call first to discover repo_ids. Inspect the response's _meta.empty_state_reason before assuming an empty result means you need to re-index. | none |
delete_repository | Permanently remove all nodes, edges, episodes, and embeddings for a repository. Re-index with index_directory to restore it. | repo_id (required) |
check_job_status | Poll a background indexing job's stage (scan → parse → resolve → communities → processes → persist → embeddings → api_detect → done), node/edge counts, and embed progress. | job_id (required) |
list_jobs | List all indexing jobs with status and timestamps. | none |
get_repository_stats | Node counts by kind, total edges, community count, episode count, and last-indexed timestamp for a repository. | repo_id (required), branch (default main) |
watch_directory | Watch a directory for file saves and git ref changes, triggering incremental re-indexing (debounced 500ms). Source saves create working_tree episodes within ~1s; commits/pulls/rebases create git_commit episodes anchored to the real commit time. Respects .gitignore and repo-root .memtraceignore. | path (required), repo_id (required), branch (default main) |
list_watched_paths | List all directories currently watched for live changes, with repo_id, branch, and watch start time. | none |
unwatch_directory | Stop watching a directory for file changes. | path (required) |
Workspace#
Worktree overlays and graph hygiene for multi-agent and multi-branch setups.
| Tool | Description | Key params |
|---|---|---|
list_worktrees | List worktree overlays known to Memtrace, one entry per repo_id:worktree_basename, with branch, path, file-diff count vs main, and recency. | repo_id (optional — omit to scan every repo) |
cleanup_worktrees | Sweep stale worktree overlays for a repo: directory missing, branch merged into main, or overlay older than MEMTRACE_OVERLAY_TTL_HOURS (default 168h). Idempotent; also runs automatically at the end of every index_directory call against a worktree path. | repo_id (required) |
cleanup_stale_records | Targeted scrub for orphan Node/Edge records from removed worktrees, files deleted while memtrace start was off, or branch checkouts. Scope by file_path_pattern substring and/or check_missing (stat every file_path against disk). | repo_id (required), file_path_pattern, check_missing, dry_run (default true — must pass false to mutate) |
cleanup_episodes | Delete episodes and their historical CodeNode/CodeEdge snapshots — use to reset a broken replay before re-running replay_history. HEAD-indexed nodes (current codebase snapshot) are never deleted, only historical replay snapshots. Marks the repo needs_replay=true afterward. | source_type (working_tree | git_commit | all), older_than, branch, repo_id, dry_run (default false) |
Diagnostics#
Read-only operator snapshots of the embed pipeline and process memory, plus one mutating reset.
| Tool | Description | Key params |
|---|---|---|
embed_diag | Single JSON snapshot of every gate the embed pipeline consults: memory pressure, circuit-breaker state, process RSS, host profile, and per-repo phase-2 embed results. Read-only. | none |
mem_diag | RAM-health snapshot attributing this process's resident memory to its subsystems per repo — prop index, edges, ANN vectors, record index, page cache, episodes, plus incremental live-graph mirror bytes. Estimates are attribution-grade, not allocator-exact. Read-only. | none |
embed_reset_breaker | Reset the embed-pipeline circuit breaker. Idempotent — resetting an already-closed breaker is a no-op. Flips a Tripped breaker back to Closed so the next embed batch can run without restarting the daemon. There is no CLI subcommand for this — reset via this tool, SIGUSR1, or a daemon restart. | session_id (optional, audit-log correlation only) |
Search & discovery#
Hybrid BM25 + semantic search, exact symbol lookup, bounded source reads, and repo skeleton maps.
| Tool | Description | Key params |
|---|---|---|
find_code | Hybrid BM25 full-text + semantic search fused with Reciprocal Rank Fusion, across natural-language queries and exact symbol names. Omit repo_id to search all indexed repos at once. Supports as_of time-travel and worktree overlay merging. | query (required), repo_id, limit (default 20), as_of, file_path, worktree, include_overlays, view (live | committed) |
find_symbol | Find a symbol by exact or fuzzy name match, faster than find_code when you know the identifier. Returns the symbol's location plus a precomputed blast-radius envelope (complexity_score, direct_callers, risk_level). | name (required), fuzzy, edit_distance (default 2), repo_id, kind, file_path, limit (default 10) |
get_source_window | Read a bounded, numbered source-code window. Defaults to 8 lines before / 24 after, max 120 returned lines (hard cap 400). mode controls compression: raw (default, verbatim), lightweight, aggressive, or map (signatures only). | file_path (required), repo_id, start_line, end_line, before_lines (default 8), after_lines (default 24), max_lines (default 120, cap 400), mode |
get_directory_tree | Compact, bounded directory tree built from Memtrace's File-kind graph nodes (not a raw filesystem walk), so it never surfaces dependencies or build artifacts that weren't indexed. mode: compact (default, collapses single-child chains), verbose, or map (adds a per-directory signature summary). | repo_id (required), max_depth (default 4, clamped 1-8), max_entries_per_dir (default 30, clamped 1-100), mode |
Relationships#
Graph traversal from a symbol's neighborhood to its full blast radius.
| Tool | Description | Key params |
|---|---|---|
analyze_relationships | Traverse the graph from a symbol via a query_type: find_callers, find_callees, class_hierarchy, overrides, imports, exporters, or type_usages. | target (required), query_type (required), repo_id (required), file_path, depth (default 3, max 10), branch |
get_symbol_context | A 360-degree view of a symbol's role in one call: direct callers, callees, type references, community membership, process membership, and cross-repo API callers. Use before modifying a symbol. | symbol (required), repo_id (required, comma-separated for multi-repo), branch, file_path, as_of, view, viewer_agent_id |
get_impact | Blast radius of changing a symbol — affected symbols by depth, an overall risk rating (Low/Medium/High/Critical), and affected files/processes. Call before any change. | target (required), repo_id (required, comma-separated), direction (upstream | downstream | both, default both), depth (default 5, max 15), branch, as_of |
preflight_check | Pre-flight check before editing a symbol: blast radius, process-flow membership, co-change partners, complexity, 30-day churn, and a generated verification checklist — in one call. | repo_id (required), symbol (required) |
Quality & review#
Dead-code and complexity analysis, style fingerprinting, session self-audit, and the deterministic diff-review workflow (AST detectors, YAML rule pack, cross-module graph checks, GitHub PR posting).
| Tool | Description | Key params |
|---|---|---|
find_dead_code | Functions/methods with zero callers — dead-code candidates. Excludes exported symbols, process entry points, and test files by default. | repo_id (required), branch, include_tests, limit (default 50), include_historical, as_of_micros |
calculate_cyclomatic_complexity | Approximate cyclomatic complexity for one function/method from call-graph out-degree. Risk levels: low (<5), medium (5-10), high (10-20), critical (>20). | target (required), repo_id (required), branch |
find_most_complex_functions | Top-N most complex functions/methods in a repository, ranked by call-graph out-degree. | repo_id (required), branch, top_n (default 20, max 100), kinds |
get_function_quality_metrics | Measured metrics for one named function: cyclomatic and cognitive complexity, parameter count, fanout, direct callers, outgoing calls, risk level, file location, scope path. | repo_id (required), function_name (required), branch, file_path, kind |
find_hotspots | Functions ranked by complexity × recent churn from bi-temporal version history — a complex function under active churn is where the next bug lives. | repo_id (required), window_days (default 14), top_n (default 20) |
get_style_fingerprint | Empirical style histograms for a repo (ternary vs if-else, arrow vs function declaration, const vs let, await vs .then, early return vs nested) plus dominant idioms. Descriptive, not prescriptive. Pass file_path for a per-file delta from the codebase norm. | repo_id (required), branch, file_path |
review_agent_sessions | Recent editing sessions clustered by actor and time gap, each judged clean / review / risky by net complexity added, riskiest function touched, and new symbols left behind. Self-audit after a task. | repo_id (required), window_hours |
find_ast_review_issues | AST-level review detectors against modified Python files in a unified diff: abstract_method_not_implemented (Critical), signature_changed_docstring_drift (Low), mutated_copy_original_returned (High), db_query_in_loop (Medium). No MemDB read path; Python-only. | diff (required), repo_root (required), base_sha_files |
find_yaml_rule_matches | Runs the bundled multi-language YAML rule pack (ast-grep/tree-sitter) against a diff — CSPRNG misuse, SQL string concat, TLS-verify disable, unsafe deserialization, ORM N+1, sync I/O in async, and more, across Python, TypeScript/JavaScript, Go, Java, Ruby, C#, Rust, Swift, Kotlin, Lua. | diff (required), repo_root (required), rules_dir, base_sha_files |
find_cross_module_issues | Cross-module graph review using callers/exports/inheritance/references to catch what single-file detectors cannot: import-not-found, caller signature drift, stale call sites after a rename, removed-symbol-still-referenced (Critical), interface method drift. Returns zero issues plus a _graph_state note when the graph is stale rather than guessing. | diff (required), repo_root (required), repo_id (required), base_sha_files, branch |
find_code_review_issues | Memtrace's full deterministic review workflow for a diff: combines AST detectors, the YAML rule pack, and optional cross-module graph review (when repo_id is set) under one confidence/ranking policy. review_mode strict keeps benchmark-safe high-precision findings only; online adds evidence-gated repo-convention and invariant-drift candidates. | diff (required), repo_root (required), repo_id, graph_mode, review_mode (strict | online), base_sha_files, rules_dir, max_candidates (default 20) |
review_github_pr | Reviews a GitHub PR with the local indexed workspace and, optionally, posts findings back to GitHub as the Memtrace Code Reviewer App. Fetches the diff via a short-lived GitHub App token minted by memtrace.io; source code itself is never sent to Memtrace SaaS. | pr_url (required), post (default false), watch, dry_run, max_comments, min_severity (default high), graph_mode (default strict), review_mode, repo_id, repo_root |
Temporal & evolution#
Bi-temporal history — what changed, when, in one episode or across a window — plus session-anchor catch-up and co-change coupling.
| Tool | Description | Key params |
|---|---|---|
replay_history | Re-run git history replay for an already-indexed repo without re-indexing HEAD or re-embedding. Doesn't re-parse HEAD source; writes per-symbol bi-temporal windows on top of existing HEAD records. | repo_id (required), days (omit for all reachable history) |
get_daily_briefing | Every function changed in a window (default 24h) with cyclomatic/cognitive complexity delta, new functions, new API endpoints, and per-module change distribution. | repo_id (required), window_hours (default 24) |
get_evolution | How the codebase changed between two points in time. mode: recent (default, per-episode adds/removes/modifies, paginated), compound (top-N changed files + touched symbols rolled up), summary (totals + first/last episode metadata; overview is an alias). Works across both git commits and uncommitted working-tree saves. | repo_id (required), from (required), to, mode (recent | compound | summary | overview), target, branch, kind, file_path, limit (default 100), cursor |
get_timeline | A single symbol's full version history across every episode — signature and content at each point, AST hash for structural-vs-whitespace change detection, active/deleted status. | repo_id (required), scope_path (required), file_path (required), branch |
detect_changes | Given changed file paths or a git diff, identify every affected symbol and its structural roles (community, process, blast radius) — beyond just file-level scope. | repo_id (required), diff, changed_files, as_of, branch |
get_changes_since | Session-anchor entry point for temporal memory: pass last_episode_id or last_reference_time to get only what changed since you last looked. Auto-selects overview for large windows, compound for focused ones, and returns a new session_anchor. | repo_id (required), since (required), until, branch |
get_cochange_context | Symbols that historically co-change with a target — same-commit coupling the static call graph cannot show. Complements get_impact (structural) with behavioral coupling. | repo_id (required), target (required), window_days (default 30), limit (default 10), as_of, branch |
get_episode_replay | Replay what one episode (a git commit or working-tree save) touched: nodes/edges added, modified, removed. mode graph_summary gives an algorithm-curated digest (top central symbols, communities, bridge symbols, top files) for sizing up a chunky commit before drilling in. | episode_id (or repo_id + branch + episode_index), compress (default true), symbol, kind, file_path, limit (default 200 per bucket), cursor, mode |
record_external_episode | Persist an externally-authored episode (e.g. from a fleet coordinator) onto the canonical timeline. source_type must start with agent_ or external_ — git_commit and working_tree are reserved for Memtrace’s own ingestion. | repo_id (required), source_type (required), source_id (required), reference_time, branch_name, parent_episode_id, sampling_tier, metadata |
Graph & architecture#
Cross-repo API topology, execution-flow tracing, community detection, and centrality algorithms over the whole-codebase graph.
| Tool | Description | Key params |
|---|---|---|
find_api_endpoints | List HTTP endpoints (APIEndpoint nodes) exposed by a service, auto-detected from Express, Encore, NestJS, Axum, FastAPI, Flask, Gin, Spring Boot, and more. Shows handler, method, path template, and cross-repo callers. | repo_id (required), method, path_contains, branch, limit (default 50) |
find_api_calls | List outbound HTTP calls (APICall nodes) made by a service — fetch, axios, callTypedAPI, useSWR, useQuery, reqwest, and similar patterns. Shows calling function, URL/path template, and which endpoint each call resolves to. | repo_id (required), method, path_contains, branch, limit (default 50) |
get_api_topology | Full cross-repo HTTP call topology across every indexed repository — which services call which, with matched route pairs and confidence scores. No repo_id required. | min_confidence (default 0.7), include_external, repo_id, include_endpoints (default true), include_calls (default true) |
link_repositories | Add a typed LINKED_TO edge between two indexed repositories — for cross-service relationships the HTTP linker cannot infer, such as a queue producer/consumer pair. | from_repo (required), to_repo (required), reason |
get_service_diagram | Generate a Mermaid graph LR service-dependency diagram from CROSS_REPO_HTTP_CALLS and API_CALLS edges, styling external third-party APIs with dashed borders. Returns null when no inter-service edges exist yet. | repo_id (optional filter) |
list_processes | List execution processes — BFS-traced call chains from entry points representing major flows (HTTP handlers, background jobs, CLI commands, event handlers, init sequences). | repo_id (required), branch, limit (default 50) |
get_process_flow | Trace every step of a named execution process from entry point through the full call chain, in order, with file/line and community membership per step. | process (required), repo_id (required), branch |
list_communities | List Louvain community clusters — groups of tightly-coupled symbols that correspond to bounded contexts or subsystems, even when the code doesn't label them that way. | repo_id (required), branch, min_size (default 3), limit (default 50) |
find_central_symbols | PageRank over the full graph, filtered to the requested repo/branch/kinds. Higher score = more transitive dependents — load-bearing code that deserves extra care during refactoring. Falls back to in-degree centrality if full computation is unavailable. | repo_id (required), branch, limit (default 25, max 100), kinds |
find_dependency_path | Shortest call/dependency path between two symbols — 'how does X connect to Y?'. | source (required), target (required), repo_id (required), branch, max_depth (default 20, max 20), edge_type |
find_bridge_symbols | Architectural chokepoints — symbols with high betweenness centrality sitting on many paths between otherwise disconnected parts of the codebase. A high bridge score with low PageRank is often an undocumented hidden dependency. | repo_id (required), branch, limit (default 25, max 100), kinds |
get_codebase_briefing | Compact structural briefing at session start: scale, modules, endpoint coverage, high-risk symbols, dead-code candidates, and next graph queries to run. detail_level summary (default) or full. | repo_id (omit to use MEMTRACE_DEFAULT_REPO), detail_level |
Fleet coordination#
In-process coordination for multiple agents sharing one repo and branch — typed intents, conflict classification, exclusive leases, escalation to a human, and a durable audit trail. None of these are billable.
| Tool | Description | Key params |
|---|---|---|
fleet_publish_intent | Announce a typed coordination intent before editing. Returns impact_preview (real blast radius of touched symbols), active_conflicts (overlapping live intents from other agents), and the registered intent_id. TTL 120s. | repo_id (required), agent_id (required), touched (required), intent (required, typed IntentKind JSON), assignment, branch |
fleet_status | Count of live (unexpired) intents in the registry — confirms coordination is active. | none |
fleet_branch_context | Bundled same-branch snapshot: your agent id, live peer intents, pending escalations, recent peer episodes. Call at session start and after idle periods. | repo_id (required), agent_id (required), branch |
fleet_preflight | Read-only “is the coast clear?” check before publishing an intent or committing an edit. Returns other agents' overlapping live intents and active exclusive leases, with no side effects. | repo_id (required), touched (required), agent_id, intent, branch |
fleet_record_episode | Record an edit episode and get its CRDT conflict class against live intents: A (additive/safe), B (touched-set overlap, re-read first), C (destructive overlap, defer or abandon). | repo_id (required), agent_id (required), touched (required), intent (required), metadata, branch |
fleet_get_node_state | Coordination rollup for a single symbol: recent touching episodes, active overlapping intents, dominant intent kind, conflict density score. | repo_id (required), node (required), branch |
fleet_query_episodes | List recorded coordination episodes, optionally scoped to a node and/or filtered by conflict_class (A|B|C) — use B/C as a conflict inbox. | repo_id (required), node, conflict_class |
fleet_acquire_lease | Request an exclusive lease on a set of symbols before a destructive edit. Returns state granted or requested (queued behind a higher-priority holder). Higher priority can preempt lower-priority holders. | repo_id (required), agent_id (required), scope (required), priority (default 0), ttl_seconds |
fleet_release_lease | Release a held lease by lease_id. The next queued requester for an overlapping scope, if any, is automatically granted. | lease_id (required) |
fleet_renew_lease | Extend a granted lease's expiry by ttl_seconds from now. Errors if the lease is not currently granted. | lease_id (required), ttl_seconds (required) |
fleet_get_episode | Fetch a single recorded coordination episode by episode_id. Returns found: false when unknown. | episode_id (required) |
fleet_list_escalations | List the per-repo "needs human" queue — Class C conflicts escalated for a human decision, newest first, with triggering episode, agent, touched symbols, and conflicting agents. | repo_id (required) |
fleet_resolve_escalation | Apply a human decision to a Class C escalation, recording the resolution and clearing it from the needs-human queue. | escalation_id (required), resolution (required), winner |
fleet_get_escalation | Poll a Class C escalation for the human decision. Pass your agent_id to get your_directive: wait, proceed, defer, or review. | escalation_id (required), agent_id |
fleet_submit_verdict | Submit a mediation verdict for a Class C conflict — reconcile, recommend (with winner + confidence), or defer_to_human. The daemon auto-applies on safe agent consensus, recommends for one-click human confirm, or escalates. | escalation_id (required), agent_id (required), verdict (required) |
fleet_ydoc_append | Leave a note on a symbol’s collaborative CRDT thread. kind: intent, edit, conflict, or resolution (default edit). | repo_id (required), symbol_id (required), agent_id (required), body (required), kind, episode_ref |
fleet_ydoc_read | Read a symbol's collaborative thread in append order. Omit symbol_id to read the whole repo's thread. | repo_id (required), symbol_id |
fleet_audit | Query the durable fleet audit trail (compliance layer): which engineer, via which agent product, did what and when — backed by append-only provenance records that survive forever, independent of the TTL’d live intents. | repo_id (required), branch, from, to, engineer, agent, agent_id, limit (default 500, max 5000), cursor |
Cortex decision memory (sidecar)#
A SEPARATE MCP SERVER, NOT PART OF THIS LIST
These five tools are not registered in memtrace mcp's own tool router — they belong to memcortex-mcp, a separate stdio MCP server that Memtrace spawns alongside the main daemon when Cortex is active. Your client connects to it independently. Cortex access itself is universal on every plan (no dev flag, no grant) since v0.8.3; see Cortex decision memory for activation details.
| Tool | Description | Key params |
|---|---|---|
recall_decision | Statistically-ranked decision recall for a free-text query over the Decision/Conversation lanes. An empty or unknown query yields an explicit CannotProve, never a fabricated answer. | query (required) |
get_arc | The episodic arc implementing a decision — episodes reachable by Produced/DerivedFrom edges. DeterministicallyDerived, or CannotProve when the decision is invisible or has no implementing episode. | decision_id (required) |
verify_intent | Did the decision hold across its arc? Returns Held, ViolatedAt, or CannotProve — a deterministically-defended verdict. | decision_id (required) |
why_is_this_here | A symbol's governing decision/conversation lineage (its Governs/Produced provenance). DeterministicallyDerived, or CannotProve for a symbol no decision produced. | symbol_id (required) |
governing_contracts | Contract nodes that constrain a symbol, or an honest CannotProve when none apply — never a false "no contracts" verdict. | symbol_id (required) |
GATING IN ONE PLACE
Billable: 37 of the 75 memtrace mcp tools consume the plan's query quota; the rest (indexing/watch lifecycle, all fleet_* tools, diagnostics, and plain metadata reads like list_indexed_repositories, get_repository_stats, get_directory_tree) are never metered. The teams plan is unmetered.
Cortex tools absent when the sidecar is missing: the five decision-memory tools above only exist if memcortex-mcp started successfully. Any sidecar spawn/connect failure degrades to a warning and never blocks the core memtrace mcp server — the other 75 tools keep working either way.