syncable-dev/memtrace-index

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.

Full parameter spec for every Memtrace tool: references/mcp-parameters.md (bundled at the memtrace-skills plugin root).

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

If the selected path is just a folder containing multiple independent git repos, do not index that parent folder unless the user explicitly wants a shared workspace. For separate repos, index each repo root separately. For intentional sharing, ask the user to bless the parent explicitly with memtrace start --bless-workspace first, then verify the boundary with memtrace workspace status <path>.

Success criteria: You receive a job_id immediately.

3. Poll for completion

Use check_job_status with the job_id every 2–3 seconds. The loop must never run unbounded — hard cap at ~100 polls (~5 minutes). On hitting the cap: stop polling, report the job_id and last observed status to the user, and tell them the job keeps running server-side — they (or you, later) can resume with check_job_status on that job_id or find it via list_jobs.

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, but respect the poll cap: stop, report job_id + last status, resume later via check_job_status / list_jobs. For monorepos, index subdirectories separately | | Already indexed | Use incremental: true to update, or skip indexing entirely |

Output

index_directory returns a job handle immediately; check_job_status tracks it to a terminal state:

json
{ "job_id": "6f9a2c1e-...-uuid" }
{ "status": "completed" }

While running, the job advances through the pipeline stages listed in step 3; status = "failed" carries an error message. The final user-facing report (confirmed via list_indexed_repositories) covers: repo_id, languages detected, total symbols, total relationships (node/edge counts).