@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/cli/coding-agent/bank-from-cwd.mjs

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "yaml";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+function validGitEntry(root) {
+  const entry = path.join(root, ".git");
+  try {
+    const stat = fs.statSync(entry);
+    if (stat.isDirectory()) return fs.existsSync(path.join(entry, "HEAD")) && fs.existsSync(path.join(entry, "config"));
+    if (!stat.isFile()) return false;
+    const match = /^gitdir:\s*(.+)\s*$/m.exec(fs.readFileSync(entry, "utf8"));
+    if (!match) return false;
+    const gitDir = path.resolve(root, match[1]);
+    return fs.statSync(gitDir).isDirectory()
+      && (fs.existsSync(path.join(gitDir, "HEAD")) || fs.existsSync(path.join(gitDir, "commondir")));
+  } catch { return false; }
+}
+
+function projectRoot(cwd) {
+  try {
+    if (!fs.statSync(cwd).isDirectory()) return cwd;
+  } catch { return cwd; }
+  let candidate = cwd;
+  while (true) {
+    if (validGitEntry(candidate)) return candidate;
+    const parent = path.dirname(candidate);
+    if (parent === candidate) return cwd;
+    candidate = parent;
+  }
+}
+
+function projectName(root) {
+  try {
+    const gitEntry = path.join(root, ".git");
+    const stat = fs.statSync(gitEntry);
+    let gitDir = gitEntry;
+    if (stat.isFile()) {
+      const match = /^gitdir:\s*(.+)\s*$/m.exec(fs.readFileSync(gitEntry, "utf8"));
+      if (match) gitDir = path.resolve(root, match[1]);
+    }
+    const commonFile = path.join(gitDir, "commondir");
+    const commonPath = fs.existsSync(commonFile)
+      ? path.resolve(gitDir, fs.readFileSync(commonFile, "utf8").trim())
+      : gitDir;
+    // Only linked worktrees use a shared project's name. Submodules retain their own repository name.
+    if (path.basename(path.dirname(gitDir)) === "worktrees" && path.basename(commonPath) === ".git") {
+      return path.basename(path.dirname(commonPath));
+    }
+  } catch { /* non-git workspace */ }
+  return path.basename(root);
+}
+
+function expandPrefix(prefix, home) {
+  if (typeof prefix !== "string" || !prefix.trim()) return null;
+  let expanded = prefix;
+  if (prefix === "~" || prefix.startsWith("~/")) {
+    expanded = prefix === "~" ? home : path.join(home, prefix.slice(2));
+  } else if (prefix.startsWith("~")) {
+    const slash = prefix.indexOf(path.sep);
+    const username = slash < 0 ? prefix.slice(1) : prefix.slice(1, slash);
+    if (!username) return null;
+    let userHome = null;
+    try {
+      userHome = fs.readFileSync("/etc/passwd", "utf8").split(/\r?\n/)
+        .map((line) => line.split(":"))
+        .find((fields) => fields[0] === username)?.[5] || null;
+    } catch { /* passwd is not available on every platform */ }
+    if (!userHome && username === os.userInfo().username) userHome = home;
+    if (!userHome) return null;
+    expanded = slash < 0 ? userHome : path.join(userHome, prefix.slice(slash + 1));
+  }
+  if (!path.isAbsolute(expanded)) return null;
+  return path.resolve(expanded);
+}
+
+function matchingBank(target, mappings, home) {
+  if (!mappings || typeof mappings !== "object" || Array.isArray(mappings)) return null;
+  return Object.entries(mappings)
+    .filter(([prefix, bank]) => typeof bank === "string" && bank.trim() && expandPrefix(prefix, home))
+    .map(([prefix, bank]) => [expandPrefix(prefix, home), bank.trim()])
+    .filter(([prefix]) => target === prefix || target.startsWith(`${prefix}${path.sep}`))
+    .sort(([a], [b]) => b.length - a.length)[0]?.[1] || null;
+}
+
+function readJson(file) {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  } catch { return {}; }
+}
+
+function yamlBanks(file, home) {
+  const source = fs.readFileSync(file, "utf8");
+  const document = parseDocument(source, { uniqueKeys: true, version: "1.1" });
+  if (document.errors.length) throw new Error(`${file}: ${document.errors[0].message}`);
+  const data = document.toJS() ?? {};
+  if (typeof data !== "object" || Array.isArray(data)) throw new Error(`${file}: expected a YAML mapping`);
+  const banks = Object.hasOwn(data, "banks")
+    ? data.banks
+    : { "~/Documents/sample-project": "coding-agent::documents-sample-project" };
+  if (!banks || typeof banks !== "object" || Array.isArray(banks)) throw new Error(`${file}: banks must be a mapping`);
+  const result = {};
+  for (const [key, value] of Object.entries(banks)) {
+    if (typeof key !== "string" || !key.trim()) throw new Error(`${file}: banks key must be a non-empty string`);
+    if (typeof value !== "string" || !value.trim()) throw new Error(`${file}: banks[${key}] must be a non-empty bank id string`);
+    const prefix = expandPrefix(key, home);
+    if (!prefix) throw new Error(`${file}: banks key must be an absolute path: ${key}`);
+    result[prefix] = value;
+  }
+  return result;
+}
+
+function configuredBanks(home, env) {
+  const override = env.HINDSIGHT_INDEX_CONFIG;
+  const user = path.join(home, ".config", "hindsight", "index.yml");
+  const configFile = override ? (expandPrefix(override, home) || path.resolve(override))
+    : fs.existsSync(user) ? user : path.join(PKG_ROOT, "config", "index.yml");
+  return yamlBanks(configFile, home);
+}
+
+/** Map a workspace cwd to the indexer's project bank. */
+export function bankFromCwd(cwd, options = {}) {
+  const dir = path.resolve(String(cwd || process.cwd()));
+  const root = projectRoot(dir);
+  const home = options.home || process.env.HOME || os.homedir();
+  const env = options.env || process.env;
+  const indexBanks = options.banks || configuredBanks(home, env);
+  const personalConfig = readJson(path.join(home, ".config", "personal-memory", "coding-agent.json"));
+  const legacyConfig = readJson(path.join(home, ".hindsight", "coding-agent.json"));
+  const mappingTarget = root === dir ? dir : root;
+  for (const mapping of [indexBanks, options.mapPathToBank || personalConfig.mapPathToBank, legacyConfig.mapPathToBank]) {
+    const bank = matchingBank(mappingTarget, mapping, home);
+    if (bank) return bank;
+  }
+  return `coding-agent::${projectName(root) || "workspace"}`;
+}

