@bcmyguest/openmem 0.6.3 → 0.9.0

package/wizard/lib/context-step.mjs

@@ -0,0 +1,140 @@
+import { spawnSync } from "node:child_process";
+import {
+  CONTEXT_PROXY_SERVICE,
+  contextProxyRunning,
+  prepareContextProxyFiles,
+  proxyServiceNeeded,
+} from "../../cli/context-management.mjs";
+import { agentsPointedAtContextProxy } from "../../cli/coding-agent/install-context-proxy.mjs";
+import { act } from "./exec.mjs";
+import { composeArgs, composeSpawnOptions } from "./compose.mjs";
+import { info, ok, step, warn } from "./log.mjs";
+import { multiselect } from "./prompts.mjs";
+import { CONTEXT_AGENT_KEYS, contextAgentsFromPmConfig, updatePmConfigContextAgents } from "./pm-config.mjs";
+
+/**
+ * Wizard step "Context management (smart compaction)": pick the installed agents to trim, save
+ * `[context_proxy.agents]` and `[context_proxy] enabled` (syncPmConfig keeps the table when it rewrites
+ * config.toml), and start or stop the compose `context-proxy` service. install-coding-agent reads the
+ * saved values when the next step wires agents.
+ */
+
+export const CONTEXT_STEP_TITLE = "Context management (smart compaction)";
+/** Agents the step offers. */
+const SELECTABLE = ["claude-code", "opencode1", "codex", "opencode2"];
+const LABELS = {
+  "claude-code": "Claude Code (context-proxy service)",
+  opencode1: "OpenCode 1 (context-proxy service)",
+  codex: "Codex (context-proxy service, ChatGPT login)",
+  opencode2: "OpenCode 2 (native plugin, no service)",
+};
+
+/**
+ * Config keys for detected harnesses (`claude-code`, `codex`, `opencode`, `cursor-cli`).
+ * @param {string[]} harnesses
+ * @param {number} opencodeMajor
+ */
+export function contextAgentKeys(harnesses, opencodeMajor) {
+  const keys = [];
+  if (harnesses.includes("claude-code")) keys.push("claude-code");
+  if (harnesses.includes("codex")) keys.push("codex");
+  if (harnesses.includes("opencode")) keys.push(opencodeMajor >= 2 ? "opencode2" : "opencode1");
+  return keys;
+}
+
+/**
+ * Defaults: a saved per-agent key, else a saved `enabled`, else OpenCode 2 on and the proxy-routed agents off.
+ * @param {Record<string, unknown>} cfg
+ * @returns {Record<string, boolean>}
+ */
+export function contextAgentDefaults(cfg) {
+  return contextAgentsFromPmConfig(cfg).agents;
+}
+
+/** Whether the proxy service is needed: the step's choice, else the saved config. */
+export function contextServiceWanted(ctx) {
+  return proxyServiceNeeded(ctx.contextAgents || contextAgentsFromPmConfig(ctx.pmMerged || {}).agents);
+}
+
+/** Context with the context-proxy profile added, for compose calls on that service. */
+function withProxyProfile(ctx) {
+  return { ...ctx, extraComposeProfiles: [...(ctx.extraComposeProfiles || []), CONTEXT_PROXY_SERVICE] };
+}
+
+/**
+ * Multi-select the installed agents (defaults: contextAgentDefaults) and save the values when they differ
+ * from config. Agents that are not installed keep their saved value, else their default.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} number step number shown in the title
+ * @param {string[]} installed config keys of the installed agents (contextAgentKeys)
+ * @returns {Promise<Record<string, boolean>>}
+ */
+export async function chooseContextManagement(ctx, number, installed) {
+  step(`${number}. ${CONTEXT_STEP_TITLE}`);
+  info("Stores every session message in a local SQLite store and trims long sessions; agents query the trimmed turns with smart_compact_search and smart_compact_sql.");
+  info("Claude Code, OpenCode 1 and Codex go through the local context-proxy compose service; OpenCode 2 uses its native plugin.");
+  const cfg = ctx.pmMerged || {};
+  const { agents: current, saved } = contextAgentsFromPmConfig(cfg);
+  const defaults = contextAgentDefaults(cfg);
+  const offered = SELECTABLE.filter((k) => installed.includes(k));
+  let values;
+  if (!offered.length) {
+    info("no agent that supports context management is installed; saved values kept");
+    values = current;
+  } else {
+    const picked = await multiselect(
+      ctx,
+      "Trim long sessions for which agents?",
+      offered.map((k) => ({ value: k, label: LABELS[k] })),
+      offered.filter((k) => defaults[k]),
+    );
+    values = Object.fromEntries(CONTEXT_AGENT_KEYS.map((k) => [k, offered.includes(k) ? picked.includes(k) : (saved.includes(k) ? current[k] : defaults[k])]));
+    const changed = CONTEXT_AGENT_KEYS.some((k) => !saved.includes(k) || current[k] !== values[k]);
+    if (changed) {
+      const r = updatePmConfigContextAgents(ctx.home, values, { dry: ctx.dry });
+      const summary = CONTEXT_AGENT_KEYS.map((k) => `${k} = ${values[k]}`).join(", ");
+      info(`${r.result === "dry-run" ? "[dry-run] would save" : "saved"} [context_proxy.agents] ${summary}`);
+      if (r.result !== "dry-run") {
+        const table = { ...(cfg.context_proxy || {}), enabled: r.enabled, agents: r.agents };
+        ctx.pmMerged = { ...cfg, context_proxy: table };
+      }
+    }
+  }
+  ctx.contextAgents = values;
+  ok(`context management: ${CONTEXT_AGENT_KEYS.map((k) => `${k} ${values[k] ? "on" : "off"}`).join(", ")}`);
+  return values;
+}
+
+/**
+ * Start the service when a proxy-routed agent is on (before agents are pointed at it). Writes the key file
+ * and store directories compose needs first.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ */
+export async function startContextProxy(ctx) {
+  if (!contextServiceWanted(ctx)) return;
+  if (!ctx.dry) prepareContextProxyFiles(ctx.home);
+  const c = withProxyProfile(ctx);
+  const up = composeArgs(c, "up", "-d", "--no-build", CONTEXT_PROXY_SERVICE);
+  await act(ctx, `docker ${up.join(" ")}`, "docker", up, composeSpawnOptions(c));
+  if (!ctx.dry) ok("context-proxy started");
+}
+
+/**
+ * Stop the service when no proxy-routed agent is on and it runs, unless an agent still points at it
+ * (stopping would break that agent's every request).
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {typeof spawnSync} [spawn]
+ */
+export async function stopContextProxy(ctx, spawn = spawnSync) {
+  if (contextServiceWanted(ctx)) return;
+  const c = withProxyProfile(ctx);
+  if (!contextProxyRunning(composeArgs(c), composeSpawnOptions(c), spawn)) return;
+  const pointed = ctx.dry ? [] : agentsPointedAtContextProxy(ctx.home);
+  if (pointed.length) {
+    warn(`context-proxy left running: ${pointed.join(", ")} still point at it. Run: npx @bcmyguest/openmem install-coding-agent --yes`);
+    return;
+  }
+  const stop = composeArgs(c, "stop", CONTEXT_PROXY_SERVICE);
+  await act(ctx, `docker ${stop.join(" ")}`, "docker", stop, composeSpawnOptions(c));
+  if (!ctx.dry) ok("context-proxy stopped");
+}

