| name | memtrace-index |
| description | Always use when the user asks to index, parse, ingest, reindex, watch, or prepare a source-code repo for Memtrace analysis, when code exploration needs an index, or when searches return 0/partial results for source paths under an indexed root. Use this before Grep, Glob, rg, find, or manual code search whenever the repo can be indexed. |
Overview
Index a local codebase into the persistent code knowledge graph. This is always the first step — it parses every source file, resolves cross-file relationships, detects API endpoints/calls, runs community detection and process tracing, and embeds all symbols for semantic search.
Quick Reference
| Parameter | Purpose |
|---|
path | Absolute path to the directory to index |
incremental | Only re-parse changed files (use for subsequent runs) |
clear_existing | Wipe and rebuild from scratch |
Parameter types: MCP parameters are strictly typed. Numbers (limit, depth, min_size, last_n, etc.) must be JSON numbers — not strings. Use limit: 20, never limit: "20". Passing a string yields MCP error -32602: invalid type: string, expected usize.
Steps
1. Check if already indexed
Use the list_indexed_repositories MCP tool first. If the repo is already indexed and recent, skip to step 4.
Success criteria: You have a list of repo_ids and their last-indexed timestamps.
If a repo is present but searches miss a source subdirectory under that repo
root (for example ui/, memtrace-ui/, web/, frontend/, or src/), treat
that as a stale/partial index. Do not use grep as a workaround. Run incremental
indexing on the repo root, then retry the Memtrace query.
2. Index the directory
Use the index_directory MCP tool:
- Set
path to the project root (absolute path)
- Set
incremental: true if re-indexing after changes
- Set
clear_existing: true only if a full rebuild is needed
Success criteria: You receive a job_id immediately.
3. Poll for completion
Use check_job_status with the job_id every 2–3 seconds.
Pipeline stages in order: scan → parse → resolve → communities → processes → persist → embeddings → api_detect → done
Wait until status = "completed". If status = "failed", report the error message to the user.
4. Report to user
After indexing completes, call list_indexed_repositories to confirm the repo appears with correct node/edge counts. Report: repo_id, languages detected, total symbols, total relationships.
Save the repo_id — most other memtrace tools require it.
Error Handling
| Error | Action |
|---|
| Path does not exist | Ask user to verify the absolute path |
| Job status "failed" | Report the error message; suggest clear_existing: true for a fresh rebuild |
| Timeout (job running > 5 min) | Large repos are normal; keep polling. For monorepos, index subdirectories separately |
| Already indexed | Use incremental: true to update, or skip indexing entirely |