package/cli/coding-agent/capabilities.mjs

@@ -0,0 +1,23 @@
+/** Session-memory hook parity vs Hindsight plugin (non-Hindsight uses MCP shim). */
+
+import { CODING_AGENTS, DEFAULT_AGENT_IDS } from "./agents.mjs";
+
+export const AGENT_IDS = Object.freeze(CODING_AGENTS.map((a) => a.id));
+export { DEFAULT_AGENT_IDS };
+
+/** @typedef {"retain" | "recall" | "reflect" | "consolidate" | "bank_scope"} Feature */
+
+/** @type {Record<string, Partial<Record<Feature, boolean>>>} */
+export const PROVIDER_CAPABILITIES = {
+  hindsight: { retain: true, recall: true, reflect: true, consolidate: true, bank_scope: true },
+  mem0: { retain: true, recall: true, reflect: true, consolidate: false, bank_scope: true },
+  cognee: { retain: true, recall: true, reflect: true, consolidate: true, bank_scope: true },
+};
+
+/**
+ * @param {string} provider
+ * @param {Feature} feature
+ */
+export function providerSupports(provider, feature) {
+  return Boolean(PROVIDER_CAPABILITIES[provider]?.[feature]);
+}

package/cli/coding-agent/hook-harnesses.mjs

