Skip to content

tools.md

Latest commit

 

History

History
415 lines (287 loc) · 12.3 KB

tools.md

File metadata and controls

415 lines (287 loc) · 12.3 KB

Tool catalogue

You don't call these tools. Your agent does, automatically, when you ask it questions in plain English. This page is a reference — for understanding what Memtrace has under the hood, debugging when something looks off, or for people building integrations on top (orchestrators, custom MCP proxies, alternative agent skills).

If you're a regular user wondering "how do I use Memtrace", workflows.md is the page you want — it's framed around the kinds of questions you'd actually type, not tool names.

The complete list of MCP tools an agent gains when Memtrace is wired in. Grouped by what you'd reach for them for.

All tool names are the literal strings your agent sees — for example mcp__memtrace__find_symbol. Argument types are JSON; integer args must be JSON numbers (not quoted strings), and required args are called out per tool.

If your agent isn't using these automatically, check troubleshooting.md.

Index management

list_indexed_repositories

No arguments. Returns every repo currently in the graph along with basic stats. Always call this first to discover valid repo_id values.

index_directory

Index a new repository or re-index an existing one.

Arg Type Required Notes
path string yes Absolute path to the repo root.
incremental boolean no (default true) False = re-parse everything. True = only changed files.
clear_existing boolean no (default false) True = drop existing graph for this repo before indexing.

Returns a job_id. Indexing runs asynchronously — poll check_job_status(job_id) for progress.

delete_repository

Permanently remove a repo's graph data.

Arg Type Required
repo_id string yes

Wipes nodes, edges, episodes, and embeddings. The on-disk .memdb/ for that repo shrinks immediately. Source files are not touched.

cleanup_stale_records

Targeted scrub for orphan records — useful when files were deleted while the daemon was off, when an agent worktree was removed, or when a branch checkout left old paths resolvable. Two scopes:

Arg Type Required Notes
repo_id string yes Required to scope the cleanup.
file_path_pattern string no Substring filter — delete records whose file_path contains this.
check_missing boolean no (default false) If true, also delete records whose file_path doesn't exist on disk.
dry_run boolean no (default true) Counts what would be deleted; pass false to actually mutate.

Returns scanned record count, matched paths, would-delete counts, actually-deleted counts (zero in dry-run), and a sample of paths.

check_job_status

Arg Type Required
job_id string yes

Returns progress + state for an async job (indexing, replay).

list_jobs

No arguments. Returns recent and active jobs.

Discovery

find_symbol

Exact / fuzzy lookup by symbol name. Sub-millisecond.

Arg Type Required Notes
name string yes The symbol name.
repo_id string no Restrict to one repo.
fuzzy boolean no (default false) Levenshtein-tolerant.
limit integer no (default 10)

Returns {file_path, start_line, end_line, kind, name, scope_path} per match.

find_code

Hybrid retrieval (BM25 + vector + graph + cross-encoder rerank). Best for natural-language queries and concept search.

Arg Type Required Notes
query string yes Free-form description, identifier, or string fragment.
repo_id string no Restrict to one repo.
limit integer no (default 10)
file_path_filter string no Restrict to files whose path contains this substring.

Strong on identifier-like queries and on string literals / error messages baked into function bodies. The semantic side embeds the first ~1500 chars of every Function / Method / Class body, so things like find_code("STRIPE_KEY_FOO_BAR") find the function that uses the constant — no grep needed.

get_symbol_context

Full picture of a symbol — callers, callees, community, processes, recent changes. The agent's go-to "tell me about X" tool.

Arg Type Required
name or id string one of these
repo_id string no

Returns the symbol's metadata, its callers and callees with file:line, the community / module it belongs to, the processes it participates in, and a short evolution summary.

get_source_window

Read a specific span of a file with surrounding context. Cheaper than reading the whole file when you only need a few lines.

Arg Type Required
file_path string yes
start_line integer yes
end_line integer yes
context_before integer no (default 3)
context_after integer no (default 5)
repo_id string no

Returns the requested window plus N lines of context on each side.

Impact + dependencies

get_impact

Blast radius of changing a symbol. Returns transitive callers + the symbols that would be affected.

Arg Type Required
name or id string one of these
depth integer no (default 2)
repo_id string no

Critical before any non-trivial refactor.

find_dependency_path

Show how two symbols relate in the call graph.

Arg Type Required
from string (symbol id or name) yes
to string (symbol id or name) yes
max_depth integer no (default 5)
repo_id string no

analyze_relationships

Bulk relationship analysis — for each input symbol, returns its direct callers, callees, and structural neighbours.

Architecture overview

list_communities

Louvain-detected modules — clusters of tightly-coupled symbols. Useful as a starting point when onboarding to a new codebase.

find_central_symbols

PageRank-ranked "important" symbols. The functions / classes most other code depends on.

Arg Type Required
repo_id string no
limit integer no (default 20)

find_bridge_symbols

Symbols with high betweenness centrality — the chokepoints. Touching these has outsized blast radius.

