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 is proxied through the main server), see MCP overview first.
memtrace mcp registers 90 tools: 81 core graph/runtime tools, three hosted-docs tools, and the six Cortex decision-memory tools below. Of the core 81, 38 are billable — they consume your plan's query quota; Cortex retrievals use the Cortex usage meter. The tables below don't mark billing status per row — see the closing callout for the category-level rules. On quota exhaustion a metered 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 | Five node counts (see the field reference below), node counts by kind, total edges, community count, episode count, last-indexed timestamp, plus indexing_incomplete, stats_source, and a scope_hint diagnosis when the branch-scoped scan diverges from what the repository record claims. | repo_id (required), branch (default: the repository's primary indexed branch — the one list_indexed_repositories reports) |
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) |
get_repository_stats result fields#
get_repository_stats reports five node counts that answer different questions — comparing them is how the tool distinguishes "small repository" from "partial index" from "wrong branch scope". When branch is omitted, stats cover the repository's primary indexed branch — the branch on the newest repository record, the same one list_indexed_repositories reports — not whatever branch the local checkout happens to be on.
| Field | What it counts |
|---|---|
total_nodes | Deduplicated logical graph nodes visible in the selected branch scope. The headline size — compare with the nodes count from list_indexed_repositories. |
queryable_node_count | Raw live rows the scan matched before deduplication. Always ≥ total_nodes; temporal re-index copies inflate it. |
indexed_node_count | The node count the last index run claimed on the repository summary record. Written by the indexer at index time, not a live scan — so it can disagree with the counts above. |
typed_node_count | Logical nodes with a recognized kind — everything that appears in nodes_by_kind. |
symbol_node_count | The subset of typed nodes that are code symbols (Function, Method, Class, …). |
indexing_incomplete | true when the scan shape looks partial: a populated scan with zero symbols and mostly untyped rows, or total_nodes below 80% of an indexed_node_count of at least 20. |
stats_source | How rows were admitted to the scan: branch_scoped_scan (exact branch match), branch_lineage_scan (a near-empty exact scan was re-admitted through recorded branch ancestry — the same visibility get_impact and the graph use), or unscoped_scan (no branch resolved; counts cover all branches). |
scope_hint | Present only when the scan stays nearly empty while the repository record claims a large index. Explains the divergence: live store-wide node/edge counts, the primary indexed branch, the branches actually observed in scope, and a likely_cause. |
READ SCOPE_HINT BEFORE RE-INDEXING
scope_hint.likely_cause has two values. branch_scope_mismatch means the data exists under another branch — the graph is intact, the scope is wrong; re-run with the branch named in primary_indexed_branch or observed_branches_in_scope, and do not re-index. stale_or_partially_written_repository_record means the store itself holds far fewer live rows than the record claims — the record is stale or an index run never finished; if get_impact, find_symbol, and list_indexed_repositories still return healthy results, trust them over the record, otherwise re-index. Never treat total_edges: 0 as a failed index while scope_hint is present.
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. Four scopes: file_path_pattern (substring), check_missing (stat every file_path against disk), check_stale_spans (files that still exist but hold a symbol whose start line is past the end of the file — the case check_missing cannot reach), and dedup_drifted_node_ids (duplicate rows minted for one symbol identity). A pattern supplied alone selects every matching record; combined with any other scope it is a boundary instead — the other scopes can only delete records whose file_path contains it, a pattern match alone selects nothing, and a pattern matching zero paths deletes zero records. The response echoes the role the pattern played in scope.pattern_role (selector | boundary). | repo_id (required), file_path_pattern, check_missing, check_stale_spans, dedup_drifted_node_ids, 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, the store-wide query audit export, 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 |
export_query_audit | Export the store-wide query audit log: who ran which tool against which repository, when, whether it succeeded, and how long it took — every MCP tool call, unlike fleet_audit, which records fleet coordination events only. Off by default: set MEMTRACE_QUERY_AUDIT=1 and restart to record access. When off it returns enabled: false rather than an error — an auditor asking an un-instrumented store deserves “this store keeps no record” as a finding, not a malfunction. Tool arguments are deliberately not recorded, so the audit log never becomes a second copy of your source. | from, to (same formats as get_evolution; default: now), limit (default 500, newest first, capped server-side) |
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 |
find_code result fields: start_line and end_line#
Each compact find_code result points at a source span. Line numbers are 1-based and inclusive: a result with start_line: 40 and end_line: 49 covers ten lines, and both boundary lines are part of the result.
| Field | Exact contract |
|---|---|
start_line | First line of the source window the caller should read now. 1-based and inclusive. |
end_line | Last line of that source window. 1-based and inclusive. |
symbol_start_line | Optional first line of the complete symbol when the default line budget narrowed a long symbol to a smaller match window. |
symbol_end_line | Optional inclusive last line of the complete symbol. It is paired with symbol_start_line. |
scope_path | Optional containing scope when the result name alone would be ambiguous. |
find_code result
{ "name": "handleRequest", "kind": "Function", "file_path": "src/server.ts", "start_line": 140, "end_line": 149, "symbol_start_line": 100, "symbol_end_line": 159, "scope_path": "ApiServer::handleRequest" }
In this example the full function spans lines 100–159, but find_code returned the ten-line window 140–149 around the match. Pass file_path, start_line, and end_line to get_source_window for a bounded read. Use the symbol_* fields only when you deliberately need the whole function.
THE FULL-SPAN FIELDS ARE OPTIONAL
Short symbols are returned without windowing, so start_line/end_line already describe the complete symbol and the symbol_start_line/symbol_end_line fields can be absent.
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. When the symbol resolves but no edges are found, the response carries edges_conclusive: false and a zero_means note — count: 0 is not proof the symbol is unused, and must not be read as one before deleting or changing it. | 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, exact-duplication, 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 |
find_duplicate_code | Functions/methods whose normalized body is an exact copy of another symbol's — same body shape, same kind, same parameter count, above a minimum body size so shared ceremony (constructors, one-line wrappers) doesn't register. Findings are live code, not dead code: extract a shared implementation, don't delete. Each finding cites the earliest declaration as the original. When branch is omitted, the repository's current branch is used; an explicit branch that matches no indexed function records is an error, never a silent unscoped scan. See Quality & review for the full contract. | repo_id (required), branch, include_tests (default false), limit (default 20, max 200), 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 named milestone anchors, 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 or from_anchor (one required; the anchor wins when both are set), to / to_anchor (default: now), mode (recent | compound | summary | overview), target, branch, kind, file_path, limit (default 100), cursor |
create_anchor | Bind a name to an instant — release-1.4, audit-2026Q3, test-cycle-7 — so change reports can be addressed by milestone instead of by timestamp. Pass the name to get_evolution (from_anchor / to_anchor) to diff the graph between two named states: release-to-release change reports, “what changed since the last QA pass”, compliance snapshots. Re-creating an existing name moves the anchor — a re-cut release is the common case — and names normalize to a lowercase slug, so Release-1.4 and release 1.4 are the same anchor. | name (required), repo_id (required), at (same formats as get_evolution; default: now), commit_sha, note |
list_anchors | List the named milestone anchors recorded for a repository, newest instant first, with instant, commit, and note. Use it to discover what baselines exist before calling get_evolution with from_anchor. | repo_id (omit to list across every repository) |
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 — plus operator-recorded links and externally contributed graph structure.
| 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 |
link_symbols | Record a typed relationship between two indexed symbols in different (or the same) repositories — the symbol-level counterpart to link_repositories, for the seams the cross-repo HTTP linker cannot infer: queue producer/consumer pairs, gRPC client/server methods, batch handoffs, shared schemas. An ambiguous symbol name is refused, never guessed — disambiguate with from_file_path / to_file_path. The edge is walked by get_impact in both directions and carries provenance link_symbols, so an operator assertion is always distinguishable from a parser-derived fact. | from_repo, from_symbol, to_repo, to_symbol, edge_kind (all required; conventionally calls, consumes, implements, produces, replaces, shares_schema — free-form accepted, normalized to lowercase snake_case), reason, from_file_path, to_file_path |
ingest_graph_fragment | Contribute nodes and edges Memtrace's own parsers cannot produce — generated code (protobuf / OpenAPI stubs), in-house DSLs, IaC beyond HCL, build-graph output — the symbol-and-edge counterpart to record_external_episode. Every record is stamped with your provenance (the producing tool, which may not impersonate Memtrace's own ingestion) and surfaced as contributed in find_symbol and get_symbol_context, so contributed facts always stay distinguishable from parsed ones. Re-running a generator rewrites the same rows instead of duplicating them; an ambiguous edge endpoint is reported in edges_unresolved, never guessed; validation reports every problem in one pass, so a large batch needs one round-trip to fix. | repo_id (required), provenance (required), nodes, edges, branch (default main) |
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#
PROXIED THROUGH MEMTRACE MCP
These six tools are registered in memtrace mcp's tool router. That server forwards calls to the local Cortex sidecar started by memtrace start. Your client must not connect to memcortex-mcp independently or pass it a store path. Use the same command="memtrace", args=["mcp"] entry as every other Memtrace tool. Cortex access is universal on every plan (no dev flag, no grant); see Cortex decision memory for activation and recovery 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) |
governing_rules | The in-force governance rules for a file path. Use this when you have a repo_id and a file path — which is what every Memtrace search result gives you — rather than a Cortex symbol id. | repo_id (required), file_path (required, absolute or repo-relative) |
GATING IN ONE PLACE
Billable: 38 of the 81 core graph/runtime tools consume the plan's query quota; the rest of that core set (indexing/watch lifecycle, all fleet_* tools, diagnostics, and plain metadata reads like list_indexed_repositories, get_repository_stats, get_directory_tree) are never metered. Cortex retrievals use the Cortex meter. The teams plan is unmetered.
Cortex unavailable when the sidecar is missing: the six schemas remain in tools/list, but calls return a clear unavailable result when the local Cortex endpoint cannot answer. A sidecar spawn/connect failure never blocks the core memtrace mcp server — the other 84 tools keep working either way.