package/wizard/lib/litellm-env.mjs

@@ -0,0 +1,55 @@
+/**
+ * The stack LiteLLM's secrets file (litellm.env, mode 600): LITELLM_MASTER_KEY and the
+ * provider keys its routes reference as os.environ/<NAME>. Shared by every provider that
+ * enables the `litellm` compose service (Hindsight, mem0).
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Create litellm.env (mode 600) with a fresh LITELLM_MASTER_KEY when it does not exist.
+ * @param {string} litellmEnv
+ * @returns {boolean} true when the file was created
+ */
+export function ensureLitellmEnv(litellmEnv) {
+  if (fs.existsSync(litellmEnv)) return false;
+  const key = crypto.randomBytes(24).toString("hex");
+  const body =
+    "# LiteLLM proxy secrets. Read by the litellm compose service. Do not commit.\n" +
+    `LITELLM_MASTER_KEY=sk-${key}\n` +
+    "# lemond ignores the key; any non-empty value works.\n" +
+    "LEMOND_API_KEY=placeholder\n" +
+    "# Hosted models: add the provider key here, e.g. ANTHROPIC_API_KEY=..., and reference it as os.environ/ANTHROPIC_API_KEY.\n";
+  fs.mkdirSync(path.dirname(litellmEnv), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(litellmEnv, body, { mode: 0o600 });
+  return true;
+}
+
+/**
+ * Set NAME=value in litellm.env (mode 600), creating the file with a master key first when
+ * it does not exist. Never prints the value.
+ * @param {string} litellmEnv
+ * @param {string} name
+ * @param {string} value
+ * @returns {"unchanged"|"updated"|"added"}
+ */
+export function setLitellmEnvValue(litellmEnv, name, value) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(name)) throw new Error(`invalid variable name: ${name}`);
+  if (/[\r\n]/.test(value)) throw new Error(`${name} must be one line`);
+  ensureLitellmEnv(litellmEnv);
+  const lines = fs.readFileSync(litellmEnv, "utf8").replace(/\n$/, "").split("\n");
+  const line = `${name}=${value}`;
+  const at = lines.findIndex((l) => l.startsWith(`${name}=`));
+  if (at >= 0 && lines[at] === line) {
+    fs.chmodSync(litellmEnv, 0o600);
+    return "unchanged";
+  }
+  if (at >= 0) lines[at] = line;
+  else lines.push(line);
+  const tmp = path.join(path.dirname(litellmEnv), `.litellm.env.${process.pid}`);
+  fs.writeFileSync(tmp, `${lines.join("\n")}\n`, { mode: 0o600 });
+  fs.chmodSync(tmp, 0o600);
+  fs.renameSync(tmp, litellmEnv);
+  return at >= 0 ? "updated" : "added";
+}

