syncable-dev 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. Uselimit: 20, neverlimit: "20". Passing a string yieldsMCP 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
pathto the project root (absolute path) - Set
incremental: trueif re-indexing after changes - Set
clear_existing: trueonly 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:
{ "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).