@@ -0,0 +1,87 @@
+/** Hook event names and stdout shapes per coding-agent host. */
+
+export const SHIM_MARKER = "coding-agent/hook-runner.mjs";
+
+export const SHIM_HARNESSES = {
+  "claude-code": {
+    configStyle: "nested",
+    settingsPath: (home) => `${home}/.claude/settings.json`,
+    rootKey: "hooks",
+    events: {
+      sessionStart: { hook: "SessionStart", timeout: 30 },
+      prompt: { hook: "UserPromptSubmit", timeout: 30 },
+      stop: { hook: "Stop", timeout: 60 },
+    },
+    parse: {
+      sessionStart: (ev) => ({ cwd: ev.cwd, sessionId: ev.session_id }),
+      prompt: (ev) => ({ cwd: ev.cwd, sessionId: ev.session_id, prompt: ev.prompt }),
+      stop: (ev) => ({ cwd: ev.cwd, sessionId: ev.session_id, transcriptPath: ev.transcript_path }),
+    },
+    emit: {
+      sessionStart: (ctx) => ({
+        hookSpecificOutput: { hookEventName: "SessionStart", ...(ctx ? { additionalContext: ctx } : {}) },
+      }),
+      prompt: (ctx) => ({
+        hookSpecificOutput: { hookEventName: "UserPromptSubmit", ...(ctx ? { additionalContext: ctx } : {}) },
+      }),
+      stop: () => ({}),
+    },
+  },
+  codex: {
+    configStyle: "nested",
+    settingsPath: (home) => `${home}/.codex/hooks.json`,
+    rootKey: "hooks",
+    events: {
+      sessionStart: { hook: "SessionStart", timeout: 30 },
+      prompt: { hook: "UserPromptSubmit", timeout: 30 },
+      stop: { hook: "Stop", timeout: 60 },
+    },
+    parse: {
+      sessionStart: (ev) => ({ cwd: ev.cwd, sessionId: ev.session_id }),
+      prompt: (ev) => ({ cwd: ev.cwd, sessionId: ev.session_id, prompt: ev.prompt ?? ev.user_prompt }),
+      stop: (ev) => ({ cwd: ev.cwd, sessionId: ev.session_id, transcriptPath: ev.transcript_path }),
+    },
+    emit: {
+      sessionStart: (ctx) => ({
+        hookSpecificOutput: { hookEventName: "SessionStart", ...(ctx ? { additionalContext: ctx } : {}) },
+      }),
+      prompt: (ctx) => ({
+        hookSpecificOutput: { hookEventName: "UserPromptSubmit", ...(ctx ? { additionalContext: ctx } : {}) },
+      }),
+      stop: () => ({}),
+    },
+  },
+  "cursor-cli": {
+    configStyle: "flat",
+    settingsPath: (home) => `${home}/.cursor/hooks.json`,
+    rootKey: null,
+    events: {
+      sessionStart: { hook: "sessionStart", timeout: 30 },
+      prompt: { hook: "beforeSubmitPrompt", timeout: 30 },
+      stop: { hook: "stop", timeout: 30 },
+    },
+    parse: {
+      sessionStart: (ev) => ({
+        cwd: ev.cwd ?? ev.workspace_root ?? ev.workspace_roots?.[0],
+        sessionId: ev.conversation_id ?? ev.session_id,
+      }),
+      prompt: (ev) => ({
+        cwd: ev.cwd ?? ev.workspace_root ?? ev.workspace_roots?.[0],
+        sessionId: ev.conversation_id ?? ev.session_id,
+        prompt: ev.prompt ?? ev.user_prompt,
+      }),
+      stop: (ev) => ({
+        cwd: ev.cwd ?? ev.workspace_root ?? ev.workspace_roots?.[0],
+        sessionId: ev.conversation_id ?? ev.session_id,
+        transcriptPath: ev.transcript_path,
+      }),
+    },
+    emit: {
+      sessionStart: (ctx) => (ctx ? { additional_context: ctx } : {}),
+      prompt: (ctx) => ({ continue: true, ...(ctx ? { additional_context: ctx } : {}) }),
+      stop: () => ({}),
+    },
+  },
+};
+
+export const SHIM_AGENT_IDS = Object.freeze(Object.keys(SHIM_HARNESSES));

