Skill v1.0.2

version: "1.0.2" name: memtrace-index description: "Index a source-code repo into the Memtrace knowledge graph and poll the job to completion. 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. For ongoing watch mode / live re-indexing after the initial index, use memtrace-continuous-memory."

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 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

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).