memtrace-skills 0.8.3 → 0.8.5

package/dist/commands/doctor.js

@@ -159,6 +159,17 @@ function checkAgent(agent) {
             mcpConfigPath,
         };
     }
+    if (agent === 'warp') {
+        const skillsDir = path.join(os.homedir(), '.warp', 'skills');
+        const mcpConfigPath = path.join(os.homedir(), '.warp', '.mcp.json');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: mcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
     const skillsDir = path.join(os.homedir(), '.cursor', 'skills');
     const mcpConfigPath = path.join(os.homedir(), '.cursor', 'mcp.json');
     return {

package/dist/index.js

@@ -15,7 +15,7 @@ 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,gemini,windsurf,vscode,hermes,opencode,kiro)', parseOnly)
+    .option('--only <agents>', 'comma-separated agent names (claude,cursor,codex,gemini,windsurf,vscode,hermes,opencode,kiro,warp)', 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)

package/dist/rail-install.js

@@ -8,7 +8,7 @@ import os from 'os';
 import path from 'path';
 import { registerRailHookInSettingsAt, removeRailHookFromSettingsAt, } from './transformers/claude.js';
 import { geminiSettingsPath } from './transformers/gemini.js';
-import { registerCursorRailHook, removeCursorRailHook, registerSettingsHook, removeSettingsHook, registerWindsurfRailHook, removeWindsurfRailHook, registerVsCodeRailHook, removeVsCodeRailHook, windsurfHooksPath, vscodeCopilotRailHookPath, CODEX_MATCHER, GEMINI_MATCHER, openCodePluginSource, } from './transformers/rail-hooks.js';
+import { registerCursorRailHook, removeCursorRailHook, registerSettingsHook, removeSettingsHook, registerWindsurfRailHook, removeWindsurfRailHook, registerVsCodeRailHook, removeVsCodeRailHook, windsurfHooksPath, vscodeCopilotRailHookPath, CODEX_MATCHER, GEMINI_MATCHER, openCodeRailPluginPaths, openCodePluginSource, } from './transformers/rail-hooks.js';
 /** Hosts with no Rail hook surface yet (MCP/skills only). */
 export const RAIL_UNSUPPORTED = [
     { host: 'hermes', reason: 'Hermes pre_tool_call adapter not wired yet' },
@@ -22,17 +22,6 @@ function cursorHooksPath(ctx) {
     const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
     return path.join(base, '.cursor', 'hooks.json');
 }
-function opencodeConfigDir(ctx) {
-    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
-    return ctx.scope === 'global' ? path.join(xdg, 'opencode') : path.join(ctx.cwd, '.opencode');
-}
-function opencodeRailPluginPaths(ctx) {
-    const base = opencodeConfigDir(ctx);
-    return [
-        path.join(base, 'plugin', 'memtrace-rail.js'),
-        path.join(base, 'plugins', 'memtrace-rail.js'),
-    ];
-}
 /**
  * Wire Rail discovery hooks for Claude, Cursor, Codex, Gemini, and OpenCode.
  * Idempotent. Does not install skills or MCP — hooks only.
@@ -80,14 +69,14 @@ export function installRailHooks(ctx) {
     });
     try {
         const src = openCodePluginSource(bin);
-        for (const pluginPath of opencodeRailPluginPaths(ctx)) {
+        for (const pluginPath of openCodeRailPluginPaths(ctx)) {
             fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
             fs.writeFileSync(pluginPath, src);
         }
         results.push({
             host: 'opencode',
             registered: true,
-            path: opencodeRailPluginPaths(ctx)[0],
+            path: openCodeRailPluginPaths(ctx)[0],
         });
     }
     catch (e) {
@@ -135,7 +124,7 @@ export function uninstallRailHooks(ctx) {
     const geminiPath = geminiSettingsPath(ctx);
     const gemini = removeSettingsHook(geminiPath, 'BeforeTool');
     results.push({ host: 'gemini', registered: false, path: geminiPath, skipped: gemini.changed ? undefined : 'no rail hook' });
-    for (const p of opencodeRailPluginPaths(ctx)) {
+    for (const p of openCodeRailPluginPaths(ctx)) {
         try {
             fs.rmSync(p, { force: true });
         }

package/dist/transformers/codex.js

@@ -4,7 +4,6 @@ import path from 'path';
 import { commandExists, execCommand } from '../utils.js';
 import { registerSettingsHook, removeSettingsHook, CODEX_MATCHER, } from './rail-hooks.js';
 const MCP_SERVER_NAME = 'memtrace';
-const CODEX_MCP_SHIM_NAME = 'memtrace-mcp-codex-shim.cjs';
 function codexRailHooksPath(ctx) {
     const base = ctx.scope === 'global' ? path.join(os.homedir(), '.codex') : path.join(ctx.cwd, '.codex');
     return path.join(base, 'hooks.json');
@@ -38,82 +37,6 @@ function writeTextAtomic(filePath, content) {
     fs.writeFileSync(tmpPath, content);
     fs.renameSync(tmpPath, filePath);
 }
-function codexMcpShimSource() {
-    return `#!/usr/bin/env node
-const { spawn } = require('node:child_process');
-
-const binary = process.argv[2] || 'memtrace';
-const child = spawn(binary, ['mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
-
-process.stdin.pipe(child.stdin);
-child.stderr.pipe(process.stderr);
-
-function stripAnnotations(line) {
-  let message;
-  try {
-    message = JSON.parse(line);
-  } catch {
-    return line;
-  }
-
-  const content = message && message.result && message.result.content;
-  if (!Array.isArray(content)) return line;
-
-  const assistantItems = [];
-  const fallbackItems = [];
-  for (const item of content) {
-    if (!item || typeof item !== 'object') continue;
-    const clean = { ...item };
-    const annotations = clean.annotations;
-    delete clean.annotations;
-    fallbackItems.push(clean);
-    const audience = annotations && annotations.audience;
-    if (Array.isArray(audience) && audience.includes('assistant')) {
-      assistantItems.push(clean);
-    }
-  }
-
-  message.result.content = assistantItems.length > 0 ? assistantItems : fallbackItems;
-  return JSON.stringify(message);
-}
-
-let buffer = '';
-child.stdout.on('data', (chunk) => {
-  buffer += chunk.toString('utf8');
-  let index = buffer.indexOf('\\n');
-  while (index !== -1) {
-    const line = buffer.slice(0, index);
-    buffer = buffer.slice(index + 1);
-    process.stdout.write(stripAnnotations(line) + '\\n');
-    index = buffer.indexOf('\\n');
-  }
-});
-
-child.stdout.on('end', () => {
-  if (buffer.length > 0) process.stdout.write(stripAnnotations(buffer));
-});
-
-child.on('exit', (code, signal) => {
-  if (signal) process.kill(process.pid, signal);
-  process.exit(code ?? 0);
-});
-`;
-}
-function codexMcpShimPath(configFile) {
-    return path.join(path.dirname(configFile), CODEX_MCP_SHIM_NAME);
-}
-function writeCodexMcpShim(configFile) {
-    const shimPath = codexMcpShimPath(configFile);
-    writeTextAtomic(shimPath, codexMcpShimSource());
-    try {
-        fs.chmodSync(shimPath, 0o755);
-    }
-    catch {
-        // Windows and locked-down filesystems may reject chmod; Codex invokes it
-        // through Node, so executable bits are a convenience, not a requirement.
-    }
-    return shimPath;
-}
 function isMemtraceMcpTable(tableName) {
     return tableName === `mcp_servers.${MCP_SERVER_NAME}`
         || tableName === `mcp_servers."${MCP_SERVER_NAME}"`
@@ -196,11 +119,15 @@ export function registerCodexMcpAt(configFile, binary) {
     // after the freshly written parent block for readability.
     const stripped = stripCodexMcpServer(existing);
     const { rest, envBlock } = extractMemtraceEnvBlock(stripped);
-    const shimPath = writeCodexMcpShim(configFile);
+    // Bare `memtrace mcp` — no shim. The server now emits a Codex-safe, plain
+    // (annotation-free) tool response when the client identifies as Codex at
+    // `initialize` (MemtraceMcpServer / shape_tool_content), so Codex talks to the
+    // binary directly. This removes the Node shim that hand-configuring users
+    // (who wrote `command = "memtrace"` themselves) used to miss.
     const block = [
         `[mcp_servers.${MCP_SERVER_NAME}]`,
-        `command = ${tomlString(process.execPath)}`,
-        `args = [${[shimPath, binary].map(tomlString).join(', ')}]`,
+        `command = ${tomlString(binary)}`,
+        `args = ["mcp"]`,
     ].join('\n');
     const parts = [];
     if (rest)

package/dist/transformers/index.d.ts

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

package/dist/transformers/index.js

@@ -7,6 +7,7 @@ import { vscodeTransformer } from './vscode.js';
 import { hermesTransformer } from './hermes.js';
 import { opencodeTransformer } from './opencode.js';
 import { kiroTransformer } from './kiro.js';
+import { warpTransformer } from './warp.js';
 export const ALL_TRANSFORMERS = [
     claudeTransformer,
     cursorTransformer,
@@ -17,8 +18,9 @@ export const ALL_TRANSFORMERS = [
     hermesTransformer,
     opencodeTransformer,
     kiroTransformer,
+    warpTransformer,
 ];
 export function findTransformer(name) {
     return ALL_TRANSFORMERS.find(t => t.name === name);
 }
-export { claudeTransformer, cursorTransformer, codexTransformer, geminiTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, };
+export { claudeTransformer, cursorTransformer, codexTransformer, geminiTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, warpTransformer, };

package/dist/transformers/opencode.js

@@ -1,33 +1,17 @@
 import fs from 'fs';
-import os from 'os';
 import path from 'path';
 import { registerOpenCodeMcpAt, removeMemtraceSkills, removeOpenCodeMcpAt, writeSkills, } from './shared.js';
-import { openCodePluginSource } from './rail-hooks.js';
-function opencodeConfigDir() {
-    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
-    return path.join(xdg, 'opencode');
-}
+import { openCodeConfigDir, openCodeRailPluginPaths, openCodePluginSource, } from './rail-hooks.js';
 function skillsRoot(ctx) {
     return ctx.scope === 'global'
-        ? path.join(opencodeConfigDir(), 'skills')
+        ? path.join(openCodeConfigDir(ctx), 'skills')
         : path.join(ctx.cwd, '.opencode', 'skills');
 }
 function mcpPath(ctx) {
     return ctx.scope === 'global'
-        ? path.join(opencodeConfigDir(), 'opencode.json')
+        ? path.join(openCodeConfigDir(ctx), 'opencode.json')
         : path.join(ctx.cwd, 'opencode.json');
 }
-// OpenCode's plugin directory name changed across versions: current official
-// docs use `plugins/` (plural) while older/community builds load `plugin/`
-// (singular). We write the plugin to BOTH so it loads regardless of version;
-// uninstall removes both. (Identical content — whichever the runtime reads.)
-function railPluginPaths(ctx) {
-    const base = ctx.scope === 'global' ? opencodeConfigDir() : path.join(ctx.cwd, '.opencode');
-    return [
-        path.join(base, 'plugin', 'memtrace-rail.js'),
-        path.join(base, 'plugins', 'memtrace-rail.js'),
-    ];
-}
 export const opencodeTransformer = {
     name: 'opencode',
     async install(skills, ctx) {
@@ -47,7 +31,7 @@ export const opencodeTransformer = {
         // has no stdio hook). Defaults to observe; fail-open. Best effort.
         try {
             const src = openCodePluginSource(ctx.memtraceBinary);
-            for (const pluginPath of railPluginPaths(ctx)) {
+            for (const pluginPath of openCodeRailPluginPaths(ctx)) {
                 fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
                 fs.writeFileSync(pluginPath, src);
             }
@@ -67,7 +51,7 @@ export const opencodeTransformer = {
     async uninstall(ctx) {
         removeMemtraceSkills(skillsRoot(ctx));
         removeOpenCodeMcpAt(mcpPath(ctx));
-        for (const p of railPluginPaths(ctx)) {
+        for (const p of openCodeRailPluginPaths(ctx)) {
             try {
                 fs.rmSync(p, { force: true });
             }

package/dist/transformers/rail-hooks.d.ts

@@ -5,6 +5,19 @@ export declare const CLAUDE_MATCHER = "Grep|Glob|Bash";
 export declare const CODEX_MATCHER = "Bash";
 export declare const GEMINI_MATCHER = "run_shell_command|read_file|read_many_files|glob|search_file_content";
 export declare function railCommand(binary: string, host: string): string;
+export interface OpenCodePathContext {
+    scope: 'global' | 'local';
+    cwd: string;
+}
+export interface OpenCodePathOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    homedir?: string;
+}
+export declare function openCodeHomeDir(options?: OpenCodePathOptions): string;
+export declare function openCodeGlobalConfigDir(options?: OpenCodePathOptions): string;
+export declare function openCodeConfigDir(ctx: OpenCodePathContext, options?: OpenCodePathOptions): string;
+export declare function openCodeRailPluginPaths(ctx: OpenCodePathContext, options?: OpenCodePathOptions): string[];
 export declare function isRailHookEntry(entry: unknown): boolean;
 export interface HookResult {
     registered: boolean;

package/dist/transformers/rail-hooks.js

@@ -28,6 +28,56 @@ export const GEMINI_MATCHER = 'run_shell_command|read_file|read_many_files|glob|
 export function railCommand(binary, host) {
     return `${binary} route --hook --host ${host}`;
 }
+function trimmed(value) {
+    const clean = value?.trim();
+    return clean ? clean : undefined;
+}
+function windowsProfileHome(env) {
+    const userProfile = trimmed(env.USERPROFILE);
+    if (userProfile)
+        return userProfile;
+    const drive = trimmed(env.HOMEDRIVE);
+    const homePath = trimmed(env.HOMEPATH);
+    return drive && homePath ? `${drive}${homePath}` : undefined;
+}
+export function openCodeHomeDir(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const fallbackHome = trimmed(options.homedir ?? os.homedir());
+    const posixHome = trimmed(env.HOME);
+    const winHome = windowsProfileHome(env);
+    if (platform === 'win32') {
+        return winHome ?? posixHome ?? fallbackHome ?? '';
+    }
+    return posixHome ?? fallbackHome ?? winHome ?? '';
+}
+export function openCodeGlobalConfigDir(options = {}) {
+    const env = options.env ?? process.env;
+    const xdg = trimmed(env.XDG_CONFIG_HOME);
+    if (xdg)
+        return path.join(xdg, 'opencode');
+    const home = openCodeHomeDir(options);
+    if (!home) {
+        throw new Error('OpenCode config path unavailable: HOME or USERPROFILE is not set');
+    }
+    return path.join(home, '.config', 'opencode');
+}
+export function openCodeConfigDir(ctx, options = {}) {
+    return ctx.scope === 'global'
+        ? openCodeGlobalConfigDir(options)
+        : path.join(ctx.cwd, '.opencode');
+}
+// OpenCode's plugin directory name changed across versions: current official
+// docs use `plugins/` (plural) while older/community builds load `plugin/`
+// (singular). We write the plugin to BOTH so it loads regardless of version;
+// uninstall removes both. (Identical content — whichever the runtime reads.)
+export function openCodeRailPluginPaths(ctx, options = {}) {
+    const base = openCodeConfigDir(ctx, options);
+    return [
+        path.join(base, 'plugin', 'memtrace-rail.js'),
+        path.join(base, 'plugins', 'memtrace-rail.js'),
+    ];
+}
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }

package/dist/transformers/types.d.ts

@@ -29,7 +29,7 @@ export interface InstallResult {
     mcpRegistered: boolean;
     warnings: string[];
 }
-export type AgentName = 'claude' | 'cursor' | 'codex' | 'gemini' | 'windsurf' | 'vscode' | 'hermes' | 'opencode' | 'kiro';
+export type AgentName = 'claude' | 'cursor' | 'codex' | 'gemini' | 'windsurf' | 'vscode' | 'hermes' | 'opencode' | 'kiro' | 'warp';
 /**
  * One transformer per supported AI coding agent.
  */

package/dist/transformers/warp.d.ts

@@ -0,0 +1,4 @@
+import { Transformer } from './types.js';
+/** Global Warp MCP config: `~/.warp/.mcp.json` (auto-spawns by default). */
+export declare function warpMcpPath(): string;
+export declare const warpTransformer: Transformer;

package/dist/transformers/warp.js

@@ -0,0 +1,83 @@
+import os from 'os';
+import path from 'path';
+import { registerMcpServersJsonAt, removeMcpServersJsonAt, removeMemtraceSkills, writeSkills, } from './shared.js';
+// Warp (https://docs.warp.dev/agent-platform/capabilities/mcp/) is a terminal
+// with a built-in agent that reads the open Agent Skills format (SKILL.md +
+// name/description frontmatter) and stdio MCP servers from JSON config.
+//
+// Two things make Warp's wiring different from the other transformers:
+//
+//   1. Skills + MCP both live under `~/.warp/` (global) or `<cwd>/.warp/`
+//      (project). We write to Warp's NATIVE provider paths rather than the
+//      `~/.agents/` "Other agents" paths, because the Warp provider row
+//      auto-spawns global servers by default — the "Other agents" row
+//      requires the user to toggle "Auto-spawn servers from third-party
+//      agents" on. Native paths = MCP works on first launch, zero toggling.
+//
+//   2. The MCP config file is a dotfile: `~/.warp/.mcp.json` (note the
+//      leading dot on the filename). The shared JSON helpers don't care
+//      about the basename — they read/merge/write atomically — so the only
+//      thing we customize is the path.
+//
+// Warp uses the same `mcpServers` schema as Claude Code / Windsurf / Kiro
+// (each entry: `{ command, args, env? }`), so we reuse
+// `registerMcpServersJsonAt` / `removeMcpServersJsonAt` from shared.ts —
+// corrupted-file backup, unrelated-server preservation, and empty-file
+// deletion on uninstall all come for free.
+function warpRoot(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(os.homedir(), '.warp')
+        : path.join(ctx.cwd, '.warp');
+}
+function skillsRoot(ctx) {
+    return path.join(warpRoot(ctx), 'skills');
+}
+/** Global Warp MCP config: `~/.warp/.mcp.json` (auto-spawns by default). */
+export function warpMcpPath() {
+    return path.join(os.homedir(), '.warp', '.mcp.json');
+}
+function mcpPath(ctx) {
+    // Global: the Warp provider file (auto-spawns). Local: project-scoped
+    // `.warp/.mcp.json` at the repo root — Warp detects these but NEVER
+    // auto-spawns them (security: a cloned repo can't start arbitrary local
+    // commands). The install warning below tells the user to toggle it on.
+    return ctx.scope === 'global'
+        ? warpMcpPath()
+        : path.join(ctx.cwd, '.warp', '.mcp.json');
+}
+export const warpTransformer = {
+    name: 'warp',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        const count = writeSkills(skills, rootDir);
+        const warnings = [];
+        let mcpRegistered = false;
+        const mcpConfigPath = mcpPath(ctx);
+        if (!ctx.skipMcp) {
+            const result = registerMcpServersJsonAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+            if (!mcpRegistered && result.backupPath) {
+                warnings.push(`Warp MCP config was malformed; backed up to ${result.backupPath}.`);
+            }
+            // Project-scoped Warp servers never auto-spawn — the user must toggle
+            // the server on from Settings > Agents > MCP servers after install.
+            // Surface that so a `--local` install doesn't look like a no-op.
+            if (ctx.scope === 'local') {
+                warnings.push('Warp project-scoped MCP servers never auto-spawn — ' +
+                    'enable "memtrace" under Settings > Agents > MCP servers in Warp.');
+            }
+        }
+        return {
+            agent: 'warp',
+            skillsWritten: count,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSkills(skillsRoot(ctx));
+        removeMcpServersJsonAt(mcpPath(ctx));
+    },
+};

package/package.json

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

package/plugins/memtrace-skills/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memtrace-skills",
   "description": "Memtrace skills for codebase exploration, code search, relationship analysis, temporal evolution, blast radius impact, code quality, graph algorithms, API topology, GitHub PR code review, multi-agent fleet coordination (branch-scoped intents, conflict classification, and agent-judged Class C resolution), and multi-step workflows for change impact, incident investigation, refactoring, session continuity, co-change analysis, and episode replay, Cortex decision memory (decision recall, provenance, intent verification), session bookends (daily briefing, hotspots, self-audit), and single-symbol pre-edit preflight checks.",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "author": {
     "name": "Syncable",
     "email": "support@syncable.dev"

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

@@ -372,8 +372,9 @@ No parameters. Returns `{ watches: [{ path, repo_id, branch, started_at, origin
 
 ## Cortex decision memory
 
-Proxied to memcortex-serve; available when the Cortex store is enabled. Ids are
-**JSON numbers** (Cortex node ids), not strings — `decision_id: 1`, never `"1"`.
+Exposed on the normal `memtrace` MCP server and proxied to the local MemCortex
+sidecar when Cortex is enabled. Ids are **JSON numbers** (Cortex node ids), not
+strings — `decision_id: 1`, never `"1"`.
 An unknown or empty query/id returns an explicit **CannotProve**, never a
 fabricated result.
 
@@ -381,6 +382,8 @@ fabricated result.
 | Field | Type | Required | Notes |
 |---|---|---|---|
 | `query` | string | yes | Free text; drives the lexical lane, decisions ranked first |
+| `top_k` | integer | no | Optional result cap; must be > 0 |
+| `min_score` | number | no | Optional finite score floor |
 
 (A tier-based decision cap is applied server-side; it is not a caller parameter.)
 
@@ -397,7 +400,7 @@ fabricated result.
 ## When this file is wrong
 
 It's drift-prone. Regenerate by grepping `crates/memtrace-mcp/src/tools/*.rs`
-for `^pub struct.*Params` — the Rust declarations are the source of truth
-(Cortex decision tools: `MemCortex/crates/memcortex-mcp/src/request.rs`).
+and `crates/memtrace-mcp/src/cortex_client.rs` for `Params` declarations — the
+Rust declarations are the source of truth.
 If a live tool call rejects with `-32602`, trust the Rust struct over this
 doc and file a fix PR.

package/plugins/memtrace-skills/skills/memtrace-change-impact-analysis/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: memtrace-change-impact-analysis
-description: "Compute what a planned source-code change will break — blast radius, affected processes, cross-repo callers — and produce a risk-rated change plan. Use when the user needs to know what will break before a change: edits, refactors, API changes, renames, removals, PR reviews, or risk assessments. Do not manually grep references or browse files for impact; this workflow uses Memtrace graph context, impact, and change history. For a quick blast-radius check on one symbol, use memtrace-impact."
+description: "Compute what a planned source-code change will break — blast radius, affected processes, cross-repo callers, temporal stability, and Cortex decision-memory constraints — and produce a risk-rated change plan. Use before edits, refactors, API changes, renames, removals, PR reviews, or risk assessments, especially when changing established behavior or deleting code. Do not manually grep references or browse files for impact; use Memtrace graph context, change history, and decision recall/provenance."
 ---
 
 ## Overview
 
-Pre-change risk assessment workflow. Before modifying code, this workflow maps the full blast radius, identifies affected processes, checks recent change history for instability signals, and produces a risk-rated change plan.
+Pre-change risk assessment workflow. Before modifying code, this workflow maps the full blast radius, identifies affected processes, checks recent change history for instability signals, checks Cortex decision memory for recorded decisions/bans/contracts, and produces a risk-rated change plan.
 
 ## Steps
 
@@ -42,20 +42,30 @@ For each target, call `get_impact` (`repo_id`, `target`) with `direction: "both"
 | High | Plan incremental migration; consider feature flags |
 | Critical | Full migration strategy; backward-compatible changes required |
 
-### 4. Check temporal stability
+### 4. Check Cortex decision memory
+
+For each target or subsystem, call `recall_decision("<target/subsystem/approach>")`.
+If the graph result exposes a numeric `symbol_id`, also call
+`why_is_this_here(symbol_id)` and `governing_contracts(symbol_id)`.
+
+- Matching decision/ban/convention → include it in the plan before recommending a change.
+- Decision you intend to rely on → run `verify_intent(decision_id)` first.
+- CannotProve → record "no decision proven"; do not treat it as approval.
+
+### 5. Check temporal stability
 
 Call `get_evolution` (`repo_id`, `from: "30d ago"`, `mode: "compound"`), then `get_timeline` on each target symbol (requires `scope_path` + `file_path` from `find_symbol`):
 - Sparse timeline history + you're about to change it → structurally surprising; extra scrutiny warranted.
 - Target appears in `top_touched_symbols` → high churn + high impact = volatile hotspot.
 
-### 5. Map affected execution flows
+### 6. Map affected execution flows
 
 From step 2, you already know which processes are affected. For critical changes, use `analyze_relationships` (`repo_id`, `target`) with `query_type: "find_callers"` at `depth: 3` to trace the full transitive caller chain.
 
 `depth: 3` is a JSON number, not a string — the validator rejects `"3"`.
 Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
-### 6. Produce the risk assessment
+### 7. Produce the risk assessment
 
 Synthesize into a change plan:
 
@@ -64,8 +74,9 @@ Synthesize into a change plan:
 3. **Affected Processes** — which execution flows will be impacted
 4. **Cross-Service Impact** — any external callers or consumers
 5. **Stability Signal** — sparse `get_timeline` history (stable) vs frequent appearance in `top_touched_symbols` (volatile)
-6. **Recommended Approach** — based on risk: direct change, incremental migration, or backward-compatible evolution
-7. **Test Coverage** — which callers/processes to verify after the change
+6. **Decision Memory** — relevant decisions/bans/contracts, or CannotProve as unknown
+7. **Recommended Approach** — based on risk and decision constraints: direct change, incremental migration, or backward-compatible evolution
+8. **Test Coverage** — which callers/processes to verify after the change
 
 ## Decision Points
 
@@ -76,6 +87,7 @@ Synthesize into a change plan:
 | Symbol has sparse timeline but high impact | Extra review — this rarely changes; make sure the change is intentional |
 | Multiple processes affected | List each affected flow; recommend testing each one |
 | Symbol is a bridge point | Change may disconnect parts of the architecture — verify alternative paths exist |
+| Cortex returns a held ban/contract | Do not recommend contradicting it without explicit user sign-off |
 
 ## Output
 

package/plugins/memtrace-skills/skills/memtrace-decision-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-decision-memory
-description: "Check Cortex decision memory — the umbrella entry point for decision recall, provenance (why is this here), intent verification, and governing contracts. Use before assuming WHY code exists, before making a choice that may contradict a past one, or before deleting/rewriting code that looks odd or redundant. Route: free-text what-was-decided → memtrace-decision-recall; why does this symbol exist / what constrains it → memtrace-provenance; did the decision hold → memtrace-intent-verification. Do not guess rationale from the diff or git log; Cortex remembers the decision, the ban, and whether it still holds."
+description: "Check Cortex decision memory through the normal Memtrace MCP tools — the umbrella entry point for decision recall, provenance (why is this here), intent verification, and governing contracts. Use before assuming WHY code exists, before any non-trivial edit/refactor/delete of existing code, before re-picking a library/pattern/architecture, or before contradicting an apparent convention. Route: free-text decisions/bans/conventions → memtrace-decision-recall; symbol lineage/contracts → memtrace-provenance; did the decision hold → memtrace-intent-verification. Do not guess rationale from the diff or git log."
 ---
 
 # Decision Memory First
@@ -42,12 +42,14 @@ These five tools are **deterministic, zero-LLM**. Every call returns a labeled
 `CannotProve` is a real, trustworthy answer ("memory has nothing on this"), not a
 failure and not a green light. Never invent a rationale to fill the gap.
 
-## Server check (once per session)
+## Tool availability (once per session)
 
-These tools are served by the **`memcortex`** MCP server (decision memory), separate
-from the `memtrace` code-graph server. If `recall_decision` isn't available, decision
-memory isn't wired in this environment — say so and use `memtrace-first` instead;
-don't fabricate decisions.
+These tools are exposed on the normal **`memtrace` MCP server**:
+`recall_decision`, `why_is_this_here`, `verify_intent`, `get_arc`, and
+`governing_contracts`. Hosts do not need a second MemCortex MCP connection. If a
+tool call returns CannotProve because Cortex is unavailable (for example native
+Windows without WSL2), say decision memory was unavailable/unknown and continue
+with `memtrace-first`; do not fabricate decisions.
 
 ## The decision rule
 
@@ -55,9 +57,9 @@ don't fabricate decisions.
 |---|---|---|
 | "Did we already decide/choose/reject X?" "What's our convention on Y?" | `recall_decision("X")` | `memtrace-decision-recall` |
 | "Is there a ban / a 'don't do this' on Z?" | `recall_decision("Z")` — bans surface as decisions | `memtrace-decision-recall` |
-| About to re-pick a library/pattern/approach | `recall_decision` FIRST — don't re-litigate a settled call | `memtrace-decision-recall` |
+| About to edit behavior, re-pick a library/pattern/architecture, or change a subsystem policy | `recall_decision` FIRST — don't re-litigate a settled call | `memtrace-decision-recall` |
 | "Why is this code here?" "Why is it done this odd way?" | `why_is_this_here(symbol_id)` | `memtrace-provenance` |
-| About to delete/refactor code that looks unused or strange | `why_is_this_here` + `governing_contracts` before touching it | `memtrace-provenance` |
+| About to delete/refactor/clean up existing code, especially odd or "dead" code | `why_is_this_here` + `governing_contracts` before touching it | `memtrace-provenance` |
 | "What rules/contracts constrain this symbol?" | `governing_contracts(symbol_id)` | `memtrace-provenance` |
 | "Did decision D actually hold, or did we drift?" | `verify_intent(decision_id)` | `memtrace-intent-verification` |
 | "What commits/episodes implemented decision D?" | `get_arc(decision_id)` | `memtrace-intent-verification` |
@@ -85,10 +87,11 @@ have a name or a free-text question, start with `recall_decision`.** Do not inve
 ## Standard workflows
 
 ### "Why does this code exist / can I delete it?"
-1. `why_is_this_here(symbol_id)` → the governing decision, if any
-2. `governing_contracts(symbol_id)` → constraints that must survive a rewrite
-3. If a decision governs it → `verify_intent(decision_id)` to see if it still holds
-4. **CannotProve on all three ≠ safe to delete** — confirm with `memtrace-impact` (blast radius) and the user
+1. If you only have a name/free-text target, `recall_decision("<symbol/subsystem>")` first.
+2. If you have a `symbol_id`, `why_is_this_here(symbol_id)` → the governing decision, if any.
+3. `governing_contracts(symbol_id)` → constraints that must survive a rewrite.
+4. If a decision governs it → `verify_intent(decision_id)` to see if it still holds.
+5. **CannotProve on all checks ≠ safe to delete** — confirm with `memtrace-impact` (blast radius) and the user.
 
 ### "Should I do X?" (about to make a choice)
 1. `recall_decision("X")` → did we already decide or ban this?
@@ -104,6 +107,7 @@ have a name or a free-text question, start with `recall_decision`.** Do not inve
 | Thought | Reality |
 |---|---|
 | "This code looks unused, I'll delete it" | `why_is_this_here` first — a decision may govern it; deletion may reopen a closed issue |
+| "I'll just edit/refactor this existing behavior" | `recall_decision("<behavior/subsystem>")` first — the change may violate a recorded decision or ban |
 | "I'll just use library/pattern X" | `recall_decision("X")` — you may be undoing a deliberate ban |
 | "The diff/git log will tell me why" | Git shows *what changed*, not *what was decided or rejected*. Decision memory has the rationale and the bans. |
 | "CannotProve, so it's fine/approved" | CannotProve = unknown, not approved. Don't treat absence of a record as permission. |