forget-connect 0.5.2 → 0.6.0

package/src/cli.js

@@ -20,12 +20,13 @@ import {
   validateScopeId,
   validateApiKey,
 } from "./core.js";
-import { doctorRemote } from "./doctor.js";
+import { CODEX_REQUIRED_TOOLS, doctorRemote } from "./doctor.js";
 import {
   commandsDirFor,
   connectHooksSettings,
   disconnectHooksSettings,
   hooksDirFor,
+  hooksInstalled,
   inspectHooks,
   installCommandAssets,
   installHookScripts,
@@ -33,6 +34,24 @@ import {
   removeHookScripts,
   settingsPathFor,
 } from "./hooks.js";
+import {
+  PROXY_BASE_URL,
+  PROXY_LABEL,
+  WATCHDOG_LABEL,
+  findExecutable,
+  installProxyServices,
+  readWiringState,
+  removeProxyServices,
+  unwireProxyEnv,
+  wireProxyEnv,
+  writeWiringState,
+} from "./proxy.js";
+import {
+  inspectMemoryAgentSkill,
+  installMemoryAgentSkill,
+  removeMemoryAgentSkill,
+  skillDirFor,
+} from "./skills.js";
 
 const CLIENT_IDS = new Set(["claude-code", "codex", "claude-desktop"]);
 
@@ -55,13 +74,19 @@ Options:
 
 Scope:
   Local connections default to one canonical scoped endpoint (all clients share it):
-  /mcp/<client>/http/<os-username>. This keeps each user's and client's
-  memories isolated. Override with --user-id/--app-id, or opt out with
-  --no-scope. An explicit --url is installed verbatim.
+  /mcp/forget/http/<os-username>. This keeps each user's vault isolated while
+  Codex and Claude retain distinct provider profiles and provenance. Override
+  with --user-id/--app-id, or opt out with --no-scope. An explicit --url is
+  installed verbatim.
   --no-auth            Connect without a Bearer token
+  --local-auth         Send FORGET_API_KEY to an explicit loopback server
+                       (required by credential-bound Memory Agent tools)
   --no-rules           Do not manage CLAUDE.md or AGENTS.md instruction blocks
-  --no-hooks           Do not install Claude Code memory hooks (session capsule,
-                       per-turn recall, conflict alerts, session capture)
+  --no-skill           Do not install the shared Memory Agent skill
+  --no-hooks           Do not install Codex/Claude Code memory hooks (session
+                       capsule, per-turn recall, session capture)
+  --no-proxy           Do not wire the local capture proxy (launchd service +
+                       ANTHROPIC_BASE_URL override + health watchdog; macOS only)
   --no-migrate-enacta  Keep matching legacy config and rules blocks
   --dry-run            Show the files that would change without writing them
   --timeout <seconds>  Doctor network timeout (default: 10)
@@ -73,6 +98,7 @@ Scope:
 Authentication:
   The default local server needs no token. For --hosted (legacy) set
   FORGET_API_KEY, or run interactively and paste the key when prompted.
+  Credential-bound local tools require FORGET_API_KEY plus --local-auth.
   Keys are intentionally not accepted as command-line arguments.
 
 Examples:
@@ -125,8 +151,11 @@ export function parseArgs(argv, env = process.env) {
     scope: null,
     defaultScope: null,
     auth: true,
+    localAuth: false,
     rules: true,
+    skills: true,
     hooks: true,
+    proxy: true,
     migrateLegacy: true,
     dryRun: false,
     yes: false,
@@ -170,10 +199,16 @@ export function parseArgs(argv, env = process.env) {
       options.noScope = true;
     } else if (arg === "--no-auth") {
       options.auth = false;
+    } else if (arg === "--local-auth") {
+      options.localAuth = true;
     } else if (arg === "--no-rules") {
       options.rules = false;
+    } else if (arg === "--no-skill") {
+      options.skills = false;
     } else if (arg === "--no-hooks") {
       options.hooks = false;
+    } else if (arg === "--no-proxy") {
+      options.proxy = false;
     } else if (arg === "--no-migrate-enacta") {
       options.migrateLegacy = false;
     } else if (arg === "--dry-run") {
@@ -211,6 +246,12 @@ export function parseArgs(argv, env = process.env) {
   }
   options.baseUrl = normalizeUrl(options.url);
   options.hosted = isHostedBaseUrl(options.baseUrl);
+  if (options.localAuth && !options.auth) {
+    throw new ConfigError("--local-auth and --no-auth are mutually exclusive.");
+  }
+  if (options.localAuth && !isLoopbackUrl(options.baseUrl)) {
+    throw new ConfigError("--local-auth is only allowed for a loopback MCP URL.");
+  }
   if (Boolean(options.userId) !== Boolean(options.appId)) {
     throw new ConfigError("--user-id and --app-id must be provided together.");
   }
@@ -226,12 +267,10 @@ export function parseArgs(argv, env = process.env) {
   options.url = options.scope
     ? scopedMcpUrl(options.baseUrl, options.scope)
     : options.baseUrl;
-  // Cold-install default: scope each client into its own memory pool at
-  // /mcp/<client>/http/<os-username>. The unscoped /mcp endpoint pools every
-  // client's memories into the server's fallback scope (cold-install audit
-  // 2026-07-29), so plain /mcp is now the opt-in (--no-scope), not the
-  // default. An explicit --url stays verbatim, and hosted keeps requiring an
-  // explicit account identity — the OS username is not a hosted account.
+  // Cold-install default: all providers use one personal vault at
+  // /mcp/forget/http/<os-username>; the query profile keeps their tool surface
+  // and provenance separate. The unscoped /mcp endpoint pools data into the
+  // server fallback, so it remains an explicit opt-in (--no-scope).
   options.defaultScope = null;
   if (!options.scope && !options.noScope && !options.hosted && !options.urlExplicit) {
     const osUser = defaultScopeUserId(env);
@@ -259,17 +298,23 @@ function defaultScopeUserId(env) {
 }
 
 export function urlForClient(options, client) {
-  if (options.scope) return options.url;
+  let resolved = options.url;
+  if (options.scope) resolved = options.url;
   if (options.defaultScope && client) {
     // Every client shares the canonical pool; which tool wrote a memory is
     // provenance, not a scope boundary (issue #27). A per-client pool made
     // Codex writes invisible to Claude and vice versa.
-    return scopedMcpUrl(options.baseUrl, {
+    resolved = scopedMcpUrl(options.baseUrl, {
       userId: options.defaultScope.userId,
       appId: CANONICAL_APP_ID,
     });
   }
-  return options.url;
+  if (client?.id === "codex" || client?.id === "claude-code") {
+    const parsed = new URL(normalizeUrl(resolved));
+    parsed.searchParams.set("profile", client.id === "codex" ? "codex" : "claude");
+    return parsed.toString().replace(/\/$/, "");
+  }
+  return resolved;
 }
 
 function requestedClientIds(values) {
@@ -389,12 +434,16 @@ async function apiKeyFor(options, env) {
         "Bearer authentication requires HTTPS. Use --no-auth for a local HTTP server.",
       );
     }
-    // A leftover hosted key must not block the local-first default flow, and
-    // a loopback target never puts the secret on the wire anyway.
+    if (options.localAuth) return validateApiKey(fromEnv);
+    // A leftover hosted key must not silently become a local credential.
+    // Credential-bound local features opt in with --local-auth.
     stderr.write(
       "Note: FORGET_API_KEY is set but the target is a loopback HTTP server; connecting without a token.\n",
     );
   }
+  if (options.localAuth) {
+    throw new ConfigError("Set FORGET_API_KEY when using --local-auth.");
+  }
   if (!options.hosted) return "";
   const prompted = (await promptHidden("Paste your Forget API key: ")).trim();
   if (!prompted) {
@@ -445,7 +494,13 @@ function printDoctor(result) {
     const hooksDetail = result.hooks.registered
       ? `registered, scripts ${result.hooks.scripts_present ? "present" : "missing"}, python3 ${result.hooks.python3 ? "ok" : "missing"}`
       : "not installed (use connect without --no-hooks)";
-    stdout.write(`${result.hooks.ok ? "✓" : "✗"} Hooks: ${hooksDetail}\n`);
+    stdout.write(`${result.hooks.ok ? "✓" : "✗"} Claude Code hooks: ${hooksDetail}\n`);
+  }
+  if (result.codex_hooks) {
+    const hooksDetail = result.codex_hooks.registered
+      ? `registered, scripts ${result.codex_hooks.scripts_present ? "present" : "missing"}, python3 ${result.codex_hooks.python3 ? "ok" : "missing"}`
+      : "not installed (use connect without --no-hooks)";
+    stdout.write(`${result.codex_hooks.ok ? "✓" : "✗"} Codex hooks: ${hooksDetail}\n`);
   }
   for (const client of result.clients) {
     const details = [
@@ -524,7 +579,13 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
       }
       const installed = scopeFromUrl(configuredServerUrl(client, raw));
       if (!installed) continue;
-      urlOverrides.set(client.id, scopedMcpUrl(installed.baseUrl, installed));
+      const installedScopedUrl = scopedMcpUrl(installed.baseUrl, installed);
+      urlOverrides.set(client.id, urlForClient({
+        ...options,
+        url: installedScopedUrl,
+        scope: installed,
+        defaultScope: null,
+      }, client));
       if (!first) first = installed;
     }
     if (first) {
@@ -555,6 +616,7 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
         clientVersion: await version(),
         expectedScope: probeScope,
         requireScope: options.hosted,
+        ...(clients[0]?.id === "codex" ? { requiredTools: CODEX_REQUIRED_TOOLS } : {}),
       })
       : {
         ok: false,
@@ -575,14 +637,26 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
         },
       };
     const hooksStatus = clients.some((client) => client.id === "claude-code")
-      ? await inspectHooks({ env })
+      ? await inspectHooks({ env, clientId: "claude-code" })
+      : null;
+    const codexHooksStatus = clients.some((client) => client.id === "codex")
+      ? await inspectHooks({ env, clientId: "codex" })
       : null;
+    const skillStatus = await Promise.all(
+      clients
+        .filter((client) => ["claude-code", "codex"].includes(client.id))
+        .map(async (client) => ({ client: client.id, ...await inspectMemoryAgentSkill(client.id, { env }) })),
+    );
     const result = {
-      ok: local.every((client) => client.ok) && remote.ok && (hooksStatus?.ok ?? true),
+      ok: local.every((client) => client.ok) && remote.ok
+        && (hooksStatus?.ok ?? true) && (codexHooksStatus?.ok ?? true)
+        && (!options.skills || skillStatus.every((skill) => skill.installed && skill.current)),
       url: redactUrlForDisplay(probeUrl),
       scope: { configured: Boolean(probeScope) },
       clients: local,
       hooks: hooksStatus,
+      codex_hooks: codexHooksStatus,
+      skills: skillStatus,
       remote,
     };
     if (options.json) stdout.write(`${JSON.stringify(result)}\n`);
@@ -598,12 +672,15 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     migrateLegacy: options.migrateLegacy,
     legacyUrls: [...new Set([options.url, options.baseUrl, HOSTED_MCP_URL])],
   });
+  const skillClients = clients.filter((client) => ["claude-code", "codex"].includes(client.id));
+  const manageSkills = skillClients.length > 0
+    && (options.action === "disconnect" || options.skills);
 
-  // Claude Code is the only client with a hook system today; the hooks are
-  // what make memory arrive without being asked. Disconnect always cleans
-  // them up, even when the install used --no-hooks.
+  // Codex and Claude Code use different lifecycle event sets but share the
+  // same fail-open scripts. Disconnect removes only our entries.
   const claudeCode = clients.find((client) => client.id === "claude-code");
-  let manageHooks = Boolean(claudeCode)
+  const hookClients = clients.filter((client) => ["claude-code", "codex"].includes(client.id));
+  let manageHooks = hookClients.length > 0
     && (options.action === "disconnect" || options.hooks);
   if (manageHooks && process.platform === "win32" && options.action === "connect") {
     // The hook commands are POSIX shell strings and the scripts need
@@ -611,33 +688,112 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     stderr.write("Note: memory hooks are not yet supported on Windows; skipping hook install.\n");
     manageHooks = false;
   }
+  // The capture proxy (zero-config memory capture) rides the same
+  // settings.json: env.ANTHROPIC_BASE_URL points Claude Code at the local
+  // forget-proxy. launchd-only for now, so connect wires it on macOS;
+  // disconnect always unwires — a no-op wherever connect never ran.
+  let manageProxy = Boolean(claudeCode)
+    && (options.action === "disconnect" || options.proxy);
+  if (manageProxy && options.action === "connect" && process.platform !== "darwin") {
+    stderr.write("Note: the capture proxy service requires launchd (macOS); skipping proxy wiring.\n");
+    manageProxy = false;
+  }
+  if (manageProxy && options.action === "connect" && !options.dryRun
+    && !(await findExecutable("forget-proxy", { env }))) {
+    // Checked before any file changes: an env override pointing at a proxy
+    // that cannot start would break the user's Claude, not just capture.
+    stderr.write("Note: forget-proxy not found on PATH; skipping proxy wiring (pip install 'forget-ai[server]').\n");
+    manageProxy = false;
+  }
+
   const hooksDir = manageHooks ? hooksDirFor({ env }) : "";
+  const hookSettings = new Map();
+  let proxyPlan = null;
   if (manageHooks) {
-    const settingsPath = settingsPathFor({ env });
-    let settingsRaw = "";
-    try {
-      settingsRaw = await readFile(settingsPath, "utf8");
-    } catch (error) {
-      if (!error || error.code !== "ENOENT") throw error;
+    for (const client of hookClients) {
+      const settingsPath = settingsPathFor({ env, clientId: client.id });
+      let settingsRaw = "";
+      try {
+        settingsRaw = await readFile(settingsPath, "utf8");
+      } catch (error) {
+        if (!error || error.code !== "ENOENT") throw error;
+      }
+      const settingsNext = options.action === "connect"
+        ? connectHooksSettings(settingsRaw, {
+          hooksDir,
+          url: urlFor(client),
+          clientId: client.id,
+        })
+        : disconnectHooksSettings(settingsRaw, { clientId: client.id });
+      hookSettings.set(client.id, { client, settingsPath, settingsRaw, settingsNext });
+    }
+  }
+  if (manageProxy) {
+    const settingsPath = settingsPathFor({ env, clientId: "claude-code" });
+    let record = hookSettings.get("claude-code");
+    if (!record) {
+      let settingsRaw = "";
+      try {
+        settingsRaw = await readFile(settingsPath, "utf8");
+      } catch (error) {
+        if (!error || error.code !== "ENOENT") throw error;
+      }
+      record = { client: claudeCode, settingsPath, settingsRaw, settingsNext: settingsRaw };
+    }
+    let settingsNext = record.settingsNext;
+    if (manageProxy && options.action === "connect") {
+      proxyPlan = wireProxyEnv(settingsNext);
+      if (proxyPlan.status === "skip") {
+        // (c) an odd configuration skips the whole wiring, loudly — being
+        // invisible must never mean silently breaking the user's setup.
+        stderr.write(`Warning: ${proxyPlan.reason}; skipping proxy wiring. Nothing was changed.\n`);
+        manageProxy = false;
+        proxyPlan = null;
+      } else {
+        settingsNext = proxyPlan.next;
+      }
     }
-    const settingsNext = options.action === "connect"
-      ? connectHooksSettings(settingsRaw, { hooksDir, url: urlFor(claudeCode) })
-      : disconnectHooksSettings(settingsRaw);
-    if (settingsRaw !== settingsNext) {
+    if (manageProxy && options.action === "disconnect") {
+      const wiring = await readWiringState({ env });
+      settingsNext = unwireProxyEnv(settingsNext, {
+        original: wiring?.original_base_url ?? null,
+      }).next;
+    }
+    hookSettings.set("claude-code", { ...record, settingsNext });
+  }
+  for (const record of hookSettings.values()) {
+    if (record.settingsRaw !== record.settingsNext) {
       changes.push({
-        client: claudeCode,
-        filePath: settingsPath,
-        before: settingsRaw,
-        after: settingsNext,
-        kind: "hooks",
+        client: record.client,
+        filePath: record.settingsPath,
+        before: record.settingsRaw,
+        after: record.settingsNext,
+        kind: "settings",
         sensitive: false,
         backup: options.action === "connect",
       });
     }
   }
+  let removeSharedHookScripts = false;
+  if (manageHooks && options.action === "disconnect") {
+    let anyRegistered = false;
+    for (const clientId of ["claude-code", "codex"]) {
+      const staged = hookSettings.get(clientId);
+      let raw = staged?.settingsNext ?? "";
+      if (!staged) {
+        try {
+          raw = await readFile(settingsPathFor({ env, clientId }), "utf8");
+        } catch (error) {
+          if (!error || error.code !== "ENOENT") throw error;
+        }
+      }
+      if (hooksInstalled(raw, { hooksDir, clientId })) anyRegistered = true;
+    }
+    removeSharedHookScripts = !anyRegistered;
+  }
 
   if (options.dryRun) {
-    if (!changes.length && !manageHooks) {
+    if (!changes.length && !manageHooks && !manageProxy && !manageSkills) {
       stdout.write("No changes needed.\n");
       return;
     }
@@ -646,29 +802,88 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     }
     if (manageHooks && options.action === "connect") {
       stdout.write(`Would install hook scripts into ${hooksDir}\n`);
-      stdout.write(`Would install slash commands (/forget, /forget-settings) into ${commandsDirFor({ env })}\n`);
+      if (claudeCode) {
+        stdout.write(`Would install slash commands (/forget, /forget-settings) into ${commandsDirFor({ env })}\n`);
+      }
     }
     if (manageHooks && options.action === "disconnect") {
-      stdout.write(`Would remove hook scripts from ${hooksDir}\n`);
-      stdout.write(`Would remove our slash commands from ${commandsDirFor({ env })} (user-edited files are kept)\n`);
+      if (removeSharedHookScripts) stdout.write(`Would remove hook scripts from ${hooksDir}\n`);
+      if (claudeCode) {
+        stdout.write(`Would remove our slash commands from ${commandsDirFor({ env })} (user-edited files are kept)\n`);
+      }
+    }
+    if (manageProxy && options.action === "connect") {
+      stdout.write(`Would register launchd services ${PROXY_LABEL} + ${WATCHDOG_LABEL} (capture proxy at ${PROXY_BASE_URL})\n`);
+      if (proxyPlan?.upstream) {
+        stdout.write(`Would chain the existing ANTHROPIC_BASE_URL as the proxy upstream: ${proxyPlan.upstream}\n`);
+      }
+    }
+    if (manageProxy && options.action === "disconnect") {
+      stdout.write(`Would remove launchd services ${PROXY_LABEL} + ${WATCHDOG_LABEL} and restore ANTHROPIC_BASE_URL\n`);
+    }
+    if (manageSkills) {
+      for (const client of skillClients) {
+        const verb = options.action === "connect" ? "install" : "remove";
+        stdout.write(`Would ${verb} the Memory Agent skill at ${skillDirFor(client.id, { env })}\n`);
+      }
     }
     return;
   }
 
   const result = await applyPlan(changes);
+  let skillPaths = [];
+  if (manageSkills) {
+    for (const client of skillClients) {
+      const skillResult = options.action === "connect"
+        ? await installMemoryAgentSkill(client.id, { env })
+        : await removeMemoryAgentSkill(client.id, { env });
+      skillPaths = skillPaths.concat(skillResult.written ?? skillResult.removed ?? []);
+      if ((skillResult.skipped ?? skillResult.kept ?? []).length) {
+        stderr.write(`Note: kept an existing unowned Memory Agent skill for ${client.name}.\n`);
+      }
+    }
+  }
   let hookScriptPaths = [];
   if (manageHooks) {
-    hookScriptPaths = options.action === "connect"
-      ? await installHookScripts(hooksDir)
-      : await removeHookScripts(hooksDir);
-    const commandsDir = commandsDirFor({ env });
-    const commandPaths = options.action === "connect"
-      ? await installCommandAssets(commandsDir)
-      : await removeCommandAssets(commandsDir);
-    hookScriptPaths = hookScriptPaths.concat(commandPaths);
+    if (options.action === "connect") hookScriptPaths = await installHookScripts(hooksDir);
+    else if (removeSharedHookScripts) hookScriptPaths = await removeHookScripts(hooksDir);
+    if (claudeCode) {
+      const commandsDir = commandsDirFor({ env });
+      const commandPaths = options.action === "connect"
+        ? await installCommandAssets(commandsDir)
+        : await removeCommandAssets(commandsDir);
+      hookScriptPaths = hookScriptPaths.concat(commandPaths);
+    }
+  }
+  let proxyPaths = [];
+  let proxyUpstream = null;
+  if (manageProxy) {
+    if (options.action === "connect") {
+      // State first: the watchdog and a future disconnect must know the
+      // user's original base URL before either could ever act on it. A
+      // no-op re-connect keeps the existing record (it holds the original).
+      let wiring = await readWiringState({ env });
+      if (proxyPlan.status === "wire" || !wiring) {
+        wiring = await writeWiringState({ env }, {
+          upstream: proxyPlan.upstream,
+          original: proxyPlan.original,
+        });
+      }
+      proxyUpstream = wiring.upstream ?? null;
+      const service = await installProxyServices({ env }, { upstream: proxyUpstream });
+      proxyPaths = service.written;
+      if (!service.installed) {
+        stderr.write(
+          `Warning: capture proxy service not fully registered — ${service.reason}\n`
+          + "  If Claude Code cannot reach the API, run: forget-connect disconnect --client claude-code\n",
+        );
+      }
+    } else {
+      proxyPaths = await removeProxyServices({ env });
+    }
   }
   const verb = options.action === "connect" ? "Connected" : "Disconnected";
-  if (!result.changed.length && !hookScriptPaths.length) {
+  if (!result.changed.length && !hookScriptPaths.length && !proxyPaths.length && !skillPaths.length) {
     stdout.write("No changes needed.\n");
   } else {
     stdout.write(`${verb} ${clients.map((client) => client.name).join(", ")}.\n`);
@@ -676,6 +891,8 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     for (const filePath of result.backups) stdout.write(`  backup  ${filePath}\n`);
     const hookVerb = options.action === "connect" ? "installed" : "removed";
     for (const filePath of hookScriptPaths) stdout.write(`  ${hookVerb} ${filePath}\n`);
+    for (const filePath of proxyPaths) stdout.write(`  ${hookVerb} ${filePath}\n`);
+    for (const filePath of skillPaths) stdout.write(`  ${hookVerb} ${filePath}\n`);
   }
   if (options.action === "connect") {
     if (options.scope) {
@@ -686,8 +903,19 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
       );
     }
     if (manageHooks) {
-      stdout.write("  hooks: session capsule, per-turn recall, conflict alerts, session capture (needs python3 on PATH)\n");
-      stdout.write("  commands: /forget (the recall dial) · /forget-settings (status, doctor, cloud usage)\n");
+      stdout.write("  hooks: shared capsule, per-turn recall, and session capture (needs python3 on PATH)\n");
+      if (claudeCode) {
+        stdout.write("  commands: /forget (the recall dial) · /forget-settings (status, doctor, cloud usage)\n");
+      }
+    }
+    if (manageProxy) {
+      stdout.write(`  proxy: capture proxy at ${PROXY_BASE_URL} (launchd ${PROXY_LABEL}, watchdog ${WATCHDOG_LABEL})\n`);
+      if (proxyUpstream) {
+        stdout.write(`  proxy upstream: ${proxyUpstream} (your previous ANTHROPIC_BASE_URL, chained)\n`);
+      }
+    }
+    if (manageSkills) {
+      stdout.write("  skill: shared Memory Agent quote, approval, receipt, and revoke contract\n");
     }
     if (options.hosted && !options.scope) {
       stdout.write(

package/src/core.js

@@ -43,6 +43,19 @@ export const MEMORY_RULES = [
   RULES_END,
 ].join("\n");
 
+export const CODEX_MEMORY_RULES = [
+  RULES_START,
+  "# Memory (Forget)",
+  "You have the user's long-term memory via the `forget` MCP server.",
+  "At session start and on resume/continue requests, call `prepare_codex_context` once with a short query for the current work and the exact current working directory as `client_workdir`. Use only its project-bound results. If it returns `project_unresolved`, `empty`, or `unavailable`, continue without memory; do not fall back to generic autopilot or cross-project task state.",
+  "Whenever the user refers to their own past decisions, preferences, plans, people, or prior discussions, call `search_memories` FIRST. For project-specific history, prefer `prepare_codex_context(query, client_workdir)` so another project's state cannot enter the capsule.",
+  "Results may carry a `trust` label: green (user-stated or tool-observed) is safe to act on; yellow (agent-inferred or self-summarized) requires confirmation before real-world action; red is superseded; unlabeled is yellow.",
+  "When the user states a durable decision, preference, or lasting fact, save it with `add_memory`; use `source_role=\"user\"` only for the user's own words and check `get_event_status` before claiming the write completed. Never record a planned action as completed without evidence.",
+  "Use `supersede_memory` to retire a wrong fact and `confirm_memory` when evidence verifies a provisional claim. When a context trace materially influenced work, call `record_context_outcome` with the memory ids actually used or rejected.",
+  "Use `team_read` and `team_note` only for explicit agent collaboration, never as a substitute for personal memory.",
+  RULES_END,
+].join("\n");
+
 export class ConfigError extends Error {
   constructor(message) {
     super(message);
@@ -315,16 +328,16 @@ function removeRulesBlock(text, startMarker, endMarker) {
   return left || right;
 }
 
-export function installRules(raw, { migrateLegacy = true } = {}) {
+export function installRules(raw, { migrateLegacy = true, rules = MEMORY_RULES } = {}) {
   let next = raw;
   if (migrateLegacy) {
     next = removeRulesBlock(next, LEGACY_RULES_START, LEGACY_RULES_END);
   }
   const bounds = findManagedBlock(next, RULES_START, RULES_END);
   if (bounds) {
-    return next.slice(0, bounds.start) + MEMORY_RULES + next.slice(bounds.end);
+    return next.slice(0, bounds.start) + rules + next.slice(bounds.end);
   }
-  return next ? `${next}\n${MEMORY_RULES}\n` : `${MEMORY_RULES}\n`;
+  return next ? `${next}\n${rules}\n` : `${rules}\n`;
 }
 
 export function removeRules(raw) {
@@ -579,10 +592,10 @@ function rulesConnected(raw) {
   }
 }
 
-function rulesCurrent(raw) {
+function rulesCurrent(raw, rules = MEMORY_RULES) {
   try {
     const bounds = findManagedBlock(raw, RULES_START, RULES_END);
-    return Boolean(bounds && raw.slice(bounds.start, bounds.end) === MEMORY_RULES);
+    return Boolean(bounds && raw.slice(bounds.start, bounds.end) === rules);
   } catch {
     return false;
   }
@@ -602,7 +615,10 @@ export async function inspectClients(clients, { url = "", apiKey = "", urlFor =
         client,
         config: configConnected(client, configRaw),
         rules: client.rulesPath ? rulesConnected(rulesRaw) : null,
-        rulesCurrent: client.rulesPath ? rulesCurrent(rulesRaw) : null,
+        rulesCurrent: client.rulesPath ? rulesCurrent(
+          rulesRaw,
+          client.id === "codex" ? CODEX_MEMORY_RULES : MEMORY_RULES,
+        ) : null,
         ...expected,
       };
     }),
@@ -631,8 +647,8 @@ export async function buildPlan(
   }
   const changes = [];
   for (const client of clients) {
-    // urlFor lets connect scope each client into its own memory pool
-    // (/mcp/{app}/http/{user}) while everything else shares one plan.
+    // urlFor lets every provider share one vault scope while retaining its
+    // own query profile and provenance in the installed URL.
     const clientUrl = urlFor ? urlFor(client) : url;
     const configRaw = await readOptional(client.configPath);
     let configNext;
@@ -665,7 +681,10 @@ export async function buildPlan(
     if (client.rulesPath && installInstructionRules) {
       const rulesRaw = await readOptional(client.rulesPath);
       const rulesNext = action === "connect"
-        ? installRules(rulesRaw, { migrateLegacy })
+        ? installRules(rulesRaw, {
+          migrateLegacy,
+          rules: client.id === "codex" ? CODEX_MEMORY_RULES : MEMORY_RULES,
+        })
         : removeRules(rulesRaw);
       addChange(
         changes,

package/src/doctor.js

@@ -9,6 +9,29 @@ export const REQUIRED_TOOLS = [
   "record_context_outcome",
   "record_task_state",
   "get_task_state",
+  "catalog_search",
+  "product_quote",
+  "grant_create",
+  "agent_consult",
+  "receipt_verify",
+  "grant_revoke",
+];
+export const CODEX_REQUIRED_TOOLS = [
+  "prepare_codex_context",
+  "search_memories",
+  "add_memory",
+  "supersede_memory",
+  "confirm_memory",
+  "get_event_status",
+  "record_context_outcome",
+  "team_read",
+  "team_note",
+  "catalog_search",
+  "product_quote",
+  "grant_create",
+  "agent_consult",
+  "receipt_verify",
+  "grant_revoke",
 ];
 
 function addSensitiveValueVariants(variants, value) {