package/wizard/lib/pm-config.mjs

@@ -1,8 +1,36 @@
 import fs from "node:fs";
 import path from "node:path";
 import TOML from "@iarna/toml";
+import { writeFileAtomic } from "../../cli/coding-agent/file-io.mjs";
 import { DEFAULT_PROVIDER_ID } from "./providers/registry.mjs";
 
+/** Tables owned by install-coding-agent; the wizard carries them over when it rewrites the file. */
+const INSTALLER_TABLES = ["agents", "context_proxy", "compaction", "context_store"];
+const AGENT_INTEGRATIONS = ["openmem", "provider"];
+const DEFAULT_CONTEXT_PROXY_PORT = 4100;
+/** `[context_proxy.agents]` keys. opencode2 trims in its plugin; the others route through the proxy service. */
+export const CONTEXT_AGENT_KEYS = ["claude-code", "opencode1", "codex", "opencode2"];
+export const CONTEXT_PROXY_AGENT_KEYS = ["claude-code", "opencode1", "codex"];
+// Same defaults as proxy/openmem_context/settings.py and cli/coding-agent/context-trim.mjs.
+const DEFAULT_TRIM_AT_TOKENS = 125000;
+const DEFAULT_COMPRESS_OVER_TOKENS = 4000;
+const DEFAULT_COMPACTION_MAX_CHARS = 12000;
+/** Config keys that reach the proxy container (stack .env) and the OpenCode 2 plugin as env. */
+const CONTEXT_TRIM_ENV_KEYS = [
+  ["context_proxy", "trim_at_tokens", "CONTEXT_TRIM_AT_TOKENS"],
+  ["context_proxy", "compress_over_tokens", "CONTEXT_COMPRESS_OVER_TOKENS"],
+  ["compaction", "max_chars", "CONTEXT_COMPACTION_MAX_CHARS"],
+  ["context_store", "ttl_days", "CONTEXT_STORE_TTL_DAYS"],
+  ["context_store", "embedding_max_chars", "CONTEXT_EMBEDDING_MAX_CHARS"],
+];
+/** String keys of `[context_store]` and their env names (session database vectors, docs/context-store.md). */
+const CONTEXT_STORE_STRING_KEYS = [
+  ["embedding_model", "CONTEXT_EMBEDDING_MODEL"],
+  ["embedding_url", "CONTEXT_EMBEDDING_URL"],
+];
+const CONFIG_MODE = 0o600;
+const CONFIG_HEADER = "# Written by openmem — mise-like config.\n# Docs: docs/openmem-config.md\n";
+
 /** @param {string} home */
 export function userConfigPath(home) {
   return path.join(home, ".config/personal-memory/config.toml");
@@ -32,6 +60,11 @@ function readTomlFile(file) {
   }
 }
 
