@bcmyguest/openmem 0.6.3 → 0.8.0

package/cli/schedule.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/** Install a per-user, hourly feed-sync job using the host scheduler. */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { pythonCandidates } from "./feed-sync.mjs";
+import { isMainModule } from "./is-main.mjs";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PACKAGE_NAME = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).name;
+const JOB_NAME = "openmem-feed-sync";
+const LAUNCHD_LABEL = "io.github.bcmyguest.openmem.feed-sync";
+const WINDOWS_TASK = "OpenMemFeedSync";
+
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+
+function systemdArg(value) {
+  const escaped = value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%");
+  return `"${escaped}"`;
+}
+
+export function schedulePaths(platform, home, env = process.env) {
+  if (platform === "linux") {
+    const config = path.isAbsolute(env.XDG_CONFIG_HOME || "") ? env.XDG_CONFIG_HOME : path.join(home, ".config");
+    return {
+      runner: path.join(config, "openmem", "feed-sync-runner.mjs"),
+      service: path.join(config, "systemd", "user", `${JOB_NAME}.service`),
+      timer: path.join(config, "systemd", "user", `${JOB_NAME}.timer`),
+    };
+  }
+  if (platform === "darwin") {
+    return {
+      runner: path.join(home, "Library", "Application Support", "OpenMem", "feed-sync-runner.mjs"),
+      plist: path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`),
+    };
+  }
+  if (platform === "win32") {
+    const local = path.win32.isAbsolute(env.LOCALAPPDATA || "") ? env.LOCALAPPDATA : path.win32.join(home, "AppData", "Local");
+    return { runner: path.win32.join(local, "OpenMem", "feed-sync-runner.mjs") };
+  }
+  throw new Error(`native scheduling is unavailable on ${platform}; run ${PACKAGE_NAME} feed-sync with your system scheduler`);
+}
+
+export function renderRunner(nodePath, npmCliPath, pythonPath) {
+  return `// Generated by OpenMem schedule install. Reinstall after changing Node.js installations.\n` +
+    `import { spawnSync } from "node:child_process";\n` +
+    `import path from "node:path";\n` +
+    `const node = ${JSON.stringify(nodePath)};\n` +
+    `const npm = ${JSON.stringify(npmCliPath)};\n` +
+    `const python = ${JSON.stringify(pythonPath)};\n` +
+    `const env = { ...process.env };\n` +
+    `const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path") || "PATH";\n` +
+    `env[pathKey] = [path.dirname(node), path.dirname(python), env[pathKey] || ""].join(path.delimiter);\n` +
+    `env.PYTHON = python;\n` +
+    `const result = spawnSync(node, [npm, "exec", "--yes", "--package=${PACKAGE_NAME}", "--", "openmem", "feed-sync"], { env, stdio: "inherit" });\n` +
+    `if (result.error) console.error(result.error.message);\n` +
+    `process.exit(result.status ?? 1);\n`;
+}
+
+export function renderSystemdUnits(nodePath, runnerPath) {
+  return {
+    service: `[Unit]\nDescription=Refresh OpenMem feed cache\n\n[Service]\nType=oneshot\nExecStart=${systemdArg(nodePath)} ${systemdArg(runnerPath)}\n`,
+    timer: `[Unit]\nDescription=Refresh OpenMem feed cache hourly\n\n[Timer]\nOnCalendar=hourly\nPersistent=true\n\n[Install]\nWantedBy=timers.target\n`,
+  };
+}
+
+export function renderLaunchAgent(nodePath, runnerPath) {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n` +
+    `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n` +
+    `<plist version="1.0"><dict>\n` +
+    `  <key>Label</key><string>${LAUNCHD_LABEL}</string>\n` +
+    `  <key>ProgramArguments</key><array><string>${escapeXml(nodePath)}</string><string>${escapeXml(runnerPath)}</string></array>\n` +
+    `  <key>StartInterval</key><integer>3600</integer>\n` +
+    `</dict></plist>\n`;
+}
+
+export function windowsTaskArgs(nodePath, runnerPath) {
+  return ["/create", "/sc", "hourly", "/mo", "1", "/tn", WINDOWS_TASK, "/tr", `"${nodePath}" "${runnerPath}"`, "/f"];
+}
+
+function run(command, args, env, allowMissing = false) {
+  const result = spawnSync(command, args, { encoding: "utf8", env });
+  if (result.error) throw result.error;
+  if (result.status !== 0 && !allowMissing) throw new Error(`${command} ${args.join(" ")}: ${(result.stderr || result.stdout).trim()}`);
+  return result.status === 0;
+}
+
+function writeFile(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, { mode: 0o600 });
+}
+
+function resolvePython(platform, env) {
+  for (const [command, prefix] of pythonCandidates(platform, env)) {
+    const result = spawnSync(command, [...prefix, "-c", "import sys, yaml; print(sys.executable)"], { encoding: "utf8", env });
+    if (result.status === 0) return result.stdout.trim();
+  }
+  throw new Error("Python 3 with PyYAML is required for feed sync; install PyYAML or set PYTHON to a working interpreter");
+}
+
+function install(platform, home, env, dryRun) {
+  const files = schedulePaths(platform, home, env);
+  const npmCli = env.npm_execpath;
+  if (!npmCli || !fs.existsSync(npmCli)) throw new Error("run schedule install through npx so OpenMem can locate npm");
+  const nodePath = process.execPath;
+  if (dryRun) {
+    console.log(`Would write ${files.runner} and install an hourly ${JOB_NAME} job using ${nodePath} and ${npmCli}`);
+    return;
+  }
+  const runner = renderRunner(nodePath, npmCli, resolvePython(platform, env));
+  writeFile(files.runner, runner);
+  if (platform === "linux") {
+    const units = renderSystemdUnits(nodePath, files.runner);
+    writeFile(files.service, units.service);
+    writeFile(files.timer, units.timer);
+    run("systemctl", ["--user", "daemon-reload"], env);
+    run("systemctl", ["--user", "enable", "--now", `${JOB_NAME}.timer`], env);
+  } else if (platform === "darwin") {
+    const target = `gui/${process.getuid()}`;
+    if (fs.existsSync(files.plist)) run("launchctl", ["bootout", target, files.plist], env, true);
+    writeFile(files.plist, renderLaunchAgent(nodePath, files.runner));
+    run("launchctl", ["bootstrap", target, files.plist], env);
+  } else {
+    run("schtasks", windowsTaskArgs(nodePath, files.runner), env);
+  }
+  console.log(`Installed hourly ${JOB_NAME} job`);
+}
+
+function remove(platform, home, env, dryRun) {
+  const files = schedulePaths(platform, home, env);
+  if (dryRun) {
+    console.log(`Would remove ${JOB_NAME} job and ${files.runner}`);
+    return;
+  }
+  if (platform === "linux") {
+    run("systemctl", ["--user", "disable", "--now", `${JOB_NAME}.timer`], env, true);
+    fs.rmSync(files.service, { force: true });
+    fs.rmSync(files.timer, { force: true });
+    run("systemctl", ["--user", "daemon-reload"], env);
+  } else if (platform === "darwin") {
+    if (fs.existsSync(files.plist)) run("launchctl", ["bootout", `gui/${process.getuid()}`, files.plist], env, true);
+    fs.rmSync(files.plist, { force: true });
+  } else {
+    if (run("schtasks", ["/query", "/tn", WINDOWS_TASK], env, true)) {
+      run("schtasks", ["/delete", "/tn", WINDOWS_TASK, "/f"], env);
+    }
+  }
+  fs.rmSync(files.runner, { force: true });
+  console.log(`Removed ${JOB_NAME} job`);
+}
+
+export function main(argv = process.argv.slice(2), platform = process.platform, home = os.homedir(), env = process.env) {
+  const { values, positionals } = parseArgs({ args: argv, options: { "dry-run": { type: "boolean" }, help: { type: "boolean" } }, allowPositionals: true });
+  if (values.help || positionals.length === 0) {
+    console.log(`Usage: npx ${PACKAGE_NAME} schedule <install|remove> [--dry-run]\nInstalls an hourly per-user feed sync with the native OS scheduler.`);
+    return;
+  }
+  if (positionals.length !== 1) throw new Error("schedule accepts one action: install or remove");
+  if (positionals[0] === "install") install(platform, home, env, values["dry-run"]);
+  else if (positionals[0] === "remove") remove(platform, home, env, values["dry-run"]);
+  else throw new Error(`unknown schedule action: ${positionals[0]}`);
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`openmem schedule: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/cli/stack.mjs

@@ -47,6 +47,8 @@ export const STACK_ASSETS = [
     include:
       /^config\/(?:[^/]+\.example|index\.yml|notebooklm\.yml|litellm\.[^/]+\.yaml|coding-agent\.json)$/,
   },
+  // context-proxy mounts ./proxy (LiteLLM config and hook).
+  { tree: "proxy" },
   // Per-provider compose fragments (hooks and manifests stay in the read-only package).
   { tree: "providers", include: /^providers\/[^/]+\/compose[^/]*\.ya?ml$/ },
   // Deliberately absent: scripts/ and wizard/. They are code, so they run from the

package/cli/switch-memory-provider.mjs

@@ -4,7 +4,7 @@
  *
  *   npx openmem switch <hindsight|mem0|cognee> [--yes] [--dry-run] [--no-stack] [--no-mcp]
  *   openmem-switch-provider …
- *   npx . switch <id> … / ./pm switch <id> …
+ *   node cli/openmem.mjs switch <id> … / ./pm switch <id> …
  *
  * Does not migrate data between providers. No secrets in logs.
  */

package/compose.yaml

@@ -4,7 +4,9 @@ name: openmem
 # 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).
+#   - litellm and hindsight carry the profile "hindsight" (and "notebooklm", which needs them). litellm also carries
+#     its own profile "litellm", so a provider other than Hindsight can run the stack LiteLLM as its model gateway
+#     (mem0: providers/mem0/compose.yaml publishes it on loopback; docs/mem0.md "Models through the stack LiteLLM").
 #   - 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
@@ -21,10 +23,11 @@ x-indexer-build: &indexer-build
 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.
+  # Internal network only under Hindsight: nothing is published to the host. The "litellm" profile runs it without
+  # Hindsight; providers/mem0/compose.yaml then publishes it on 127.0.0.1 and refuses to start without a master key.
   litellm:
-    profiles: ["hindsight", "notebooklm"]
-    image: ghcr.io/berriai/litellm:v1.105.1
+    profiles: ["hindsight", "notebooklm", "litellm"]
+    image: ghcr.io/berriai/litellm:v1.106.6
     command: ["--config", "/app/config.yaml", "--port", "4000"]
     env_file: ${LITELLM_ENV_FILE:-${HOME}/.config/hindsight/litellm.env}
     volumes:
@@ -157,6 +160,66 @@ services:
         required: false
     restart: unless-stopped
 
+  # Opt-in: docker compose --profile context-proxy up -d context-proxy. LiteLLM in front of Anthropic for coding
+  # agents: compresses large tool results and trims long sessions (docs/context-proxy.md). Separate from the litellm
+  # service and outside the hindsight profile, so Hindsight's own model traffic never passes through it.
+  context-proxy:
+    profiles: ["context-proxy"]
+    # Dev build on purpose: v1.109.0-dev.1 is the only LiteLLM release with PR #41522, the ChatGPT/Codex
+    # subscription pass-through (/backend-api/codex/{endpoint}) that routes Codex here; stable releases
+    # (v1.106.6, v1.108.0-rc.1) lack it. The litellm service above stays on stable. Move to the first stable
+    # release that contains #41522, then rerun proxy/tests/image/run.py.
+    image: ghcr.io/berriai/litellm:v1.109.0-dev.1
+    command: ["--config", "/app/proxy/config.yaml", "--port", "4000"]
+    # LITELLM_MASTER_KEY (and any provider keys for extra routes). Written by install-coding-agent.
+    env_file: ${CONTEXT_PROXY_ENV_FILE:-${HOME}/.config/personal-memory/context-proxy.env}
+    # Host UID/GID from .env, written by scripts/setup.sh; the context store stays host-owned (docs/context-store.md).
+    user: "${HOST_UID:?run scripts/setup.sh}:${HOST_GID:?run scripts/setup.sh}"
+    ports:
+      - "127.0.0.1:${CONTEXT_PROXY_PORT:-4100}:4000"
+    environment:
+      HOME: /tmp
+      PYTHONDONTWRITEBYTECODE: "1"
+      OPENMEM_STATE_DIR: /state
+      HINDSIGHT_URL: ${CONTEXT_PROXY_HINDSIGHT_URL:-http://hindsight:8888}
+      CONTEXT_PROXY_ENABLED: ${CONTEXT_PROXY_ENABLED:-1}
+      # From config.toml [context_proxy] trim_at_tokens / trim_to_fraction / compress_over_tokens / standing_instruction / chars_per_token, [compaction] max_chars / recall
+      # and [context_store] ttl_days / embedding_model / embedding_timeout_s / embedding_max_chars,
+      # written into .env by scripts/setup.mjs and install-coding-agent; a shell export overrides .env.
+      # CONTEXT_TRIM_AT_TOKENS stays empty when unset, so the proxy picks the threshold by model.
+      CONTEXT_TRIM_AT_TOKENS: ${CONTEXT_TRIM_AT_TOKENS:-}
+      CONTEXT_TRIM_TO_FRACTION: ${CONTEXT_TRIM_TO_FRACTION:-0.3}
+      CONTEXT_COMPRESS_OVER_TOKENS: ${CONTEXT_COMPRESS_OVER_TOKENS:-4000}
+      CONTEXT_COMPACTION_MAX_CHARS: ${CONTEXT_COMPACTION_MAX_CHARS:-12000}
+      CONTEXT_COMPACTION_RECALL: ${CONTEXT_COMPACTION_RECALL:-1}
+      CONTEXT_STANDING_INSTRUCTION: ${CONTEXT_STANDING_INSTRUCTION:-1}
+      CONTEXT_CHARS_PER_TOKEN: ${CONTEXT_CHARS_PER_TOKEN:-2.5}
+      # Session databases (docs/context-store.md): [context_store] ttl_days and embedding_model. Vectors are off while
+      # CONTEXT_EMBEDDING_MODEL is empty; the embeddings URL is the container's view of an OpenAI-compatible
+      # /embeddings endpoint (Ollama on the host by default). CONTEXT_EMBEDDING_API_KEY, if needed, goes in the env file.
+      CONTEXT_STORE_TTL_DAYS: ${CONTEXT_STORE_TTL_DAYS:-30}
+      CONTEXT_EMBEDDING_MODEL: ${CONTEXT_EMBEDDING_MODEL:-}
+      CONTEXT_EMBEDDING_URL: ${CONTEXT_PROXY_EMBEDDING_URL:-http://host.docker.internal:11434/v1}
+      CONTEXT_EMBEDDING_TIMEOUT_S: ${CONTEXT_EMBEDDING_TIMEOUT_S:-30}
+      CONTEXT_EMBEDDING_MAX_CHARS: ${CONTEXT_EMBEDDING_MAX_CHARS:-4000}
+    volumes:
+      - ./proxy:/app/proxy:ro
+      # Create it first (mode 700, host-owned); compose would otherwise create a root-owned directory.
+      - type: bind
+        source: ${OPENMEM_STATE_DIR:-${HOME}/.local/share/openmem}/context
+        target: /state/context
+        bind:
+          create_host_path: false
+    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
+
 volumes:
   hindsight-data:
   indexer-state:

package/config/hindsight.env.example

@@ -19,6 +19,8 @@ HINDSIGHT_API_LLM_MAX_CONCURRENT=1
 HINDSIGHT_API_LLM_TIMEOUT=300
 HINDSIGHT_API_LLM_MAX_RETRIES=1
 
+# verbatim: store chunk text as-is; LLM only extracts entities/time/location (faster than concise).
+HINDSIGHT_API_RETAIN_EXTRACTION_MODE=verbatim
 HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS=16384
 HINDSIGHT_API_REFLECT_MAX_COMPLETION_TOKENS=2048
 HINDSIGHT_API_CONSOLIDATION_MAX_COMPLETION_TOKENS=2048

package/config/openmem.toml.example

@@ -24,9 +24,9 @@ control_plane_port = 9999
 [wizard]
 action = "configure" # configure | up | down
 
-# LLM routing for Hindsight (LiteLLM → lemond/Ollama/custom). Not lemond's own config.
+# LLM routing for Hindsight (LiteLLM → lemond/Ollama/custom/Meridian). Not lemond's own config.
 [model]
-backend = "lemond" # lemond | ollama | custom
+backend = "lemond" # lemond | ollama | custom | meridian (Claude subscription, docs/meridian-litellm.md)
 retain = "Gemma-4-E2B-it-GGUF"
 reflect = ""       # empty = shipped memory-reflect route
 api_base = ""      # custom backend only
@@ -37,6 +37,68 @@ host = "http://127.0.0.1:13305"
 [model.ollama]
 host = "http://127.0.0.1:11434"
 
+# meridian backend only: Meridian's URL as seen from this host. The wizard does not run Meridian.
+# [model.meridian]
+# host = "http://127.0.0.1:3456"
+
+# Coding-agent wiring, written by `install-coding-agent`.
+# integration: "openmem" = OpenMem session hooks; "provider" = the provider's own plugin
+# (Hindsight: @vectorize-io/hindsight-coding-agents). The two hook sets are exclusive.
+[agents]
+integration = "openmem"
+
+# Local LiteLLM context proxy (`install-coding-agent --context-proxy`). When enabled,
+# Claude Code's ANTHROPIC_BASE_URL points at http://127.0.0.1:<port>.
+# trim_at_tokens / compress_over_tokens (and [compaction] max_chars) reach the proxy
+# container through the stack .env (written by ./setup and install-coding-agent) and the
+# OpenCode 2 plugin; the env vars CONTEXT_TRIM_AT_TOKENS, CONTEXT_COMPRESS_OVER_TOKENS,
+# CONTEXT_TRIM_TO_FRACTION, CONTEXT_STANDING_INSTRUCTION, CONTEXT_CHARS_PER_TOKEN and CONTEXT_COMPACTION_MAX_CHARS
+# override them.
+[context_proxy]
+# enabled = false           # master switch; agents without a key below follow it (unset: opencode2 on, others off)
+port = 4100
+trim_at_tokens = 120000     # trim a session once its request exceeds this many tokens
+trim_to_fraction = 0.3      # a trim keeps older in-turn exchanges while the request is under this fraction of trim_at_tokens (0 < x < 1)
+compress_over_tokens = 4000 # compress tool results larger than this
+standing_instruction = true # constant system-prompt note telling the agent to search trimmed turns
+chars_per_token = 2.5       # token estimate before a session reports usage; reported usage calibrates it after
+
+# Session databases (sessions/<sid>.db, docs/context-store.md): every message of a trimmed session.
+# ttl_days: delete sessions idle longer than this, checked at proxy / MCP start at most once a day (0 = keep).
+# embedding_model: OpenAI-compatible embedding model for hybrid smart_compact_search; empty = vectors off.
+# The stack ships no embedding route; e.g. `ollama pull nomic-embed-text` and set it here.
+# embedding_url: that endpoint as this host sees it (the proxy container uses CONTEXT_PROXY_EMBEDDING_URL).
+# embedding_timeout_s: seconds per row of a background embeddings call (a batch of n rows gets n times this).
+#   Batches start at 4 rows, double while calls finish well inside the timeout and halve on a failure.
+# embedding_max_chars: characters of each row's head that are embedded; the vector covers only that part.
+#   4000 fits nomic-embed-text's 2048-token context; raise it only for a model with a longer one.
+[context_store]
+ttl_days = 30
+embedding_model = ""
+embedding_url = "http://127.0.0.1:11434/v1"
+embedding_timeout_s = 30
+embedding_max_chars = 4000
+
+# Optional per-agent overrides (written by the wizard and `openmem context on|off --agents`).
+# claude-code and opencode1 go through the context-proxy service, which install-coding-agent starts
+# when one of them is on and stops when none is. opencode2 trims in its own plugin (no service;
+# CONTEXT_PROXY_ENABLED overrides it); with neither its key nor `enabled` set it is on.
+# codex is accepted but not routed yet.
+# [context_proxy.agents]
+# claude-code = true
+# opencode1 = true
+# codex = false
+# opencode2 = true
+
+# native (OpenCode 2 only): when OpenCode compacts a session, OpenMem's plugin supplies the
+# smart_compact_search pointer + recall as the summary instead of a model call.
+# false leaves compaction to OpenCode.
+# max_chars: cap on the recall text placed after a trim or compaction pointer.
+[compaction]
+native = true
+max_chars = 12000
+# recall = true             # provider recall in the trim pointer, framed as untrusted data (env CONTEXT_COMPACTION_RECALL)
+
 # Optional indexer defaults (wizard may still prompt interactively)
 # [[index.roots]]
 # path = "~"

package/docs/architecture.md

@@ -1,6 +1,25 @@
 # Architecture
 
-openmem’s job is **not** to be the memory — it is to let you run **whichever memory system you choose** on one machine with shared indexing and setup. A **shared indexer** writes into the active **provider**; **coding agents** reach that API through unified `memory_*` MCP, in-repo **session hooks**, and optional native paths (Hindsight plugin, mem0/Cognee MCP). Only one provider is active at a time; `npx @bcmyguest/openmem switch` rewires the stack without pretending to migrate your data. Setup (`npx @bcmyguest/openmem`) is install plumbing only — not part of the runtime data path.
+OpenMem connects coding agents and a shared indexer to one active [memory provider](provider-status.md). Agents use the stable `memory_*` MCP and session hooks; the indexer writes sources to the same provider. This page shows the full runtime paths and optional integrations. Setup (`npx @bcmyguest/openmem`) configures them but is outside the runtime data path. Switching providers does not migrate memories.
+
+## Overview
+
+Two paths. **A, memory:** sources go through the indexer into one active provider, which agents reach through the `memory_*` MCP and session hooks. **B, context management:** the context proxy (OpenCode 2: a native plugin) keeps each session under `trim_at_tokens` by moving older turns to a local session store that the agent searches; no model call summarizes them. OpenMem parts are tinted.
+
+<p align="center">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://bcmyguest.github.io/openmem/media/overview-memory-dark.png" />
+<img src="https://bcmyguest.github.io/openmem/media/overview-memory.png" alt="A, memory: sources, OpenMem indexer, one active provider, OpenMem MCP, coding agents with session hooks" width="360" />
+</picture>
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://bcmyguest.github.io/openmem/media/overview-context-dark.png" />
+<img src="https://bcmyguest.github.io/openmem/media/overview-context.png" alt="B, context management: coding agent, context proxy, model API, session store read back over MCP; OpenCode 2 uses a native plugin" width="360" />
+</picture>
+<br />
+<sub>A, memory · B, context management</sub>
+</p>
+
+The sections below show every runtime path and optional integration.
 
 ## Runtime data flow
 
@@ -31,7 +50,7 @@ flowchart TB
     AG[Coding agents]
     UMCP["openmem MCP\n(memory_*)"]
     SHIM["Session hooks\n(all providers)"]
-    PLG["Hindsight plugin\n(optional --hindsight-plugin)"]
+    PLG["Hindsight plugin\n(--provider-plugin, replaces hooks)"]
     PMCP["Provider MCP\nmem0 or Cognee, optional"]
     NLMCP["NotebookLM MCP\noptional, separate server"]
   end
@@ -68,7 +87,7 @@ Only **one provider** is active at a time (`MEMORY_PROVIDER`). The indexer uses
 
 Product framing: [Concepts](concepts.md).
 
-openmem is a **meta layer**: it does not replace provider APIs. It wires the same plumbing (indexer, compose, wizard, MCP) to **different backends** through manifests and thin adapters.
+OpenMem connects the indexer, Compose, wizard, and MCP to the selected provider through its manifest and adapter. Provider support levels come from [Provider status](provider-status.md).
 
 ```mermaid
 flowchart TB
@@ -110,7 +129,7 @@ flowchart TB
 | **Wizard hooks** | Provider-specific env, keys, smoke, coding-agent notes | `providers/<id>/wizard.mjs` |
 | **Indexer sink** | Poll/vault → retain/update/delete on the provider API | `indexer/` (driver id in manifest, e.g. `hindsight-rest-v1`, `mem0-rest`) |
 | **Unified MCP** | Stable `memory_*` tools → provider HTTP | `cli/mcp/memory-facade.mjs`, `cli/openmem-mcp.mjs` |
-| **Native agent paths** | Session hooks + optional plugin/MCP | `cli/coding-agent/hook-runner.mjs`; optional Hindsight plugin; `cli/mem0-mcp.mjs`, `cli/cognee-mcp.mjs`, NotebookLM |
+| **Native agent paths** | Session hooks or provider plugin (`[agents] integration`) + optional MCP | `cli/coding-agent/hook-runner.mjs`; optional Hindsight plugin; `cli/mem0-mcp.mjs`, `cli/cognee-mcp.mjs`, NotebookLM |
 
 Adding a provider means a new manifest + hooks + sink driver; agents can keep using **`memory_*`** once the facade implements that backend.
 
@@ -118,7 +137,7 @@ Adding a provider means a new manifest + hooks + sink driver; agents can keep us
 
 | Input | Resolves |
 | --- | --- |
-| `MEMORY_PROVIDER` | Active backend (`wizard.conf`, optional `config.toml`) |
+| `MEMORY_PROVIDER` | Active provider (`wizard.conf`, optional `config.toml`) |
 | Stack `.env` | API URLs, ports, `MEMORY_SINK`, indexer → provider URL |
 | Provider secret files | e.g. `~/.config/personal-memory/mem0.env` (never committed; not written to `mcp.json`) |
 | `~/.config/hindsight/index.yml` | What the indexer watches |
@@ -153,8 +172,8 @@ Default scope key for MCP-created rows: bank / `user_id` **`openmem-mcp`** unles
 
 | Provider | Session / tools | Install |
 | --- | --- | --- |
-| **All providers** | In-repo session hooks → unified `memory_*` | `install-coding-agent --yes` |
-| **Hindsight (optional)** | `@vectorize-io/hindsight-coding-agents` plugin | `install-coding-agent --hindsight-plugin` |
+| **All providers** | In-repo session hooks → unified `memory_*` (`[agents] integration = "openmem"`, default) | `install-coding-agent --yes` |
+| **Hindsight (optional)** | `@vectorize-io/hindsight-coding-agents` plugin instead of the session hooks (`integration = "provider"`) | `install-coding-agent --provider-plugin` |
 | **mem0** | `@yeyuan98/mem0-mcp` tools | `install-mcp --provider-only` |
 | **Cognee** | `cognee_health`, `cognee_search` | `install-mcp --provider-only` |
 | **NotebookLM** | `notebooklm_list_banks`, `notebooklm_search` | `install-mcp` when sync enabled or `--notebooklm` |
@@ -194,15 +213,22 @@ There is **no** cross-vendor standard for agent memory APIs. MCP standardizes to
 | `memory_forget` | Delete by id (mem0) or drop a Hindsight bank |
 | `memory_provider_status` | Active provider and loopback URL (no secrets) |
 | `memory_export` / `memory_import` | PMM portable format — [Portable memory (PMM)](memory-portability.md) |
+| `memory_project_scope` | Resolve a workspace's bank and hook access (local) |
+| `memory_pages_list` / `memory_pages_search` / `memory_pages_read` | List, search, and read curated knowledge pages (Hindsight; others return `supported: false`) |
+| `memory_capture_initiative` | Record an approved feature plan as a tracked initiative page plus marker memory (Hindsight) |
+| `memory_status` | Async ingest drain state and operation status (Hindsight; mem0 always ready) |
+| `smart_compact_search` | Search a session's SQLite store of every message (FTS5 BM25 `query`, merged with embeddings when present, or a `pattern` regex), filtered by `role` and `in_context`, with `context` neighbouring rows (local files, every provider) — [Context store](context-store.md) |
+| `smart_compact_sql` | One read-only SELECT against a session database, for counts and aggregates (2 s, 200 rows) |
+| `smart_compact_get` | Return the full text of a compressed tool result by blob id, paged at 100k chars (local files, every provider) |
 
-**Session hooks** (all providers) call the unified MCP via `cli/coding-agent/hook-runner.mjs`. Optional [`@vectorize-io/hindsight-coding-agents`](https://www.npmjs.com/package/@vectorize-io/hindsight-coding-agents) with `--hindsight-plugin` adds a second hook set on Hindsight stacks.
+**Session hooks** (all providers) call the unified MCP via `cli/coding-agent/hook-runner.mjs`. Optional [`@vectorize-io/hindsight-coding-agents`](https://www.npmjs.com/package/@vectorize-io/hindsight-coding-agents) replaces them on Hindsight stacks: `--provider-plugin` sets `[agents] integration = "provider"`, removes OpenMem's hooks and keeps the unified MCP; `--no-provider-plugin` switches back. `--hindsight-plugin` was renamed to `--provider-plugin`. See [Coding-agent hooks](coding-agent-hooks.md).
 
 ### Other MCP integrations
 
 | Integration | Tools / path | Role |
 | --- | --- | --- |
 | Session hooks | SessionStart / prompt / Stop → `memory_*` | Default in-IDE session memory (all providers) |
-| Hindsight plugin (optional) | Upstream retain / recall / reflect | `--hindsight-plugin` only |
+| Hindsight plugin (optional) | Upstream retain / recall / reflect, instead of the session hooks | `--provider-plugin` only |
 | `notebooklm` (`install-mcp`) | `notebooklm_list_banks`, `notebooklm_search` | Opt-in synced notebooks |
 | `mem0` (`--provider-only`) | mem0 REST tools via `@yeyuan98/mem0-mcp` | Native mem0 tool names |
 | `cognee` (`--provider-only`) | `cognee_health`, `cognee_search` | Native Cognee read-only MCP |

package/docs/coding-agent-hooks.md

@@ -24,16 +24,40 @@ which session features work for the active provider.
 npx @bcmyguest/openmem install-coding-agent --yes
 ```
 
-- **All providers:** unified MCP and [shared skill](../skills/openmem/SKILL.md), plus session hooks (`cli/coding-agent/hook-runner.mjs`) for Claude Code, Codex, Cursor Agent, and a JavaScript OpenCode plugin (`cli/coding-agent/opencode-plugin.mjs`).
-- **Optional:** `--hindsight-plugin` with `MEMORY_PROVIDER=hindsight` also runs `@vectorize-io/hindsight-coding-agents install` (legacy/alternate hook set).
+- **All providers:** unified MCP and [shared skill](../.agents/skills/openmem/SKILL.md), plus session hooks (`cli/coding-agent/hook-runner.mjs`) for Claude Code, Codex, Cursor Agent, and a JavaScript OpenCode plugin: `cli/coding-agent/opencode-plugin.mjs` for OpenCode 1, `cli/coding-agent/opencode2-plugin/` for OpenCode 2 (the installer picks one from `opencode --version`).
+- **Exclusive hook sets:** `[agents] integration` in `~/.config/personal-memory/config.toml` picks one. `openmem` (default) installs the hooks above and removes the upstream Hindsight install: hook entries (commands under `hindsight-coding-agents` / `.hindsight/coding-agents`), the matching OpenCode `plugin` entry, the `hindsight` MCP server when it runs the upstream `dist/mcp-server.js` (Claude Code `~/.claude.json`, Codex `config.toml`, Cursor `mcp.json`), and the `hindsight-coding-agent` skill copies. Upstream writes no MCP or skill for OpenCode. `provider` (`--provider-plugin`, Hindsight only) removes OpenMem's hooks, keeps the unified MCP, and runs `@vectorize-io/hindsight-coding-agents install`. `--no-provider-plugin` switches back; `--hindsight-plugin` was renamed to `--provider-plugin`. Other providers always get OpenMem hooks.
+
+SessionStart output starts with a two-line banner: provider, bank, and the tools to use. It names `memory_pages_search` and `memory_capture_initiative` only when `PROVIDER_CAPABILITIES` marks `knowledge_pages` / `initiatives` for the provider. The same hook writes `sessions/<sid>.json` per [context store](context-store.md); a write failure is ignored. Denied workspaces get no registration.
+
+`/smart-compact`: the installer writes `~/.claude/commands/smart-compact.md`. The prompt hook (Claude Code, Codex, Cursor) and the OpenCode plugin write `sessions/<sid>.force` when the prompt starts with `/smart-compact`, contains `<command-name>/smart-compact</command-name>`, or contains the command body's `openmem:smart-compact` marker; that prompt skips recall. The flag is written even when memory hooks are denied. Claude Code's hook docs say UserPromptSubmit receives the typed `/command args` text; the other two forms cover expanded deliveries.
+
+Cursor hooks live under `hooks` in `~/.cursor/hooks.json` with `version: 1`, as Cursor documents; reinstall moves entries older OpenMem versions wrote at the top level.
 
 See [MCP setup](mcp-setup.md) and [coding agents](coding-agents.md).
 
 Claude Code Stop retention parses ordinary message and tool-use rows. Codex Stop retention is best effort because Codex does not guarantee a stable transcript format. Cursor Stop retention has a bounded adapter for the observed local agent-transcripts JSONL shape (top-level user/assistant role and `message.content` parts). Live Cursor Hook `transcript_path` linkage to that format remains unverified; unknown row shapes are skipped. Cursor recall and explicit `memory_add` remain available. OpenCode retention uses its plugin's session messages API.
 
+### OpenCode 2 plugin
+
+OpenCode 2 does not run OpenCode 1 plugins ([migration guide](https://opencode.ai/v2/docs/build/plugins/migrate-v1/)). `cli/coding-agent/opencode2-plugin/index.js` default-exports a plain `{ id: "openmem", setup }` object. `Plugin.define` from `@opencode/plugin` 2.2.1 returns its argument unchanged, and OpenCode reads the default export's `id` and `setup()` ([Support V1](https://opencode.ai/v2/docs/build/plugins/server/#support-v1)), so the plugin adds no runtime dependency. `setup(ctx)` registers:
+
+| Feature | OpenCode 2 API | Behaviour |
+| --- | --- | --- |
+| Registration | `prompt` / `context` hooks, `session.created` event | Writes `sessions/<sid>.json` on the first hook call per session. In OpenCode 2.2.1 a location's plugins loaded after `opencode run` had created the session, so `session.created` never arrived |
+| Prompt recall | `ctx.session.hook("prompt")` | First prompt: `memory_reflect`; later prompts: `memory_recall` |
+| System context | `ctx.session.hook("context")` | Pushes the session banner onto `event.system`; puts `Personal memory for <bank>:` and the framed recall block in a leading text part of the user message the prompt belongs to, never in `event.system` |
+| Native trim | `ctx.session.hook("context")` | Replaces `event.messages` per [context proxy](context-proxy.md) rules (`cli/coding-agent/context-trim.mjs`) |
+| Native compaction | `ctx.session.hook("compaction")` | Sets `event.result.summary` to the pointer + recall; `[compaction] native = false` disables it |
+| `/smart-compact` | `prompt` hook; `ctx.command.transform` adds a `smart-compact` command | Writes `sessions/<sid>.force`; no recall for that prompt |
+| Retention | `ctx.session.hook("experimental.idle")`; `session.execution.succeeded`, `session.status` idle and `session.idle` events as fallbacks | Reads `ctx.session.context()` and retains the new user/assistant text once per turn |
+
+The access policy matches OpenCode 1: denied workspaces get no registration, recall or retention, but `/smart-compact`, trimming and compression still run. As with the proxy, a trim pointer carries recall only when the session's registration names a bank.
+
 Hindsight Stop hooks submit retains with `async: true` so model extraction runs after the hook returns. A successful queue response advances the transcript cursor; later extraction failures must be checked through Hindsight operations. MCP `memory_add` defaults to async; pass `async: false` to wait for extraction.
 SessionStart hooks use recall instead of reflect. Hindsight startup recall requests `budget: low` and `max_tokens: 1200`; all hook recall output is limited to eight hits and 8000 characters. Explicit `memory_reflect` remains available through the MCP.
 
+Every hook and plugin recall (SessionStart and prompt hooks for Claude Code, Codex and Cursor; the OpenCode 1 and 2 per-prompt recall) is framed as untrusted data with the trim pointer's frame ([format](context-store.md#proxy-inserted-text)): the fixed sentence, then the text in an `<openmem-recall untrusted="true">` block whose inner `openmem-recall` tags are escaped. The 8000-character cap includes the 147-character frame; the SessionStart banner and the OpenCode `Personal memory for <bank>:` label sit outside it. `hookRecallBlock` in `cli/coding-agent/session-facade.mjs` builds it from the shared `recallBlock` (`cli/coding-agent/recall-frame.mjs`). `[compaction] recall` does not affect hook recall.
+
 ## Session scopes
 
 Indexer banks map to provider scopes (`coding-agent::repo`, `obsidian::vault`, mem0 `user_id`, Cognee dataset names). Default MCP scope key: `openmem-mcp`. See [coding-agent-scopes.md](coding-agent-scopes.md).

package/docs/coding-agents.md

@@ -1,22 +1,42 @@
 # Coding agents and MCP
 
+Prerequisite: run the wizard (`npx @bcmyguest/openmem`) so a provider stack is up. The MCP server and hooks only forward to that stack. Per-agent support and evidence levels: [Compatibility matrix](compatibility.md).
+
 One entry point for session wiring on **every** provider (unified MCP + in-repo session hooks):
 
 ```sh
 npx @bcmyguest/openmem install-coding-agent --yes
-# optional: --hindsight-plugin (also run @vectorize-io/hindsight-coding-agents on Hindsight stacks)
+# --provider-plugin / --no-provider-plugin: upstream Hindsight hooks instead of openmem's (saved in config)
+# --no-rtk: skip rtk wiring;  --context-proxy / --no-context-proxy: local context proxy (saved in config)
 # same flags: --dry-run, --agents claude-code,codex,opencode,cursor-cli,hermes,gemini-cli,amp,cline
 ```
 
-This stages a persistent runtime under `~/.local/share/personal-memory/agent-runtime`, registers the unified MCP globally in Claude Code, Codex, Cursor Agent, and OpenCode, and installs their session hooks. It also copies the [openmem skill](../skills/openmem/SKILL.md) into each agent's global skill directory. The runtime path stays valid after an `npx` cache cleanup. Re-run the command after upgrading this package to refresh the runtime and skill. See [hook parity](coding-agent-hooks.md).
+Persisted choices live in `~/.config/personal-memory/config.toml`:
+
+| Table | Key | Default | Flag |
+| --- | --- | --- | --- |
+| `[agents]` | `integration` = `openmem` \| `provider` | `openmem` | `--provider-plugin`, `--no-provider-plugin` |
+| `[context_proxy]` | `enabled` | `false` | `--context-proxy`, `--no-context-proxy` |
+| `[context_proxy]` | `port` | `4100` | edit the file |
+| `[compaction]` | `native` | `true` | edit the file; OpenCode 2 only (see below) |
+
+The two hook sets are exclusive; see [hook parity](coding-agent-hooks.md#install-per-agent).
+
+**rtk.** When [`rtk`](https://github.com/rtk-ai/rtk) is on `PATH`, the installer runs rtk's own setup per selected agent: `rtk init -g --auto-patch` (Claude Code), `rtk init -g --codex`, `rtk init -g --agent cursor`, `rtk init -g --opencode`. rtk adds PreToolUse-style command rewriting and keeps other hooks; OpenMem's reinstall keeps rtk's entries. `rtk init` is idempotent. `--no-rtk` skips it.
+
+**Context proxy.** `--context-proxy` creates `~/.config/personal-memory/context-proxy.env` (mode 600) with `LITELLM_MASTER_KEY` once and reuses it. Claude Code gets `env.ANTHROPIC_BASE_URL = http://127.0.0.1:<port>` and `env.ANTHROPIC_CUSTOM_HEADERS = x-litellm-api-key: Bearer <key>` in `~/.claude/settings.json`; OpenCode gets `provider.anthropic.options.baseURL = http://127.0.0.1:<port>/v1` and the same header ([OpenCode providers](https://opencode.ai/docs/providers/#base-url)). Claude Code then fails until the proxy runs. The proxy trims long sessions and compresses tool results; typing `/smart-compact` makes the prompt hook flag the next request for a trim. See [Context proxy](context-proxy.md). `--no-context-proxy` removes those keys when they still point at the loopback proxy; the key file stays. Codex stays hook-only. OpenCode 2 is never pointed at the proxy, even with `--context-proxy`; see below.
+
+**OpenCode 1 or 2.** The installer runs `opencode --version`; output naming major 2 or later (OpenCode 2.2.1 prints `opencode v2.2.1`) selects OpenCode 2, and any failure or other output selects OpenCode 1. OpenCode 1 gets the file entry `cli/coding-agent/opencode-plugin.mjs` under `"plugin"`. OpenCode 2 gets the runtime directory `cli/coding-agent/opencode2-plugin` under `"plugins"` ([OpenCode 2 plugin config](https://opencode.ai/v2/docs/plugins/); configured local paths must be directories). Each install removes OpenMem's entry of the other shape, so only one OpenMem plugin loads. On OpenCode 2 the plugin trims context itself in its `context` hook, with the proxy's rules, thresholds (`CONTEXT_TRIM_AT_TOKENS`, `CONTEXT_COMPRESS_OVER_TOKENS`, `CONTEXT_COMPACTION_MAX_CHARS`, read from the environment OpenCode runs in), standing system-prompt instruction (`CONTEXT_STANDING_INSTRUCTION`) and [context store](context-store.md) files: every message goes into the session database `sessions/<sid>.db` through `node:sqlite` (Node ≥ 24). The installer therefore removes any earlier `provider.anthropic` proxy settings and says so in its summary. When OpenCode 2 compacts a session itself, the plugin's `compaction` hook marks every stored message out of context and supplies the `smart_compact_search` pointer plus bounded recall as the summary, so no model call is made. `[compaction] native = false` returns compaction to OpenCode's own summary.
+
+This stages a persistent runtime under `~/.local/share/personal-memory/agent-runtime`, registers the unified MCP globally in Claude Code, Codex, Cursor Agent, and OpenCode, and installs their session hooks. It also copies the [openmem skill](../.agents/skills/openmem/SKILL.md) into each agent's global skill directory. The runtime path stays valid after an `npx` cache cleanup. Re-run the command after upgrading this package to refresh the runtime and skill. See [hook parity](coding-agent-hooks.md).
 
-For Codex, installation enables `features.hooks` when unset and preserves an explicit `false`. For OpenCode, the plugin and MCP entry go into the existing `opencode.jsonc` or `opencode.json`; unrelated settings and JSONC comments outside the updated fields are retained.
+For Codex, installation sets `sandbox_mode = "workspace-write"` and enables `features.hooks` and `sandbox_workspace_write.network_access` when unset, and preserves explicit values. Codex otherwise defaults to a read-only sandbox without network, which breaks `curl` and package installs. For OpenCode, the plugin and MCP entry go into the existing `opencode.jsonc` or `opencode.json`; unrelated settings and JSONC comments outside the updated fields are retained.
 
 Codex requires review of new or changed non-managed hooks in `/hooks` before they run. [Codex hook documentation](https://developers.openai.com/codex/hooks) describes this trust step.
 
-The command keeps existing agent settings and other MCP servers. It does not remove the optional Hindsight plugin; after checking the new MCP and hooks, remove the old plugin through its own uninstaller if you no longer want both integrations running.
+The command keeps existing agent settings and other MCP servers. With `integration = "openmem"` it removes what the upstream Hindsight plugin installed: its hook entries, its `hindsight` MCP server (`~/.claude.json`, `~/.codex/config.toml`, `~/.cursor/mcp.json`) and its `hindsight-coding-agent` skill (`~/.claude/skills`, `~/.agents/skills`, `~/.cursor/skills`). An MCP entry goes only when it runs the upstream `hindsight-coding-agents/dist/mcp-server.js`; a skill only when its `SKILL.md` declares `name: hindsight-coding-agent`. A `hindsight` MCP entry of your own that points elsewhere stays. `--dry-run` lists the removals; `provider` mode removes none of these.
 
-The wizard coding-agent step follows the same idea for Hindsight-first flows.
+Wizard step 8 (Coding agents) offers the same `install-coding-agent --yes` for detected CLIs.
 
 Use a **real** `~/.hindsight/coding-agent.json` on disk (seed from `config/coding-agent.json`). Do not symlink into the repo — machine fields such as `optInPaths` and `notebooklmAccess` must not live in the checkout. The indexer reads this file through the `$HOME` mount. If it is missing, the indexer logs a warning and still indexes everything under `$HOME`.
 
@@ -26,7 +46,7 @@ To register **only** Cursor's memory-related MCP entries (NotebookLM, mem0, Cogn
 
 ```sh
 npx @bcmyguest/openmem install-mcp --yes
-# checkout: npx . install-mcp --yes
+# checkout: node cli/openmem.mjs install-mcp --yes
 
 # mem0 self-hosted REST → @yeyuan98/mem0-mcp via cli/mem0-mcp.mjs
 MEMORY_PROVIDER=mem0 npx @bcmyguest/openmem install-mcp --yes --provider-only
@@ -45,7 +65,7 @@ To change `MEMORY_PROVIDER` (updates `~/.config/hindsight/wizard.conf`, optional
 
 ```sh
 npx @bcmyguest/openmem switch mem0 --yes
-# checkout: npx . switch cognee --yes
+# checkout: node cli/openmem.mjs switch cognee --yes
 ```
 
 Flags: `--dry-run`, `--no-stack` (skip compose down/up), `--no-mcp` (skip `install-mcp --provider-only`). Switching does **not** migrate memories between backends. After a switch: restart Cursor Agent, then `npx @bcmyguest/openmem doctor`.