get_codebase_briefing

A short prose summary of the indexed repo: what it does, key modules, important symbols. Good "first-look" tool.

get_repository_stats

Headline numbers — file count, symbol count, edge count, language distribution.

Time travel

get_evolution

How a symbol or file evolved over time. Six modes:

Arg Type Required
symbol or file_path string one of these
from string (relative date or ISO) no
to string no
mode string no — one of recent (default), impact, novelty, directional, compound, overview

get_timeline

Bi-temporal version history of a symbol. Returns every version with valid_from / valid_to timestamps tied to commits or working-tree saves.

get_changes_since

What changed in the indexed repo between from and to dates.

detect_changes

Given a git diff, classify which symbols are affected and how.

get_cochange_context

Files / symbols that historically change together. Surfaces hidden coupling.

get_episode_replay

Replay a specific commit or working-tree episode — see exactly what the graph looked like at that moment.

replay_history

Re-run history replay on an already-indexed repo. Useful after a bad replay or to apply a different time window.

Arg Type Required
repo_id string yes
days integer no
clear_existing boolean no

cleanup_episodes

Delete episodes + their historical snapshots. Run before replay_history if you want to redo replay from scratch.

Processes + flows

list_processes

Named execution pipelines through the call graph (e.g. "user signup flow", "payment processing"). Auto-detected from entry points.

get_process_flow

Step-by-step execution path for a named process. Critical when tracing a request through a service.

Arg Type Required
process_name string yes
repo_id string no

API topology

find_api_endpoints

HTTP endpoints exposed by the indexed services — Express, Encore, NestJS, Axum, FastAPI, Flask, Gin, Spring Boot, and friends. Returns method + path + handler + request shape.

Arg Type Required
repo_id string no
path_filter string no — substring filter

find_api_calls

Where a given endpoint is called from — including across-repo HTTP calls if you've indexed both ends.

get_api_topology

Cross-service call graph. If you've indexed multiple repos, returns the full directed graph of which services call which endpoints on which others.

get_service_diagram

Mermaid-flavoured diagram of the cross-service topology. Paste into your docs.

Quality

find_dead_code

Symbols with zero callers. Refactoring candidates.

Arg Type Required
repo_id string no
min_size integer no (default 10 lines)

calculate_cyclomatic_complexity

Cyclomatic complexity per symbol.

find_most_complex_functions

Top-N functions by complexity score.

Arg Type Required
repo_id string no
limit integer no (default 20)

Watching + uncommitted changes

watch_directory

Tell the daemon to watch a path for changes. Edits create working_tree episodes — your in-progress code becomes queryable within ~1 second of saving.

unwatch_directory

Reverse of the above.

list_watched_paths

What's currently being watched.

record_external_episode

For non-file-watcher integrations — record a manually-supplied episode (e.g. a CI run, a deploy event) into the bi-temporal history.

Common tool-call sequences (agent-level, FYI)

These are the typical sequences a well-configured agent runs to answer a given user question. Useful if you're building an integration / custom skill / orchestrator and want to understand the agent's expected behaviour. Regular users never see these.

When the user asks "Tell me about X" the agent typically runs:

  1. find_symbol(name="X") or find_code(query="X") to locate it.
  2. get_symbol_context(id=<id from step 1>) for callers, callees, community.
  3. get_source_window(file_path, start_line, end_line) only if it needs to quote the body.

When the user asks "What breaks if I change X?":

  1. find_symbol(name="X") to locate.
  2. get_impact(id=<id>, depth=3) for blast radius.
  3. get_evolution(name="X", mode="recent") to check if X is volatile — recent churn often predicts more callers landing soon.

When the user asks "Why does X look this way?":

  1. find_symbol(name="X").
  2. get_evolution(name="X", from=<long ago>, mode="compound") for the evolution history.
  3. get_episode_replay(episode_id=<one from above>) to see the exact graph state at a suspicious revision.

When the user asks "Where's the handler for /users/:id?":

  1. find_api_endpoints(path_filter="/users").
  2. find_api_calls(endpoint=<found>) for call sites — including cross-repo if multiple services are indexed.

When the user asks "What's the architecture of this codebase?":

  1. list_indexed_repositories().
  2. list_communities(repo_id=<R>) for the major modules.
  3. find_central_symbols(repo_id=<R>, limit=20) for the most-depended-on symbols.
  4. list_processes(repo_id=<R>) for named flows.
  5. get_service_diagram() for cross-repo systems.

Parameter type rules

The MCP server is strictly typed. Pass JSON numbers for integer args (not quoted strings), JSON booleans for booleans, and JSON strings for strings.

Right Wrong
limit: 20 limit: "20" — fails with invalid type: string "20", expected usize
fuzzy: true fuzzy: "true"
repo_id: "my-repo" repo_id: my-repo (unquoted)

What this catalogue isn't

This document is the agent-facing API. There are also a handful of CLI subcommands (memtrace status, memtrace reset, etc.) that humans run from the terminal — those are listed in getting-started.md.