memtrace 0.3.24 → 0.3.25

package/installer/dist/commands/doctor.js

@@ -34,6 +34,12 @@ function mcpHasMemtrace(file) {
         return false;
     return Boolean(value.mcpServers && value.mcpServers['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 checkAgent(agent) {
     if (agent === 'claude') {
         const skillsDir = path.join(os.homedir(), '.claude', 'skills');
@@ -46,6 +52,17 @@ function checkAgent(agent) {
             mcpConfigPath,
         };
     }
+    if (agent === 'codex') {
+        const skillsDir = path.join(os.homedir(), '.agents', 'skills');
+        const mcpConfigPath = path.join(os.homedir(), '.codex', 'config.toml');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: codexMcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
     const skillsDir = path.join(os.homedir(), '.cursor', 'skills');
     const mcpConfigPath = path.join(os.homedir(), '.cursor', 'mcp.json');
     return {
@@ -60,7 +77,7 @@ export async function runDoctorChecks() {
     const binary = await checkBinary();
     return {
         ...binary,
-        agents: [checkAgent('claude'), checkAgent('cursor')],
+        agents: [checkAgent('claude'), checkAgent('cursor'), checkAgent('codex')],
     };
 }
 export function formatReport(r) {

package/installer/dist/index.js

@@ -13,9 +13,9 @@ 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)', parseOnly)
-    .option('--local', 'install into the current project (./.claude/, ./.cursor/)', false)
-    .option('--global', 'install globally (~/.claude/, ~/.cursor/) [default]', false)
+    .option('--only <agents>', 'comma-separated agent names (claude,cursor,codex)', parseOnly)
+    .option('--local', 'install into the current project (./.claude/, ./.cursor/, ./.agents/)', 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')
     .option('-y, --yes', 'non-interactive, accept defaults')

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

@@ -0,0 +1,8 @@
+import { Transformer, InstallContext } from './types.js';
+export declare function codexConfigPath(ctx: InstallContext): string;
+export declare function stripCodexMcpServer(raw: string): string;
+export interface CodexMcpResult {
+    registered: boolean;
+}
+export declare function registerCodexMcpAt(configFile: string, binary: string): CodexMcpResult;
+export declare const codexTransformer: Transformer;

package/installer/dist/transformers/codex.js

@@ -0,0 +1,134 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { commandExists, execCommand } from '../utils.js';
+const MCP_SERVER_NAME = 'memtrace';
+function skillsRoot(ctx) {
+    const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
+    return path.join(base, '.agents', 'skills');
+}
+export function codexConfigPath(ctx) {
+    const base = ctx.scope === 'global' ? path.join(os.homedir(), '.codex') : path.join(ctx.cwd, '.codex');
+    return path.join(base, 'config.toml');
+}
+function writeSkill(skill, rootDir) {
+    const name = skill.filename.replace(/\.md$/, '');
+    const outDir = path.join(rootDir, name);
+    fs.mkdirSync(outDir, { recursive: true });
+    const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
+    const content = `---\nname: ${name}\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
+    fs.writeFileSync(path.join(outDir, 'SKILL.md'), content);
+}
+function tomlString(value) {
+    return `"${value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')}"`;
+}
+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);
+}
+function isMemtraceMcpTable(tableName) {
+    return tableName === `mcp_servers.${MCP_SERVER_NAME}`
+        || tableName === `mcp_servers."${MCP_SERVER_NAME}"`
+        || tableName.startsWith(`mcp_servers.${MCP_SERVER_NAME}.`)
+        || tableName.startsWith(`mcp_servers."${MCP_SERVER_NAME}".`);
+}
+export function stripCodexMcpServer(raw) {
+    const lines = raw.split(/\r?\n/);
+    const kept = [];
+    let skipping = false;
+    for (const line of lines) {
+        const table = line.match(/^\s*\[([^\]]+)\]\s*$/);
+        if (table) {
+            skipping = isMemtraceMcpTable(table[1].trim());
+            if (skipping)
+                continue;
+        }
+        if (!skipping)
+            kept.push(line);
+    }
+    return kept.join('\n').trimEnd();
+}
+export function registerCodexMcpAt(configFile, binary) {
+    const existing = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf-8') : '';
+    const base = stripCodexMcpServer(existing);
+    const block = [
+        `[mcp_servers.${MCP_SERVER_NAME}]`,
+        `command = ${tomlString(binary)}`,
+        `args = [${tomlString('mcp')}]`,
+        '',
+    ].join('\n');
+    const next = `${base}${base ? '\n\n' : ''}${block}`;
+    writeTextAtomic(configFile, next);
+    return { registered: true };
+}
+function shellQuote(value) {
+    if (process.platform === 'win32')
+        return `"${value.replace(/"/g, '\\"')}"`;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+async function tryCodexMcpAdd(binary) {
+    if (!(await commandExists('codex')))
+        return false;
+    try {
+        await execCommand(`codex mcp add ${MCP_SERVER_NAME} -- ${shellQuote(binary)} mcp`, { timeoutMs: 5_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const codexTransformer = {
+    name: 'codex',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        for (const s of skills)
+            writeSkill(s, rootDir);
+        let mcpRegistered = false;
+        const warnings = [];
+        const mcpConfigPath = codexConfigPath(ctx);
+        if (!ctx.skipMcp) {
+            if (ctx.scope === 'global' && await tryCodexMcpAdd(ctx.memtraceBinary)) {
+                mcpRegistered = true;
+            }
+            else {
+                registerCodexMcpAt(mcpConfigPath, ctx.memtraceBinary);
+                mcpRegistered = true;
+                if (ctx.scope === 'global') {
+                    warnings.push('codex CLI MCP registration was unavailable; wrote ~/.codex/config.toml directly.');
+                }
+            }
+        }
+        return {
+            agent: 'codex',
+            skillsWritten: skills.length,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(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 });
+                }
+            }
+        }
+        const configFile = codexConfigPath(ctx);
+        if (fs.existsSync(configFile)) {
+            const next = stripCodexMcpServer(fs.readFileSync(configFile, 'utf-8'));
+            if (next.trim())
+                writeTextAtomic(configFile, `${next}\n`);
+            else
+                fs.unlinkSync(configFile);
+        }
+    },
+};

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

@@ -1,7 +1,8 @@
 import { Transformer } from './types.js';
 import { claudeTransformer } from './claude.js';
 import { cursorTransformer } from './cursor.js';
+import { codexTransformer } from './codex.js';
 export declare const ALL_TRANSFORMERS: Transformer[];
 export declare function findTransformer(name: string): Transformer | undefined;
-export { claudeTransformer, cursorTransformer };
+export { claudeTransformer, cursorTransformer, codexTransformer };
 export type { Transformer, InstallContext, InstallResult, TransformResult } from './types.js';

package/installer/dist/transformers/index.js

@@ -1,7 +1,8 @@
 import { claudeTransformer } from './claude.js';
 import { cursorTransformer } from './cursor.js';
-export const ALL_TRANSFORMERS = [claudeTransformer, cursorTransformer];
+import { codexTransformer } from './codex.js';
+export const ALL_TRANSFORMERS = [claudeTransformer, cursorTransformer, codexTransformer];
 export function findTransformer(name) {
     return ALL_TRANSFORMERS.find(t => t.name === name);
 }
-export { claudeTransformer, cursorTransformer };
+export { claudeTransformer, cursorTransformer, codexTransformer };

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

@@ -12,7 +12,7 @@ export interface TransformResult {
  * Runtime context passed to every transformer during install/uninstall.
  */
 export interface InstallContext {
-    /** 'global' = write to ~/.<agent>/; 'local' = write to cwd's .<agent>/ */
+    /** 'global' = write user-level config; 'local' = write project-level config under cwd. */
     scope: 'global' | 'local';
     /** Used for local scope. Absolute path. */
     cwd: string;
@@ -33,7 +33,7 @@ export interface InstallResult {
  * One transformer per supported AI coding agent.
  */
 export interface Transformer {
-    name: 'claude' | 'cursor';
+    name: 'claude' | 'cursor' | 'codex';
     install(skills: Skill[], ctx: InstallContext): Promise<InstallResult>;
     uninstall(ctx: InstallContext): Promise<void>;
 }

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

@@ -1,42 +1,32 @@
 ---
 name: memtrace-graph
-description: "Use when the user asks about architectural bottlenecks, important symbols, PageRank, centrality, bridge functions, code communities, logical modules, service boundaries, chokepoints, or wants to understand the high-level architecture of a codebase"
+description: "Use when the user asks about architectural bottlenecks, important symbols, PageRank, centrality, bridge functions, code communities, logical modules, service boundaries, chokepoints, dependency paths between symbols, or wants to understand the high-level architecture of a codebase"
 allowed-tools:
   - mcp__memtrace__find_bridge_symbols
   - mcp__memtrace__find_central_symbols
+  - mcp__memtrace__find_dependency_path
   - mcp__memtrace__list_communities
   - mcp__memtrace__list_processes
   - mcp__memtrace__get_process_flow
-  - mcp__memtrace__execute_cypher
 user-invocable: true
 ---
 
 ## Overview
 
-Graph algorithms that reveal the structural architecture of a codebase — community detection (Louvain), centrality ranking (PageRank/degree), bridge symbol identification (betweenness), and execution flow tracing.
+Graph algorithms that reveal the structural architecture of a codebase — community detection (Louvain), centrality ranking (PageRank), bridge symbol identification (Tarjan articulation points), shortest-path discovery, and execution flow tracing.
+
+All four algorithm tools (`find_central_symbols`, `find_bridge_symbols`, `find_dependency_path`, `list_communities`) run natively against the MemDB-backed knowledge graph — no Cypher required.
 
 ## Quick Reference
 
 | Tool | Purpose |
 |------|---------|
-| `find_bridge_symbols` | Architectural chokepoints — symbols that connect otherwise-separate modules |
-| `find_central_symbols` | Most important symbols by PageRank or degree centrality |
+| `find_bridge_symbols` | Architectural chokepoints — symbols whose removal disconnects the graph (Tarjan articulation points) |
+| `find_central_symbols` | Most important symbols by **PageRank** (default) or degree centrality |
+| `find_dependency_path` | Shortest call/import path between two symbols (BFS over typed edges) |
 | `list_communities` | Louvain-detected logical modules/services |
 | `list_processes` | Execution flows: HTTP handlers, background jobs, CLI commands, event handlers |
 | `get_process_flow` | Trace a single process step-by-step |
-| `execute_cypher` | Direct read-only Cypher queries for custom analysis |
-
-## Parameter Types — Read This First
-
-All memtrace MCP tools are **strictly typed**. Numbers must be JSON numbers, not strings.
-
-| Parameter shape | Correct | Wrong (will fail deserialization) |
-|-----------------|---------|-----------------------------------|
-| Integer/count (`limit`, `min_size`, `depth`) | `limit: 20` | `limit: "20"` |
-| String identifier (`repo_id`, `branch`, `name`) | `repo_id: "my-repo"` | `repo_id: my-repo` |
-| Boolean (`fuzzy`, `include_tests`) | `fuzzy: true` | `fuzzy: "true"` |
-
-If you see `MCP error -32602: invalid type: string "N", expected usize`, you passed a string where a number was required. Remove the quotes.
 
 ## Steps
 
@@ -44,67 +34,34 @@ If you see `MCP error -32602: invalid type: string "N", expected usize`, you pas
 
 Start with `list_communities` to see how the codebase is naturally partitioned into logical modules. Each community has a name, member count, and representative symbols.
 
-**`list_communities` parameters:**
-- `repo_id` — string, required. Repository ID (from `list_indexed_repositories`).
-- `branch` — string, optional. Defaults to `"main"`.
-- `min_size` — **integer**, optional. Minimum community size to include. Default `3`.
-- `limit` — **integer**, optional. Max communities to return. Default `50`, capped at `200`.
-
-Example (correct):
-```json
-{ "repo_id": "Memtrace", "limit": 20 }
-```
-Example (WRONG — will fail):
-```json
-{ "repo_id": "Memtrace", "limit": "20" }
-```
-
 ### 2. Find critical infrastructure
 
 Use `find_central_symbols` to identify the most important symbols:
+- `method: "pagerank"` — importance by link structure (default; same algorithm Google uses)
+- `method: "degree"` — importance by direct connection count
+- `limit` — how many to return
 
-**`find_central_symbols` parameters:**
-- `repo_id` — string, required.
-- `branch` — string, optional. Defaults to `"main"`.
-- `limit` — **integer**, optional. How many to return. Default `20`, capped at `100`.
-- `algorithm` — string, optional. `"pagerank"` (default, via MAGE — falls back to degree if unavailable) or `"degree"` (simple in-degree count, no MAGE required).
+The PageRank pass walks every CALLS / REFERENCES edge in the repo, distributes rank with the standard 0.85 damping factor, and converges on a stable ordering. The output is sorted by score descending, with each entry carrying `name`, `kind`, `file_path`, `score`, and the `in_degree`/`out_degree` it accumulated during the walk.
 
 ### 3. Find architectural chokepoints
 
-Use `find_bridge_symbols` to find symbols that, if removed, would disconnect parts of the graph. These are:
+Use `find_bridge_symbols` to find symbols that, if removed, would disconnect parts of the graph (Tarjan articulation points). These are:
 - **Single points of failure** — if they break, cascading failures occur
 - **Integration points** — good places for interfaces/contracts
 - **Refactoring targets** — often too much responsibility concentrated in one place
 
-**`find_bridge_symbols` parameters:**
-- `repo_id` — string, required.
-- `branch` — string, optional. Defaults to `"main"`.
-- `limit` — **integer**, optional. Default `15`, capped at `50`.
+### 4. Discover the path between two symbols
 
-### 4. Trace execution flows
+Use `find_dependency_path` to answer "how does symbol A reach symbol B?" — returns the shortest call/import chain via BFS over typed edges. Useful for:
+- "Why does the auth handler depend on the database client?"
+- "How does this CLI command reach the logging subsystem?"
+- "Confirm symbol X actually transitively depends on Y."
 
-Use `list_processes` to see all entry points (HTTP handlers, background jobs, CLI commands, event handlers).
-
-**`list_processes` parameters:**
-- `repo_id` — string, required.
-- `branch` — string, optional. Defaults to `"main"`.
-- `limit` — **integer**, optional. Default `50`.
-
-Use `get_process_flow` with a process name to trace a specific flow step-by-step — shows the full call chain from entry point through business logic to data access.
+### 5. Trace execution flows
 
-**`get_process_flow` parameters:**
-- `process` — string, required. Process name or entry-point symbol name (from `list_processes`).
-- `repo_id` — string, required.
-- `branch` — string, optional. Defaults to `"main"`.
-
-### 5. Custom queries
-
-Use `execute_cypher` for advanced graph queries not covered by built-in tools. This is read-only and runs directly against the knowledge graph.
+Use `list_processes` to see all entry points (HTTP handlers, background jobs, CLI commands, event handlers).
 
-**`execute_cypher` parameters:**
-- `query` — string, required. A read-only Cypher query. Write keywords (CREATE, MERGE, DELETE, SET, etc.) are forbidden. Use `$repo_id` to scope to a repository.
-- `params` — object, optional. JSON object of parameter bindings.
-- `repo_id` — string, optional. If provided, injected as `$repo_id` into `params`.
+Use `get_process_flow` with a process name to trace a specific flow step-by-step — shows the full call chain from entry point through business logic to data access, ordered by the indexed `step` property on each STEP_IN_PROCESS edge.
 
 ## Decision Points
 
@@ -113,5 +70,6 @@ Use `execute_cypher` for advanced graph queries not covered by built-in tools. T
 | "What are the main modules?" | `list_communities` |
 | "What are the most important functions?" | `find_central_symbols` with method=pagerank |
 | "Where are the bottlenecks?" | `find_bridge_symbols` |
+| "How does symbol A reach symbol B?" | `find_dependency_path` |
 | "How does a request flow through the system?" | `list_processes` → `get_process_flow` |
 | "What's the entry point for feature X?" | `list_processes`, then filter by name |

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

@@ -50,7 +50,7 @@ Each community represents a cohesive module — these are the "areas" of the cod
 
 ### 4. Find the most important symbols
 
-Call `find_central_symbols` with `method: "pagerank"` and `limit: 15`.
+Call `find_central_symbols` with `limit: 15`. It ranks symbols by PageRank over the repo's CALLS / REFERENCES edges (default `method: "pagerank"`, 0.85 damping factor).
 
 These are the symbols that the rest of the codebase depends on most heavily. They form the "skeleton" of the architecture.
 

package/installer/skills/workflows/memtrace-continuous-memory.md

@@ -0,0 +1,104 @@
+---
+name: memtrace-continuous-memory
+description: "Use when the user asks to keep memtrace fresh while editing, watch a directory for live updates, enable incremental indexing, set up always-on memory, or wants their just-saved code to be queryable immediately"
+allowed-tools:
+  - mcp__memtrace__watch_directory
+  - mcp__memtrace__list_watched_paths
+  - mcp__memtrace__unwatch_directory
+  - mcp__memtrace__index_directory
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__check_job_status
+user-invocable: true
+---
+
+## Overview
+
+Memtrace keeps the knowledge graph live as you edit. Once you call `watch_directory`, every save runs through the **incremental indexing fast-path** — a notify-based file watcher debounces saves, the indexer re-parses only the touched files, and the engine commits the delta in a single WAL transaction. Steady-state latency is **~80 ms from save to queryable** on a typical project.
+
+This is what makes "session continuity" actually work: by the time you ask `find_symbol` after a save, the new symbol is already in the graph.
+
+## Steps
+
+### 1. Confirm the repo is indexed
+
+```
+mcp__memtrace__list_indexed_repositories
+```
+
+If the repo isn't there, run `index_directory` first. The watcher requires an existing repo_id — it never bootstraps from scratch.
+
+### 2. Start watching
+
+```
+mcp__memtrace__watch_directory(
+  path: "/abs/path/to/repo"
+)
+```
+
+The tool registers a `notify` watcher on the directory tree, debounces save bursts (so a `:wq` that touches a swap file doesn't trigger twice), and routes deltas through the indexer's incremental fast-path. Returns immediately — watching runs in the background.
+
+### 3. Confirm it's live
+
+```
+mcp__memtrace__list_watched_paths
+```
+
+Each entry shows the watched root, the bound repo_id, and the last delta's `persist_ms`.
+
+### 4. Edit normally — Memtrace catches up
+
+After every save the watcher emits a `labels_updated` WebSocket event:
+
+```json
+{
+  "event":           "labels_updated",
+  "repo_id":         "demo",
+  "nodes_changed":   12,
+  "persist_ms":      78,
+  "timestamp":       "2026-04-27T10:42:13Z"
+}
+```
+
+Dashboards and IDE plugins subscribe to this on `/ws` and refresh themselves. As an agent you don't have to listen — your next `find_symbol` / `find_code` / `get_symbol_context` call will see the new state automatically.
+
+### 5. Stop watching
+
+```
+mcp__memtrace__unwatch_directory(path: "/abs/path/to/repo")
+```
+
+Idempotent — unwatching an already-unwatched path is a no-op.
+
+## When to Use
+
+- **Long sessions on the same repo** — keeps `get_symbol_context` accurate without rerunning `index_directory`
+- **Pair programming with an IDE plugin** — the dashboard's WebSocket subscription auto-refreshes panels
+- **Demo / live coding** — every save reflects in the graph within 80–150 ms
+- **Long-running agents** — instead of polling `index_directory`, the watcher pushes deltas
+
+## When NOT to Use
+
+- **One-shot batch edits** — running `index_directory --incremental` at the end is cheaper than spinning up a watcher
+- **Generated / build output trees** — exclude paths under `target/`, `dist/`, `node_modules/` (the watcher honours common ignore patterns but a noisy build can still saturate the debounce queue)
+- **CI / containerised runs** — file events are unreliable across container boundaries; index explicitly instead
+
+## Latency Expectations
+
+| Operation | Typical wall time |
+|---|---|
+| File save → watcher fires | < 5 ms |
+| Debounce window | 50 ms |
+| Incremental parse + delta persist | ~80 ms |
+| `labels_updated` broadcast | < 1 ms after persist |
+| Total: save → queryable | ~80–150 ms |
+
+If you see `persist_ms` consistently above 500 ms, the saved files are larger than expected (e.g., generated bundles) — narrow the watch root or add ignore patterns.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---|---|
+| Calling `watch_directory` on an unindexed repo | Returns an error — run `index_directory` first |
+| Watching `node_modules/` or `target/` | Saturates the watcher with build noise — point at the source root only |
+| Polling `find_symbol` every second to "wait" for indexing | Subscribe to the `labels_updated` WS event, or just call once after the save — the delta is already there |
+| Forgetting to `unwatch_directory` between sessions | Watchers are per-process; restarting `memtrace start` wipes them, but for hosted instances unwatching cleanly avoids leaks |

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

@@ -9,17 +9,51 @@ description: "Use when working on any indexed codebase before searching files, r
 
 ```
 IF THE REPO IS INDEXED IN MEMTRACE → USE MEMTRACE TOOLS FIRST.
-NEVER reach for Grep/Glob/Read to discover or understand code.
+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.
 ```
 
 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.
 
-**97% better accuracy. 83% fewer wasted tokens. No exceptions.**
+**97% better accuracy. 83% fewer wasted tokens. No exceptions for what's in the graph.**
 
 ## Value Tracking
 
 Do not print usage receipts in normal answers. Memtrace records tool usage, graph facts, file references, and estimated context avoided internally. Users can inspect that in the local UI's Value panel.
 
+## What Memtrace actually indexes
+
+Memtrace's hybrid search = **BM25 over symbol metadata** (name, signature, file_path, kind) **+ semantic vector search over embedded code bodies** (first ~1500 chars of every Function / Method / Class / Struct / Interface body), fused via Reciprocal Rank Fusion.
+
+The semantic side means **string literals, error messages, magic constants, log strings, and any text inside an indexed symbol's body are findable through `find_code`**. The body got embedded; the embedding catches it. You do NOT need `Grep` to hunt for `STRIPE_KEY_FOO_BAR` if it lives inside a function in your indexed codebase.
+
+## The narrow exceptions where grep/glob are still right
+
+These are the ONLY cases where file tools beat memtrace:
+
+- **Files outside the indexed repo.** Vendored deps, system headers, dirs `walker::is_excluded_path` skipped (`.git`, `node_modules`, `target`, `dist`). Memtrace literally cannot see them.
+- **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`.
+
+For everything else inside the indexed repo, memtrace is the right tool.
+
+## The decision rule
+
+| Question Claude is asking | Right tool |
+|---|---|
+| "Where is symbol `foo` defined?" | `find_symbol(name="foo")` → file:line. Then `Read` that range. |
+| "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. |
+| "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). |
+
 ## Parameter Types — Read This Before Calling Any Tool
 
 All memtrace MCP tools are **strictly typed**. Pass JSON numbers (not strings) for integer parameters.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.3.24",
+  "version": "0.3.25",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -28,6 +28,7 @@
     "uninstall.js"
   ],
   "scripts": {
+    "prepack": "node ../../installer/scripts/prepare-npm-package.js",
     "postinstall": "node install.js",
     "preuninstall": "node uninstall.js"
   },
@@ -36,9 +37,9 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.3.24",
-    "@memtrace/linux-x64": "0.3.24",
-    "@memtrace/win32-x64": "0.3.24"
+    "@memtrace/darwin-arm64": "0.3.25",
+    "@memtrace/linux-x64": "0.3.25",
+    "@memtrace/win32-x64": "0.3.25"
   },
   "engines": {
     "node": ">=18"