memtrace-skills 1.2.6 → 1.2.8

package/plugins/memtrace-skills/skills/memtrace-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-search
-description: "Find source code with Memtrace hybrid BM25+semantic search: symbols, functions, classes, types, constants, definitions, implementations, logic, or error strings inside code. Use when the user wants to find, search, locate, or look up code or asks where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery. If Memtrace returns 0 results, broaden the Memtrace query and diagnose/reindex; do not switch to grep."
+description: "Find source code with Memtrace hybrid BM25+semantic search: symbols, functions, classes, types, constants, definitions, implementations, logic, or error strings inside code. Use when the user wants to find, search, locate, or look up code or asks where code lives. Use Memtrace first; after a diagnosed miss and one targeted retry, allow bounded source verification or fallback. Reindex only for evidence of stale or incomplete coverage."
 ---
 
 ## Overview
@@ -22,11 +22,13 @@ Find code using hybrid BM25 + semantic search (RRF). Primary discovery tool —
 | Param | Required | Default | Notes |
 |---|---|---|---|
 | `query` | yes | — | Natural language or symbol text |
-| `repo_id` | no | all repos | |
+| `repo_id` | no | this store's members | Safe scope inference: omitted, an unambiguous session resolves to its own repository; a multi-repo store fans out across its discovered members |
 | `limit` | no | 20 | Max 100 |
 | `file_path` | no | — | Path/directory substring filter |
 | `as_of` | no | now | ISO-8601 time-travel |
 | `include_diagnostics` | no | false | Set true for `id`, `score` in results |
+| `include_dependency_checks` | no | true | With diagnostics, set false for scores without pre-edit risk checks |
+| `include_context` | no | auto | Query-matched processes, communities and selected callers/callees; auto on for concept queries, off for identifiers |
 
 **No `kind` param on `find_code`** — use `find_symbol(kind=...)` to filter by symbol type.
 
@@ -39,7 +41,7 @@ Find code using hybrid BM25 + semantic search (RRF). Primary discovery tool —
 | Param | Required | Default | Notes |
 |---|---|---|---|
 | `name` | yes | — | Symbol name to search |
-| `repo_id` | no | all repos | |
+| `repo_id` | no | inferred | Safe scope inference: one repository is inferred only when that is unambiguous; otherwise the call returns `repo_scope_required` |
 | `fuzzy` | no | false | API field exists; currently exact-match in backend |
 | `edit_distance` | no | 2 | Only when fuzzy enabled |
 | `kind` | no | — | `Function`, `Class`, `Method`, etc. |
@@ -58,15 +60,33 @@ Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bun
 
 - Exact name → `find_symbol`
 - Behaviour description → `find_code`
