@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/cli/switch-memory-provider.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/**
+ * Switch the active memory provider (wizard.conf + optional stack restart + MCP).
+ *
+ *   npx openmem switch <hindsight|mem0|cognee> [--yes] [--dry-run] [--no-stack] [--no-mcp]
+ *   openmem-switch-provider …
+ *   npx . switch <id> … / ./pm switch <id> …
+ *
+ * Does not migrate data between providers. No secrets in logs.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./is-main.mjs";
+import { resolveMemoryProvider } from "./install-memory-mcp.mjs";
+import { resolveStackRoot } from "./stack.mjs";
+import { envValue } from "../wizard/lib/paths.mjs";
+import { updatePmConfigProvider, userConfigPath } from "../wizard/lib/pm-config.mjs";
+import { listSelectableProviders, loadManifest } from "../wizard/lib/providers/registry.mjs";
+import { upsertWizardConf } from "../wizard/lib/wizard-conf.mjs";
+import { resolveMem0EnvFilePath, resolveMem0ApiUrl } from "../providers/mem0/lib/mcp-install.mjs";
+import { envFileProblem } from "../providers/mem0/lib/state.mjs";
+import { urlProblem } from "../providers/mem0/lib/url.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const BIN = "openmem-switch-provider";
+
+const HELP = `${BIN}: switch the active memory provider
+
+Usage:
+  ${BIN} <provider> [flags]
+  npm run switch-provider -- <provider> [flags]
+  ./pm switch <provider> [flags]
+
+Providers (selectable): hindsight, mem0, cognee (see providers/*/manifest.json).
+
+Flags:
+  --yes               no confirmation prompts
+  --dry-run           print actions; write nothing / skip stack+MCP side effects
+  --no-stack          skip compose down/up for the new provider
+  --no-mcp            skip install-mcp --provider-only
+  -h, --help          this help
+
+Current provider: MEMORY_PROVIDER, else ~/.config/hindsight/wizard.conf, else hindsight.
+No automatic data migration between providers.
+`;
+
+/**
+ * @typedef {{
+ *   yes: boolean,
+ *   dry: boolean,
+ *   noStack: boolean,
+ *   noMcp: boolean,
+ *   help: boolean,
+ *   provider: string,
+ *   unknown: string[],
+ * }} SwitchProviderFlags
+ */
+
+/**
+ * @param {string[]} argv
+ * @returns {SwitchProviderFlags}
+ */
+export function parseSwitchProviderArgs(argv) {
+  /** @type {SwitchProviderFlags} */
+  const flags = {
+    yes: false,
+    dry: false,
+    noStack: false,
+    noMcp: false,
+    help: false,
+    provider: "",
+    unknown: [],
+  };
+  for (const arg of argv) {
+    switch (arg) {
+      case "--yes":
+      case "-y":
+        flags.yes = true;
+        break;
+      case "--dry-run":
+        flags.dry = true;
+        break;
+      case "--no-stack":
+        flags.noStack = true;
+        break;
+      case "--no-mcp":
+        flags.noMcp = true;
+        break;
+      case "-h":
+      case "--help":
+        flags.help = true;
+        break;
+      default:
+        if (arg.startsWith("-")) flags.unknown.push(arg);
+        else if (!flags.provider) flags.provider = arg;
+        else flags.unknown.push(arg);
+        break;
+    }
+  }
+  return flags;
+}
+
+/** @returns {string[]} */
+export function selectableProviderIds() {
+  return listSelectableProviders().map((m) => m.id);
+}
+
+export { updatePmConfigProvider };
+
+/**
+ * mem0 must have a usable API URL (and a valid env-file path). Never logs secrets.
+ * @param {{ home: string, stackRoot: string, env?: NodeJS.ProcessEnv }} opts
+ */
+export function ensureMem0SwitchReady(opts) {
+  const env = opts.env || process.env;
+  const apiUrl = resolveMem0ApiUrl({ home: opts.home, stackRoot: opts.stackRoot, env });
+  const issue = urlProblem(apiUrl);
+  if (issue) {
+    throw new Error(`mem0 API URL: ${issue} — see providers/mem0/OPERATOR.md`);
+  }
+  const envFile = resolveMem0EnvFilePath({ home: opts.home, stackRoot: opts.stackRoot, env });
+  const fileIssue = envFileProblem(envFile);
+  if (fileIssue) {
+    throw new Error(`mem0 env file: ${fileIssue} — see providers/mem0/OPERATOR.md`);
+  }
+}
+
+/**
+ * Cognee needs a sensible COGNEE_PORT (env / stack .env / wizard.conf / default 8766).
+ * @param {{ home: string, stackRoot: string, env?: NodeJS.ProcessEnv }} opts
+ */
+export function ensureCogneeSwitchReady(opts) {
+  const env = opts.env || process.env;
+  const stackEnv = path.join(opts.stackRoot, ".env");
+  const wizardConf = path.join(opts.home, ".config/hindsight/wizard.conf");
+  const candidates = [
+    env.COGNEE_PORT,
+    envValue(stackEnv, "COGNEE_PORT"),
+    envValue(wizardConf, "COGNEE_PORT"),
+    "8766",
+  ];
+  const port = candidates.map((v) => String(v || "").trim()).find(Boolean) || "";
+  if (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
+    throw new Error(
+      `COGNEE_PORT must be 1–65535 (got ${JSON.stringify(port)}) — see providers/cognee/OPERATOR.md`,
+    );
+  }
+}
+
+/** @param {{ info: Function, ok: Function, warn: Function }} h */
+function makeLogger() {
+  return {
+    info: (/** @type {string} */ m) => console.log(`  ${m}`),
+    ok: (/** @type {string} */ m) => console.log(`✓ ${m}`),
+    warn: (/** @type {string} */ m) => console.warn(`! ${m}`),
+  };
+}
+
+/**
+ * @param {string} question
+ * @returns {Promise<boolean>}
+ */
+function confirmProceed(question) {
+  if (!process.stdin.isTTY) return Promise.resolve(true);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} [Y/n] `, (answer) => {
+      rl.close();
+      const a = String(answer || "").trim().toLowerCase();
+      resolve(a === "" || a === "y" || a === "yes");
+    });
+  });
+}
+
+/**
+ * @param {string} script relative to pkgRoot
+ * @param {string[]} args
+ * @param {{ pkgRoot: string, stackRoot: string, env: NodeJS.ProcessEnv, dry: boolean, h: any, label: string }} opts
+ */
+function spawnNodeScript(script, args, opts) {
+  const { pkgRoot, stackRoot, env, dry, h, label } = opts;
+  const abs = path.join(pkgRoot, script);
+  if (dry) {
+    h.info(`[dry-run] ${label}: node ${script} ${args.join(" ")}`);
+    return;
+  }
+  const r = spawnSync(process.execPath, [abs, ...args], {
+    cwd: stackRoot,
+    stdio: "inherit",
+    env,
+  });
+  if (r.error) throw new Error(`${label}: ${r.error.message}`);
+  if (r.status !== 0) throw new Error(`${label} exited ${r.status ?? "null"}`);
+}
+
+/**
+ * @param {{
+ *   home: string,
+ *   repoRoot: string,
+ *   stackRoot: string,
+ *   flags: SwitchProviderFlags,
+ *   env?: NodeJS.ProcessEnv,
+ *   h?: { info: Function, ok: Function, warn: Function },
+ *   confirm?: (q: string) => Promise<boolean>,
+ * }} opts
+ */
+export async function runSwitchMemoryProvider(opts) {
+  const home = opts.home;
+  const stackRoot = opts.stackRoot;
+  const repoRoot = opts.repoRoot;
+  const flags = opts.flags;
+  const env = opts.env || process.env;
+  const h = opts.h || makeLogger();
+  const ask = opts.confirm || confirmProceed;
+
+  const target = String(flags.provider || "").trim();
+  if (!target) {
+    throw new Error(`provider id required\n\n${HELP}`);
+  }
+
+  const selectable = selectableProviderIds();
+  if (!selectable.includes(target)) {
+    throw new Error(
+      `unknown or non-selectable provider "${target}" (want one of: ${selectable.join(", ")})`,
+    );
+  }
+
+  const current = resolveMemoryProvider(home, env);
+  h.info(`current=${current} → target=${target}`);
+
+  if (current === target) {
+    h.ok(`provider "${target}" is already active`);
+    return { current, target, same: true, aborted: false };
+  }
+
+  h.warn("Switching providers does not migrate memories or banks between backends.");
+
+  if (!flags.yes && !flags.dry) {
+    const ok = await ask(`Switch memory provider from ${current} to ${target}?`);
+    if (!ok) {
+      h.warn("aborted");
+      return { current, target, same: false, aborted: true };
+    }
+  }
+
+  const wizardConf = path.join(home, ".config/hindsight/wizard.conf");
+  const hsDir = path.join(home, ".config/hindsight");
+  const manifest = loadManifest(target);
+  const ctx = {
+    home,
+    hsDir,
+    wizardConf,
+    dry: flags.dry,
+    memoryProvider: manifest || { id: target },
+  };
+
+  if (flags.dry) {
+    h.info(`[dry-run] upsert MEMORY_PROVIDER=${target} in ${wizardConf}`);
+  } else {
+    upsertWizardConf(ctx, {});
+    h.ok(`MEMORY_PROVIDER=${target} in ${wizardConf}`);
+  }
+
+  const pmResult = updatePmConfigProvider(home, target, { dry: flags.dry });
+  if (pmResult === "updated") h.ok(`memory.provider=${target} in ${userConfigPath(home)}`);
+  else if (pmResult === "dry-run") h.info(`[dry-run] would update memory.provider in ${userConfigPath(home)}`);
+  else h.info(`${userConfigPath(home)} absent — skipped`);
+
+  const childEnv = {
+    ...env,
+    MEMORY_PROVIDER: target,
+    PM_STACK_ROOT: stackRoot,
+    PM_PACKAGE_ROOT: repoRoot,
+  };
+
+  if (!flags.noStack) {
+    if (target === "mem0") {
+      ensureMem0SwitchReady({ home, stackRoot, env: childEnv });
+      h.ok("mem0 URL/env-file path look usable");
+    } else if (target === "cognee") {
+      ensureCogneeSwitchReady({ home, stackRoot, env: childEnv });
+      h.ok("cognee port looks usable");
+    }
+
+    spawnNodeScript(
+      "wizard/bin/setup.mjs",
+      ["--down", "--yes"],
+      { pkgRoot: repoRoot, stackRoot, env: childEnv, dry: flags.dry, h, label: "setup --down" },
+    );
+    spawnNodeScript(
+      "wizard/bin/setup.mjs",
+      ["--up", "--yes"],
+      { pkgRoot: repoRoot, stackRoot, env: childEnv, dry: flags.dry, h, label: "setup --up" },
+    );
+    if (!flags.dry) h.ok(`stack restarted for provider=${target}`);
+  } else {
+    h.info("skipped stack restart (--no-stack)");
+  }
+
+  if (!flags.noMcp) {
+    const mcpArgs = ["--yes", "--provider-only"];
+    if (flags.dry) mcpArgs.push("--dry-run");
+    spawnNodeScript("cli/install-memory-mcp.mjs", mcpArgs, {
+      pkgRoot: repoRoot,
+      stackRoot,
+      env: childEnv,
+      dry: false, // dry-run is passed through to install-mcp
+      h,
+      label: "install-mcp --provider-only",
+    });
+  } else {
+    h.info("skipped MCP install (--no-mcp)");
+  }
+
+  h.ok("Restart Cursor Agent so it picks up the new provider / MCP wiring");
+  h.info("Then run: ./pm doctor");
+
+  return { current, target, same: false, aborted: false };
+}
+
+async function main(argv) {
+  const flags = parseSwitchProviderArgs(argv);
+  if (flags.help) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  if (flags.unknown.length) {
+    console.error(`${BIN}: unknown option(s): ${flags.unknown.join(", ")}`);
+    console.error(HELP);
+    process.exit(2);
+  }
+  if (!flags.provider) {
+    console.error(`${BIN}: provider id required`);
+    console.error(HELP);
+    process.exit(2);
+  }
+
+  const home = process.env.HOME || os.homedir();
+  const stack = resolveStackRoot({ pkgRoot: PKG_ROOT, env: process.env, home });
+  const repoRoot = PKG_ROOT;
+  const stackRoot = stack.root;
+
+  try {
+    const result = await runSwitchMemoryProvider({ home, repoRoot, stackRoot, flags });
+    if (result.aborted) process.exit(1);
+  } catch (err) {
+    console.error(`${BIN}: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  main(process.argv.slice(2));
+}

package/cli/wiring-report.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/** Agent wiring report: provider, API URLs, MCP entries vs expectations. */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "./is-main.mjs";
+import { PROVIDER_CAPABILITIES } from "./coding-agent/capabilities.mjs";
+import { resolveMcpContext } from "./mcp/context.mjs";
+import { resolveMemoryProvider, shouldInstallNotebooklm } from "./install-memory-mcp.mjs";
+import { resolveStackRoot } from "./stack.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * @param {{ home: string, stackRoot: string, repoRoot: string, env?: NodeJS.ProcessEnv }} opts
+ */
+export function buildWiringReport(opts) {
+  const home = opts.home;
+  const env = opts.env || process.env;
+  const provider = resolveMemoryProvider(home, env);
+  const ctx = resolveMcpContext({ ...opts, home, env });
+  const mcpPath = path.join(home, ".cursor/mcp.json");
+  /** @type {Record<string, unknown>} */
+  let mcp = {};
+  if (fs.existsSync(mcpPath)) {
+    try {
+      mcp = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+    } catch {
+      mcp = { _parseError: true };
+    }
+  }
+  const servers = mcp.mcpServers && typeof mcp.mcpServers === "object" ? mcp.mcpServers : {};
+  const names = Object.keys(servers);
+  const expectUnified = true;
+  const expectProviderNative = provider === "mem0" || provider === "cognee";
+  const nlm = shouldInstallNotebooklm({
+    home,
+    flags: { notebooklm: false, notebooklmOnly: false, providerOnly: false },
+  });
+  const issues = [];
+  if (expectUnified && !servers["openmem"]) {
+    issues.push("missing unified MCP server `openmem` in ~/.cursor/mcp.json (run install-mcp)");
+  }
+  if (expectProviderNative && !servers[provider]) {
+    issues.push(`active provider is ${provider} but mcp.json has no \`${provider}\` entry (optional: install-mcp --provider-only)`);
+  }
+  if (provider === "hindsight" && servers.mem0) {
+    issues.push("MEMORY_PROVIDER is hindsight but mcp.json still has mem0 (stale after switch?)");
+  }
+  if (provider === "mem0" && servers.hindsight && servers.hindsight.command !== "keep") {
+    /* hindsight key often kept intentionally */
+  }
+  const manifestPath = path.join(opts.repoRoot, "providers", provider, "manifest.json");
+  let sinkDriver = null;
+  if (fs.existsSync(manifestPath)) {
+    try {
+      sinkDriver = JSON.parse(fs.readFileSync(manifestPath, "utf8"))?.indexer?.sinkDriver ?? null;
+    } catch {
+      sinkDriver = null;
+    }
+  }
+  return {
+    memory_provider: provider,
+    api: {
+      hindsightUrl: ctx.hindsightUrl ?? null,
+      mem0BaseUrl: ctx.mem0?.baseUrl ?? null,
+      cogneeBaseUrl: ctx.cognee?.baseUrl ?? null,
+    },
+    indexer: { sink_driver: sinkDriver },
+    mcp: {
+      path: mcpPath,
+      servers: names,
+      notebooklm_recommended: nlm,
+      has_notebooklm: Boolean(servers.notebooklm),
+    },
+    coding_agent: {
+      hindsight_plugin: provider === "hindsight" ? "@vectorize-io/hindsight-coding-agents" : null,
+      non_hindsight_session:
+        provider !== "hindsight" ? "openmem session shim (install-coding-agent) + memory_* MCP" : null,
+      session_capabilities: PROVIDER_CAPABILITIES[provider] ?? {},
+    },
+    issues,
+    ok: issues.length === 0,
+  };
+}
+
+function main() {
+  const json = process.argv.includes("--json");
+  const home = process.env.HOME || "";
+  const sr = resolveStackRoot({ pkgRoot: PKG_ROOT });
+  const report = buildWiringReport({ home, stackRoot: sr.root, repoRoot: PKG_ROOT, env: process.env });
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(report.ok ? 0 : 1);
+  }
+  console.log(`Memory provider: ${report.memory_provider}`);
+  if (report.api.hindsightUrl) console.log(`  Hindsight: ${report.api.hindsightUrl}`);
+  if (report.api.mem0BaseUrl) console.log(`  mem0: ${report.api.mem0BaseUrl}`);
+  if (report.api.cogneeBaseUrl) console.log(`  Cognee: ${report.api.cogneeBaseUrl}`);
+  if (report.indexer.sink_driver) console.log(`  Indexer sink: ${report.indexer.sink_driver}`);
+  console.log(`MCP (${report.mcp.path}): ${report.mcp.servers.join(", ") || "(none)"}`);
+  if (report.mcp.notebooklm_recommended && !report.mcp.has_notebooklm) {
+    console.log("  NotebookLM sync enabled but notebooklm MCP not in mcp.json");
+  }
+  if (report.coding_agent.hindsight_plugin) {
+    console.log(`Session plugin: ${report.coding_agent.hindsight_plugin}`);
+  } else if (report.coding_agent.non_hindsight_session) {
+    console.log(`Session memory: ${report.coding_agent.non_hindsight_session}`);
+  }
+  const caps = report.coding_agent.session_capabilities;
+  if (caps && Object.keys(caps).length) {
+    const on = Object.entries(caps)
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+    const off = Object.entries(caps)
+      .filter(([, v]) => !v)
+      .map(([k]) => k);
+    if (on.length) console.log(`  Session features: ${on.join(", ")}`);
+    if (off.length) console.log(`  Unavailable for ${report.memory_provider}: ${off.join(", ")}`);
+  }
+  for (const i of report.issues) console.log(`Issue: ${i}`);
+  process.exit(report.ok ? 0 : 1);
+}
+
+if (isMainModule(import.meta.url)) main();

