@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/providers/cognee/OPERATOR.md

@@ -0,0 +1,82 @@
+# Cognee operator notes
+
+Self-hosted graph/RAG memory via a pinned `cognee/cognee` image on a loopback
+port (`COGNEE_PORT`, default **8766**). Auth is off in this stack. Cognify
+defaults to **local GLiNER + FastEmbed** (no API key). Optional secrets
+(`LLM_API_KEY` for OpenAI/Ollama paths, `COGNEE_API_KEY` if you enable auth)
+live in env files under `~/.config/personal-memory/`, never in the stack
+`.env`, `wizard.conf`, or `mcp.json`.
+
+See also [docs/memory-providers.md](../../docs/memory-providers.md) and
+[docs/openmem-config.md](../../docs/openmem-config.md).
+
+## Cognify defaults (GLiNER + FastEmbed)
+
+Fresh setup / `./setup --yes` with no LLM answers writes:
+
+```env
+GRAPH_EXTRACTOR=gliner_demo
+EMBEDDING_PROVIDER=fastembed
+EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
+EMBEDDING_DIMENSIONS=384
+AUTO_FEEDBACK=false
+```
+
+The pinned image already includes `gliner2` and `fastembed`. First cognify
+downloads ~800 MB of models into `HF_HOME` / `FASTEMBED_CACHE_PATH` under the
+`cognee-data` volume (`/cognee-storage/.cache/...`). Changing embedding
+dimensions (for example from Ollama's 768 to FastEmbed's 384) requires
+rebuilding vectors — prune datasets or recreate the `cognee-data` volume.
+
+Overrides: `PM_COGNEE_LLM_PROVIDER=ollama` (Ollama LLM + embeddings), or
+`PM_COGNEE_LLM_API_KEY` / Clack "OpenAI-compatible". `EMBEDDING_PROVIDER=fastembed`
+is allowed with Ollama LLM.
+
+## Coding agents (no plugin package)
+
+Agents use the REST API (`/docs`, `/health`, `/api/v1/add`, `/cognify`, `/search`)
+or the **read-only** stdio MCP shipped in this repo.
+
+### Cursor MCP (`~/.cursor/mcp.json`)
+
+When `MEMORY_PROVIDER=cognee`:
+
+```sh
+npx openmem install-mcp --yes --provider-only
+# checkout: npx . install-mcp --yes --provider-only
+# or during setup: coding-agent step registers the same entry
+```
+
+That merges a `cognee` server pointing at `cli/cognee-mcp.mjs` with
+`env.COGNEE_API_URL` only (host URL; **never** `COGNEE_API_KEY`). Existing
+`hindsight` / `codegraph` / `notebooklm` / `mem0` entries are left alone.
+
+| Tool | Purpose |
+| --- | --- |
+| `cognee_health` | `GET /health` |
+| `cognee_search` | `POST /api/v1/search` (`query`, optional `searchType`, `datasets`) |
+
+Run by hand:
+
+```sh
+node cli/cognee-mcp.mjs
+# or: openmem-cognee-mcp
+```
+
+Base URL resolution inside the MCP: `COGNEE_API_URL` / `COGNEE_URL`, else
+`http://127.0.0.1:${COGNEE_PORT|8766}`. If you enable auth in compose, export
+`COGNEE_API_KEY` in the agent environment (not in `mcp.json`).
+
+v1 MCP is read-only (no add/cognify). Ingest stays with the indexer or curl.
+
+### Switch to / from Cognee
+
+```sh
+npx openmem switch cognee --yes
+# later: npx openmem switch hindsight --yes
+# checkout: npx . switch cognee --yes
+```
+
+Updates `wizard.conf` (and `config.toml` `[memory].provider` when present), restarts the stack
+unless `--no-stack`, and runs `install-mcp --provider-only` unless `--no-mcp`. Does **not**
+migrate memories. Flags: [README — Switch memory provider](../../README.md#switch-memory-provider).

package/providers/cognee/compose.yaml

@@ -0,0 +1,89 @@
+# Cognee provider fragment: one `cognee` service (single container, SQLite + LanceDB + Ladybug under /cognee-storage)
+# and the wiring that points the shared indexer at it. Modeled on Cognee's official minimal compose file
+# (docs/minimal-docker-compose.md in github.com/topoteretes/cognee), with a pinned image and a loopback-only port.
+#
+# Layering (the wizard passes both, then `up -d`):
+#   docker compose -f compose.yaml -f providers/cognee/compose.yaml --profile cognee up -d
+# Add `-f compose.override.yaml` when you use the generated secret masks (Compose skips that file once -f is given).
+#
+# Notes:
+#   - The indexer maps each bank to a Cognee dataset (see indexer/sinks/cognee.py). Ingestion is asynchronous: the
+#     sink adds documents, then its flush() step runs cognify per dataset, so a document is stored first and becomes
+#     searchable only after cognify finishes. Cognify needs a working LLM key (below).
+#   - Cognify defaults to local GLiNER + FastEmbed (no API key) in cognee.env; optional LLM_* / Ollama overrides
+#     go there too (mode 600). HF_HOME / FASTEMBED_CACHE_PATH under /cognee-storage persist model downloads on the
+#     cognee-data volume. The indexer reads a SEPARATE env file (COGNEE_API_KEY only, never LLM_API_KEY). The
+#     directory holding cognee.env (~/.config/personal-memory) is masked from the indexer's $HOME mount by
+#     compose.override.yaml once the wizard has created it; until then the read-only $HOME mount can see it.
+#   - Authentication: ENABLE_BACKEND_ACCESS_CONTROL is pinned to "false" below and overrides the env file, so
+#     REQUIRE_AUTHENTICATION=true in cognee.env alone cannot turn auth on. To enable auth you must change that
+#     compose pin and set REQUIRE_AUTHENTICATION=true; the indexer then needs COGNEE_API_KEY in
+#     cognee-indexer.env (the sink sends it as X-Api-Key).
+#   - Both env files are optional (required: false, Compose 2.24+) so `config` and `up` work before they exist.
+
+services:
+  cognee:
+    profiles: ["cognee"]
+    # Release 1.6.5, pinned by index digest (pushed 2026-10-16; `latest` pointed at the same digest then).
+    # Do not use the `main` tag from the minimal compose file. Bump deliberately.
+    image: cognee/cognee@sha256:29427e968f8b273db0bb7b037a7bb119d7695d960f73a59d649f00c5111a85bd
+    # Loopback only. Host port from .env (COGNEE_PORT); the container listens on 8000.
+    ports:
+      - "127.0.0.1:${COGNEE_PORT:-8766}:8000"
+    env_file:
+      - path: ${COGNEE_ENV_FILE:-${HOME}/.config/personal-memory/cognee.env}
+        required: false
+    environment:
+      # Documented single-user mode: no auth, one shared set of databases. Safe here because the only published port
+      # is bound to 127.0.0.1 and the indexer reaches the server on the compose network.
+      ENABLE_BACKEND_ACCESS_CONTROL: "false"
+      # Persist Hugging Face / FastEmbed / GLiNER model downloads across container recreates (under the data volume).
+      HF_HOME: /cognee-storage/.cache/huggingface
+      FASTEMBED_CACHE_PATH: /cognee-storage/.cache/fastembed
+    volumes:
+      # /cognee-storage is baked into the image owned by its non-root user (uid 1000), and the image defaults
+      # DATA_ROOT_DIRECTORY / SYSTEM_ROOT_DIRECTORY under it. A fresh named volume copies that ownership; a volume
+      # at any other path would be root-owned and unwritable.
+      - cognee-data:/cognee-storage
+    extra_hosts:
+      # A local LLM or embedding server on the host is reachable as http://host.docker.internal:<port>.
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+    # Upstream's compose uses 15s: the server drains background tasks and checkpoints SQLite on shutdown.
+    stop_grace_period: 15s
+    healthcheck:
+      # The image is Python, so python3 is there; curl may not be.
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=5)"]
+      interval: 15s
+      timeout: 10s
+      retries: 10
+      start_period: 90s
+
+  indexer:
+    environment:
+      # Selects indexer/sinks/cognee.py and gives it the API base URL (the compose service name, not localhost).
+      MEMORY_SINK: cognee
+      MEMORY_API_URL: http://cognee:8000
+    env_file:
+      # Only COGNEE_API_KEY belongs here. Never put LLM_API_KEY in this file.
+      - path: ${COGNEE_INDEXER_ENV_FILE:-${HOME}/.config/personal-memory/cognee-indexer.env}
+        required: false
+    depends_on:
+      # Hard dependency (required defaults to true): this fragment is only layered together with --profile cognee,
+      # so a missing profile fails loudly instead of starting an indexer with nothing to write to.
+      cognee:
+        condition: service_healthy
+
+  notebooklm:
+    environment:
+      MEMORY_SINK: cognee
+      MEMORY_API_URL: http://cognee:8000
+    env_file:
+      - path: ${COGNEE_INDEXER_ENV_FILE:-${HOME}/.config/personal-memory/cognee-indexer.env}
+        required: false
+    depends_on:
+      cognee:
+        condition: service_healthy
+
+volumes:
+  cognee-data:

