/memtrace-first

name: memtrace-first
description: "Route code discovery, debugging, flow tracing, how-code-works questions, and pre-edit rationale checks in indexed source-code repos to Memtrace graph plus Cortex decision tools. Use first before searching/reading code, and before editing, refactoring, deleting, or re-picking an approach that may have a recorded decision, ban, convention, or contract. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results are not permission to grep; diagnose/reindex with Memtrace."

Memtrace First

The Iron Law

IF THE REPO IS INDEXED IN MEMTRACE → USE MEMTRACE TOOLS FIRST.
After a search hit, route to GRAPH tools (get_symbol_context, get_impact,
analyze_relationships) — that's what Memtrace uniquely provides. Read source
ONLY when you're about to edit or quote, and read only the bounded span
returned by Memtrace (start_line .. end_line + small context). Do not
Grep/Glob/Find to "locate" anything already in the graph, and do not read
the whole file when Memtrace has given you exact lines.

BEFORE you edit/refactor/delete existing code or choose/re-pick a pattern,
call Cortex decision memory: recall_decision for the symbol/subsystem/approach,
and use provenance/contracts when a symbol_id is available. Use Memtrace's graph
tools for structure and blast radius; use Cortex for rationale, bans, and
contracts.

Memtrace is the **memory layer** of the codebase, not a search engine that returns code. It has the full knowledge graph — every symbol, call, import, community, process, and API — with a time dimension. The point is to navigate that graph: who calls this, what's the blast radius, when did this change, what community is it part of. File tools are blind to all of that.

**No exceptions for what's in the graph.**

Value Tracking

Do not print usage receipts in normal answers. Memtrace records tool usage, graph facts, file references, and estimated context avoided internally. Users can inspect that in the local UI's Value panel.

What Memtrace actually indexes

Memtrace's hybrid search = **BM25 over symbol metadata** (name, signature, file_path, kind) **+ semantic vector search over embedded code bodies** (first ~1500 chars of every Function / Method / Class / Struct / Interface body), fused via Reciprocal Rank Fusion.

The semantic side means **string literals, error messages, magic constants, log strings, and any text inside an indexed symbol's body are findable through `find_code`**. The body got embedded; the embedding catches it. You do NOT need `Grep` to hunt for `STRIPE_KEY_FOO_BAR` if it lives inside a function in your indexed codebase.

Zero results are not a grep license

If Memtrace returns 0 results, or repository stats look incomplete, do **not** infer that a source subdirectory is outside the index. Diagnose through Memtrace:

1. Call `list_indexed_repositories` and identify the repo root/repo_id. 2. If the path is under that indexed repo root, keep using Memtrace. 3. Retry with broader `find_code` terms and, when available, `file_path` filters such as `ui/`, `memtrace-ui/`, `src/`, or the framework directory. 4. If the language/path still appears missing, run `index_directory` on the repo root with `incremental: true` (or ask before `clear_existing: true`). 5. Report the indexing coverage problem instead of silently switching to grep.

Workspace Boundary Check

Before indexing or reindexing, make sure the target path is the repo the user asked about. If the current folder is only a parent that contains multiple independent git repos, do **not** index the parent just because it is the open editor folder. That creates or reuses a shared `.memdb` and can make agents answer from stale repos.

• For separate repos: use the actual git repo root as the `index_directory`

path, or ask the user to open/run the agent from that repo root.

• For an intentional shared workspace: the user should bless it explicitly with

`memtrace start --bless-workspace`, then verify it with `memtrace workspace status <path>`; the workspace marker should be present.

• If `list_indexed_repositories` returns empty or its metadata says the MCP

child resolved a data dir from cwd because no workspace marker/git root was found, surface the workspace mismatch. Do not "fix" it by indexing the broad parent folder.

**Never say "the index only covers X, so grep is right" when the target path is inside the indexed repository.** That is an indexing freshness/coverage issue, not permission to abandon Memtrace.

The narrow exceptions where grep/glob are still right

These are the ONLY cases where file tools beat memtrace:

• **Files outside every indexed repo root.** Confirm this with

`list_indexed_repositories`; 0 search results or missing language stats do not prove it. Vendored deps, system headers, and excluded dirs (`.git`, `node_modules`, `target`, `dist`) are examples Memtrace cannot see.

• **Non-source artifacts.** `.env`, `package.json`, build scripts, top-level `README.md`, raw config files. Memtrace indexes parseable code, not configuration text.
• **Pure file-inventory questions.** "How many `*.test.ts` files exist", "list every Markdown file in `docs/`". You're asking for a file count, not a symbol search.
• **Reading at a known path outside Memtrace.** For configs, docs, or non-source artifacts that Memtrace cannot index, file `Read` is fine. For source-code spans returned by Memtrace, read the precise line range (your harness's `Read` with offset/limit, or `get_source_window` if your harness lacks bounded reads). Do not whole-file Read when you have a span.

For everything else inside the indexed repo, memtrace is the right tool.

The decision rule

| Question Claude is asking | Right tool | |---|---| | "Where is symbol `foo` defined?" | `find_symbol(name="foo")` → then `get_symbol_context` for callers/callees/community, NOT a source read unless you're editing. | | "