package/compose.bench.yaml

@@ -0,0 +1,12 @@
+# Bench overlay: also publish Hindsight on the docker0 gateway so bridge-network
+# fabro sandboxes reach it via host.docker.internal:8888. Loopback binding is kept.
+# Needs the hindsight profile (COMPOSE_PROFILES=hindsight in .env, or add --profile hindsight).
+# Not applied. Apply by recreating only the hindsight service:
+#   cd ~/openmem && docker compose -f compose.yaml -f compose.override.yaml -f compose.bench.yaml up -d hindsight
+# The explicit -f list keeps compose.override.yaml, which compose skips when -f is given.
+services:
+  hindsight:
+    ports: !override
+      - "127.0.0.1:${HINDSIGHT_PORT:-8888}:8888"
+      - "127.0.0.1:${HINDSIGHT_CP_PORT:-9999}:9999"
+      - "172.17.0.1:${HINDSIGHT_PORT:-8888}:8888"

package/compose.yaml

@@ -0,0 +1,164 @@
+name: openmem
+
+# Memory provider stack (Hindsight by default) and the project/Obsidian indexer.
+# Set HINDSIGHT_ENV_FILE to use an env file other than ~/.config/hindsight/hindsight.env.
+#
+# Provider selection is by compose profile:
+#   - litellm and hindsight carry the profile "hindsight" (and "notebooklm", which needs them).
+#   - indexer and indexer-state-init have no profile and no hard provider dependency; they start for every provider.
+#   - Another provider ships providers/<id>/compose.yaml (see providers/_template/compose.yaml) with its own
+#     profile, and layers over this file: docker compose -f compose.yaml -f providers/<id>/compose.yaml --profile <id> up -d
+# Compose starts no profiled service unless a profile is enabled, so the plain `docker compose up -d` of the README
+# needs COMPOSE_PROFILES=hindsight in .env (or --profile hindsight). Note that a --profile flag replaces
+# COMPOSE_PROFILES rather than adding to it; name every profile you want on the command line.
+
+# Shared build for the indexer and its state-volume init step.
+x-indexer-build: &indexer-build
+  build:
+    context: .
+    dockerfile: indexer/Dockerfile
+
+services:
+  # OpenAI-compatible proxy in front of the model server. Hindsight calls it at http://litellm:4000/v1 with the
+  # fixed aliases memory-retain, memory-reflect, memory-consolidate. Routes live in LITELLM_CONFIG (set by scripts/setup.sh).
+  # Internal network only: nothing is published to the host.
+  litellm:
+    profiles: ["hindsight", "notebooklm"]
+    image: ghcr.io/berriai/litellm:v1.105.1
+    command: ["--config", "/app/config.yaml", "--port", "4000"]
+    env_file: ${LITELLM_ENV_FILE:-${HOME}/.config/hindsight/litellm.env}
+    volumes:
+      - ${LITELLM_CONFIG:?run scripts/setup.sh}:/app/config.yaml:ro
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:4000/health/liveliness', timeout=5)"]
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 30s
+
+  hindsight:
+    profiles: ["hindsight", "notebooklm"]
+    depends_on:
+      litellm:
+        condition: service_healthy
+    # Pinned to the digest running before the pin (org.opencontainers.image.version 1.0.0). Bump deliberately.
+    image: ghcr.io/vectorize-io/hindsight@sha256:a88678c038b0e4340822b02a5efc566c56d8176b5bffa731bc433fd37f978e4c
+    # Embedded Postgres needs more than Docker's 64 MB default /dev/shm.
+    shm_size: 1g
+    env_file: ${HINDSIGHT_ENV_FILE:-${HOME}/.config/hindsight/hindsight.env}
+    ports:
+      # Host ports from .env (HINDSIGHT_PORT, HINDSIGHT_CP_PORT); defaults 8888 and 9999.
+      - "127.0.0.1:${HINDSIGHT_PORT:-8888}:8888"
+      - "127.0.0.1:${HINDSIGHT_CP_PORT:-9999}:9999"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      # Named volume: the image's hindsight user (UID 1000) owns it on first use, unlike a host bind mount.
+      - hindsight-data:/home/hindsight/.pg0
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8888/health', timeout=5)"]
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 60s
+
+  indexer:
+    <<: *indexer-build
+    image: openmem-indexer:local
+    # Host UID/GID from .env, written by scripts/setup.sh. The image needs no passwd entry for this user.
+    user: "${HOST_UID:?run scripts/setup.sh}:${HOST_GID:?run scripts/setup.sh}"
+    # Same absolute paths inside the container so bank and document IDs match host paths.
+    # Read-only: the indexer reads repositories and writes only its state volume below. Tree-sitter outlines
+    # need no writes, and CodeGraph's .codegraph/ writes are gone.
+    # Secret paths under $HOME are masked by compose.override.yaml, generated by scripts/gen-masks.sh (required).
+    volumes:
+      - ${HOME}:${HOME}:ro
+      # Writable state (state.json, lock). Its mount point is inside the read-only $HOME mount.
+      - indexer-state:${HOME}/.cache/hindsight-project-index
+    environment:
+      HOME: ${HOME}
+      HINDSIGHT_URL: http://hindsight:8888
+    depends_on:
+      # Soft: waits for Hindsight to be healthy when its profile is active and is ignored otherwise (other providers
+      # add their own dependency in providers/<id>/compose.yaml). Unlike a hard dependency, an unhealthy Hindsight
+      # only logs a warning; the indexer starts anyway and its watcher retries.
+      hindsight:
+        condition: service_healthy
+        required: false
+      indexer-state-init:
+        condition: service_completed_successfully
+    restart: unless-stopped
+
+  # Named volumes are created root-owned. This one-off root step gives the state volume to the host UID, then exits.
+  indexer-state-init:
+    <<: *indexer-build
+    image: openmem-indexer:local
+    user: "0:0"
+    entrypoint: ["sh", "-c", "chown ${HOST_UID:?run scripts/setup.sh}:${HOST_GID:?run scripts/setup.sh} /state"]
+    volumes:
+      - indexer-state:/state
+    restart: "no"
+
+  # Opt-in: docker compose --profile ollama up -d ollama. Used when the host has no Ollama; LiteLLM reaches it at
+  # http://ollama:11434 on the compose network. Port 11434 is published on loopback so the wizard can probe and pull.
+  ollama:
+    profiles: ["ollama"]
+    image: ollama/ollama:latest
+    ports:
+      - "127.0.0.1:11434:11434"
+    volumes:
+      - ollama-data:/root/.ollama
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "ollama list >/dev/null 2>&1 || exit 1"]
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 20s
+
+  # Opt-in: docker compose --profile notebooklm up -d notebooklm. Syncs into notebooklm::* banks on the active MEMORY_SINK.
+  # Login is on the host (README "NotebookLM"); the storage under ~/.config/notebooklm is bind-mounted read-write.
+  notebooklm:
+    profiles: ["notebooklm"]
+    build:
+      context: .
+      dockerfile: sync/Dockerfile
+    image: openmem-notebooklm:local
+    # Host UID/GID from .env, written by scripts/setup.sh; the bind-mounted login storage must stay host-owned.
+    user: "${HOST_UID:?run scripts/setup.sh}:${HOST_GID:?run scripts/setup.sh}"
+    environment:
+      HINDSIGHT_URL: http://hindsight:8888
+      MEMORY_SINK: ${MEMORY_SINK:-hindsight}
+      MEMORY_API_URL: ${MEMORY_API_URL:-}
+      NOTEBOOKLM_HOME: /data/notebooklm
+      NOTEBOOKLM_STATE: /data/state/state.json
+    volumes:
+      - type: bind
+        source: ${HOME}/.config/notebooklm
+        target: /data/notebooklm
+        bind:
+          create_host_path: false
+      # Per-machine override (only the keys you change). Create the file before starting; compose does not create it.
+      - type: bind
+        source: ${NOTEBOOKLM_OVERRIDE:-${HOME}/.config/hindsight/notebooklm.yml}
+        target: /etc/notebooklm/override.yml
+        read_only: true
+        bind:
+          create_host_path: false
+      # Writable sync state (state.json). The image creates it 0777, so Docker copies that mode into the new volume.
+      - notebooklm-state:/data/state
+    depends_on:
+      hindsight:
+        condition: service_healthy
+        required: false
+    restart: unless-stopped
+
+volumes:
+  hindsight-data:
+  indexer-state:
+  notebooklm-state:
+  ollama-data:

package/config/coding-agent.json

@@ -0,0 +1,13 @@
+{
+  "serverMode": "self-hosted",
+  "apiUrl": "http://127.0.0.1:8888",
+  "optInOnly": true,
+  "optInPaths": [],
+  "mapPathToBank": {},
+  "notebooklmAccess": {
+    "enabled": false,
+    "banks": [
+      "*"
+    ]
+  }
+}