package/providers/cognee/lib/clack.mjs

@@ -0,0 +1,157 @@
+/**
+ * Cognee's Clack setup UI: choose local GLiNER+FastEmbed (default), Ollama, or an
+ * OpenAI-compatible key. Answers travel to the wizard only as PM_COGNEE_* in the wizard
+ * process's own environment (never on a command line, never written anywhere but cognee.env).
+ * `configureModelRouting` removes secrets from the environment once read.
+ */
+import net from "node:net";
+import {
+  KEY_NAME,
+  OLLAMA_API_KEY,
+  GLINER_FASTEMBED_DEFAULTS,
+  ollamaDefaultsForEnv,
+} from "./llm-env.mjs";
+import { readEnvFile } from "./env-file.mjs";
+import { applyConfig } from "./config.mjs";
+import fs from "node:fs";
+import path from "node:path";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * Best-effort TCP probe of host Ollama (127.0.0.1:11434). Never throws.
+ * @returns {Promise<boolean>}
+ */
+function probeHostOllama() {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: "127.0.0.1", port: 11434 });
+    const done = (/** @type {boolean} */ ok) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(500);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+/**
+ * @param {{ repoRoot: string, home: string, pmMerged?: Record<string, unknown> }} ctx
+ * @param {typeof import("@clack/prompts")} ui the @clack/prompts module
+ * @param {Helpers} h
+ * @returns {Promise<Record<string, string>>} environment for the wizard process
+ */
+export async function clackSetup(ctx, ui, h) {
+  const state = /** @type {Record<string, any>} */ (ctx);
+  state.pmMerged ||= {};
+  applyConfig(state, h);
+  /** @type {Record<string, string>} */
+  const handoff = { WIZARD_SKIP_BACKEND_STEP: "1" };
+
+  const stored = readEnvFile(state.cognee.envFile).values.get(KEY_NAME);
+  if (stored) {
+    if (typeof ui.confirm !== "function") return handoff;
+    const replace = await ui.confirm({
+      message: `${state.cognee.envFile} already has an LLM_API_KEY. Replace cognify settings?`,
+      initialValue: false,
+    });
+    if (ui.isCancel(replace)) {
+      ui.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    if (!replace) return handoff;
+  }
+
+  let choice = "gliner";
+  if (typeof ui.select === "function") {
+    const picked = await ui.select({
+      message: "How should Cognee build its knowledge graph (cognify)?",
+      options: [
+        {
+          value: "gliner",
+          label: "Local GLiNER + FastEmbed (default)",
+          hint: "no API key; CPU embeddings (BAAI/bge-small-en-v1.5)",
+        },
+        {
+          value: "ollama",
+          label: "Ollama on this host",
+          hint: "LLM + embeddings via Ollama; host.docker.internal or PM_COGNEE_OLLAMA_COMPOSE=1",
+        },
+        {
+          value: "openai",
+          label: "OpenAI-compatible API key",
+          hint: "stored in cognee.env (mode 600)",
+        },
+      ],
+      initialValue: "gliner",
+    });
+    if (ui.isCancel(picked)) {
+      ui.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    choice = String(picked);
+  }
+
+  if (choice === "gliner") {
+    ui.log?.info?.(
+      "Cognee will use local GLiNER extraction and FastEmbed embeddings (first cognify downloads ~800 MB of models).",
+    );
+    handoff.PM_COGNEE_GRAPH_EXTRACTOR = GLINER_FASTEMBED_DEFAULTS.GRAPH_EXTRACTOR;
+    handoff.PM_COGNEE_EMBEDDING_PROVIDER = GLINER_FASTEMBED_DEFAULTS.EMBEDDING_PROVIDER;
+    handoff.PM_COGNEE_EMBEDDING_MODEL = GLINER_FASTEMBED_DEFAULTS.EMBEDDING_MODEL;
+    handoff.PM_COGNEE_EMBEDDING_DIMENSIONS = GLINER_FASTEMBED_DEFAULTS.EMBEDDING_DIMENSIONS;
+    handoff.PM_COGNEE_AUTO_FEEDBACK = GLINER_FASTEMBED_DEFAULTS.AUTO_FEEDBACK;
+    return handoff;
+  }
+
+  if (choice === "ollama") {
+    const up = await probeHostOllama();
+    if (up) ui.log?.info?.("Ollama answered on 127.0.0.1:11434");
+    else ui.log?.warn?.("Ollama is not answering on 127.0.0.1:11434; start it before cognify, or point LLM_ENDPOINT elsewhere in cognee.env");
+    // Prefer compose service DNS when this machine already uses compose Ollama (loopback-only).
+    const confPath = path.join(ctx.home || "", ".config/hindsight/wizard.conf");
+    let composeOllama = process.env.PM_COGNEE_OLLAMA_COMPOSE === "1" || process.env.MEMORY_OLLAMA_IN_COMPOSE === "1";
+    if (!composeOllama && fs.existsSync(confPath)) {
+      composeOllama = /^MEMORY_OLLAMA_IN_COMPOSE=1\s*$/m.test(fs.readFileSync(confPath, "utf8"));
+    }
+    const defaults = ollamaDefaultsForEnv(
+      composeOllama ? { ...process.env, PM_COGNEE_OLLAMA_COMPOSE: "1" } : process.env,
+    );
+    if (composeOllama) {
+      ui.log?.info?.(
+        "Compose Ollama detected: writing http://ollama:11434 (attach Cognee to the same Docker network).",
+      );
+      handoff.PM_COGNEE_OLLAMA_COMPOSE = "1";
+    }
+    handoff.PM_COGNEE_LLM_PROVIDER = "ollama";
+    handoff.PM_COGNEE_LLM_API_KEY = OLLAMA_API_KEY;
+    handoff.PM_COGNEE_LLM_ENDPOINT = defaults.LLM_ENDPOINT;
+    handoff.PM_COGNEE_EMBEDDING_PROVIDER = defaults.EMBEDDING_PROVIDER;
+    handoff.PM_COGNEE_EMBEDDING_MODEL = defaults.EMBEDDING_MODEL;
+    handoff.PM_COGNEE_EMBEDDING_ENDPOINT = defaults.EMBEDDING_ENDPOINT;
+    handoff.PM_COGNEE_EMBEDDING_DIMENSIONS = defaults.EMBEDDING_DIMENSIONS;
+    return handoff;
+  }
+
+  if (typeof ui.password !== "function") return handoff;
+  ui.log.info("Cognee builds its graph with an LLM; the key is stored in cognee.env (mode 600), never in the repo.");
+  const key = await ui.password({
+    message: "Cognee LLM_API_KEY (input hidden; press Enter to skip — falls back to GLiNER + FastEmbed)",
+  });
+  if (ui.isCancel(key)) {
+    ui.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+  if (String(key ?? "").trim()) {
+    handoff.PM_COGNEE_LLM_API_KEY = String(key).trim();
+  } else {
+    handoff.PM_COGNEE_GRAPH_EXTRACTOR = GLINER_FASTEMBED_DEFAULTS.GRAPH_EXTRACTOR;
+    handoff.PM_COGNEE_EMBEDDING_PROVIDER = GLINER_FASTEMBED_DEFAULTS.EMBEDDING_PROVIDER;
+    handoff.PM_COGNEE_EMBEDDING_MODEL = GLINER_FASTEMBED_DEFAULTS.EMBEDDING_MODEL;
+    handoff.PM_COGNEE_EMBEDDING_DIMENSIONS = GLINER_FASTEMBED_DEFAULTS.EMBEDDING_DIMENSIONS;
+    handoff.PM_COGNEE_AUTO_FEEDBACK = GLINER_FASTEMBED_DEFAULTS.AUTO_FEEDBACK;
+  }
+  return handoff;
+}

package/providers/cognee/lib/coding-agent.mjs

@@ -0,0 +1,26 @@
+/**
+ * Cognee has no coding-agent plugin package. This hook prints REST paths and registers
+ * the read-only Cognee MCP in ~/.cursor/mcp.json (health + search).
+ */
+import { installCogneeMcp } from "./cognee-mcp-install.mjs";
+import { currentPort, ensureState } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function setupCodingAgent(ctx, h) {
+  ensureState(ctx);
+  const url = ctx.cogneeUrl || `http://127.0.0.1:${currentPort(ctx)}`;
+  h.info(`Cognee has no coding-agent plugin package. Agents talk to it over REST at ${url}:`);
+  h.info(`  OpenAPI docs     ${url}/docs`);
+  h.info(`  Health           GET  ${url}/health`);
+  h.info(`  Ingest           POST ${url}/api/v1/add  (multipart; then cognify)`);
+  h.info(`  Cognify          POST ${url}/api/v1/cognify`);
+  h.info(`  Search           POST ${url}/api/v1/search`);
+  h.info("  Auth is off in this stack (loopback only). Set X-Api-Key only if you enable auth in compose.");
+  h.info("Read-only Cursor MCP: cognee_health / cognee_search (cli/cognee-mcp.mjs).");
+  await installCogneeMcp(ctx, h);
+}

package/providers/cognee/lib/cognee-mcp-install.mjs

@@ -0,0 +1,153 @@
+/**
+ * Merge a "cognee" stdio MCP into ~/.cursor/mcp.json.
+ * Preserves existing hindsight / codegraph / notebooklm / mem0 entries. Never writes secrets.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { envValue } from "../../../wizard/lib/paths.mjs";
+import { currentPort, DEFAULT_PORT, ensureState } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/** Sibling MCP servers this merge must never rewrite. */
+export const PRESERVE_MCP_SERVERS = Object.freeze(["hindsight", "codegraph", "notebooklm", "mem0"]);
+
+/** @param {string} repoRoot */
+export function cogneeMcpScriptPath(repoRoot) {
+  return path.resolve(repoRoot, "cli/cognee-mcp.mjs");
+}
+
+/**
+ * Host-view Cognee URL (no secrets). Order: COGNEE_API_URL / COGNEE_URL, ctx.cogneeUrl,
+ * COGNEE_PORT (env / stack .env / wizard.conf / ctx), then default port.
+ * @param {{
+ *   home?: string,
+ *   stackRoot?: string,
+ *   repoRoot?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   cogneeUrl?: string,
+ *   portCognee?: string | number,
+ * }} [opts]
+ */
+export function resolveCogneeApiUrl(opts = {}) {
+  const env = opts.env || process.env;
+  const fromUrl = String(env.COGNEE_API_URL || env.COGNEE_URL || opts.cogneeUrl || "").trim();
+  if (fromUrl) return fromUrl.replace(/\/+$/, "");
+
+  const home = opts.home || "";
+  const stackRoot = opts.stackRoot || opts.repoRoot || "";
+  const candidates = [
+    env.COGNEE_PORT,
+    opts.portCognee,
+    stackRoot ? envValue(path.join(stackRoot, ".env"), "COGNEE_PORT") : "",
+    home ? envValue(path.join(home, ".config/hindsight/wizard.conf"), "COGNEE_PORT") : "",
+  ];
+  const port = String(candidates.map((v) => String(v || "").trim()).find((v) => /^\d+$/.test(v)) || DEFAULT_PORT);
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * mcp.json entry: node + script + COGNEE_API_URL only (never COGNEE_API_KEY).
+ * @param {string} scriptPath
+ * @param {string} [apiUrl]
+ */
+export function cogneeMcpEntry(scriptPath, apiUrl) {
+  const url = String(apiUrl || `http://127.0.0.1:${DEFAULT_PORT}`).replace(/\/+$/, "");
+  return {
+    command: "node",
+    args: [scriptPath],
+    env: {
+      COGNEE_API_URL: url,
+    },
+  };
+}
+
+/** @deprecated alias — use cogneeMcpEntry */
+export const cogneeMcpStubEntry = cogneeMcpEntry;
+
+/**
+ * @param {Record<string, any>} mcp
+ * @param {string} scriptPath
+ * @param {string} [apiUrl]
+ * @returns {{ mcp: Record<string, any>, changed: boolean, skipped?: string, refused?: string }}
+ */
+export function mergeCogneeMcpServer(mcp, scriptPath, apiUrl) {
+  const out = { ...mcp };
+  const servers = { ...(mcp.mcpServers && typeof mcp.mcpServers === "object" ? mcp.mcpServers : {}) };
+  const before = Object.fromEntries(PRESERVE_MCP_SERVERS.map((k) => [k, servers[k]]));
+  const next = cogneeMcpEntry(scriptPath, apiUrl);
+  const prev = servers.cognee;
+  const same = prev && JSON.stringify(prev) === JSON.stringify(next);
+  if (same) {
+    return { mcp: { ...out, mcpServers: servers }, changed: false, skipped: "already configured" };
+  }
+  servers.cognee = next;
+  for (const k of PRESERVE_MCP_SERVERS) {
+    if (before[k] !== undefined && servers[k] !== before[k]) {
+      return { mcp, changed: false, refused: `refusing to alter ${k} MCP entry` };
+    }
+  }
+  return { mcp: { ...out, mcpServers: servers }, changed: true };
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function installCogneeMcp(ctx, h) {
+  ensureState(ctx);
+  const script = cogneeMcpScriptPath(ctx.repoRoot);
+  if (!fs.existsSync(script)) {
+    h.warn(`cognee MCP script missing: ${script}`);
+    return;
+  }
+
+  const apiUrl =
+    ctx.cogneeUrl ||
+    resolveCogneeApiUrl({
+      home: ctx.home,
+      stackRoot: ctx.repoRoot,
+      repoRoot: ctx.repoRoot,
+      env: process.env,
+      portCognee: ctx.portCognee || currentPort(ctx),
+    });
+
+  const mcpPath = path.join(ctx.home, ".cursor", "mcp.json");
+  let existing = {};
+  if (fs.existsSync(mcpPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+    } catch (err) {
+      h.warn(`cannot parse ${mcpPath}: ${err instanceof Error ? err.message : err}`);
+      return;
+    }
+  }
+
+  const snapshots = Object.fromEntries(
+    PRESERVE_MCP_SERVERS.map((k) => [k, existing.mcpServers?.[k]]),
+  );
+  const { mcp, changed, skipped, refused } = mergeCogneeMcpServer(existing, script, apiUrl);
+  if (refused) {
+    h.warn(refused);
+    return;
+  }
+  for (const k of PRESERVE_MCP_SERVERS) {
+    if (snapshots[k] && mcp.mcpServers?.[k] !== snapshots[k]) {
+      h.warn(`refusing to alter ${k} MCP entry`);
+      return;
+    }
+  }
+
+  if (!changed) {
+    h.ok(`cognee MCP already in ${mcpPath}${skipped ? ` (${skipped})` : ""}`);
+    return;
+  }
+  if (ctx.dry) {
+    h.info(`[dry-run] merge cognee MCP into ${mcpPath} → node ${script} (COGNEE_API_URL=${apiUrl}; no API key)`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(mcpPath), { recursive: true });
+  fs.writeFileSync(mcpPath, `${JSON.stringify(mcp, null, 2)}\n`);
+  h.ok(`registered cognee MCP in ${mcpPath}`);
+  h.info("Never put COGNEE_API_KEY in mcp.json; export it in the agent environment if auth is enabled");
+}

package/providers/cognee/lib/config.mjs

@@ -0,0 +1,98 @@
+/**
+ * Cognee's slice of ~/.config/personal-memory/config.toml: the `[memory.cognee]` table
+ * (`port`, `env_file`, `indexer_env_file`). It never holds a secret.
+ */
+import {
+  DEFAULT_ENV_FILE,
+  DEFAULT_INDEXER_ENV_FILE,
+  currentPort,
+  ensureState,
+  resolveFile,
+  tildePath,
+} from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * @param {unknown} value
+ * @returns {string} the port as a string, or "" when unset
+ */
+function portText(value) {
+  if (value === undefined || value === null || value === "") return "";
+  return String(value);
+}
+
+/**
+ * The `[memory.cognee]` table from a merged TOML config.
+ * @param {Record<string, unknown>} cfg
+ * @returns {{ port: string, envFile: string, indexerEnvFile: string }}
+ */
+export function defaultsFromConfig(cfg) {
+  const memory = /** @type {Record<string, any>} */ (cfg.memory || {});
+  const table = /** @type {Record<string, unknown>} */ (
+    memory.cognee && typeof memory.cognee === "object" ? memory.cognee : {}
+  );
+  return {
+    port: portText(table.port),
+    envFile: String(table.env_file || ""),
+    indexerEnvFile: String(table.indexer_env_file || ""),
+  };
+}
+
+/**
+ * Map `[memory.cognee]` into the wizard context and, where the table is the only source,
+ * into the environment compose and the stack setup script read (COGNEE_PORT,
+ * COGNEE_ENV_FILE). The environment and the CLI keep precedence.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function applyConfig(ctx, h) {
+  ensureState(ctx);
+  const d = defaultsFromConfig(ctx.pmMerged || {});
+  if (d.port) {
+    if (!/^\d+$/.test(d.port) || Number(d.port) < 1 || Number(d.port) > 65535) {
+      h.die(`[memory.cognee] port must be a number from 1 to 65535 (got: ${d.port})`);
+    }
+    ctx.cognee.port = d.port;
+    if (!process.env.COGNEE_PORT) process.env.COGNEE_PORT = d.port;
+  }
+  const defaults = {
+    COGNEE_ENV_FILE: DEFAULT_ENV_FILE,
+    COGNEE_INDEXER_ENV_FILE: DEFAULT_INDEXER_ENV_FILE,
+  };
+  for (const [setting, name, field] of /** @type {const} */ ([
+    [d.envFile, "COGNEE_ENV_FILE", "configEnvFile"],
+    [d.indexerEnvFile, "COGNEE_INDEXER_ENV_FILE", "configIndexerEnvFile"],
+  ])) {
+    if (process.env[name]?.startsWith("~")) process.env[name] = resolveFile(process.env[name], ctx);
+    if (setting) {
+      ctx.cognee[field] = setting;
+      // Compose reads the path from the environment (or the stack .env, which the stack
+      // setup script fills from this export), so a TOML value must be a real absolute path.
+      // The shipped default location needs no export (and no .env line).
+      const file = resolveFile(setting, ctx);
+      if (!process.env[name] && file !== resolveFile(defaults[name], ctx)) process.env[name] = file;
+    }
+  }
+  ensureState(ctx);
+}
+
+/**
+ * Tables merged into config.toml when the wizard saves it. `memory` replaces the meta
+ * wizard's own `[memory]` table, so it carries `provider` too.
+ * @param {Record<string, any>} ctx
+ * @returns {Record<string, Record<string, unknown>>}
+ */
+export function configToml(ctx) {
+  ensureState(ctx);
+  return {
+    memory: {
+      provider: "cognee",
+      cognee: {
+        port: Number(currentPort(ctx)),
+        env_file: tildePath(ctx.cognee.envFile, ctx.home) || DEFAULT_ENV_FILE,
+        indexer_env_file: tildePath(ctx.cognee.indexerEnvFile, ctx.home) || DEFAULT_INDEXER_ENV_FILE,
+      },
+    },
+  };
+}