package/cli/coding-agent/hook-runner.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/**
+ * Session hook entry: node hook-runner.mjs <harness> <sessionStart|prompt|stop>
+ * stdin: host hook JSON. Uses unified memory facade (active MEMORY_PROVIDER).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { bankFromCwd } from "./bank-from-cwd.mjs";
+import { accessAllowed, readAccessConfig } from "./access-policy.mjs";
+import { SHIM_HARNESSES } from "./hook-harnesses.mjs";
+import { sessionRecall, sessionRetain } from "./session-facade.mjs";
+import { resolveMcpContext } from "../mcp/context.mjs";
+import { resolveStackRoot } from "../stack.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+function resolveAccess(cwd, config, home = process.env.HOME || os.homedir()) {
+  if (!accessAllowed(cwd, config)) return { allowed: false };
+  return { allowed: true, bank: bankFromCwd(cwd, { home, mapPathToBank: config.mapPathToBank }) };
+}
+
+async function readStdinJson() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) return {};
+  return JSON.parse(raw);
+}
+
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+const TRANSCRIPT_MAX_CHARS = 12000;
+
+function blockText(content, acceptedTypes) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part) => part && acceptedTypes.includes(part.type) && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("");
+}
+
+function safeAction(label, input) {
+  let parsed = input;
+  if (typeof input === "string") {
+    try { parsed = JSON.parse(input); } catch { /* retain only valid structured arguments */ }
+  }
+  const summary = parsed && typeof parsed === "object" ? JSON.stringify(parsed) : "";
+  return `[action: ${label}${summary ? ` ${summary.slice(0, 800)}` : ""}]`;
+}
+
+function parseTranscriptRecord(harnessId, record) {
+  if (!record || typeof record !== "object") return [];
+  const out = [];
+  if (harnessId === "codex") {
+    // Best-effort adapter for observed rollout response_item rows. Codex says
+    // transcript_path is provided for convenience, but its transcript schema is unstable.
+    const payload = record.type === "response_item" ? record.payload : null;
+    if (!payload || typeof payload !== "object") return out;
+    if (payload.type === "message" && ["user", "assistant"].includes(payload.role)) {
+      const accepted = payload.role === "user" ? ["input_text"] : ["output_text"];
+      const text = blockText(payload.content, accepted);
+      if (text.trim()) out.push(`${payload.role}: ${text.trim()}`);
+    } else if (payload.type === "function_call" || payload.type === "custom_tool_call") {
+      const label = payload.name || payload.type;
+      out.push(safeAction(label, payload.arguments ?? payload.input));
+    }
+    return out;
+  }
+  if (harnessId === "claude-code") {
+    // Claude transcript message rows use user/assistant roles. Keep only ordinary
+    // text and explicit tool-use blocks; thinking and tool-result blocks are omitted.
+    const message = record.message;
+    if (!["user", "assistant"].includes(message?.role)) return out;
+    const text = blockText(message.content, ["text"]);
+    if (text.trim()) out.push(`${message.role}: ${text.trim()}`);
+    if (message.role === "assistant" && Array.isArray(message.content)) {
+      for (const part of message.content) {
+        if (part?.type === "tool_use") out.push(safeAction(part.name || "tool", part.input));
+      }
+    }
+    return out;
+  }
+  if (harnessId === "cursor-cli") {
+    // Observed Cursor agent-transcripts rows have a top-level role and a
+    // message.content array. This adapter is based on the local schema shape;
+    // live Hook transcript_path linkage remains unverified.
+    const role = record.role;
+    const message = record.message;
+    if (!["user", "assistant"].includes(role) || !Array.isArray(message?.content)) return out;
+    const text = blockText(message.content, ["text"]);
+    if (text.trim()) out.push(`${role}: ${text.trim()}`);
+    if (role === "assistant") {
+      for (const part of message.content) {
+        if (part?.type === "tool_use") out.push(safeAction(part.name || "tool", part.input));
+      }
+    }
+    return out;
+  }
+  return out;
+}
+
+function cursorFile(home) {
+  return path.join(home, ".config", "personal-memory", "transcript-cursors.json");
+}
+
+function loadTranscriptCursors(home) {
+  try {
+    const value = JSON.parse(fs.readFileSync(cursorFile(home), "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  } catch { return {}; }
+}
+
+function saveTranscriptCursors(home, cursors) {
+  const file = cursorFile(home);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify(cursors), { mode: 0o600 });
+  fs.renameSync(temporary, file);
+}
+
+function readNewTranscript(harnessId, transcriptPath, home, sessionId) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return null;
+  try {
+    const stat = fs.statSync(transcriptPath);
+    if (!stat.isFile()) return null;
+    const key = `${harnessId}:${sessionId || path.resolve(transcriptPath)}`;
+    const cursors = loadTranscriptCursors(home);
+    const saved = cursors[key];
+    const oldPosition = Number.isSafeInteger(saved) ? saved
+      : Number.isSafeInteger(saved?.position) ? saved.position : 0;
+    const position = oldPosition <= stat.size ? oldPosition : 0;
+    let validPosition = position;
+    if (position && typeof saved === "object" && saved.anchor) {
+      const anchorLength = Math.min(256, position);
+      const anchorBuffer = Buffer.alloc(anchorLength);
+      const anchorFd = fs.openSync(transcriptPath, "r");
+      try { fs.readSync(anchorFd, anchorBuffer, 0, anchorLength, position - anchorLength); }
+      finally { fs.closeSync(anchorFd); }
+      if (anchorBuffer.toString("base64") !== saved.anchor) validPosition = 0;
+    }
+    const start = Math.max(validPosition, stat.size - TRANSCRIPT_TAIL_BYTES);
+    const length = stat.size - start;
+    const fd = fs.openSync(transcriptPath, "r");
+    const buffer = Buffer.alloc(length);
+    try { fs.readSync(fd, buffer, 0, length, start); } finally { fs.closeSync(fd); }
+    const text = buffer.toString("utf8");
+    const completeText = text.endsWith("\n") ? text : text.slice(0, text.lastIndexOf("\n") + 1);
+    const completeLines = completeText.split("\n");
+    if (completeLines.at(-1) === "") completeLines.pop();
+    if (harnessId === "cursor-cli") {
+      // Do not create a cursor for unknown or unverified row shapes. A single
+      // structurally recognized message row enables the bounded adapter.
+      const recognized = completeLines.some((line) => {
+        try {
+          const record = JSON.parse(line);
+          return ["user", "assistant"].includes(record?.role) && Array.isArray(record?.message?.content);
+        } catch { return false; }
+      });
+      if (!recognized) return null;
+    }
+    const extracted = [];
+    for (const line of completeLines) {
+      if (!line.trim()) continue;
+      try { extracted.push(...parseTranscriptRecord(harnessId, JSON.parse(line))); } catch { /* ignore malformed rows */ }
+    }
+    const content = extracted.join("\n").slice(-TRANSCRIPT_MAX_CHARS).trim();
+    // A bounded tail can begin mid-row. If it contains no newline, do not
+    // checkpoint that interior offset; retry from the last known boundary.
+    const nextPosition = completeText.length
+      ? start + Buffer.byteLength(completeText)
+      : validPosition;
+    const anchorLength = Math.min(256, nextPosition);
+    const anchorBuffer = Buffer.alloc(anchorLength);
+    const anchorFd = fs.openSync(transcriptPath, "r");
+    try {
+      if (anchorLength) fs.readSync(anchorFd, anchorBuffer, 0, anchorLength, nextPosition - anchorLength);
+    } finally { fs.closeSync(anchorFd); }
+    return {
+      key, cursors, position: { position: nextPosition, anchor: anchorBuffer.toString("base64") }, content,
+    };
+  } catch { return null; }
+}
+
+export async function runHook(harnessId, phase, { home, env, repoRoot, ev, fetchFn = fetch }) {
+  const spec = SHIM_HARNESSES[harnessId];
+  if (!spec) throw new Error(`unknown harness ${harnessId}`);
+  const parsed = spec.parse[phase](ev);
+  const config = readAccessConfig(home);
+  const access = config ? resolveAccess(parsed.cwd, config, home) : { allowed: false };
+  if (!access.allowed) return spec.emit[phase](undefined);
+  const bank = access.bank;
+  let runtimeConfig = {};
+  try {
+    runtimeConfig = JSON.parse(fs.readFileSync(path.join(repoRoot, "agent-runtime.json"), "utf8"));
+  } catch {
+    // Checkout and direct test calls use ordinary stack resolution.
+  }
+  const runtimeEnv = { ...env, PM_STACK_ROOT: env.PM_STACK_ROOT || runtimeConfig.stackRoot };
+  const stack = resolveStackRoot({ pkgRoot: repoRoot, env: runtimeEnv, home });
+  const ctx = resolveMcpContext({ home, stackRoot: stack.root, repoRoot, env: runtimeEnv });
+  let context = "";
+
+  if (phase === "sessionStart") {
+    context = await sessionRecall(
+      ctx,
+      { query: "What should I know about this project and recent decisions?", bank, limit: 8,
+        budget: "low", maxTokens: 1200 },
+      fetchFn,
+    );
+  } else if (phase === "prompt") {
+    const q = String(parsed.prompt || "").trim();
+    if (q) {
+      context = await sessionRecall(ctx, { query: q, bank, limit: 8 }, fetchFn);
+    }
+  } else if (phase === "stop") {
+    const transcript = readNewTranscript(harnessId, parsed.transcriptPath, home, parsed.sessionId);
+    if (transcript) {
+      if (transcript.content) {
+        await sessionRetain(
+          ctx,
+          {
+            bank,
+            content: `Session turn (${harnessId} ${parsed.sessionId || "unknown"}):\n${transcript.content}`,
+          },
+          fetchFn,
+        );
+      }
+      transcript.cursors[transcript.key] = transcript.position;
+      saveTranscriptCursors(home, transcript.cursors);
+    }
+    return spec.emit.stop();
+  }
+
+  return spec.emit[phase](context?.trim() || undefined);
+}
+
+async function main() {
+  const [harnessId, phase] = process.argv.slice(2);
+  if (!harnessId || !phase || !SHIM_HARNESSES[harnessId]?.parse[phase]) {
+    console.error("usage: hook-runner.mjs <claude-code|codex|cursor-cli> <sessionStart|prompt|stop>");
+    process.exit(2);
+  }
+  try {
+    const ev = await readStdinJson();
+    const out = await runHook(harnessId, phase, {
+      home: process.env.HOME || os.homedir(),
+      env: process.env,
+      repoRoot: PKG_ROOT,
+      ev,
+    });
+    if (out && Object.keys(out).length) process.stdout.write(`${JSON.stringify(out)}\n`);
+  } catch (err) {
+    console.error(`openmem hook: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+}
+
+const self = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(self)) main();

package/cli/coding-agent/install-access.mjs

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { mergeOpencodeConfig, opencodeConfigPath } from "./opencode-config.mjs";
+
+const SKILL_TARGETS = {
+  "claude-code": ".claude/skills/openmem",
+  codex: ".agents/skills/openmem",
+  "cursor-cli": ".cursor/skills/openmem",
+  opencode: ".config/opencode/skills/openmem",
+};
+
+function readJson(file) {
+  return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {};
+}
+
+function writeJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function updateCodexToml(text, scriptPath, stackRoot) {
+  const blocks = text.split(/(?=^[ \t]*\[)/m);
+  const featureIndex = blocks.findIndex((block) => /^[ \t]*\[features\][ \t]*(?:#.*)?(?:\r?\n|$)/.test(block));
+  if (featureIndex < 0) blocks.push(`${text && !text.endsWith("\n") ? "\n" : ""}[features]\nhooks = true\n`);
+  else if (!/^hooks\s*=/m.test(blocks[featureIndex])) blocks[featureIndex] = `${blocks[featureIndex].trimEnd()}\nhooks = true\n`;
+  text = blocks.join("");
+  const section = [
+    "[mcp_servers.openmem]",
+    'command = "node"',
+    `args = [${JSON.stringify(scriptPath)}]`,
+    "[mcp_servers.openmem.env]",
+    `PM_STACK_ROOT = ${JSON.stringify(stackRoot)}`,
+  ].join("\n");
+  // Drop current openmem blocks and the pre-rebrand personal-memory name.
+  const oldServer =
+    /^[ \t]*\[mcp_servers\.(?:openmem|"openmem"|'openmem'|personal-memory|"personal-memory"|'personal-memory')(?:\.(?:env|"env"|'env'))?[ \t]*\]/;
+  const retained = text.split(/(?=^[ \t]*\[)/m).filter((block) => !oldServer.test(block));
+  return `${retained.join("").trimEnd()}\n\n${section}\n`;
+}
+
+/** Install one shared skill and the unified MCP in each selected agent's global config. */
+export function installAgentAccess({ home, runtimeRoot, stackRoot, agents, dry = false, h }) {
+  const scriptPath = path.join(runtimeRoot, "cli", "openmem-mcp.mjs");
+  const skillSource = path.join(runtimeRoot, "skills", "openmem", "SKILL.md");
+  for (const agent of agents) {
+    const skillRel = SKILL_TARGETS[agent];
+    if (!skillRel) continue;
+    const skillPath = path.join(home, skillRel, "SKILL.md");
+    if (dry) h?.info(`[dry-run] install ${agent} openmem skill → ${skillPath}`);
+    else {
+      fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+      fs.copyFileSync(skillSource, skillPath);
+      h?.ok(`${agent} skill → ${skillPath}`);
+    }
+    if (agent === "cursor-cli") continue; // install-mcp owns ~/.cursor/mcp.json
+    if (agent === "codex") {
+      const file = path.join(home, ".codex", "config.toml");
+      if (dry) h?.info(`[dry-run] merge openmem MCP into ${file}`);
+      else {
+        const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, updateCodexToml(current, scriptPath, stackRoot));
+        h?.ok(`codex MCP → ${file}`);
+      }
+      continue;
+    }
+    const file = agent === "claude-code" ? path.join(home, ".claude.json") : opencodeConfigPath(home);
+    if (dry) {
+      h?.info(`[dry-run] merge openmem MCP into ${file}`);
+      continue;
+    }
+    if (agent === "claude-code") {
+      const config = readJson(file);
+      const servers = { ...(config.mcpServers || {}) };
+      delete servers["personal-memory"];
+      servers.openmem = {
+        type: "stdio", command: "node", args: [scriptPath], env: { PM_STACK_ROOT: stackRoot },
+      };
+      config.mcpServers = servers;
+      writeJson(file, config);
+    } else {
+      mergeOpencodeConfig(home, "mcp", (existing) => {
+        const next = { ...existing, openmem: {
+          type: "local", command: ["node", scriptPath], enabled: true,
+          environment: { PM_STACK_ROOT: stackRoot },
+        } };
+        delete next["personal-memory"];
+        return next;
+      });
+    }
+    h?.ok(`${agent} MCP → ${file}`);
+  }
+}