memtrace-skills 1.2.6 → 1.2.8

package/dist/skills.js

@@ -5,7 +5,8 @@ import path from 'path';
  * Handles the subset of YAML used in skill files (no nested objects).
  */
 function parseFrontmatter(raw) {
-    const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    // Skill files are LF in git but CRLF in a Windows checkout; read both.
+    const match = raw.replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
     if (!match)
         return null;
     const frontmatterRaw = match[1];

package/dist/tool-names.d.ts

@@ -0,0 +1 @@
+export declare const MEMTRACE_TOOL_NAMES: readonly string[];

package/dist/tool-names.js

@@ -0,0 +1,101 @@
+// Every tool the Memtrace MCP server registers, by its bare name.
+//
+// Pi registers each one as `memtrace_<name>`, so the Pi installer rewrites
+// these names wherever skill text mentions them. Deriving the list from the
+// tools skills happen to allow missed any tool no skill allowed (e.g.
+// find_code_review_issues). `installer_tool_list_matches_the_router` in
+// crates/memtrace-mcp/src/server.rs pins this list to the server's router.
+export const MEMTRACE_TOOL_NAMES = Object.freeze([
+    'analyze_relationships',
+    'ask_docs',
+    'calculate_cyclomatic_complexity',
+    'check_job_status',
+    'cleanup_episodes',
+    'cleanup_stale_records',
+    'cleanup_worktrees',
+    'create_anchor',
+    'delete_repository',
+    'detect_changes',
+    'embed_diag',
+    'embed_reset_breaker',
+    'export_query_audit',
+    'find_api_calls',
+    'find_api_endpoints',
+    'find_ast_review_issues',
+    'find_bridge_symbols',
+    'find_central_symbols',
+    'find_code',
+    'find_code_review_issues',
+    'find_cross_module_issues',
+    'find_dead_code',
+    'find_dependency_path',
+    'find_duplicate_code',
+    'find_hotspots',
+    'find_import_cycles',
+    'find_most_complex_functions',
+    'find_symbol',
+    'find_tool_definitions',
+    'find_yaml_rule_matches',
+    'fleet_acquire_lease',
+    'fleet_audit',
+    'fleet_branch_context',
+    'fleet_get_episode',
+    'fleet_get_escalation',
+    'fleet_get_node_state',
+    'fleet_list_escalations',
+    'fleet_preflight',
+    'fleet_publish_intent',
+    'fleet_query_episodes',
+    'fleet_record_episode',
+    'fleet_release_lease',
+    'fleet_renew_lease',
+    'fleet_resolve_escalation',
+    'fleet_status',
+    'fleet_submit_verdict',
+    'fleet_ydoc_append',
+    'fleet_ydoc_read',
+    'get_api_topology',
+    'get_arc',
+    'get_changes_since',
+    'get_cochange_context',
+    'get_codebase_briefing',
+    'get_daily_briefing',
+    'get_directory_tree',
+    'get_episode_replay',
+    'get_evolution',
+    'get_function_quality_metrics',
+    'get_impact',
+    'get_process_flow',
+    'get_repository_stats',
+    'get_service_diagram',
+    'get_source_window',
+    'get_style_fingerprint',
+    'get_symbol_context',
+    'get_timeline',
+    'governing_contracts',
+    'governing_rules',
+    'index_directory',
+    'ingest_graph_fragment',
+    'link_repositories',
+    'link_symbols',
+    'list_anchors',
+    'list_communities',
+    'list_indexed_repositories',
+    'list_jobs',
+    'list_processes',
+    'list_watched_paths',
+    'list_worktrees',
+    'mem_diag',
+    'preflight_check',
+    'read_doc',
+    'recall_decision',
+    'record_external_episode',
+    'replay_history',
+    'review_agent_sessions',
+    'review_github_pr',
+    'search_docs',
+    'unwatch_directory',
+    'verify_intent',
+    'watch_directory',
+    'why_is_this_here',
+]);

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/dist/transformers/pi.d.ts

@@ -1,5 +1,13 @@
+import { Skill } from '../skills.js';
 import { Transformer, InstallContext } from './types.js';
 export declare function piSettingsPath(ctx: InstallContext): string;
 /** Resolve the pi-package directory shipped inside the memtrace npm bundle. */
 export declare function resolveBundledPiPackage(fromDir?: string): string;
+/**
+ * Every Memtrace tool name skill text may mention, bare (`find_code`): the
+ * server's full tool list, plus any tool a skill allows. The allowed tools
+ * alone missed tools no skill allows, which then stayed bare in Pi skills.
+ */
+export declare function memtraceToolNames(skills: readonly Skill[]): string[];
+export declare function transformForPi(text: string, toolNames: readonly string[]): string;
 export declare const piTransformer: Transformer;

package/dist/transformers/pi.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 import { removeMemtraceSkills, skillName } from './shared.js';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
 import { commandExists } from '../utils.js';
+import { MEMTRACE_TOOL_NAMES } from '../tool-names.js';
 // Pi (https://pi.dev/docs/latest/packages) uses native pi packages — not MCP JSON
 // config like Cursor. The bundled `pi-package/` extension spawns `memtrace mcp`
 // itself and registers every Memtrace tool as a native Pi tool (`memtrace_*`).
@@ -30,8 +31,32 @@ export function resolveBundledPiPackage(fromDir = path.dirname(fileURLToPath(imp
     }
     throw new Error('bundled pi-package not found (reinstall memtrace from npm)');
 }
-function transformForPi(text) {
-    return text.replace(/mcp__memtrace__/g, 'memtrace_');
+const MEMTRACE_TOOL_PREFIX = 'mcp__memtrace__';
+/**
+ * Every Memtrace tool name skill text may mention, bare (`find_code`): the
+ * server's full tool list, plus any tool a skill allows. The allowed tools
+ * alone missed tools no skill allows, which then stayed bare in Pi skills.
+ */
+export function memtraceToolNames(skills) {
+    const names = new Set(MEMTRACE_TOOL_NAMES);
+    for (const skill of skills) {
+        for (const tool of skill.frontmatter['allowed-tools'] ?? []) {
+            if (tool.startsWith(MEMTRACE_TOOL_PREFIX))
+                names.add(tool.slice(MEMTRACE_TOOL_PREFIX.length));
+        }
+    }
+    return [...names].sort();
+}
+// Pi registers each Memtrace tool as `memtrace_<name>`. Skill bodies name tools
+// bare (`find_code`), so rewriting only the `mcp__memtrace__` prefix changed
+// nothing in them: every Pi skill allowed `memtrace_get_evolution` while its
+// prose told the agent to call `get_evolution`.
+export function transformForPi(text, toolNames) {
+    const prefixed = text.replace(/mcp__memtrace__/g, 'memtrace_');
+    if (toolNames.length === 0)
+        return prefixed;
+    const bare = new RegExp(`(?<![A-Za-z0-9_])(${toolNames.join('|')})(?![A-Za-z0-9_])`, 'g');
+    return prefixed.replace(bare, 'memtrace_$1');
 }
 function transformAllowedTool(tool) {
     return tool
@@ -40,23 +65,28 @@ function transformAllowedTool(tool) {
         .replace(/^Grep$/, 'grep')
         .replace(/^Glob$/, 'find');
 }
-function skillMarkdownForPi(skill) {
+function skillMarkdownForPi(skill, toolNames) {
     const name = skillName(skill);
-    const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
+    // The description is what Pi routes on, so it names tools the way Pi
+    // registers them too.
+    const safeDesc = transformForPi(skill.frontmatter.description, toolNames)
+        .replace(/"/g, '\\"')
+        .trim();
     const tools = skill.frontmatter['allowed-tools'];
     const toolsLine = tools?.length
         ? `\nallowed-tools: ${tools.map(transformAllowedTool).join(' ')}`
         : '';
-    const body = transformForPi(skill.body);
+    const body = transformForPi(skill.body, toolNames);
     return `---\nname: ${name}\ndescription: "${safeDesc}"${toolsLine}\n---\n\n${body}`;
 }
 function writeSkillsForPi(skills, rootDir) {
     removeMemtraceSkills(rootDir);
+    const toolNames = memtraceToolNames(skills);
     for (const skill of skills) {
         const name = skillName(skill);
         const outDir = path.join(rootDir, name);
         fs.mkdirSync(outDir, { recursive: true });
-        fs.writeFileSync(path.join(outDir, 'SKILL.md'), skillMarkdownForPi(skill));
+        fs.writeFileSync(path.join(outDir, 'SKILL.md'), skillMarkdownForPi(skill, toolNames));
     }
     return skills.length;
 }

package/package.json

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

package/plugin-assets/index.d.ts

@@ -1,4 +1,4 @@
-export const PLUGIN_ASSET_PATHS: readonly ['commands', 'README.md'];
+export const PLUGIN_ASSET_PATHS: readonly ['commands', 'references', 'README.md'];
 export const PLUGIN_MANIFEST_PATH: string;
 export const LEGACY_PLUGIN_ASSET_PATHS: readonly [
   'hooks',

package/plugin-assets/index.js

@@ -1,7 +1,11 @@
 import fs from 'fs';
 import path from 'path';
 
-export const PLUGIN_ASSET_PATHS = Object.freeze(['commands', 'README.md']);
+// `references/` holds the parameter spec that 25 skills send the agent to
+// ("bundled at the memtrace-skills plugin root"); without it here the
+// plugin install never wrote the file those skills name. Only the Claude
+// Code plugin carries it; other agents' skill installs do not.
+export const PLUGIN_ASSET_PATHS = Object.freeze(['commands', 'references', 'README.md']);
 export const PLUGIN_MANIFEST_PATH = path.join('.claude-plugin', 'plugin.json');
 export const LEGACY_PLUGIN_ASSET_PATHS = Object.freeze([
   'hooks',

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

@@ -31,24 +31,66 @@ 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 |
 | `include_diagnostics` | boolean | no | `false` | Include `id`, `score` in results |
+| `include_dependency_checks` | boolean | no | `true` | With diagnostics, set false for scores without pre-edit risk checks |
+| `include_context` | boolean | no | auto | Bounded processes, communities and selected callers/callees; default on for concepts, off for identifiers |
 
 No `kind` param — use `find_symbol(kind=...)` instead.
 
@@ -58,7 +100,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` |
@@ -88,8 +130,11 @@ No parameters. Call once at session start to get `repo_id` values.
 | `branch` | string | no | `"main"` |
 | `as_of` | string | no | now |
 | `view` | string | no | `"live"` |
+| `include_content` | boolean | no | `false` |
+| `limit` | integer | no | `20` (max `200`) |
+| `offset` | integer | no | `0` |
 
-Returns: symbol, callers, callees, type_references, community, processes, api_callers_cross_repo.
+Returns compact symbol locations, relationship sections, community and process context. Source bodies require `include_content: true`, or use `get_source_window`. Each section has `pagination` metadata with `available`, `returned`, `offset`, and `next_offset`. The offset applies independently to each section; repeat with that section's `next_offset` to continue it. These pages cover the bounded graph result: `graph_truncated` and `available_is_lower_bound` remain true when an internal graph cap was reached.
 
 ### `analyze_relationships`
 | Field | Type | Required | Default | Notes |
@@ -229,6 +274,10 @@ Returns `cochanged_files[]` with `file_path`, `cochange_count`, `last_cochanged_
 | `repo_id` | string | yes | — |
 | `process` | string | yes | — |
 | `branch` | string | no | `"main"` |
+| `limit` | integer | no | `20` (max `200`) |
+| `offset` | integer | no | `0` |
+
+Returns ordered steps, `total_steps`, `returned_steps`, `next_offset`, and `scan_truncated`. Follow `next_offset` to continue. The existing internal scan cap still applies; `scan_truncated` signals when pagination cannot expose the entire process.
 
 ### `find_dependency_path`
 | Field | Type | Required | Default | Notes |

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 |