+/** Atomic rewrite; a new file is created mode 600, an existing one keeps its mode. */
+function writeConfigFile(file, text) {
+  writeFileAtomic(file, text, fs.existsSync(file) ? {} : { mode: CONFIG_MODE });
+}
+
 /** @param {Record<string, unknown>} base @param {Record<string, unknown>} over */
 function deepMerge(base, over) {
   const out = { ...base };
@@ -116,7 +149,16 @@ export function syncPmConfig(ctx, sections = {}) {
   const dir = path.dirname(userConfigPath(ctx.home));
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   const file = userConfigPath(ctx.home);
-  fs.writeFileSync(file, buildPmConfigToml(ctx, sections), { mode: 0o600 });
+  let previous = {};
+  try {
+    previous = readTomlFile(file);
+  } catch {
+    // A malformed file is replaced, as before; nothing to carry over.
+  }
+  const kept = Object.fromEntries(
+    INSTALLER_TABLES.filter((t) => previous[t] && !(t in sections)).map((t) => [t, previous[t]]),
+  );
+  writeConfigFile(file, buildPmConfigToml(ctx, { ...sections, ...kept }));
 }
 
 /**
@@ -140,12 +182,178 @@ export function updatePmConfigProvider(home, providerId, opts = {}) {
     provider: providerId,
   };
   doc.memory = memory;
-  const header =
-    "# Written by openmem — mise-like config.\n# Docs: docs/openmem-config.md\n";
-  fs.writeFileSync(file, `${header}${TOML.stringify(doc)}`, { mode: 0o600 });
+  writeConfigFile(file, `${CONFIG_HEADER}${TOML.stringify(doc)}`);
   return "updated";
 }
 
+/**
+ * Merge `values` into one top-level table of the user config.toml, creating the file
+ * (mode 600, directory 700) when it is missing. Other tables are kept.
+ *
+ * @param {string} home
+ * @param {string} table
+ * @param {Record<string, unknown>} values
+ * @param {{ dry?: boolean }} [opts]
+ * @returns {"updated"|"dry-run"}
+ */
+export function updatePmConfigTable(home, table, values, opts = {}) {
+  if (opts.dry) return "dry-run";
+  const file = userConfigPath(home);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const doc = readTomlFile(file);
+  const current = doc[table] && typeof doc[table] === "object" && !Array.isArray(doc[table])
+    ? /** @type {Record<string, unknown>} */ (doc[table])
+    : {};
+  doc[table] = { ...current, ...values };
+  writeConfigFile(file, `${CONFIG_HEADER}${TOML.stringify(doc)}`);
+  return "updated";
+}
+
+/**
+ * Write per-agent context management values into `[context_proxy.agents]` (merged with saved keys) and set
+ * `[context_proxy] enabled` to whether any agent resolves on. Other `[context_proxy]` keys are kept.
+ * @param {string} home
+ * @param {Record<string, boolean>} values keys from CONTEXT_AGENT_KEYS
+ * @param {{ dry?: boolean }} [opts]
+ * @returns {{ result: "updated"|"dry-run", agents: Record<string, boolean>, enabled: boolean }}
+ */
+export function updatePmConfigContextAgents(home, values, opts = {}) {
+  const file = userConfigPath(home);
+  const doc = fs.existsSync(file) ? readTomlFile(file) : {};
+  const current = contextAgentsFromPmConfig(doc).agents;
+  const agents = { ...current, ...values };
+  const enabled = CONTEXT_AGENT_KEYS.some((k) => agents[k]);
+  const result = updatePmConfigTable(home, "context_proxy", { enabled, agents }, opts);
+  return { result, agents, enabled };
+}
+
+/**
+ * `[agents] integration`: "openmem" (OpenMem hooks) or "provider" (the provider's own plugin).
+ * @param {Record<string, unknown>} cfg
+ */
+export function agentIntegrationFromPmConfig(cfg) {
+  const value = String(/** @type {Record<string, unknown>} */ (cfg.agents || {}).integration || "");
+  return AGENT_INTEGRATIONS.includes(value) ? value : "openmem";
+}
+
+/** @param {Record<string, unknown>} cfg @param {string} name */
+function tableOf(cfg, name) {
+  const t = cfg?.[name];
+  return t && typeof t === "object" && !Array.isArray(t) ? /** @type {Record<string, unknown>} */ (t) : {};
+}
+
+/** A non-negative integer config value, or undefined when unset or invalid. */
+function countValue(value) {
+  if (value === null || value === undefined || typeof value === "boolean" || typeof value === "string") return undefined;
+  const n = Number(value);
+  return Number.isSafeInteger(n) && n >= 0 ? n : undefined;
+}
+
+/**
+ * `[context_proxy]` wiring with defaults: disabled, port 4100.
+ * @param {Record<string, unknown>} cfg
+ */
+export function contextProxyFromPmConfig(cfg) {
+  const table = tableOf(cfg, "context_proxy");
+  const port = Number(table.port);
+  return {
+    enabled: table.enabled === true,
+    port: Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_CONTEXT_PROXY_PORT,
+  };
+}
+
+/**
+ * Per-agent context management: `[context_proxy.agents] <key> = true|false`, a missing key following
+ * `[context_proxy] enabled`; with neither set, opencode2 is on (it needs no service) and the proxy-routed
+ * agents are off. Keys: CONTEXT_AGENT_KEYS. `saved` lists the keys that config.toml sets.
+ * @param {Record<string, unknown>} cfg
+ * @returns {{ agents: Record<string, boolean>, saved: string[], enabledSaved: boolean }}
+ */
+export function contextAgentsFromPmConfig(cfg) {
+  const table = tableOf(cfg, "context_proxy");
+  const overrides = tableOf(table, "agents");
+  const enabledSaved = typeof table.enabled === "boolean";
+  const agents = {};
+  const saved = [];
+  for (const key of CONTEXT_AGENT_KEYS) {
+    if (typeof overrides[key] === "boolean") {
+      agents[key] = overrides[key];
+      saved.push(key);
+    } else agents[key] = enabledSaved ? table.enabled : key === "opencode2";
+  }
+  return { agents, saved, enabledSaved };
+}
+
+/**
+ * Trim settings with defaults: `[context_proxy] trim_at_tokens` (125000; unset, the proxy and plugin trim Haiku at 95000), `compress_over_tokens`
+ * (4000), `standing_instruction` (true), `[compaction] max_chars` (12000), `native` (true). Env overrides are applied by
+ * `contextTrimEnvFromPmConfig` + `trimSettings()`, not here.
+ * @param {Record<string, unknown>} cfg
+ */
+export function contextTrimFromPmConfig(cfg) {
+  const proxy = tableOf(cfg, "context_proxy");
+  const compaction = tableOf(cfg, "compaction");
+  return {
+    trimAtTokens: countValue(proxy.trim_at_tokens) ?? DEFAULT_TRIM_AT_TOKENS,
+    compressOverTokens: countValue(proxy.compress_over_tokens) ?? DEFAULT_COMPRESS_OVER_TOKENS,
+    compactionMaxChars: countValue(compaction.max_chars) ?? DEFAULT_COMPACTION_MAX_CHARS,
+    compactionNative: compaction.native !== false,
+    standingInstruction: proxy.standing_instruction !== false,
+  };
+}
+
+/**
+ * Context-trim settings that config.toml sets, as the environment variables the proxy and
+ * `trimSettings()` read: `[context_proxy] trim_at_tokens` → CONTEXT_TRIM_AT_TOKENS,
+ * `compress_over_tokens` → CONTEXT_COMPRESS_OVER_TOKENS, `[compaction] max_chars` →
+ * CONTEXT_COMPACTION_MAX_CHARS, `[context_proxy] standing_instruction` (boolean) →
+ * CONTEXT_STANDING_INSTRUCTION ("1" / "0"), `[compaction] recall` (boolean) → CONTEXT_COMPACTION_RECALL
+ * ("1" / "0"), `[context_proxy] chars_per_token` (positive number) →
+ * CONTEXT_CHARS_PER_TOKEN, `trim_to_fraction` (0 < x < 1) → CONTEXT_TRIM_TO_FRACTION, `[context_store] ttl_days` → CONTEXT_STORE_TTL_DAYS, `embedding_model` →
+ * CONTEXT_EMBEDDING_MODEL, `embedding_url` → CONTEXT_EMBEDDING_URL, `embedding_timeout_s` (positive number) →
+ * CONTEXT_EMBEDDING_TIMEOUT_S, `embedding_max_chars` → CONTEXT_EMBEDDING_MAX_CHARS. Unset or invalid keys are left out, so the reader's defaults
+ * apply. Real env vars override: `trimSettings({ ...contextTrimEnvFromPmConfig(cfg), ...process.env })`.
+ * @param {Record<string, unknown>} cfg
+ * @returns {Record<string, string>}
+ */
+export function contextTrimEnvFromPmConfig(cfg) {
+  const out = {};
+  for (const [table, key, envName] of CONTEXT_TRIM_ENV_KEYS) {
+    const value = countValue(tableOf(cfg, table)[key]);
+    if (value !== undefined) out[envName] = String(value);
+  }
+  const standing = tableOf(cfg, "context_proxy").standing_instruction;
+  if (typeof standing === "boolean") out.CONTEXT_STANDING_INSTRUCTION = standing ? "1" : "0";
+  const recall = tableOf(cfg, "compaction").recall;
+  if (typeof recall === "boolean") out.CONTEXT_COMPACTION_RECALL = recall ? "1" : "0";
+  const fraction = tableOf(cfg, "context_proxy").trim_to_fraction;
+  if (typeof fraction === "number" && Number.isFinite(fraction) && fraction > 0 && fraction < 1) {
+    out.CONTEXT_TRIM_TO_FRACTION = String(fraction);
+  }
+  const ratio = tableOf(cfg, "context_proxy").chars_per_token;
+  if (typeof ratio === "number" && Number.isFinite(ratio) && ratio > 0) out.CONTEXT_CHARS_PER_TOKEN = String(ratio);
+  const store = tableOf(cfg, "context_store");
+  const timeout = store.embedding_timeout_s;
+  if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) out.CONTEXT_EMBEDDING_TIMEOUT_S = String(timeout);
+  for (const [key, envName] of CONTEXT_STORE_STRING_KEYS) {
+    if (typeof store[key] === "string") out[envName] = store[key].trim();
+  }
+  return out;
+}
+
+/**
+ * Stack .env entries for the context-proxy compose service: the trim env above plus
+ * CONTEXT_PROXY_PORT when `[context_proxy] port` is set, so the container binds the port
+ * Claude Code is pointed at.
+ * @param {Record<string, unknown>} cfg
+ * @returns {Record<string, string>}
+ */
+export function contextProxyStackEnvFromPmConfig(cfg) {
+  const out = contextTrimEnvFromPmConfig(cfg);
+  if (tableOf(cfg, "context_proxy").port !== undefined) out.CONTEXT_PROXY_PORT = String(contextProxyFromPmConfig(cfg).port);
+  return out;
+}
+
 /**
  * Apply config defaults into process.env when env/CLI did not set them. Only the
  * provider-neutral keys live here; a provider maps its own tables in its `init` hook.

package/wizard/lib/prompts.mjs

@@ -28,6 +28,34 @@ export async function ask(ctx, prompt, defaultValue) {
   }
 }
 
+/**
+ * Pick any of `options`; `--yes` and non-TTY runs return `initial`.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} prompt
+ * @param {{ value: string, label: string }[]} options
+ * @param {string[]} initial
+ * @returns {Promise<string[]>}
+ */
+export async function multiselect(ctx, prompt, options, initial) {
+  if (ctx.yes) return initial;
+  if (!process.stdin.isTTY) return initial;
+  try {
+    const clack = await import("@clack/prompts");
+    const v = await clack.multiselect({ message: prompt, options, initialValues: initial, required: false });
+    if (clack.isCancel(v)) process.exit(0);
+    return /** @type {string[]} */ (v);
+  } catch {
+    const rl = readline.createInterface({ input, output });
+    const names = options.map((o) => o.value).join(", ");
+    const line = await rl.question(`  ${prompt} (comma-separated: ${names}; "none" for none) [${initial.join(",") || "none"}]: `);
+    rl.close();
+    const s = line.trim();
+    if (!s) return initial;
+    if (s === "none") return [];
+    return s.split(",").map((x) => x.trim()).filter((x) => options.some((o) => o.value === x));
+  }
+}
+
 /**
  * @param {import("./run-wizard.mjs").WizardContext} ctx
  * @param {string} prompt

package/wizard/lib/run-wizard.mjs

@@ -25,6 +25,8 @@ import { validateMemorySetup } from "./validate-setup.mjs";
 import { actionLabel, parseActionFromArgv } from "./wizard-action.mjs";
 import { applyPmConfigEnv, loadPmConfig, syncPmConfig } from "./pm-config.mjs";
 import { writeWizardConf } from "./wizard-conf.mjs";
+import { chooseContextManagement, contextAgentKeys, contextServiceWanted, startContextProxy, stopContextProxy } from "./context-step.mjs";
+import { opencodeMajorVersion } from "../../cli/coding-agent/opencode-config.mjs";
 import { setupNotebooklm as runNotebooklmSetup } from "./notebooklm.mjs";
 import { createHelpers } from "./provider-wizard/helpers.mjs";
 import {
@@ -492,8 +494,10 @@ async function smokeTest(ctx) {
 async function stackDown(ctx) {
   step("Stop the stack");
   info(`action: ${actionLabel("down")}`);
-  const args = composeArgs(ctx, "down");
-  await act(ctx, `docker ${args.join(" ")}`, "docker", args, composeSpawnOptions(ctx));
+  // A profiled service is part of `down` only when its profile is active.
+  const c = contextServiceWanted(ctx) ? { ...ctx, extraComposeProfiles: [...(ctx.extraComposeProfiles || []), "context-proxy"] } : ctx;
+  const args = composeArgs(c, "down");
+  await act(ctx, `docker ${args.join(" ")}`, "docker", args, composeSpawnOptions(c));
   ok(`compose project ${ctx.project} stopped`);
 }
 
@@ -555,46 +559,29 @@ function detectedCodingHarnesses() {
 }
 
 async function setupCodingAgents(ctx) {
-  step("8. Coding-agent plugin (optional)");
+  step("9. Coding agents (optional)");
   const pkg = ctx.memoryProvider.codingAgent?.pluginPackage;
   const harnesses = detectedCodingHarnesses();
-  // Link config/coding-agent.json first so the installer can adopt self-hosted settings
-  // (and mem0/Cognee hooks can print their non-plugin guidance).
+  // Link config/coding-agent.json first (mem0/Cognee hooks print their own guidance here).
   await runProviderPhase(ctx, PROVIDER_PHASES.setupCodingAgent, providerHelpers());
-  if (!pkg) {
-    info(`no coding-agent plugin defined for ${ctx.memoryProvider.label}; step skipped`);
-    return;
-  }
+  if (!pkg) info(`no coding-agent plugin defined for ${ctx.memoryProvider.label}; OpenMem hooks cover it`);
   if (!harnesses.length) {
-    info("no supported coding-agent CLIs on PATH (claude, codex, opencode, agent/cursor-agent): plugin skipped");
+    info("no supported coding-agent CLIs on PATH (claude, codex, opencode, agent/cursor-agent): step skipped");
     return;
   }
-  const apiUrl = await resolveApiBase(ctx);
-  // Scripted install: --server/--api-url skip the "Where should memory live?" prompt
-  // (--server/--api-url skip the installer's memory-location prompt.)
-  const installArgs = [
-    ...harnesses,
-    "--server",
-    "self-hosted",
-    "--api-url",
-    apiUrl,
-  ];
-  info(`detected harnesses: ${harnesses.join(" ")} → self-hosted ${apiUrl}`);
-  if (await confirm(ctx, `Install the ${ctx.memoryProvider.label} plugin for them now (npx)?`, "n")) {
-    await act(ctx, `npx --yes ${pkg} install ${installArgs.join(" ")}`, "npx", [
-      "--yes",
-      pkg,
-      "install",
-      ...installArgs,
-    ]);
-    ok("restart Cursor Agent (or your coding agent) so it picks up the new plugin wiring");
+  // install-coding-agent honours [agents] integration (openmem hooks, or the provider's own plugin).
+  const later = "npx @bcmyguest/openmem install-coding-agent --yes";
+  info(`detected coding agents: ${harnesses.join(" ")}`);
+  if (await confirm(ctx, "Wire them now (unified memory MCP, openmem skill, session hooks)?", "n")) {
+    await act(ctx, later, process.execPath, [path.join(ctx.packageRoot, "cli", "install-coding-agent.mjs"), "--yes"]);
+    ok("restart your coding agents so they pick up the new wiring");
   } else {
-    info(`skipped; later: npx --yes ${pkg} install ${installArgs.join(" ")}`);
+    info(`skipped; later: ${later}`);
   }
 }
 
 async function assertMemorySetup(ctx) {
-  step("9. Validate memory setup");
+  step("10. Validate memory setup");
   ctx.validationErrors = [];
   ctx.validationChecks = [];
   await runProviderPhase(ctx, PROVIDER_PHASES.extendValidation, providerHelpers());
@@ -726,6 +713,8 @@ export async function runWizard(repoRoot, argv) {
     }
     await runProviderPhase(ctx, PROVIDER_PHASES.beforeStack, providerHelpers());
     await startStack(ctx);
+    await startContextProxy(ctx);
+    await stopContextProxy(ctx);
     await assertMemorySetup(ctx);
     await summary(ctx);
     console.log(`wizard: changed=${await changedCount(ctx, before)}`);
@@ -747,7 +736,13 @@ export async function runWizard(repoRoot, argv) {
   await setupNotebooklm(ctx);
   await runProviderPhase(ctx, PROVIDER_PHASES.beforeStack, providerHelpers());
   await startStack(ctx);
+  const harnesses = detectedCodingHarnesses();
+  const opencodeMajor = harnesses.includes("opencode") ? opencodeMajorVersion() : 1;
+  await chooseContextManagement(ctx, "8", contextAgentKeys(harnesses, opencodeMajor));
+  // On: start the proxy before agents point at it. Off: stop it after they are unwired.
+  await startContextProxy(ctx);
   await setupCodingAgents(ctx);
+  await stopContextProxy(ctx);
   await assertMemorySetup(ctx);
   syncPmConfig(ctx, await providerConfigSections(ctx));
   await summary(ctx);