memtrace 0.3.31 → 0.3.34

package/README.md

@@ -24,11 +24,11 @@ Memtrace gives coding agents something they've never had: **structural memory**.
 Index once. Every agent query after that resolves through graph traversal — callers, callees, implementations, imports, blast radius, temporal evolution — in milliseconds, with zero token waste.
 
 ```bash
-npm install -g memtrace    # binary + 12 skills + MCP server — one command
+npm install -g memtrace    # binary + 17 skills + MCP server — one command
 memtrace start             # launches the graph database and auto-indexes the current project
 ```
 
-That's it. Run `memtrace start` from your project root — it spins up the graph database and kicks off indexing automatically. Claude and Cursor (v2.4+) pick up the skills and MCP tools automatically.
+That's it. Run `memtrace start` from your project root — it spins up the graph database and kicks off indexing automatically. Claude, Cursor, Codex, Windsurf, VS Code/Copilot, Hermes, OpenCode, and Kiro pick up the skills/guidance and MCP tools automatically.
 
 ---
 
@@ -175,9 +175,9 @@ Memtrace exposes a full structural toolkit via the [Model Context Protocol](http
 </tr>
 </table>
 
-## 12 Agent Skills
+## 17 Agent Skills
 
-Memtrace ships skills that teach Claude *how* to use the graph. They fire automatically based on what you ask — no prompt engineering required.
+Memtrace ships skills that teach agents *how* to use the graph. They fire automatically based on what you ask — no prompt engineering required.
 
 | | Skill | You say... |
 |:--|:------|:-----------|
@@ -189,8 +189,9 @@ Memtrace ships skills that teach Claude *how* to use the graph. They fire automa
 | **Architecture** | `memtrace-graph` | _"show me the architecture"_, _"find bottlenecks"_ |
 | **APIs** | `memtrace-api-topology` | _"list API endpoints"_, _"service dependencies"_ |
 | **Index** | `memtrace-index` | _"index this project"_, _"parse this codebase"_ |
+| **Co-change** | `memtrace-cochange` | _"what else changes with this"_, _"hidden coupling"_ |
 
-Plus **4 workflow skills** that chain multiple tools with decision logic:
+Plus **8 workflow skills** that chain multiple tools with decision logic:
 
 | Skill | You say... |
 |:------|:-----------|
@@ -198,6 +199,10 @@ Plus **4 workflow skills** that chain multiple tools with decision logic:
 | `memtrace-change-impact-analysis` | _"what will break if I refactor this"_ |
 | `memtrace-incident-investigation` | _"something broke"_, _"root cause analysis"_ |
 | `memtrace-refactoring-guide` | _"help me refactor"_, _"clean up tech debt"_ |
+| `memtrace-first` | _"use Memtrace before file search"_ |
+| `memtrace-continuous-memory` | _"watch this repo"_, _"keep the graph fresh"_ |
+| `memtrace-episode-replay` | _"why does this code look this way"_ |
+| `memtrace-session-continuity` | _"continue"_, _"catch me up"_ |
 
 ## Temporal Engine
 
@@ -216,24 +221,27 @@ Uses **Structural Significance Budgeting** to surface the minimum set of changes
 
 ## Compatibility
 
-| Editor / Agent | MCP Tools (25+) | Skills (12) | Install |
+| Editor / Agent | MCP Tools (25+) | Skills / Guidance | Install |
 |:---------------|:---------------:|:-----------:|:--------|
 | **Claude Code** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
 | **Claude Desktop** | ✅ | ✅ | Automatic — shared with Claude Code |
 | **Cursor** (v2.4+) | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
-| **Windsurf** | ✅ | Coming soon | Add MCP server manually |
-| **VS Code (Copilot)** | ✅ | — | Add MCP server manually |
+| **Codex CLI** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
+| **Windsurf** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
+| **VS Code (Copilot)** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
+| **Hermes** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
+| **OpenCode** | ✅ | ✅ | `npm install -g memtrace` — fully automatic |
+| **Kiro** | ✅ | Steering | `npm install -g memtrace` — fully automatic |
 | **Cline / Roo Code** | ✅ | — | Add MCP server manually |
-| **Codex CLI** | ✅ | Coming soon | Add MCP server manually |
 | **Any MCP client** | ✅ | — | Add MCP server manually |
 
-> **MCP tools** work with any editor or agent that supports the [Model Context Protocol](https://modelcontextprotocol.io). **Skills** are workflow prompts that teach the agent *how* to chain tools — Claude Code, Claude Desktop, and Cursor (v2.4+) all load them natively from the same `SKILL.md` format.
+> **MCP tools** work with any editor or agent that supports the [Model Context Protocol](https://modelcontextprotocol.io). **Skills** are workflow prompts that teach the agent *how* to chain tools. Kiro does not use `SKILL.md`, so Memtrace writes equivalent auto steering files instead.
 
 ## Setup
 
 ### Claude Code + Claude Desktop
 
-`npm install -g memtrace` handles everything automatically — binary, 12 skills, MCP server, plugin, and marketplace all register in one command for both Claude Code and Claude Desktop.
+`npm install -g memtrace` handles everything automatically — binary, 17 skills, MCP server, plugin, and marketplace all register in one command for both Claude Code and Claude Desktop.
 
 For manual setup:
 
@@ -249,17 +257,42 @@ Cursor **v2.4+** supports Agent Skills natively, and `npm install -g memtrace` h
 
 What the installer writes:
 - **MCP server** → `~/.cursor/mcp.json` (global — works in every project you open)
-- **12 skills + 4 workflows** → `~/.cursor/skills/memtrace-*/SKILL.md`
+- **17 skills/workflows** → `~/.cursor/skills/memtrace-*/SKILL.md`
 
 For a **project-local** install (so the skills travel with your repo and teammates get them on clone), run inside the project:
 
 ```bash
-memtrace install --only cursor --local
+npx memtrace-skills install --only cursor --local
 ```
 
-### Other Editors (Windsurf, VS Code, Cline)
+### Codex, Windsurf, VS Code, Hermes, OpenCode, and Kiro
 
-After `npm install -g memtrace`, add the MCP server to your editor's config:
+The installer also writes skills/guidance and MCP configuration for the newer agent surfaces:
+
+| Agent | Global skills / guidance | Global MCP config | Project-local support |
+|:------|:-------------------------|:------------------|:----------------------|
+| **Codex** | `~/.agents/skills/` | `~/.codex/config.toml` | `.agents/skills/`, `.codex/config.toml` |
+| **Windsurf** | `~/.codeium/windsurf/skills/` | `~/.codeium/windsurf/mcp_config.json` | `.windsurf/skills/`; MCP remains user-level |
+| **VS Code / Copilot** | `~/.copilot/skills/` | VS Code user `mcp.json` | `.github/skills/`, `.vscode/mcp.json` |
+| **Hermes** | `~/.hermes/skills/` | `~/.hermes/config.yaml` | user-level only |
+| **OpenCode** | `~/.config/opencode/skills/` | `~/.config/opencode/opencode.json` | `.opencode/skills/`, `opencode.json` |
+| **Kiro** | `~/.kiro/steering/` | `~/.kiro/settings/mcp.json` | `.kiro/steering/`, `.kiro/settings/mcp.json` |
+
+Install only selected integrations:
+
+```bash
+npx memtrace-skills install --only codex,windsurf,vscode,hermes,opencode,kiro
+```
+
+Install project-local config where supported:
+
+```bash
+npx memtrace-skills install --only codex,vscode,opencode,kiro --local
+```
+
+### Other MCP Clients
+
+For Cline, Roo Code, or any client that only needs MCP tools, add this server manually:
 
 ```json
 {
@@ -280,6 +313,10 @@ After `npm install -g memtrace`, add the MCP server to your editor's config:
 |:-------|:------------|
 | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
 | **VS Code (Copilot)** | `.vscode/mcp.json` in your project root |
+| **Codex** | `~/.codex/config.toml` or `.codex/config.toml` |
+| **Hermes** | `~/.hermes/config.yaml` |
+| **OpenCode** | `~/.config/opencode/opencode.json` or project `opencode.json` |
+| **Kiro** | `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json` |
 | **Cline** | Cline MCP settings in the extension panel |
 
 </details>

package/bin/memtrace.js

@@ -6,6 +6,7 @@ const path = require("path");
 const fs   = require("fs");
 const { spawnSync, spawn } = require("child_process");
 const { getBinaryPath } = require("../install.js");
+const { platformBinary, spawnOptionsForPlatform } = require("../lib/spawn-helper");
 
 // ── Handle `memtrace uninstall` before delegating to the Rust binary ────────
 // npm v7+ does NOT fire preuninstall hooks for global packages (npm/cli#3042).
@@ -27,14 +28,20 @@ const args = process.argv.slice(2);
 // which now resolves to the freshly-installed shim, not this old one.
 
 if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
-  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
-  const memtraceCmd = process.platform === "win32" ? "memtrace.cmd" : "memtrace";
+  // `npm.cmd` on win32 needs `shell: true` since the CVE-2024-27980
+  // mitigation in Node 18.20+ / 20.12+ / 21.7+. The helpers in
+  // `lib/spawn-helper.js` are unit + property tested.
+  const npmCmd = platformBinary("npm", process.platform);
+  const memtraceCmd = platformBinary("memtrace", process.platform);
 
   process.stdout.write("memtrace: fetching latest from npm registry…\n");
   const installResult = spawnSync(
     npmCmd,
     ["install", "-g", "memtrace@latest"],
-    { stdio: "inherit", env: process.env }
+    spawnOptionsForPlatform(process.platform, {
+      stdio: "inherit",
+      env: process.env,
+    })
   );
 
   if (installResult.error) {
@@ -60,10 +67,15 @@ if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
   process.stdout.write(
     `memtrace: upgrade complete — running 'memtrace ${rest.join(" ")}'\n`
   );
-  const runResult = spawnSync(memtraceCmd, rest, {
-    stdio: "inherit",
-    env: process.env,
-  });
+  // memtrace.cmd on Windows needs the same shell:true handling.
+  const runResult = spawnSync(
+    memtraceCmd,
+    rest,
+    spawnOptionsForPlatform(process.platform, {
+      stdio: "inherit",
+      env: process.env,
+    })
+  );
   if (runResult.error) {
     console.error(`memtrace: failed to chain command — ${runResult.error.message}`);
     process.exit(1);

package/install.js

@@ -5,6 +5,7 @@ const os = require("os");
 const path = require("path");
 const fs = require("fs");
 const { spawnSync } = require("child_process");
+const { platformBinary, spawnOptionsForPlatform } = require("./lib/spawn-helper");
 
 // ── Platform binary resolution (preserved from legacy) ───────────────────────
 
@@ -68,10 +69,20 @@ function selfHealPlatformPackage() {
     `memtrace: optional platform dep ${pkg} was not installed; ` +
     `running 'npm install ${versioned}' to fetch it…`
   );
+  // On Windows, Node.js 18.20+ / 20.12+ / 21.7+ refuse to spawn `.cmd`
+  // and `.bat` files without `shell: true` as part of the
+  // CVE-2024-27980 mitigation. The platform-aware helpers in
+  // `lib/spawn-helper.js` are unit + property tested so the shell
+  // flag is set IFF process.platform === "win32" — see
+  // `test/spawn-helper.test.js` for the full regression coverage.
   const result = spawnSync(
-    process.platform === "win32" ? "npm.cmd" : "npm",
+    platformBinary("npm", process.platform),
     ["install", "--no-save", versioned],
-    { cwd: __dirname, stdio: "inherit", env: process.env }
+    spawnOptionsForPlatform(process.platform, {
+      cwd: __dirname,
+      stdio: "inherit",
+      env: process.env,
+    })
   );
   if (result.status !== 0) {
     console.warn(

package/installer/dist/commands/doctor.js

@@ -3,6 +3,7 @@ import os from 'os';
 import path from 'path';
 import { commandExists, execCommand } from '../utils.js';
 import { safeReadJson } from '../fs-safe.js';
+import { ALL_TRANSFORMERS } from '../transformers/index.js';
 async function checkBinary() {
     if (!(await commandExists('memtrace')))
         return { binaryOk: false };
@@ -28,18 +29,58 @@ function countMemtraceSkills(dir) {
         .filter(e => fs.existsSync(path.join(dir, e, 'SKILL.md')))
         .length;
 }
+function countMemtraceMarkdown(dir) {
+    if (!fs.existsSync(dir))
+        return 0;
+    return fs.readdirSync(dir)
+        .filter(e => e.startsWith('memtrace-') && e.endsWith('.md'))
+        .length;
+}
 function mcpHasMemtrace(file) {
     const { value } = safeReadJson(file);
     if (!value)
         return false;
     return Boolean(value.mcpServers && value.mcpServers['memtrace']);
 }
+function vscodeMcpHasMemtrace(file) {
+    const { value } = safeReadJson(file);
+    if (!value)
+        return false;
+    return Boolean(value.servers && value.servers['memtrace']);
+}
+function opencodeMcpHasMemtrace(file) {
+    const { value } = safeReadJson(file);
+    if (!value)
+        return false;
+    return Boolean(value.mcp && value.mcp['memtrace']);
+}
 function codexMcpHasMemtrace(file) {
     if (!fs.existsSync(file))
         return false;
     const raw = fs.readFileSync(file, 'utf-8');
     return /^\s*\[mcp_servers\.(?:"memtrace"|memtrace)\]\s*$/m.test(raw);
 }
+function hermesMcpHasMemtrace(file) {
+    if (!fs.existsSync(file))
+        return false;
+    const raw = fs.readFileSync(file, 'utf-8');
+    return /^mcp_servers:\s*$(?:[\s\S]*?)^\s{2}memtrace:\s*$/m.test(raw);
+}
+function opencodeConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
+    return path.join(xdg, 'opencode');
+}
+function vscodeUserMcpPath() {
+    if (process.platform === 'win32') {
+        const appData = process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming');
+        return path.join(appData, 'Code', 'User', 'mcp.json');
+    }
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+    }
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
+    return path.join(xdg, 'Code', 'User', 'mcp.json');
+}
 function checkAgent(agent) {
     if (agent === 'claude') {
         const skillsDir = path.join(os.homedir(), '.claude', 'skills');
@@ -63,6 +104,61 @@ function checkAgent(agent) {
             mcpConfigPath,
         };
     }
+    if (agent === 'windsurf') {
+        const skillsDir = path.join(os.homedir(), '.codeium', 'windsurf', 'skills');
+        const mcpConfigPath = path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: mcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'vscode') {
+        const skillsDir = path.join(os.homedir(), '.copilot', 'skills');
+        const mcpConfigPath = vscodeUserMcpPath();
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: vscodeMcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'hermes') {
+        const skillsDir = path.join(os.homedir(), '.hermes', 'skills');
+        const mcpConfigPath = path.join(os.homedir(), '.hermes', 'config.yaml');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: hermesMcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'opencode') {
+        const skillsDir = path.join(opencodeConfigDir(), 'skills');
+        const mcpConfigPath = path.join(opencodeConfigDir(), 'opencode.json');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: opencodeMcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
+    if (agent === 'kiro') {
+        const skillsDir = path.join(os.homedir(), '.kiro', 'steering');
+        const mcpConfigPath = path.join(os.homedir(), '.kiro', 'settings', 'mcp.json');
+        return {
+            agent,
+            skillsFound: countMemtraceMarkdown(skillsDir),
+            skillsDir,
+            mcpRegistered: mcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
     const skillsDir = path.join(os.homedir(), '.cursor', 'skills');
     const mcpConfigPath = path.join(os.homedir(), '.cursor', 'mcp.json');
     return {
@@ -77,7 +173,7 @@ export async function runDoctorChecks() {
     const binary = await checkBinary();
     return {
         ...binary,
-        agents: [checkAgent('claude'), checkAgent('cursor'), checkAgent('codex')],
+        agents: ALL_TRANSFORMERS.map(t => checkAgent(t.name)),
     };
 }
 export function formatReport(r) {

package/installer/dist/index.js

@@ -13,8 +13,8 @@ function parseOnly(val) {
 program
     .command('install')
     .description('Install memtrace skills and register MCP for selected agents')
-    .option('--only <agents>', 'comma-separated agent names (claude,cursor,codex)', parseOnly)
-    .option('--local', 'install into the current project (./.claude/, ./.cursor/, ./.agents/)', false)
+    .option('--only <agents>', 'comma-separated agent names (claude,cursor,codex,windsurf,vscode,hermes,opencode,kiro)', parseOnly)
+    .option('--local', 'install into the current project where the selected agent supports project scope', false)
     .option('--global', 'install globally (~/.claude/, ~/.cursor/, ~/.agents/) [default]', false)
     .option('--skip-mcp', 'write skills only, skip MCP server registration', false)
     .option('--repair', 'alias for install — run after fixing a corrupt settings file')

package/installer/dist/transformers/claude.js

@@ -344,6 +344,13 @@ export async function installClaudePlugin(skills, memtraceBinaryPath) {
  */
 function writeUserLevelSkills(skills) {
     const userSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+    if (fs.existsSync(userSkillsDir)) {
+        for (const entry of fs.readdirSync(userSkillsDir)) {
+            if (entry.startsWith('memtrace-')) {
+                fs.rmSync(path.join(userSkillsDir, entry), { recursive: true, force: true });
+            }
+        }
+    }
     for (const skill of skills) {
         const skillName = skill.filename.replace(/\.md$/, '');
         const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
@@ -432,6 +439,13 @@ export const claudeTransformer = {
         }
         // Local scope: write skills into <cwd>/.claude/skills/
         const skillsDir = path.join(ctx.cwd, '.claude', 'skills');
+        if (fs.existsSync(skillsDir)) {
+            for (const entry of fs.readdirSync(skillsDir)) {
+                if (entry.startsWith('memtrace-')) {
+                    fs.rmSync(path.join(skillsDir, entry), { recursive: true, force: true });
+                }
+            }
+        }
         let count = 0;
         for (const skill of skills) {
             const skillName = skill.filename.replace(/\.md$/, '');

package/installer/dist/transformers/codex.js

@@ -87,6 +87,13 @@ export const codexTransformer = {
     name: 'codex',
     async install(skills, ctx) {
         const rootDir = skillsRoot(ctx);
+        if (fs.existsSync(rootDir)) {
+            for (const entry of fs.readdirSync(rootDir)) {
+                if (entry.startsWith('memtrace-')) {
+                    fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
+                }
+            }
+        }
         for (const s of skills)
             writeSkill(s, rootDir);
         let mcpRegistered = false;

package/installer/dist/transformers/cursor.js

@@ -39,6 +39,13 @@ export const cursorTransformer = {
     name: 'cursor',
     async install(skills, ctx) {
         const rootDir = skillsRoot(ctx);
+        if (fs.existsSync(rootDir)) {
+            for (const entry of fs.readdirSync(rootDir)) {
+                if (entry.startsWith('memtrace-')) {
+                    fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
+                }
+            }
+        }
         for (const s of skills)
             writeSkill(s, rootDir);
         let mcpRegistered = false;

package/installer/dist/transformers/hermes.d.ts

@@ -0,0 +1,5 @@
+import { Transformer } from './types.js';
+export declare function hermesConfigPath(): string;
+export declare function registerHermesMcpAt(configFile: string, binary: string): void;
+export declare function removeHermesMcpAt(configFile: string): void;
+export declare const hermesTransformer: Transformer;

package/installer/dist/transformers/hermes.js

@@ -0,0 +1,136 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { MEMTRACE_MCP_ENV, MCP_SERVER_NAME, removeMemtraceSkills, writeSkills, writeTextAtomic, } from './shared.js';
+function skillsRoot(ctx) {
+    void ctx;
+    return path.join(os.homedir(), '.hermes', 'skills');
+}
+export function hermesConfigPath() {
+    return path.join(os.homedir(), '.hermes', 'config.yaml');
+}
+function yamlQuote(value) {
+    return `"${value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')}"`;
+}
+function memtraceYamlBlock(binary) {
+    return [
+        `  ${MCP_SERVER_NAME}:`,
+        `    command: ${yamlQuote(binary)}`,
+        '    args:',
+        '      - "mcp"',
+        '    env:',
+        ...Object.entries(MEMTRACE_MCP_ENV).map(([key, value]) => `      ${key}: ${yamlQuote(value)}`),
+        '    enabled: true',
+    ];
+}
+function removeMemtraceYamlBlock(raw) {
+    const lines = raw.split(/\r?\n/);
+    const out = [];
+    let inMcpServers = false;
+    let skippingMemtrace = false;
+    for (const line of lines) {
+        if (/^\S/.test(line) && !line.startsWith('mcp_servers:')) {
+            inMcpServers = false;
+            skippingMemtrace = false;
+        }
+        if (/^mcp_servers:\s*$/.test(line)) {
+            inMcpServers = true;
+            skippingMemtrace = false;
+            out.push(line);
+            continue;
+        }
+        if (inMcpServers && new RegExp(`^\\s{2}${MCP_SERVER_NAME}:\\s*$`).test(line)) {
+            skippingMemtrace = true;
+            continue;
+        }
+        if (skippingMemtrace) {
+            if (/^\s{2}\S/.test(line) || /^\S/.test(line)) {
+                skippingMemtrace = false;
+            }
+            else {
+                continue;
+            }
+        }
+        if (!skippingMemtrace)
+            out.push(line);
+    }
+    return out.join('\n').trimEnd();
+}
+function removeEmptyMcpServersSection(raw) {
+    const lines = raw.split(/\r?\n/);
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!/^mcp_servers:\s*$/.test(line)) {
+            out.push(line);
+            continue;
+        }
+        let j = i + 1;
+        while (j < lines.length && /^\s*$/.test(lines[j]))
+            j++;
+        if (j >= lines.length || /^\S/.test(lines[j])) {
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join('\n').trimEnd();
+}
+export function registerHermesMcpAt(configFile, binary) {
+    const existing = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf-8') : '';
+    const withoutMemtrace = removeMemtraceYamlBlock(existing);
+    const hasMcpServers = /^mcp_servers:\s*$/m.test(withoutMemtrace);
+    const block = memtraceYamlBlock(binary);
+    let next;
+    if (hasMcpServers) {
+        const lines = withoutMemtrace.split(/\r?\n/);
+        const index = lines.findIndex(line => /^mcp_servers:\s*$/.test(line));
+        lines.splice(index + 1, 0, ...block);
+        next = lines.join('\n');
+    }
+    else {
+        next = `${withoutMemtrace}${withoutMemtrace ? '\n\n' : ''}mcp_servers:\n${block.join('\n')}`;
+    }
+    writeTextAtomic(configFile, `${next.trimEnd()}\n`);
+}
+export function removeHermesMcpAt(configFile) {
+    if (!fs.existsSync(configFile))
+        return;
+    const next = removeEmptyMcpServersSection(removeMemtraceYamlBlock(fs.readFileSync(configFile, 'utf-8')));
+    if (next.trim())
+        writeTextAtomic(configFile, `${next.trimEnd()}\n`);
+    else
+        fs.unlinkSync(configFile);
+}
+export const hermesTransformer = {
+    name: 'hermes',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        const count = writeSkills(skills, rootDir);
+        const warnings = [];
+        let mcpRegistered = false;
+        const mcpConfigPath = hermesConfigPath();
+        if (!ctx.skipMcp) {
+            registerHermesMcpAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = true;
+            if (ctx.scope === 'local') {
+                warnings.push('Hermes skills and MCP config are user-level; wrote ~/.hermes/skills and ~/.hermes/config.yaml.');
+            }
+        }
+        return {
+            agent: 'hermes',
+            skillsWritten: count,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSkills(skillsRoot(ctx));
+        removeHermesMcpAt(hermesConfigPath());
+    },
+};

package/installer/dist/transformers/index.d.ts

@@ -2,7 +2,12 @@ import { Transformer } from './types.js';
 import { claudeTransformer } from './claude.js';
 import { cursorTransformer } from './cursor.js';
 import { codexTransformer } from './codex.js';
+import { windsurfTransformer } from './windsurf.js';
+import { vscodeTransformer } from './vscode.js';
+import { hermesTransformer } from './hermes.js';
+import { opencodeTransformer } from './opencode.js';
+import { kiroTransformer } from './kiro.js';
 export declare const ALL_TRANSFORMERS: Transformer[];
 export declare function findTransformer(name: string): Transformer | undefined;
-export { claudeTransformer, cursorTransformer, codexTransformer };
+export { claudeTransformer, cursorTransformer, codexTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, };
 export type { Transformer, InstallContext, InstallResult, TransformResult } from './types.js';

package/installer/dist/transformers/index.js

@@ -1,8 +1,22 @@
 import { claudeTransformer } from './claude.js';
 import { cursorTransformer } from './cursor.js';
 import { codexTransformer } from './codex.js';
-export const ALL_TRANSFORMERS = [claudeTransformer, cursorTransformer, codexTransformer];
+import { windsurfTransformer } from './windsurf.js';
+import { vscodeTransformer } from './vscode.js';
+import { hermesTransformer } from './hermes.js';
+import { opencodeTransformer } from './opencode.js';
+import { kiroTransformer } from './kiro.js';
+export const ALL_TRANSFORMERS = [
+    claudeTransformer,
+    cursorTransformer,
+    codexTransformer,
+    windsurfTransformer,
+    vscodeTransformer,
+    hermesTransformer,
+    opencodeTransformer,
+    kiroTransformer,
+];
 export function findTransformer(name) {
     return ALL_TRANSFORMERS.find(t => t.name === name);
 }
-export { claudeTransformer, cursorTransformer, codexTransformer };
+export { claudeTransformer, cursorTransformer, codexTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, };

package/installer/dist/transformers/kiro.d.ts

@@ -0,0 +1,2 @@
+import { Transformer } from './types.js';
+export declare const kiroTransformer: Transformer;

package/installer/dist/transformers/kiro.js

@@ -0,0 +1,69 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { registerMcpServersJsonAt, removeMcpServersJsonAt, skillName, } from './shared.js';
+function steeringRoot(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(os.homedir(), '.kiro', 'steering')
+        : path.join(ctx.cwd, '.kiro', 'steering');
+}
+function mcpPath(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(os.homedir(), '.kiro', 'settings', 'mcp.json')
+        : path.join(ctx.cwd, '.kiro', 'settings', 'mcp.json');
+}
+function writeSteering(skill, rootDir) {
+    const name = skillName(skill);
+    const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
+    const content = [
+        '---',
+        'inclusion: auto',
+        `name: ${name}`,
+        `description: "${safeDesc}"`,
+        '---',
+        '',
+        skill.body,
+    ].join('\n');
+    fs.mkdirSync(rootDir, { recursive: true });
+    fs.writeFileSync(path.join(rootDir, `${name}.md`), content);
+}
+function removeMemtraceSteering(rootDir) {
+    if (!fs.existsSync(rootDir))
+        return;
+    for (const entry of fs.readdirSync(rootDir)) {
+        if (entry.startsWith('memtrace-') && entry.endsWith('.md')) {
+            fs.rmSync(path.join(rootDir, entry), { force: true });
+        }
+    }
+}
+export const kiroTransformer = {
+    name: 'kiro',
+    async install(skills, ctx) {
+        const rootDir = steeringRoot(ctx);
+        removeMemtraceSteering(rootDir);
+        for (const skill of skills)
+            writeSteering(skill, rootDir);
+        let mcpRegistered = false;
+        const warnings = [];
+        const mcpConfigPath = mcpPath(ctx);
+        if (!ctx.skipMcp) {
+            const result = registerMcpServersJsonAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+            if (!mcpRegistered && result.backupPath) {
+                warnings.push(`Kiro MCP config was malformed; backed up to ${result.backupPath}.`);
+            }
+        }
+        return {
+            agent: 'kiro',
+            skillsWritten: skills.length,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSteering(steeringRoot(ctx));
+        removeMcpServersJsonAt(mcpPath(ctx));
+    },
+};

package/installer/dist/transformers/opencode.d.ts

@@ -0,0 +1,2 @@
+import { Transformer } from './types.js';
+export declare const opencodeTransformer: Transformer;

package/installer/dist/transformers/opencode.js

@@ -0,0 +1,46 @@
+import os from 'os';
+import path from 'path';
+import { registerOpenCodeMcpAt, removeMemtraceSkills, removeOpenCodeMcpAt, writeSkills, } from './shared.js';
+function opencodeConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
+    return path.join(xdg, 'opencode');
+}
+function skillsRoot(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(opencodeConfigDir(), 'skills')
+        : path.join(ctx.cwd, '.opencode', 'skills');
+}
+function mcpPath(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(opencodeConfigDir(), 'opencode.json')
+        : path.join(ctx.cwd, 'opencode.json');
+}
+export const opencodeTransformer = {
+    name: 'opencode',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        const count = writeSkills(skills, rootDir, { compatibility: 'opencode' });
+        let mcpRegistered = false;
+        const warnings = [];
+        const mcpConfigPath = mcpPath(ctx);
+        if (!ctx.skipMcp) {
+            const result = registerOpenCodeMcpAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+            if (!mcpRegistered && result.backupPath) {
+                warnings.push(`OpenCode config was malformed; backed up to ${result.backupPath}.`);
+            }
+        }
+        return {
+            agent: 'opencode',
+            skillsWritten: count,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSkills(skillsRoot(ctx));
+        removeOpenCodeMcpAt(mcpPath(ctx));
+    },
+};

package/installer/dist/transformers/shared.d.ts

@@ -0,0 +1,20 @@
+import { Skill } from '../skills.js';
+export declare const MCP_SERVER_NAME = "memtrace";
+export declare const MEMTRACE_MCP_ENV: {
+    MEMTRACE_ARCADEDB_BOLT_URL: string;
+};
+export declare function skillName(skill: Skill): string;
+export declare function skillMarkdown(skill: Skill, extraFrontmatter?: Record<string, string>): string;
+export declare function writeSkills(skills: Skill[], rootDir: string, extraFrontmatter?: Record<string, string>): number;
+export declare function removeMemtraceSkills(rootDir: string): void;
+export declare function writeTextAtomic(filePath: string, content: string): void;
+export interface JsonMcpResult {
+    registered: boolean;
+    backupPath?: string;
+}
+export declare function registerMcpServersJsonAt(filePath: string, binary: string): JsonMcpResult;
+export declare function removeMcpServersJsonAt(filePath: string): void;
+export declare function registerVsCodeMcpAt(filePath: string, binary: string): JsonMcpResult;
+export declare function removeVsCodeMcpAt(filePath: string): void;
+export declare function registerOpenCodeMcpAt(filePath: string, binary: string): JsonMcpResult;
+export declare function removeOpenCodeMcpAt(filePath: string): void;

package/installer/dist/transformers/shared.js

@@ -0,0 +1,124 @@
+import fs from 'fs';
+import path from 'path';
+import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
+export const MCP_SERVER_NAME = 'memtrace';
+export const MEMTRACE_MCP_ENV = { MEMTRACE_ARCADEDB_BOLT_URL: 'bolt://localhost:7687' };
+export function skillName(skill) {
+    return skill.filename.replace(/\.md$/, '');
+}
+export function skillMarkdown(skill, extraFrontmatter = {}) {
+    const name = skillName(skill);
+    const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
+    const extra = Object.entries(extraFrontmatter)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join('\n');
+    return `---\nname: ${name}\ndescription: "${safeDesc}"${extra ? `\n${extra}` : ''}\n---\n\n${skill.body}`;
+}
+export function writeSkills(skills, rootDir, extraFrontmatter = {}) {
+    removeMemtraceSkills(rootDir);
+    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'), skillMarkdown(skill, extraFrontmatter));
+    }
+    return skills.length;
+}
+export function removeMemtraceSkills(rootDir) {
+    if (!fs.existsSync(rootDir))
+        return;
+    for (const entry of fs.readdirSync(rootDir)) {
+        if (entry.startsWith('memtrace-')) {
+            fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
+        }
+    }
+}
+export function writeTextAtomic(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmpPath, content);
+    fs.renameSync(tmpPath, filePath);
+}
+export function registerMcpServersJsonAt(filePath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(filePath);
+    if (corrupted)
+        return { registered: false, backupPath };
+    const cfg = (value ?? {});
+    cfg.mcpServers = cfg.mcpServers ?? {};
+    cfg.mcpServers[MCP_SERVER_NAME] = {
+        command: binary,
+        args: ['mcp'],
+        env: MEMTRACE_MCP_ENV,
+    };
+    writeJsonAtomic(filePath, cfg);
+    return { registered: true };
+}
+export function removeMcpServersJsonAt(filePath) {
+    const { value, corrupted } = safeReadJson(filePath);
+    if (corrupted || !value?.mcpServers?.[MCP_SERVER_NAME])
+        return;
+    delete value.mcpServers[MCP_SERVER_NAME];
+    if (Object.keys(value.mcpServers).length === 0)
+        delete value.mcpServers;
+    if (Object.keys(value).length === 0)
+        fs.unlinkSync(filePath);
+    else
+        writeJsonAtomic(filePath, value);
+}
+export function registerVsCodeMcpAt(filePath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(filePath);
+    if (corrupted)
+        return { registered: false, backupPath };
+    const cfg = (value ?? {});
+    cfg.servers = cfg.servers ?? {};
+    cfg.servers[MCP_SERVER_NAME] = {
+        type: 'stdio',
+        command: binary,
+        args: ['mcp'],
+        env: MEMTRACE_MCP_ENV,
+    };
+    writeJsonAtomic(filePath, cfg);
+    return { registered: true };
+}
+export function removeVsCodeMcpAt(filePath) {
+    const { value, corrupted } = safeReadJson(filePath);
+    if (corrupted || !value?.servers?.[MCP_SERVER_NAME])
+        return;
+    delete value.servers[MCP_SERVER_NAME];
+    if (Object.keys(value.servers).length === 0)
+        delete value.servers;
+    if (Object.keys(value).length === 0)
+        fs.unlinkSync(filePath);
+    else
+        writeJsonAtomic(filePath, value);
+}
+export function registerOpenCodeMcpAt(filePath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(filePath);
+    if (corrupted)
+        return { registered: false, backupPath };
+    const cfg = (value ?? {});
+    cfg.$schema = cfg.$schema ?? 'https://opencode.ai/config.json';
+    cfg.mcp = cfg.mcp ?? {};
+    cfg.mcp[MCP_SERVER_NAME] = {
+        type: 'local',
+        command: [binary, 'mcp'],
+        enabled: true,
+        environment: MEMTRACE_MCP_ENV,
+    };
+    writeJsonAtomic(filePath, cfg);
+    return { registered: true };
+}
+export function removeOpenCodeMcpAt(filePath) {
+    const { value, corrupted } = safeReadJson(filePath);
+    if (corrupted || !value?.mcp?.[MCP_SERVER_NAME])
+        return;
+    delete value.mcp[MCP_SERVER_NAME];
+    if (Object.keys(value.mcp).length === 0)
+        delete value.mcp;
+    const remainingKeys = Object.keys(value);
+    if (remainingKeys.length === 0 || (remainingKeys.length === 1 && remainingKeys[0] === '$schema')) {
+        fs.unlinkSync(filePath);
+    }
+    else
+        writeJsonAtomic(filePath, value);
+}

package/installer/dist/transformers/types.d.ts

@@ -22,18 +22,19 @@ export interface InstallContext {
     skipMcp?: boolean;
 }
 export interface InstallResult {
-    agent: string;
+    agent: AgentName;
     skillsWritten: number;
     skillsDir: string;
     mcpConfigPath?: string;
     mcpRegistered: boolean;
     warnings: string[];
 }
+export type AgentName = 'claude' | 'cursor' | 'codex' | 'windsurf' | 'vscode' | 'hermes' | 'opencode' | 'kiro';
 /**
  * One transformer per supported AI coding agent.
  */
 export interface Transformer {
-    name: 'claude' | 'cursor' | 'codex';
+    name: AgentName;
     install(skills: Skill[], ctx: InstallContext): Promise<InstallResult>;
     uninstall(ctx: InstallContext): Promise<void>;
 }

package/installer/dist/transformers/vscode.d.ts

@@ -0,0 +1,3 @@
+import { Transformer } from './types.js';
+export declare function vscodeUserMcpPath(): string;
+export declare const vscodeTransformer: Transformer;

package/installer/dist/transformers/vscode.js

@@ -0,0 +1,53 @@
+import os from 'os';
+import path from 'path';
+import { registerVsCodeMcpAt, removeMemtraceSkills, removeVsCodeMcpAt, writeSkills, } from './shared.js';
+function skillsRoot(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(os.homedir(), '.copilot', 'skills')
+        : path.join(ctx.cwd, '.github', 'skills');
+}
+export function vscodeUserMcpPath() {
+    if (process.platform === 'win32') {
+        const appData = process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming');
+        return path.join(appData, 'Code', 'User', 'mcp.json');
+    }
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+    }
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
+    return path.join(xdg, 'Code', 'User', 'mcp.json');
+}
+function mcpPath(ctx) {
+    return ctx.scope === 'global'
+        ? vscodeUserMcpPath()
+        : path.join(ctx.cwd, '.vscode', 'mcp.json');
+}
+export const vscodeTransformer = {
+    name: 'vscode',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        const count = writeSkills(skills, rootDir);
+        let mcpRegistered = false;
+        const warnings = [];
+        const mcpConfigPath = mcpPath(ctx);
+        if (!ctx.skipMcp) {
+            const result = registerVsCodeMcpAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+            if (!mcpRegistered && result.backupPath) {
+                warnings.push(`VS Code MCP config was malformed; backed up to ${result.backupPath}.`);
+            }
+        }
+        return {
+            agent: 'vscode',
+            skillsWritten: count,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSkills(skillsRoot(ctx));
+        removeVsCodeMcpAt(mcpPath(ctx));
+    },
+};

package/installer/dist/transformers/windsurf.d.ts

@@ -0,0 +1,3 @@
+import { Transformer } from './types.js';
+export declare function windsurfMcpPath(): string;
+export declare const windsurfTransformer: Transformer;

package/installer/dist/transformers/windsurf.js

@@ -0,0 +1,43 @@
+import os from 'os';
+import path from 'path';
+import { registerMcpServersJsonAt, removeMcpServersJsonAt, removeMemtraceSkills, writeSkills, } from './shared.js';
+function skillsRoot(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(os.homedir(), '.codeium', 'windsurf', 'skills')
+        : path.join(ctx.cwd, '.windsurf', 'skills');
+}
+export function windsurfMcpPath() {
+    return path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+}
+export const windsurfTransformer = {
+    name: 'windsurf',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        const count = writeSkills(skills, rootDir);
+        const warnings = [];
+        let mcpRegistered = false;
+        const mcpConfigPath = windsurfMcpPath();
+        if (!ctx.skipMcp) {
+            const result = registerMcpServersJsonAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+            if (!mcpRegistered && result.backupPath) {
+                warnings.push(`Windsurf MCP config was malformed; backed up to ${result.backupPath}.`);
+            }
+            if (ctx.scope === 'local') {
+                warnings.push('Windsurf MCP config is user-level only; wrote ~/.codeium/windsurf/mcp_config.json.');
+            }
+        }
+        return {
+            agent: 'windsurf',
+            skillsWritten: count,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSkills(skillsRoot(ctx));
+        removeMcpServersJsonAt(windsurfMcpPath());
+    },
+};

package/installer/package.json

@@ -27,6 +27,7 @@
     "@types/fs-extra": "^11.0.0",
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^4.1.4",
+    "fast-check": "^4.7.0",
     "typescript": "^5.4.0",
     "vitest": "^4.1.4"
   },

package/installer/skills/commands/memtrace-search.md

@@ -62,6 +62,23 @@ Save the symbol `id` from results — pass it to:
 - `get_symbol_context` for a 360-degree view
 - `get_impact` to assess blast radius before changes
 
+### Multi-word natural-language queries
+
+When your query is 3+ words and feels descriptive (e.g. "validate auth token", "find HTTP server error"), don't stop at the first `find_code` call:
+
+1. First try the verbatim query.
+2. If results look generic or the right doc isn't at rank 1, fan out **in parallel** with up to 3 identifier-shaped reshapes:
+   - camelCase: "validate auth token" → `validateAuthToken`
+   - snake_case: → `validate_auth_token`
+   - Domain-likely identifiers: → `auth_token`, `tokenValidator`, `verifyToken`
+3. Memtrace's tokenizer splits camelCase / snake / kebab at index time, so reshaped queries hit identifier names directly.
+4. Take the union of top-5 from each call, dedupe by `file_path:start_line`.
+
+**Worked examples** (verbatim → reshapes to try in parallel):
+- "validate auth token" → `validateAuthToken`, `validate_auth_token`, `verifyToken`
+- "find http server error" → `findHttpServerError`, `http_error`, `serverError`
+- "render value panel" → `renderValuePanel`, `ValuePanel`, `value_panel`
+
 ## Common Mistakes
 
 | Mistake | Reality |

package/installer/skills/workflows/memtrace-first.md

@@ -9,12 +9,15 @@ description: "Always use first for indexed source-code repos before searching fi
 
 ```
 IF THE REPO IS INDEXED IN MEMTRACE → USE MEMTRACE TOOLS FIRST.
-Memtrace returns exact file_path + start_line + end_line for every result.
-Read the file at THAT location. Do not Grep/Glob/Find to "locate" anything
-already in the graph.
+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.
 ```
 
-Memtrace is the memory layer of the codebase. It has the full knowledge graph: every symbol, call, import, community, process, and API — with time dimension. File tools are blind to this structure.
+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.
 
 **97% better accuracy. 83% fewer wasted tokens. No exceptions for what's in the graph.**
 
@@ -56,7 +59,7 @@ These are the ONLY cases where file tools beat memtrace:
   (`.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.** Once memtrace has handed you `file_path:start_line:end_line`, use `Read` — never substitute `Grep` for `Read`.
+- **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.
 
@@ -64,16 +67,18 @@ For everything else inside the indexed repo, memtrace is the right tool.
 
 | Question Claude is asking | Right tool |
 |---|---|
-| "Where is symbol `foo` defined?" | `find_symbol(name="foo")` → file:line. Then `Read` that range. |
+| "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. |
 | "What calls `foo`?" | `get_symbol_context(name="foo")` → callers with file:line each. |
-| "How does authentication work?" | `find_code(query="authentication")` → ranked symbols with file:line. |
+| "How does authentication work?" | `find_code(query="authentication")` → `get_symbol_context` on the top hit, NOT a source read. |
+| "Find behavior X" with multi-word phrase (3+ words) | `find_code(verbatim)` first; if low confidence, fan out with identifier-shaped reshapes (camelCase / snake_case). |
 | "Find the function that uses `STRIPE_KEY_FOO_BAR`" | `find_code(query="STRIPE_KEY_FOO_BAR")` → semantic finds it inside any embedded body. |
 | "Where's that error message `'connection refused for tenant'`?" | `find_code(query="connection refused for tenant")` → semantic catches it. |
 | "What breaks if I change `foo`?" | `get_impact(name="foo")` → blast radius with file:line. |
 | "What changed in `auth.ts` last week?" | `get_evolution(file_path="auth.ts", from="7d ago")`. |
 | "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
 | "Find this string in my `.env`." | `Grep` (non-source artifact). |
-| "Read file I already have the path of." | `Read` (path is known). |
+| "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. |
+| "Read config/doc file I already have the path of." | `Read` (non-source artifact, path is known). |
 
 ## Parameter Types — Read This Before Calling Any Tool
 
@@ -101,7 +106,7 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 | What you need | Use instead of Grep/Glob/Read |
 |---|---|
 | Find a function / class / symbol | `find_symbol` or `find_code` |
-| Understand how something works | `get_symbol_context` |
+| Understand how something works | `get_symbol_context` (the default next step) |
 | Find all callers of a function | `get_symbol_context` (callers field) |
 | Find all callees / dependencies | `get_symbol_context` (callees field) |
 | Trace a request / execution path | `get_process_flow` |
@@ -116,14 +121,15 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 | Dependency between two symbols | `find_dependency_path` |
 | What files change together? | `get_cochange_context` |
 | Architecture overview | `list_communities` + `find_central_symbols` |
+| About to edit / quote — need exact lines | Bounded `Read(file, offset=start_line, limit=N)` (preferred), or `get_source_window` for path-resolution parity |
 
 ## Standard Workflows
 
 ### "How does X work?" / "Explain X"
 1. `find_symbol` or `find_code` → locate the symbol
-2. `get_symbol_context` → callers, callees, community, processes
+2. `get_symbol_context` → callers, callees, community, processes (this usually answers "how it works")
 3. `get_process_flow` (if it's a process/request path)
-4. Read source ONLY for the exact lines you need to quote
+4. Only if you need to quote source: bounded `Read` at start_line..end_line, or `get_source_window`
 
 ### Debugging "X is broken"
 1. `find_symbol` → locate the broken thing
@@ -135,7 +141,7 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 ### "Where is X defined / called?"
 1. `find_symbol` with `fuzzy: true`
 2. `get_symbol_context` for full caller/callee map
-3. Read specific file only after locating exact line
+3. Only if you need source text: bounded `Read` at start_line..end_line, or `get_source_window`
 
 ### Before any code modification
 1. `find_symbol` → confirm you have the right target
@@ -150,7 +156,7 @@ You are violating this skill if you think:
 |---|---|
 | "Let me grep for this" | `find_code` or `find_symbol` is faster and structurally aware |
 | "Let me glob for the file" | `find_symbol` returns exact location with context |
-| "Let me read the whole file" | `get_symbol_context` gives you only what matters |
+| "Let me read the whole file" | `get_symbol_context` for the WHY (callers/callees/community); a bounded source read at start_line..end_line for the WHAT |
 | "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 |
@@ -161,10 +167,15 @@ You are violating this skill if you think:
 ## When File Tools Are Still Correct
 
 Use Grep/Glob/Read ONLY for:
-- Reading the **exact source lines** of a symbol you already located via Memtrace
+- Non-source files or paths outside every indexed source repo
 - Files that are config, data, or docs (not source code symbols)
 - Repos or paths confirmed outside every Memtrace indexed root
 
+For source-code spans already located by Memtrace, use a **bounded** read —
+your harness's `Read(file, offset, limit)` with the returned `start_line` /
+`end_line`, or `get_source_window` if your harness lacks bounded reads. Do
+not read the whole file.
+
 Never use file tools as a **discovery** mechanism when Memtrace is available.
 
 ## Skill Priority

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.3.31",
+  "version": "0.3.34",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -37,9 +37,9 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.3.31",
-    "@memtrace/linux-x64": "0.3.31",
-    "@memtrace/win32-x64": "0.3.31"
+    "@memtrace/darwin-arm64": "0.3.34",
+    "@memtrace/linux-x64": "0.3.34",
+    "@memtrace/win32-x64": "0.3.34"
   },
   "engines": {
     "node": ">=18"