memtrace-skills 1.2.5 → 1.2.7

package/dist/transformers/cursor.js

@@ -60,7 +60,7 @@ function cursorWorkspaceBoundaryWarnings(ctx) {
     if (fs.existsSync(path.join(ctx.cwd, '.memtrace-workspace')))
         return [];
     return [
-        `Cursor install target ${ctx.cwd} contains multiple sibling git repos but is not a blessed Memtrace workspace. For separate MemDBs, install/open each repo root. To intentionally share one MemDB, run 'memtrace start --bless-workspace' from ${ctx.cwd}, then verify with 'memtrace workspace status ${ctx.cwd}'.`,
+        `Cursor install target ${ctx.cwd} contains multiple sibling git repos but is not a blessed Memtrace workspace. For separate MemDBs, install/open each repo root. To intentionally share one MemDB, declare the members in a workspace manifest and run 'memtrace start --workspace-file <manifest>', or use the legacy Folder Group flow: 'memtrace start --bless-workspace' from ${ctx.cwd}, then verify with 'memtrace workspace status ${ctx.cwd}'. Once a store's membership is declared, a Memtrace MCP session can never widen it — adding a repo means editing the manifest and restarting that store's daemon with 'memtrace start --workspace-file <manifest>'.`,
     ];
 }
 export function registerCursorMcpAt(mcpFile, binary) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace-skills",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
   "type": "module",
   "bin": {

package/plugins/memtrace-skills/references/mcp-parameters.md

@@ -31,20 +31,60 @@ arrays as arrays. No quoting numbers, no `"true"` for booleans.
 
 | Param | Type | Meaning |
 |---|---|---|
-| `repo_id` | string | Repository identifier from `list_indexed_repositories` (usually the repo folder name, e.g. `"memtrace"`) |
+| `repo_id` | string | Repository identifier from `list_indexed_repositories` (usually the repo folder name, e.g. `"memtrace"`). That list covers this session's store only — see "A `repo_id` this session's store does not hold" below |
 | `branch` *or* `branch_name` | string | Git branch. Default `"main"` across every tool. Both spellings occur historically — use whichever the specific tool's schema says |
 | `limit` | integer | Cap on returned results. Always a JSON number, never a string |
 | `depth` | integer | Graph traversal hops. 1–5 is reasonable; >8 explodes on wide graphs |
 | `target` / `symbol` | string | Symbol **name** for graph tools — `get_impact`/`analyze_relationships` use `target`; `get_symbol_context` uses `symbol` |
 | `from` / `to` / `since` / `until` | string | e.g. `"90d ago"`, `"2026-04-17T13:00:00Z"`, `"yesterday"` — relative strings work for temporal tools. **Never `days` on `get_evolution`.** |
 
+
+## A `repo_id` this session's store does not hold
+
+Ten tools check the requested `repo_id` against this store's declared members
+before they answer: `find_code`, `find_symbol`, `get_codebase_briefing`,
+`find_central_symbols`, `find_dependency_path`, `find_bridge_symbols`,
+`list_processes`, `get_process_flow`, `list_communities` and
+`get_repository_stats`. On those, a wrong `repo_id` is never a success-shaped
+zero.
+
+- If a live runtime's store declares the repository, the read is forwarded to
+  it and the answer carries `_meta.answered_by: "store_owner_daemon"`,
+  `_meta.owner_pid`, `_meta.owner_http` and `_meta.store`.
+- Otherwise the call is refused: `repo_in_store: false`,
+  `error_code: "repo_not_in_store"`, `count: 0`, and a `diagnostic` naming the
+  store that answered, its `members`, `reason` and `repo_lives_in` when a
+  runtime declares the repository elsewhere. Nothing was searched. A `reason`
+  of `ambiguous_repo_id` is the opposite case: the id matches more than one
+  repository in this store, so pass the exact id.
+
+The remaining `repo_id` tools do not check membership: the relationship tools
+(`get_symbol_context`, `get_impact`, `analyze_relationships`), the temporal
+tools (`get_evolution`, `get_timeline`, `get_changes_since`), the topology
+tools (`get_api_topology`, `find_api_endpoints`, `find_api_calls`,
+`get_service_diagram`) and `get_source_window`. They read this session's store
+whatever id you pass, set no `repo_in_store` key, and return an ordinary empty
+result for a repository this store does not hold. A zero from one of them is
+not an absence — confirm the repository is a member with one of the ten above
+first.
+
+`repo_in_store: true` means membership was proven. `repo_in_store: null` means
+the session discovered no workspace, so membership was assumed rather than
+proven.
+
+Tools that change a store, a runtime, or anything outside the process
+(`index_directory`, `delete_repository`, `watch_directory`, `link_*`,
+`cleanup_*`, `replay_history`, the mutating `fleet_*` calls, and the rest) are
+never forwarded. Run them from the session attached to the store that holds
+the repository.
+
 ## Search & discovery
 
 ### `find_code`
 | Field | Type | Required | Default | Notes |
 |---|---|---|---|---|
 | `query` | string | yes | — | Natural-language text |
-| `repo_id` | string | no | all repos | Scope to one repo |
+| `repo_id` | string | no | this store's members | Scope to one repo. Omitted, an unambiguous session resolves to its own repository and a multi-repo store fans out across its discovered members |
 | `file_path` | string | no | — | Path substring filter |
 | `limit` | integer | no | `20` | Max 100 |
 | `as_of` | string | no | now | Time-travel search |
@@ -58,7 +98,7 @@ No `kind` param — use `find_symbol(kind=...)` instead.
 | `name` | string | yes | — | Exact or partial identifier |
 | `fuzzy` | boolean | no | `false` | Exact-match today; field kept for API parity |
 | `edit_distance` | integer | no | `2` | Max 2. Only used when `fuzzy: true` |
-| `repo_id` | string | no | all repos | |
+| `repo_id` | string | no | inferred | One repository is inferred only when that is unambiguous; otherwise the call returns `repo_scope_required` |
 | `kind` | string | no | — | Same enum as `find_code` |
 | `file_path` | string | no | — | |
 | `limit` | integer | no | `10` | Capped at `50` |

package/plugins/memtrace-skills/skills/memtrace-codebase-exploration/SKILL.md

@@ -15,6 +15,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
@@ -116,6 +121,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 |

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

@@ -1,6 +1,6 @@
 ---
 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."
+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. A `repo_not_in_store` refusal means a different store holds the repository: route to that store, never grep and never re-index here."
 ---
 
 # Memtrace First
@@ -37,19 +37,93 @@ Memtrace's hybrid search = **BM25 over symbol metadata** (name, signature, file_
 
 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
+## Read the envelope before you diagnose anything
+
+An empty-looking answer has three different causes and they need different
+responses: the tool refused because another store holds the repository, the
+tool never checked membership at all, or this store genuinely holds nothing
+for the query. Before diagnosing, check which tool you called and what
+`repo_in_store` and `error_code` say.
+
+### Only some tools check membership
+
+Ten tools check the requested `repo_id` against this store's declared members
+before they answer, and they are the only ones that set the top-level
+`repo_in_store` key: `find_code`, `find_symbol`, `get_codebase_briefing`,
+`find_central_symbols`, `find_dependency_path`, `find_bridge_symbols`,
+`list_processes`, `get_process_flow`, `list_communities` and
+`get_repository_stats`.
+
+Every other tool that takes a `repo_id` — `get_symbol_context`, `get_impact`,
+`analyze_relationships`, `get_evolution`, `get_timeline`, `get_source_window`,
+`get_api_topology` and the rest — reads this session's store whatever id you
+pass. Their answers carry no `repo_in_store` key at all, so a zero from one of
+them is not evidence about membership and not evidence that the repository is
+unindexed. When membership is in doubt, establish it with one of the ten above
+before you conclude anything. `repo_in_store: null` is a third case:
+membership was assumed rather than proven, because the session discovered no
+workspace.
+
+### `repo_not_in_store` — wrong store, not a missing index
+
+One of the ten, asked for a `repo_id` this session's store does not hold,
+answers `repo_in_store: false` with `error_code: "repo_not_in_store"`. It
+searched nothing. The `diagnostic` block names the store that answered, its
+`members`, the `reason`, and — when a live runtime declares the repository —
+`repo_lives_in` with that store, its path, `owner_pid`, `ui_port`,
+`control_port` and `endpoint`.
+
+1. Read `diagnostic.reason` first. `ambiguous_repo_id` is not a routing
+   problem: the id matches more than one repository in *this* store, and the
+   message says to pass the exact id. Do that and stop here. Everything below
+   applies to the `not_in_store` reason.
+2. Do not fall back to file search. The refusal says so itself, in `_note`:
+   "Wrong store for this repo_id; do not fall back to filesystem search, ask
+   the session attached to the store named in diagnostic.repo_lives_in."
+3. Do not call `index_directory`. The repository is already indexed in the
+   store `repo_lives_in` names. Indexing it here would build a second copy in
+   the wrong store — writes are never routed to another store, so the call
+   lands locally.
+4. Tell the user which store holds it, and route the question to the session
+   or daemon attached to that store. A session cannot ask an owner to add a
+   repository: changing the members of a store that already has them means
+   running `memtrace start` for that store, with `--workspace-file <manifest>`
+   or `--workspace <name>` when a manifest or a Named Workspace owns its
+   scope.
+5. If `repo_lives_in` is absent, no live Memtrace runtime declares the
+   repository. Running `memtrace start` in its own workspace is the fix.
+
+A refusal is not the only outcome. When the runtime whose store declares the
+repository is live and publishes a reachable control port, the same read is
+forwarded to it and you get the real answer, marked
+`_meta.answered_by: "store_owner_daemon"` alongside `_meta.owner_pid`,
+`_meta.owner_http` and `_meta.store`. That answer is authoritative; say which
+store produced it.
+
+A forwarded read can also come back as a bounded `busy` answer with
+`"lane": "graph_materialization"` and `retryable: true`, naming what holds
+the graph lane and for how long. That is a wait, not an absence — retry, or
+narrow the call.
 
-If Memtrace returns 0 results, or repository stats look incomplete, do **not**
-infer that a source subdirectory is outside the index. Diagnose through
-Memtrace:
+## Zero results are not a grep license
 
-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
+A genuine zero — `count: 0` from a tool that reported `repo_in_store: true` —
+is a coverage question. 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. It
+   lists this session's store only, so a repository missing from it may still
+   be indexed and live in another store.
+2. If the zero came from a tool that sets no `repo_in_store` key, re-ask about
+   the same repository through `find_code` or `find_symbol` before reading
+   anything into it. Those check membership; the first tool did not.
+3. If the path is under that indexed repo root, keep using Memtrace.
+4. 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.
+5. If the language/path still appears missing, run `index_directory` on the repo
+   root with `incremental: true` (or ask before `clear_existing: true`). Do
+   this only after steps 1 and 2 show the repository is a member of this store.
+6. Report the indexing coverage problem instead of silently switching to grep.
 
 ### Workspace Boundary Check
 
@@ -61,9 +135,22 @@ 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
+- For an intentional shared workspace: a portable manifest is the durable
+  form — `memtrace start --workspace-file <manifest>` declares the members and
+  records the manifest as the owner of the store's membership. The Folder
+  Group flow still works and the CLI now calls it legacy: the user blesses the
+  parent with `memtrace start --bless-workspace`, then verifies it with
   `memtrace workspace status <path>`; the workspace marker should be present.
+- A store whose membership is already owned by a manifest or a Named Workspace
+  cannot be widened by a plain `memtrace start` from a parent folder. That
+  start is refused with "a folder-walked start cannot widen it. Run
+  `<command>`", and the refusal names the exact command to run instead. Run
+  it. Do not route around the refusal by indexing elsewhere. A folder-sourced
+  store has no owning definition, so that refusal does not apply to it. A
+  `memtrace mcp` session can never widen an existing store under any flag,
+  including `--workspace-file`: adding a repository is always a `memtrace
+  start` for that store, carrying the manifest or the workspace name when one
+  owns its members.
 - 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
@@ -79,8 +166,11 @@ 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.
+  prove it, and neither does a `repo_not_in_store` refusal — that list covers
+  this session's store only, and the refusal's `diagnostic.repo_lives_in`
+  names the store that does hold the repository. 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.
@@ -101,6 +191,8 @@ For everything else inside the indexed repo, memtrace is the right tool.
 | "Should I change/delete/refactor `foo`?" | `find_symbol`/`get_symbol_context` → `recall_decision("foo / subsystem / approach")`; if a symbol id is available, `why_is_this_here` + `governing_contracts`; then `get_impact`. |
 | "Can I use/switch to pattern or library X?" | `recall_decision("X")` FIRST; bans and conventions are decisions. Verify a matching decision with `verify_intent(decision_id)` before relying on it. |
 | "What changed in `auth.ts` last week?" | `get_evolution(repo_id, from="7d ago", mode="recent", file_path="auth.ts")`. |
+| The answer carries `error_code: "repo_not_in_store"` | Read `diagnostic.reason`. On `ambiguous_repo_id`, pass the exact id. Otherwise read `diagnostic.repo_lives_in` and route the question to the session attached to that store. Never grep, never `index_directory`. |
+| A `repo_id` tool answered zero with no `repo_in_store` key | It never checked membership. Re-ask through `find_code` or `find_symbol` before treating the zero as an absence. |
 | "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
 | "Find this string in my `.env`." | `Grep` (non-source artifact). |
 | "I'm about to edit `foo` — show me its source." | Bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`, or `get_source_window` if your harness lacks bounded reads. Never whole-file. |
@@ -203,7 +295,9 @@ You are violating this skill if you think:
 | "I'll just switch to library/pattern X" | `recall_decision("X")` first — you may be reintroducing a banned approach. |
 | "It's just a quick search" | Grep has no understanding of call graphs, communities, or time |
 | "I don't know if it's indexed" | Check with `list_indexed_repositories` first — takes 1 second |
-| "Memtrace returned 0 results" | Broaden the Memtrace query, check repo_id/path coverage, then reindex if needed |
+| "Memtrace returned 0 results" | Check `repo_in_store` first. If it is true, broaden the query, check repo_id/path coverage, then reindex if needed |
+| "The zero had no `repo_in_store`, so the repo is not indexed" | Only ten tools set that key. A zero from the others says nothing about membership — re-ask through `find_code` or `find_symbol` |
+| "It said `repo_not_in_store`, so I'll index it here" | The repository is already indexed in the store `diagnostic.repo_lives_in` names. Indexing here makes a second copy in the wrong store |
 | "Stats only show Rust, but I need `ui/` or `memtrace-ui/`" | That is a coverage diagnostic. Reindex the repo root; do not grep source code. |
 | "The user didn't say to use Memtrace" | User asked about the code. Repo is indexed. Use Memtrace. |
 | "This is a simple question" | Simple questions benefit most — one `find_symbol` vs 20 file reads |
@@ -253,5 +347,7 @@ When this skill applies, it overrides default file-search behavior. Use the spec
 
 - The answer is grounded in Memtrace graph results (search hit → `get_symbol_context` / `get_impact`), not file-tool discovery.
 - Grep/Glob/Read appear only via the documented narrow exceptions (non-source artifacts, paths outside every indexed root, file inventory, bounded span reads).
-- Zero-result queries were diagnosed (`list_indexed_repositories` → broaden → reindex), not bypassed to grep.
+- A `repo_not_in_store` refusal was routed on `diagnostic.repo_lives_in`, not answered by grep and not answered by indexing the repository into this store.
+- Genuine zero-result queries (`repo_in_store: true`) were diagnosed (`list_indexed_repositories` → broaden → reindex), not bypassed to grep.
+- A zero from a tool that sets no `repo_in_store` key was re-checked through a membership-checking tool before it was called an absence.
 - Any source read was bounded to the span Memtrace returned.

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

@@ -73,6 +73,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/plugins/memtrace-skills/skills/memtrace-index/SKILL.md

@@ -33,6 +33,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:
@@ -44,10 +51,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/plugins/memtrace-skills/skills/memtrace-search/SKILL.md

@@ -22,7 +22,7 @@ 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 | 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 |
@@ -39,7 +39,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 | 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,7 +58,7 @@ 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
 
@@ -98,6 +98,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 +122,5 @@ 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 |

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

@@ -32,7 +32,7 @@ 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 | 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 |
@@ -49,7 +49,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 | 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,7 +68,7 @@ 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
 
@@ -108,6 +108,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 +132,5 @@ 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 |

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 |

package/skills/workflows/memtrace-first.md

@@ -1,6 +1,6 @@
 ---
 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."
+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. A `repo_not_in_store` refusal means a different store holds the repository: route to that store, never grep and never re-index here."
 allowed-tools:
   - mcp__memtrace__list_indexed_repositories
   - mcp__memtrace__index_directory
@@ -70,19 +70,93 @@ Memtrace's hybrid search = **BM25 over symbol metadata** (name, signature, file_
 
 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
+## Read the envelope before you diagnose anything
+
+An empty-looking answer has three different causes and they need different
+responses: the tool refused because another store holds the repository, the
+tool never checked membership at all, or this store genuinely holds nothing
+for the query. Before diagnosing, check which tool you called and what
+`repo_in_store` and `error_code` say.
+
+### Only some tools check membership
+
+Ten tools check the requested `repo_id` against this store's declared members
+before they answer, and they are the only ones that set the top-level
+`repo_in_store` key: `find_code`, `find_symbol`, `get_codebase_briefing`,
+`find_central_symbols`, `find_dependency_path`, `find_bridge_symbols`,
+`list_processes`, `get_process_flow`, `list_communities` and
+`get_repository_stats`.
+
+Every other tool that takes a `repo_id` — `get_symbol_context`, `get_impact`,
+`analyze_relationships`, `get_evolution`, `get_timeline`, `get_source_window`,
+`get_api_topology` and the rest — reads this session's store whatever id you
+pass. Their answers carry no `repo_in_store` key at all, so a zero from one of
+them is not evidence about membership and not evidence that the repository is
+unindexed. When membership is in doubt, establish it with one of the ten above
+before you conclude anything. `repo_in_store: null` is a third case:
+membership was assumed rather than proven, because the session discovered no
+workspace.
+
+### `repo_not_in_store` — wrong store, not a missing index
+
+One of the ten, asked for a `repo_id` this session's store does not hold,
+answers `repo_in_store: false` with `error_code: "repo_not_in_store"`. It
+searched nothing. The `diagnostic` block names the store that answered, its
+`members`, the `reason`, and — when a live runtime declares the repository —
+`repo_lives_in` with that store, its path, `owner_pid`, `ui_port`,
+`control_port` and `endpoint`.
+
+1. Read `diagnostic.reason` first. `ambiguous_repo_id` is not a routing
+   problem: the id matches more than one repository in *this* store, and the
+   message says to pass the exact id. Do that and stop here. Everything below
+   applies to the `not_in_store` reason.
+2. Do not fall back to file search. The refusal says so itself, in `_note`:
+   "Wrong store for this repo_id; do not fall back to filesystem search, ask
+   the session attached to the store named in diagnostic.repo_lives_in."
+3. Do not call `index_directory`. The repository is already indexed in the
+   store `repo_lives_in` names. Indexing it here would build a second copy in
+   the wrong store — writes are never routed to another store, so the call
+   lands locally.
+4. Tell the user which store holds it, and route the question to the session
+   or daemon attached to that store. A session cannot ask an owner to add a
+   repository: changing the members of a store that already has them means
+   running `memtrace start` for that store, with `--workspace-file <manifest>`
+   or `--workspace <name>` when a manifest or a Named Workspace owns its
+   scope.
+5. If `repo_lives_in` is absent, no live Memtrace runtime declares the
+   repository. Running `memtrace start` in its own workspace is the fix.
+
+A refusal is not the only outcome. When the runtime whose store declares the
+repository is live and publishes a reachable control port, the same read is
+forwarded to it and you get the real answer, marked
+`_meta.answered_by: "store_owner_daemon"` alongside `_meta.owner_pid`,
+`_meta.owner_http` and `_meta.store`. That answer is authoritative; say which
+store produced it.
+
+A forwarded read can also come back as a bounded `busy` answer with
+`"lane": "graph_materialization"` and `retryable: true`, naming what holds
+the graph lane and for how long. That is a wait, not an absence — retry, or
+narrow the call.
 
-If Memtrace returns 0 results, or repository stats look incomplete, do **not**
-infer that a source subdirectory is outside the index. Diagnose through
-Memtrace:
+## Zero results are not a grep license
 
-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
+A genuine zero — `count: 0` from a tool that reported `repo_in_store: true` —
+is a coverage question. 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. It
+   lists this session's store only, so a repository missing from it may still
+   be indexed and live in another store.
+2. If the zero came from a tool that sets no `repo_in_store` key, re-ask about
+   the same repository through `find_code` or `find_symbol` before reading
+   anything into it. Those check membership; the first tool did not.
+3. If the path is under that indexed repo root, keep using Memtrace.
+4. 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.
+5. If the language/path still appears missing, run `index_directory` on the repo
+   root with `incremental: true` (or ask before `clear_existing: true`). Do
+   this only after steps 1 and 2 show the repository is a member of this store.
+6. Report the indexing coverage problem instead of silently switching to grep.
 
 ### Workspace Boundary Check
 
@@ -94,9 +168,22 @@ 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
+- For an intentional shared workspace: a portable manifest is the durable
+  form — `memtrace start --workspace-file <manifest>` declares the members and
+  records the manifest as the owner of the store's membership. The Folder
+  Group flow still works and the CLI now calls it legacy: the user blesses the
+  parent with `memtrace start --bless-workspace`, then verifies it with
   `memtrace workspace status <path>`; the workspace marker should be present.
+- A store whose membership is already owned by a manifest or a Named Workspace
+  cannot be widened by a plain `memtrace start` from a parent folder. That
+  start is refused with "a folder-walked start cannot widen it. Run
+  `<command>`", and the refusal names the exact command to run instead. Run
+  it. Do not route around the refusal by indexing elsewhere. A folder-sourced
+  store has no owning definition, so that refusal does not apply to it. A
+  `memtrace mcp` session can never widen an existing store under any flag,
+  including `--workspace-file`: adding a repository is always a `memtrace
+  start` for that store, carrying the manifest or the workspace name when one
+  owns its members.
 - 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
@@ -112,8 +199,11 @@ 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.
+  prove it, and neither does a `repo_not_in_store` refusal — that list covers
+  this session's store only, and the refusal's `diagnostic.repo_lives_in`
+  names the store that does hold the repository. 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.
@@ -134,6 +224,8 @@ For everything else inside the indexed repo, memtrace is the right tool.
 | "Should I change/delete/refactor `foo`?" | `find_symbol`/`get_symbol_context` → `recall_decision("foo / subsystem / approach")`; if a symbol id is available, `why_is_this_here` + `governing_contracts`; then `get_impact`. |
 | "Can I use/switch to pattern or library X?" | `recall_decision("X")` FIRST; bans and conventions are decisions. Verify a matching decision with `verify_intent(decision_id)` before relying on it. |
 | "What changed in `auth.ts` last week?" | `get_evolution(repo_id, from="7d ago", mode="recent", file_path="auth.ts")`. |
+| The answer carries `error_code: "repo_not_in_store"` | Read `diagnostic.reason`. On `ambiguous_repo_id`, pass the exact id. Otherwise read `diagnostic.repo_lives_in` and route the question to the session attached to that store. Never grep, never `index_directory`. |
+| A `repo_id` tool answered zero with no `repo_in_store` key | It never checked membership. Re-ask through `find_code` or `find_symbol` before treating the zero as an absence. |
 | "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
 | "Find this string in my `.env`." | `Grep` (non-source artifact). |
 | "I'm about to edit `foo` — show me its source." | Bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`, or `get_source_window` if your harness lacks bounded reads. Never whole-file. |
@@ -236,7 +328,9 @@ You are violating this skill if you think:
 | "I'll just switch to library/pattern X" | `recall_decision("X")` first — you may be reintroducing a banned approach. |
 | "It's just a quick search" | Grep has no understanding of call graphs, communities, or time |
 | "I don't know if it's indexed" | Check with `list_indexed_repositories` first — takes 1 second |
-| "Memtrace returned 0 results" | Broaden the Memtrace query, check repo_id/path coverage, then reindex if needed |
+| "Memtrace returned 0 results" | Check `repo_in_store` first. If it is true, broaden the query, check repo_id/path coverage, then reindex if needed |
+| "The zero had no `repo_in_store`, so the repo is not indexed" | Only ten tools set that key. A zero from the others says nothing about membership — re-ask through `find_code` or `find_symbol` |
+| "It said `repo_not_in_store`, so I'll index it here" | The repository is already indexed in the store `diagnostic.repo_lives_in` names. Indexing here makes a second copy in the wrong store |
 | "Stats only show Rust, but I need `ui/` or `memtrace-ui/`" | That is a coverage diagnostic. Reindex the repo root; do not grep source code. |
 | "The user didn't say to use Memtrace" | User asked about the code. Repo is indexed. Use Memtrace. |
 | "This is a simple question" | Simple questions benefit most — one `find_symbol` vs 20 file reads |
@@ -286,5 +380,7 @@ When this skill applies, it overrides default file-search behavior. Use the spec
 
 - The answer is grounded in Memtrace graph results (search hit → `get_symbol_context` / `get_impact`), not file-tool discovery.
 - Grep/Glob/Read appear only via the documented narrow exceptions (non-source artifacts, paths outside every indexed root, file inventory, bounded span reads).
-- Zero-result queries were diagnosed (`list_indexed_repositories` → broaden → reindex), not bypassed to grep.
+- A `repo_not_in_store` refusal was routed on `diagnostic.repo_lives_in`, not answered by grep and not answered by indexing the repository into this store.
+- Genuine zero-result queries (`repo_in_store: true`) were diagnosed (`list_indexed_repositories` → broaden → reindex), not bypassed to grep.
+- A zero from a tool that sets no `repo_in_store` key was re-checked through a membership-checking tool before it was called an absence.
 - Any source read was bounded to the span Memtrace returned.