-- All repos → omit `repo_id`
+- Every member of this store → omit `repo_id` on `find_code`. `find_symbol` needs one repository and infers it only when that is unambiguous.
 
 ### 2. Execute search
 
 Result shape: see [Output](#output) below.
 
-### 3. Hand off to graph tools
+### 3. Inspect query context, then expand if needed
 
-Save **`name`**, **`scope_path`**, and **`file_path`** — **not** internal IDs:
+Concept searches include a bounded `context` object. Its process matches and
+community members reference the primary `results` by one-based number. Inspect
+these and the selected callers/callees before making another graph call.
+Use `include_context: true` for identifier context, or `false` for flat results.
+Check `status`, `incomplete_reasons`, `coverage` and `payload_truncated`: omitted
+relationships are not proof of absence. The context contains selected matches,
+not a complete process trace. Worktree overlays report context unavailable until
+their graph is refreshed.
+
+For a code change, inspect the relevant caller/callee contracts before editing.
+`context.next_calls` supplies valid tool names and arguments for the selected
+symbol and flow; use these directly when they address the investigation.
+They preserve repository, branch and file disambiguation. Process navigation
+uses the returned process UUID. Symbol navigation uses name plus file path.
+Expand only the evidence needed; an empty sampled process list does not mean
+the symbol has no callers or callees.
+
+For symbol navigation, save **`name`**, **`scope_path`**, and **`file_path`**.
+For process navigation, retain its **process `id`**:
 
 ```json
 { "repo_id": "memdb", "symbol": "validateToken" }
@@ -74,12 +94,12 @@ Save **`name`**, **`scope_path`**, and **`file_path`** — **not** internal IDs:
 { "repo_id": "memdb", "target": "validateToken", "query_type": "find_callers" }
 ```
 
-Read source only when editing — bounded `Read(offset, limit)` at returned lines.
+Read source when verifying behavior, editing or quoting — bounded `Read(offset, limit)` at returned lines.
 
 ### Multi-word queries
 
 1. Try verbatim `find_code` query.
-2. If weak, fan out: camelCase, snake_case, domain identifiers.
+2. If weak, make one targeted reformulation with an identifier or path hint.
 3. Dedupe top hits by `file_path:start_line`.
 
 ## Output
@@ -98,6 +118,23 @@ One `find_code` / `find_symbol` result entry:
 
 `score` (and `id`) appear only with `include_diagnostics: true`.
 
+## A `repo_id` this store does not hold
+
+`find_code` and `find_symbol` check membership before they search. If the
+`repo_id` you passed is not a member of this session's store, the call is
+handed to the live runtime whose store declares it, and the answer comes back
+marked `_meta.answered_by: "store_owner_daemon"` with `_meta.owner_pid`,
+`_meta.owner_http` and `_meta.store`. Use that answer and say which store
+produced it.
+
+If no live runtime holds the repository, or its owner cannot answer, you get
+a refusal instead: `repo_in_store: false`, `error_code: "repo_not_in_store"`,
+`count: 0`, and a `diagnostic` naming this store, its `members` and — when it
+is known — `repo_lives_in`. Nothing was searched. Do not read that as an
+empty index, do not switch to grep, and do not index the repository into this
+store. Route the question to the session attached to the store the diagnostic
+names.
+
 ## Common Mistakes
 
 | Mistake | Reality |
@@ -105,4 +142,9 @@ One `find_code` / `find_symbol` result entry:
 | `find_code(kind=...)` | **`kind` only on `find_symbol`** |
 | Passing symbol `id` to graph tools | Use **`name`** as `symbol` / `target` |
 | Assuming `fuzzy: true` always works | Backend is exact-match today — try spelling variants |
-| Skipping `list_indexed_repositories` | Verify repo is indexed first |
+| Skipping `list_indexed_repositories` | Verify repo is indexed first — it lists this session's store only |
+| Reading `repo_not_in_store` as an empty index | Nothing was searched; the repository lives in the store `diagnostic.repo_lives_in` names |
+
+## Retrieval limits and fallback
+
+A valid empty or irrelevant result is not a guarantee that the code is absent. Check scope, branch and indexing/embedding readiness; retry once with a targeted query. Then permit bounded source search and verification. Record the original miss and do not count fallback recovery as Memtrace retrieval success. Reindex only for demonstrated stale or incomplete coverage. Embeddings cannot guarantee literal-string or short-symbol recall. A `repo_not_in_store` refusal is not such a miss: nothing was searched, so route it to the store `diagnostic.repo_lives_in` names rather than falling back to source search or reindexing here.

package/skills/commands/memtrace-graph.md

@@ -85,6 +85,18 @@ Params are **`source`** and **`target`** (symbol names) — not `from`/`to`.
 
 `find_dependency_path` returns the ordered symbol chain from `source` to `target`; `list_communities` returns module partitions with their member symbols.
 
+## A `busy` answer is a wait, not an absence
+
+Heavy graph work runs one repository-sized fold at a time, because holding
+two in memory is what the bound protects against. When the lane is already
+held, a caller is not queued indefinitely: after a bounded wait it gets a
+successful answer carrying `"busy": true`, `"lane": "graph_materialization"`,
+`"retryable": true`, and a `holder` block naming the operation that holds the
+lane and how long it has held it. Report it as a wait, retry once the holder
+is likely done, or narrow the call (one `repo_id`, a smaller `limit`, a
+shorter window) so it does not need the lane. Do not read it as an empty
+graph and do not fall back to file search.
+
 ## Common Mistakes
 
 | Mistake | Reality |

package/skills/commands/memtrace-index.md

@@ -43,6 +43,13 @@ 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.
 
+If a search instead came back with `error_code: "repo_not_in_store"`, stop.
+That repository is not missing from the index; it is indexed in a different
+store, named in `diagnostic.repo_lives_in`. `list_indexed_repositories` lists
+this session's store only, so its absence there proves nothing. Indexing it
+here would build a second copy in the wrong store. Report the store that holds
+it and route the question to the session or daemon attached to that store.
+
 ### 2. Index the directory
 
 Use the `index_directory` MCP tool:
@@ -54,10 +61,20 @@ Use the `index_directory` MCP tool:
 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
+sharing, the durable form is a portable manifest started with
+`memtrace start --workspace-file <manifest>`; the legacy Folder Group flow is
+`memtrace start --bless-workspace` from the parent, verified with
 `memtrace workspace status <path>`.
 
+A store whose membership is already owned by a manifest or a Named Workspace
+cannot be widened from an MCP session, nor by a plain `memtrace start` from a
+parent folder. Adding a repository means restarting that store's daemon with
+the definition that owns it — `memtrace start --workspace-file <manifest>` or
+`memtrace start --workspace <name>`, editing the manifest first when it is a
+manifest. If a start is refused with "a folder-walked start cannot widen it",
+run the command the refusal names. No MCP session can widen an existing store
+under any flag, whatever declared it.
+
 **Success criteria:** You receive a `job_id` immediately.
 
 ### 3. Poll for completion

package/skills/commands/memtrace-search.md

@@ -1,9 +1,11 @@
 ---
 name: memtrace-search
-description: "Find source code with Memtrace hybrid BM25+semantic search: symbols, functions, classes, types, constants, definitions, implementations, logic, or error strings inside code. Use when the user wants to find, search, locate, or look up code or asks where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery. If Memtrace returns 0 results, broaden the Memtrace query and diagnose/reindex; do not switch to grep."
+description: "Find source code with Memtrace hybrid BM25+semantic search: symbols, functions, classes, types, constants, definitions, implementations, logic, or error strings inside code. Use when the user wants to find, search, locate, or look up code or asks where code lives. Use Memtrace first; after a diagnosed miss and one targeted retry, allow bounded source verification or fallback. Reindex only for evidence of stale or incomplete coverage."
 allowed-tools:
   - mcp__memtrace__find_code
   - mcp__memtrace__find_symbol
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__get_process_flow
   - mcp__memtrace__get_source_window
   - mcp__memtrace__list_indexed_repositories
   - Read
@@ -32,11 +34,13 @@ Find code using hybrid BM25 + semantic search (RRF). Primary discovery tool —
 | Param | Required | Default | Notes |
 |---|---|---|---|
 | `query` | yes | — | Natural language or symbol text |
-| `repo_id` | no | all repos | |
+| `repo_id` | no | this store's members | Safe scope inference: omitted, an unambiguous session resolves to its own repository; a multi-repo store fans out across its discovered members |
 | `limit` | no | 20 | Max 100 |
 | `file_path` | no | — | Path/directory substring filter |
 | `as_of` | no | now | ISO-8601 time-travel |
 | `include_diagnostics` | no | false | Set true for `id`, `score` in results |
+| `include_dependency_checks` | no | true | With diagnostics, set false for scores without pre-edit risk checks |
+| `include_context` | no | auto | Query-matched processes, communities and selected callers/callees; auto on for concept queries, off for identifiers |
 
 **No `kind` param on `find_code`** — use `find_symbol(kind=...)` to filter by symbol type.
 
@@ -49,7 +53,7 @@ Find code using hybrid BM25 + semantic search (RRF). Primary discovery tool —
 | Param | Required | Default | Notes |
 |---|---|---|---|
 | `name` | yes | — | Symbol name to search |
-| `repo_id` | no | all repos | |
+| `repo_id` | no | inferred | Safe scope inference: one repository is inferred only when that is unambiguous; otherwise the call returns `repo_scope_required` |
 | `fuzzy` | no | false | API field exists; currently exact-match in backend |
 | `edit_distance` | no | 2 | Only when fuzzy enabled |
 | `kind` | no | — | `Function`, `Class`, `Method`, etc. |
@@ -68,15 +72,33 @@ Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bun
 
 - Exact name → `find_symbol`
 - Behaviour description → `find_code`
-- All repos → omit `repo_id`
+- Every member of this store → omit `repo_id` on `find_code`. `find_symbol` needs one repository and infers it only when that is unambiguous.
 
 ### 2. Execute search
 
 Result shape: see [Output](#output) below.
 
-### 3. Hand off to graph tools
+### 3. Inspect query context, then expand if needed
 
-Save **`name`**, **`scope_path`**, and **`file_path`** — **not** internal IDs:
+Concept searches include a bounded `context` object. Its process matches and
+community members reference the primary `results` by one-based number. Inspect
+these and the selected callers/callees before making another graph call.
+Use `include_context: true` for identifier context, or `false` for flat results.
+Check `status`, `incomplete_reasons`, `coverage` and `payload_truncated`: omitted
+relationships are not proof of absence. The context contains selected matches,
+not a complete process trace. Worktree overlays report context unavailable until
+their graph is refreshed.
+
+For a code change, inspect the relevant caller/callee contracts before editing.
+`context.next_calls` supplies valid tool names and arguments for the selected
+symbol and flow; use these directly when they address the investigation.
+They preserve repository, branch and file disambiguation. Process navigation
+uses the returned process UUID. Symbol navigation uses name plus file path.
+Expand only the evidence needed; an empty sampled process list does not mean
+the symbol has no callers or callees.
+
+For symbol navigation, save **`name`**, **`scope_path`**, and **`file_path`**.
+For process navigation, retain its **process `id`**:
 
 ```json
 { "repo_id": "memdb", "symbol": "validateToken" }
@@ -84,12 +106,12 @@ Save **`name`**, **`scope_path`**, and **`file_path`** — **not** internal IDs:
 { "repo_id": "memdb", "target": "validateToken", "query_type": "find_callers" }
 ```
 
-Read source only when editing — bounded `Read(offset, limit)` at returned lines.
+Read source when verifying behavior, editing or quoting — bounded `Read(offset, limit)` at returned lines.
 
 ### Multi-word queries
 
 1. Try verbatim `find_code` query.
-2. If weak, fan out: camelCase, snake_case, domain identifiers.
+2. If weak, make one targeted reformulation with an identifier or path hint.
 3. Dedupe top hits by `file_path:start_line`.
 
 ## Output
@@ -108,6 +130,23 @@ One `find_code` / `find_symbol` result entry:
 
 `score` (and `id`) appear only with `include_diagnostics: true`.
 
+## A `repo_id` this store does not hold
+
+`find_code` and `find_symbol` check membership before they search. If the
+`repo_id` you passed is not a member of this session's store, the call is
+handed to the live runtime whose store declares it, and the answer comes back
+marked `_meta.answered_by: "store_owner_daemon"` with `_meta.owner_pid`,
+`_meta.owner_http` and `_meta.store`. Use that answer and say which store
+produced it.
+
+If no live runtime holds the repository, or its owner cannot answer, you get
+a refusal instead: `repo_in_store: false`, `error_code: "repo_not_in_store"`,
+`count: 0`, and a `diagnostic` naming this store, its `members` and — when it
+is known — `repo_lives_in`. Nothing was searched. Do not read that as an
+empty index, do not switch to grep, and do not index the repository into this
+store. Route the question to the session attached to the store the diagnostic
+names.
+
 ## Common Mistakes
 
 | Mistake | Reality |
@@ -115,4 +154,9 @@ One `find_code` / `find_symbol` result entry:
 | `find_code(kind=...)` | **`kind` only on `find_symbol`** |
 | Passing symbol `id` to graph tools | Use **`name`** as `symbol` / `target` |
 | Assuming `fuzzy: true` always works | Backend is exact-match today — try spelling variants |
-| Skipping `list_indexed_repositories` | Verify repo is indexed first |
+| Skipping `list_indexed_repositories` | Verify repo is indexed first — it lists this session's store only |
+| Reading `repo_not_in_store` as an empty index | Nothing was searched; the repository lives in the store `diagnostic.repo_lives_in` names |
+
+## Retrieval limits and fallback
+
+A valid empty or irrelevant result is not a guarantee that the code is absent. Check scope, branch and indexing/embedding readiness; retry once with a targeted query. Then permit bounded source search and verification. Record the original miss and do not count fallback recovery as Memtrace retrieval success. Reindex only for demonstrated stale or incomplete coverage. Embeddings cannot guarantee literal-string or short-symbol recall. A `repo_not_in_store` refusal is not such a miss: nothing was searched, so route it to the store `diagnostic.repo_lives_in` names rather than falling back to source search or reindexing here.

package/skills/workflows/memtrace-codebase-exploration.md

@@ -33,6 +33,11 @@ Call `list_indexed_repositories` first. If the repo is already indexed, skip to
 
 Otherwise, call `index_directory` with the project path, then poll `check_job_status` until completion.
 
+`list_indexed_repositories` covers this session's store only. If a later call
+answers `error_code: "repo_not_in_store"`, the repository is indexed in the
+store named in `diagnostic.repo_lives_in` — route the question there instead
+of indexing a second copy here.
+
 **Success criteria:** Repo appears in `list_indexed_repositories` with non-zero node/edge counts.
 
 ### 2. Get the lay of the land
@@ -134,6 +139,18 @@ The deliverable is the 7-part overview above. Skeleton (one headline per part):
 6. Recent Activity — 31 episodes in 30d; hottest file per `top_changed_files`
 7. Technical Debt — top-10 complex functions, highest complexity first
 
+## A `busy` answer is a wait, not an absence
+
+Heavy graph work runs one repository-sized fold at a time, because holding
+two in memory is what the bound protects against. When the lane is already
+held, a caller is not queued indefinitely: after a bounded wait it gets a
+successful answer carrying `"busy": true`, `"lane": "graph_materialization"`,
+`"retryable": true`, and a `holder` block naming the operation that holds the
+lane and how long it has held it. Report it as a wait, retry once the holder
+is likely done, or narrow the call (one `repo_id`, a smaller `limit`, a
+shorter window) so it does not need the lane. Do not read it as an empty
+graph and do not fall back to file search.
+
 ## Common Mistakes
 
 | Mistake | Reality |