@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/providers/cognee/lib/smoke.mjs

@@ -0,0 +1,246 @@
+/**
+ * Cognee smoke test (replaces the manifest's JSON-only HTTP smoke).
+ *
+ * Cognee ingests asynchronously (add, then cognify), so the test cannot read back what it
+ * wrote through search. It proves the server is up, accepts a multipart document and lists
+ * it, then removes its dataset:
+ *   1. GET  /health                          (wait, the stack may still be starting)
+ *   2. POST /api/v1/datasets                 create dataset `wizard_smoke`
+ *   3. POST /api/v1/add (multipart)          upload one small markdown file
+ *   4. GET  /api/v1/datasets/{id}/data       the document must be listed
+ *   5. DELETE /api/v1/datasets/{id}          always, even after a failure
+ * It does not call cognify: the LLM may not be configured yet. X-Api-Key is sent only when
+ * COGNEE_API_KEY is set in the environment or in the indexer env file; its value is never
+ * printed.
+ */
+import { readEnvFile } from "./env-file.mjs";
+import { capturedCogneeApiKey } from "./llm-env.mjs";
+import { SMOKE_DATASET, ensureState } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+export const SMOKE_DOC_ID = "wizard-smoke";
+export const SMOKE_FILE = "wizard-smoke.md";
+export const SMOKE_TEXT = "Wizard smoke test: the project codename is heron.";
+
+export const RECALL_SKIPPED =
+  "recall skipped: Cognee ingests asynchronously (add, then cognify); search results appear once the graph is built";
+
+const DEFAULTS = {
+  healthTimeoutMs: 120_000,
+  healthIntervalMs: 3_000,
+  requestTimeoutMs: 30_000,
+  addTimeoutMs: 120_000,
+};
+
+/** A step failed; the message is safe to print (no headers, no bodies beyond a short detail). */
+class SmokeError extends Error {}
+
+/**
+ * Replace every occurrence of `secret` in text (mem0-style). Empty secret is a no-op.
+ * @param {string} text
+ * @param {string} secret
+ */
+function redact(text, secret) {
+  let out = String(text ?? "");
+  if (secret) out = out.split(secret).join("***");
+  return out;
+}
+
+/**
+ * The API key for X-Api-Key: indexer env file first (durable), then the value captured from
+ * process.env in `init` (already scrubbed so children never inherit it). Never reads
+ * process.env at call time.
+ * @param {Record<string, any>} ctx
+ * @returns {string}
+ */
+export function apiKeyFor(ctx) {
+  const fromFile = readEnvFile(ctx.cognee.indexerEnvFile).values.get("COGNEE_API_KEY") || "";
+  if (fromFile) return fromFile;
+  return capturedCogneeApiKey(ctx);
+}
+
+/**
+ * A short, secret-free reason from an error response: the `detail` string when there is one
+ * (secrets redacted, control characters removed, at most 80 characters).
+ * @param {Response} res
+ * @param {string} [secret]
+ */
+async function reason(res, secret = "") {
+  let detail = "";
+  try {
+    const body = JSON.parse(await res.text());
+    if (typeof body?.detail === "string") {
+      // Short and printable: a server message can carry control characters, a long dump, or the key.
+      const cleaned = redact(body.detail, secret).replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, 80);
+      detail = `: ${cleaned}`;
+    }
+  } catch {
+    // not JSON: the status line is enough
+  }
+  return `HTTP ${res.status}${detail}`;
+}
+
+/**
+ * @param {Record<string, any>} item one entry of the data listing
+ * @returns {string[]} every doc_id the entry carries in its external metadata
+ */
+function docIds(item) {
+  let meta = item?.externalMetadata ?? item?.external_metadata;
+  if (typeof meta === "string") {
+    try {
+      meta = JSON.parse(meta);
+    } catch {
+      return [];
+    }
+  }
+  const entries = Array.isArray(meta) ? meta : meta ? [meta] : [];
+  return entries.map((e) => e?.doc_id).filter((v) => typeof v === "string");
+}
+
+/**
+ * Run the smoke test.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ * @param {{ fetch?: typeof fetch, sleep?: (ms: number) => Promise<void>,
+ *   healthTimeoutMs?: number, healthIntervalMs?: number,
+ *   requestTimeoutMs?: number, addTimeoutMs?: number }} [opts] test seams
+ */
+export async function runSmoke(ctx, h, opts = {}) {
+  ensureState(ctx);
+  const o = { ...DEFAULTS, ...opts };
+  const doFetch = opts.fetch || globalThis.fetch;
+  const sleep = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const base = String(await h.apiBase(ctx)).replace(/\/+$/, "");
+  const logs = `docker ${h.composeArgs(ctx, "logs", "cognee").join(" ")}`;
+
+  if (ctx.dry) {
+    h.info(`[dry-run] smoke test against ${base}:`);
+    h.info(`[dry-run]   1. wait for GET ${base}/health (up to 120s)`);
+    h.info(`[dry-run]   2. POST ${base}/api/v1/datasets {"name":"${SMOKE_DATASET}"}`);
+    h.info(`[dry-run]   3. POST ${base}/api/v1/add (multipart: ${SMOKE_FILE} into ${SMOKE_DATASET})`);
+    h.info(`[dry-run]   4. GET ${base}/api/v1/datasets/<id>/data must list the document`);
+    h.info(`[dry-run]   5. DELETE ${base}/api/v1/datasets/<id> (always)`);
+    h.info(`[dry-run] ${RECALL_SKIPPED}`);
+    return;
+  }
+
+  const key = apiKeyFor(ctx);
+  /** @type {Record<string, string>} */
+  const auth = key ? { "X-Api-Key": key } : {};
+  /** @param {Response} res */
+  const why = (res) => reason(res, key);
+
+  /**
+   * @param {string} method
+   * @param {string} route
+   * @param {{ json?: unknown, form?: FormData, timeoutMs?: number }} [req]
+   */
+  const call = async (method, route, req = {}) => {
+    /** @type {Record<string, string>} */
+    const headers = { ...auth };
+    let body;
+    if (req.json !== undefined) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(req.json);
+    } else if (req.form) body = req.form;
+    return doFetch(`${base}${route}`, {
+      method,
+      headers,
+      body,
+      signal: AbortSignal.timeout(req.timeoutMs ?? o.requestTimeoutMs),
+    });
+  };
+
+  /** Id of the dataset named wizard_smoke, from the listing; "" when absent or unlistable. */
+  const findDatasetId = async () => {
+    try {
+      const res = await call("GET", "/api/v1/datasets");
+      if (!res.ok) return "";
+      const list = await res.json().catch(() => null);
+      const found = (Array.isArray(list) ? list : []).find((d) => d?.name === SMOKE_DATASET);
+      return typeof found?.id === "string" ? found.id : "";
+    } catch {
+      return "";
+    }
+  };
+
+  /** @type {string} */
+  let datasetId = "";
+  /** @type {string} */
+  let failure = "";
+  try {
+    // 1. health
+    h.info(`smoke test: waiting for ${base}/health`);
+    const deadline = Date.now() + o.healthTimeoutMs;
+    let healthy = false;
+    for (;;) {
+      try {
+        healthy = (await call("GET", "/health", { timeoutMs: 5_000 })).ok;
+      } catch {
+        healthy = false;
+      }
+      if (healthy || Date.now() >= deadline) break;
+      await sleep(o.healthIntervalMs);
+    }
+    if (!healthy) throw new SmokeError(`GET /health did not answer 2xx within ${Math.round(o.healthTimeoutMs / 1000)}s`);
+
+    // 2. dataset. A create that times out or gets a 5xx may still have created it: look the
+    // dataset up by name so the cleanup below deletes an orphan.
+    /** @type {Response | null} */
+    let created = null;
+    let createError = "";
+    try {
+      created = await call("POST", "/api/v1/datasets", { json: { name: SMOKE_DATASET } });
+    } catch (e) {
+      createError = `create dataset request failed (${/** @type {Error} */ (e).name})`;
+    }
+    if (created?.ok) {
+      const dataset = await created.json().catch(() => null);
+      datasetId = typeof dataset?.id === "string" ? dataset.id : "";
+    }
+    if (!datasetId) {
+      if (!created || created.status >= 500 || created.ok) datasetId = await findDatasetId();
+      throw new SmokeError(createError || (created?.ok ? "create dataset returned no id" : `create dataset failed (${await why(/** @type {Response} */ (created))})`));
+    }
+
+    // 3. add (multipart)
+    const form = new FormData();
+    form.append("datasetName", SMOKE_DATASET);
+    form.append("data", new Blob([SMOKE_TEXT], { type: "text/markdown" }), SMOKE_FILE);
+    form.append("external_metadata", JSON.stringify([{ doc_id: SMOKE_DOC_ID }]));
+    const added = await call("POST", "/api/v1/add", { form, timeoutMs: o.addTimeoutMs });
+    if (!added.ok) throw new SmokeError(`add failed (${await why(added)})`);
+
+    // 4. listing
+    const listed = await call("GET", `/api/v1/datasets/${encodeURIComponent(datasetId)}/data`);
+    if (!listed.ok) throw new SmokeError(`list data failed (${await why(listed)})`);
+    const payload = await listed.json().catch(() => null);
+    const items = Array.isArray(payload) ? payload : Array.isArray(payload?.data) ? payload.data : [];
+    if (items.length < 1) throw new SmokeError("the dataset listing is empty after add");
+    const ids = items.flatMap(docIds);
+    if (ids.length && !ids.includes(SMOKE_DOC_ID)) {
+      throw new SmokeError(`the listed document carries doc_id ${JSON.stringify(ids[0])}, expected ${SMOKE_DOC_ID}`);
+    }
+  } catch (e) {
+    failure = e instanceof SmokeError ? e.message : `request failed (${/** @type {Error} */ (e).name})`;
+  } finally {
+    // 5. cleanup, best effort, before any exit
+    if (datasetId) {
+      try {
+        const del = await call("DELETE", `/api/v1/datasets/${encodeURIComponent(datasetId)}`);
+        if (del.ok) h.ok(`deleted smoke dataset ${SMOKE_DATASET}`);
+        else h.warn(`could not delete smoke dataset ${SMOKE_DATASET} (${await why(del)}); delete it by hand: DELETE ${base}/api/v1/datasets/${datasetId}`);
+      } catch (e) {
+        h.warn(`could not delete smoke dataset ${SMOKE_DATASET} (${/** @type {Error} */ (e).name}); delete it by hand: DELETE ${base}/api/v1/datasets/${datasetId}`);
+      }
+    }
+  }
+
+  if (failure) {
+    h.die(`Cognee smoke test failed: ${failure}. Check: ${logs} (and LLM_API_KEY in cognee.env)`);
+    return;
+  }
+  h.ok(`Cognee accepted and listed a document in dataset ${SMOKE_DATASET}`);
+  h.info(RECALL_SKIPPED);
+}

package/providers/cognee/lib/stack-env.mjs

@@ -0,0 +1,134 @@
+/**
+ * Cognee's contribution to scripts/setup.mjs: the COGNEE_PORT entry of the stack .env, the paths of
+ * non-default env files (COGNEE_ENV_FILE, COGNEE_INDEXER_ENV_FILE: paths, never contents), an inert
+ * LITELLM_CONFIG entry, and the end-of-run notices about the Cognee env file.
+ * Runs as a plain Node script step (no wizard context), so it only reads process environment
+ * and the paths it is given. It never prints or returns secret values.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { envValue } from "../../../wizard/lib/paths.mjs";
+import { isCognifyReady, providerMismatchWarning } from "./llm-env.mjs";
+import { parseEnvText } from "./env-file.mjs";
+
+const DEFAULT_PORT = "8766";
+
+/** Read-only code root: PM_PACKAGE_ROOT (set by scripts/setup.mjs), else this module's checkout. */
+function packageRoot() {
+  const moduleRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+  return path.resolve(process.env.PM_PACKAGE_ROOT || moduleRoot);
+}
+
+/** @param {string} home @param {NodeJS.ProcessEnv} env @param {string} [repo] */
+function cogneeEnvFile(home, env, repo) {
+  const value = env.COGNEE_ENV_FILE || (repo && envValue(path.join(repo, ".env"), "COGNEE_ENV_FILE"));
+  if (!value) return path.join(home, ".config/personal-memory/cognee.env");
+  return value.startsWith("~/") ? path.join(home, value.slice(2)) : path.resolve(repo || "", value);
+}
+
+/**
+ * An env-file path from the environment as an absolute path: `~` is expanded and a relative
+ * path is taken relative to the stack root, which is how compose resolves env_file.
+ * @param {string} value @param {string} repo @param {string} home
+ */
+function absolutePath(value, repo, home) {
+  if (/[\r\n\0]/.test(value)) throw new Error("an env file path must be a single line");
+  const expanded = value === "~" ? home : value.startsWith("~/") ? path.join(home, value.slice(2)) : value;
+  return path.resolve(repo, expanded);
+}
+
+/**
+ * @param {{ repo: string, home?: string, env: NodeJS.ProcessEnv }} opts
+ * @returns {{ entries: [string, string][], drop: string[], report: string[] }}
+ *   entries: KEY=value lines to add to the stack .env; drop: keys to remove first (so a key is
+ *   rewritten, never duplicated); report: KEY=value strings echoed in the "wrote .env" line
+ */
+export function prepareStackEnv({ repo, home = process.env.HOME || "", env }) {
+  const stackEnv = path.join(repo, ".env");
+
+  const port = env.COGNEE_PORT || envValue(stackEnv, "COGNEE_PORT") || DEFAULT_PORT;
+  if (!/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
+    throw new Error(`COGNEE_PORT must be a number from 1 to 65535 (got: ${port})`);
+  }
+
+  const profiles = ["cognee"];
+  const notebookYml = path.join(home, ".config/hindsight/notebooklm.yml");
+  if (fs.existsSync(notebookYml) && /^enabled:\s*true\b/m.test(fs.readFileSync(notebookYml, "utf8"))) {
+    profiles.push("notebooklm");
+  }
+
+  /** @type {[string, string][]} */
+  const entries = [
+    ["COGNEE_PORT", String(Number(port))],
+    ["MEMORY_SINK", "cognee"],
+    ["MEMORY_API_URL", "http://cognee:8000"],
+    ["COMPOSE_PROFILES", profiles.join(",")],
+  ];
+  const drop = ["COGNEE_PORT", "COMPOSE_PROFILES", "MEMORY_SINK", "MEMORY_API_URL"];
+  const report = [`COGNEE_PORT=${entries[0][1]}`, `COMPOSE_PROFILES=${profiles.join(",")}`];
+
+  // Env files at a non-default location: persist the PATH (not its contents) so a hand-run
+  // `docker compose` finds the same files. Absent from the environment, nothing is written and
+  // an existing line is kept.
+  for (const name of ["COGNEE_ENV_FILE", "COGNEE_INDEXER_ENV_FILE"]) {
+    if (!env[name]) continue;
+    const file = absolutePath(env[name], repo, home);
+    entries.push([name, file]);
+    drop.push(name);
+    report.push(`${name}=${file}`);
+  }
+
+  // Compose interpolates every service before it filters by profile, so the root compose.yaml
+  // requires LITELLM_CONFIG even under `--profile cognee`. The value is inert here: the litellm
+  // service is gated by the profile "hindsight" and never starts for Cognee. Keep any value the
+  // stack .env already has; otherwise honor the operator's process env; otherwise the shipped
+  // config. An empty LITELLM_CONFIG= line is dropped so it is never duplicated.
+  if (!envValue(stackEnv, "LITELLM_CONFIG")) {
+    let litellmConfig = env.LITELLM_CONFIG;
+    if (!litellmConfig) {
+      litellmConfig = path.join(packageRoot(), "config", "litellm.lemond.yaml");
+      if (!fs.existsSync(litellmConfig)) {
+        throw new Error(`shipped config not found: ${litellmConfig}`);
+      }
+    }
+    entries.push(["LITELLM_CONFIG", litellmConfig]);
+    drop.push("LITELLM_CONFIG");
+    report.push(`LITELLM_CONFIG=${litellmConfig}`);
+  }
+  return { entries, drop, report };
+}
+
+/**
+ * Printed after the .env is written. Names the env file, never its contents.
+ * @param {{ repo?: string, home: string, env: NodeJS.ProcessEnv }} opts
+ * @returns {string[]}
+ */
+export function setupNotices({ repo, home, env }) {
+  const file = cogneeEnvFile(home, env, repo);
+  const notices = [];
+  let text = "";
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    // missing or unreadable: same notice as an empty file
+  }
+  const values = parseEnvText(text);
+  if (!isCognifyReady(values)) {
+    const mismatch = providerMismatchWarning(values);
+    if (mismatch) notices.push(`NOTE: ${mismatch} in ${file}.`);
+    notices.push(
+      `NOTE: Cognee needs a cognify-ready config in ${file}: default is GRAPH_EXTRACTOR=gliner_demo ` +
+        "with FastEmbed embeddings, or LLM_PROVIDER=ollama, or LLM_API_KEY. " +
+        "Documents are stored but not searchable until cognify works.",
+    );
+  }
+  try {
+    if (fs.statSync(file).mode & 0o077) {
+      notices.push(`NOTE: ${file} is readable by other users; run: chmod 600 ${file}`);
+    }
+  } catch {
+    // no file: nothing to say about its mode
+  }
+  return notices;
+}

package/providers/cognee/lib/state.mjs

@@ -0,0 +1,101 @@
+/**
+ * Cognee's slice of the wizard context: defaults, and where the operator env files live.
+ *
+ * Two optional env files hold every Cognee secret; neither is the stack .env:
+ *   cognee.env          loaded by the cognee service (LLM_API_KEY, LLM_*, EMBEDDING_*)
+ *   cognee-indexer.env  loaded by the indexer (COGNEE_API_KEY only, when auth is enabled)
+ * Their paths follow providers/cognee/compose.yaml: COGNEE_ENV_FILE and
+ * COGNEE_INDEXER_ENV_FILE, defaulting to ~/.config/personal-memory/.
+ */
+import path from "node:path";
+import { envValue } from "../../../wizard/lib/paths.mjs";
+
+export const DEFAULT_PORT = 8766;
+export const DEFAULT_ENV_FILE = "~/.config/personal-memory/cognee.env";
+export const DEFAULT_INDEXER_ENV_FILE = "~/.config/personal-memory/cognee-indexer.env";
+
+/** Dataset the smoke test creates and deletes. */
+export const SMOKE_DATASET = "wizard_smoke";
+
+/**
+ * @param {string} p
+ * @param {string} home
+ */
+function expand(p, home) {
+  if (p === "~") return home;
+  if (p.startsWith("~/")) return path.join(home, p.slice(2));
+  return p;
+}
+
+/**
+ * Absolute path for an env-file setting: `~` is expanded and a relative path is taken
+ * relative to the stack root (compose resolves env_file against its project directory).
+ * @param {string} value
+ * @param {{ home?: string, repoRoot?: string }} ctx
+ */
+export function resolveFile(value, ctx) {
+  return path.resolve(ctx.repoRoot || "", expand(value, ctx.home || ""));
+}
+
+/**
+ * One env-file setting, most specific first: the environment variable, the `[memory.cognee]`
+ * TOML value, the stack .env (where a previous run persisted it), then the default.
+ * @param {Record<string, any>} ctx
+ * @param {string} name COGNEE_ENV_FILE or COGNEE_INDEXER_ENV_FILE
+ * @param {string} fromToml
+ * @param {string} fallback
+ */
+function envFileSetting(ctx, name, fromToml, fallback) {
+  const fromStack = ctx.repoRoot ? envValue(path.join(ctx.repoRoot, ".env"), name) : "";
+  return resolveFile(process.env[name] || fromToml || fromStack || fallback, ctx);
+}
+
+/**
+ * Fill the Cognee fields of the wizard context. Idempotent: a field that is already set
+ * is kept. The env file paths are recomputed on every call because the environment, the
+ * TOML table (applied in `init`) and the stack .env can change between phases.
+ * @param {Record<string, any>} ctx
+ */
+export function ensureState(ctx) {
+  const cognee = (ctx.cognee ||= { port: "", envFile: "", indexerEnvFile: "" });
+  cognee.envFile = envFileSetting(ctx, "COGNEE_ENV_FILE", cognee.configEnvFile || "", DEFAULT_ENV_FILE);
+  cognee.indexerEnvFile = envFileSetting(
+    ctx,
+    "COGNEE_INDEXER_ENV_FILE",
+    cognee.configIndexerEnvFile || "",
+    DEFAULT_INDEXER_ENV_FILE,
+  );
+  if (ctx.portCognee === undefined) ctx.portCognee = "";
+  if (ctx.cogneeUrl === undefined) ctx.cogneeUrl = "";
+  return ctx;
+}
+
+/**
+ * Whether an env file path differs from its shipped default (and so must be persisted).
+ * @param {Record<string, any>} ctx
+ * @param {"envFile"|"indexerEnvFile"} which
+ */
+export function isCustomPath(ctx, which) {
+  const fallback = which === "envFile" ? DEFAULT_ENV_FILE : DEFAULT_INDEXER_ENV_FILE;
+  return ctx.cognee[which] !== resolveFile(fallback, ctx);
+}
+
+/**
+ * The host port in force: the resolved one, else the environment, else the default.
+ * @param {Record<string, any>} ctx
+ */
+export function currentPort(ctx) {
+  return String(ctx.portCognee || process.env.COGNEE_PORT || DEFAULT_PORT);
+}
+
+/**
+ * A path for display and config.toml: `~/...` when it sits under the home directory.
+ * @param {string} file
+ * @param {string} [home]
+ */
+export function tildePath(file, home) {
+  if (home && (file === home || file.startsWith(`${home}${path.sep}`))) {
+    return `~${file.slice(home.length)}`;
+  }
+  return file;
+}

package/providers/cognee/lib/summary.mjs

@@ -0,0 +1,56 @@
+/** Cognee's contribution to the wizard's closing summary. */
+import fs from "node:fs";
+import path from "node:path";
+import { readEnvFile } from "./env-file.mjs";
+import { isCognifyReady } from "./llm-env.mjs";
+import { currentPort, ensureState } from "./state.mjs";
+
+/**
+ * Lines the meta wizard prints in its summary, in the order it prints them.
+ * @param {Record<string, any>} ctx
+ * @returns {{ running: string[], configFiles: string[], notes: string[], logServices: string[] }}
+ */
+export function summary(ctx) {
+  ensureState(ctx);
+  const url = ctx.cogneeUrl || `http://127.0.0.1:${currentPort(ctx)}`;
+  const running = [
+    `  Cognee API         ${url}  (docs: ${url}/docs)`,
+    "  indexer sink       cognee -> http://cognee:8000 (internal network)",
+    "  ingestion is asynchronous: the indexer requests cognify once per changed dataset",
+  ];
+  const configFiles = [`  ${ctx.cognee.envFile} (cognify settings, mode 600)`];
+  if (fs.existsSync(ctx.cognee.indexerEnvFile)) {
+    configFiles.push(`  ${ctx.cognee.indexerEnvFile} (indexer API key, mode 600)`);
+  }
+  configFiles.push(`  ${path.join(ctx.repoRoot, ".env")} (COGNEE_PORT, COMPOSE_PROFILES)`);
+  const env = readEnvFile(ctx.cognee.envFile);
+  const ready = isCognifyReady(env.values);
+  const provider = (env.values.get("LLM_PROVIDER") || "").toLowerCase();
+  const emb = (env.values.get("EMBEDDING_PROVIDER") || "").toLowerCase();
+  const extractor = (env.values.get("GRAPH_EXTRACTOR") || "").toLowerCase();
+  let readyNote;
+  if (!ready) {
+    readyNote =
+      `Cognee needs a cognify-ready config in ${ctx.cognee.envFile}: ` +
+      "GRAPH_EXTRACTOR=gliner_demo + FastEmbed (default), LLM_PROVIDER=ollama, or LLM_API_KEY; " +
+      "without it documents are stored but not searchable. Then restart with: ./pm up";
+  } else if (extractor === "gliner_demo" || emb === "fastembed") {
+    readyNote =
+      `Cognee builds its graph with local GLiNER + FastEmbed from ${ctx.cognee.envFile}; ` +
+      "change it there, then restart with: ./pm up";
+  } else if (provider === "ollama") {
+    readyNote =
+      `Cognee builds its graph with Ollama from ${ctx.cognee.envFile}; change it there, then restart with: ./pm up`;
+  } else {
+    readyNote =
+      `Cognee builds its graph with the LLM configured in ${ctx.cognee.envFile}; change it there, then restart with: ./pm up`;
+  }
+  const notes = [
+    readyNote,
+    `Graph status: GET ${url}/api/v1/datasets/status`,
+    "The first start downloads a large image and may take several minutes; GLiNER/FastEmbed add ~800 MB on first cognify.",
+    "Deleting a dataset removes its graph and vectors, not just the stored files.",
+    `Coding agents: no plugin — call the REST API at ${url} (see /docs); ingest POST /api/v1/add, then cognify, then search.`,
+  ];
+  return { running, configFiles, notes, logServices: ["cognee", "indexer"] };
+}

package/providers/cognee/lib/validate.mjs

@@ -0,0 +1,97 @@
+/**
+ * Cognee checks that run after the meta wizard's provider-neutral validation: the operator
+ * env files (mode, GLiNER/FastEmbed / Ollama / LLM-key cognify readiness), the stack .env
+ * (port present, no secret assignment lines), and the compose fragment. A missing cognify
+ * config is a warning-class check (documents are stored but not searchable); an env file
+ * that is unreadable or open to group/other is an error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { readEnvFile, tooOpen } from "./env-file.mjs";
+import { isCognifyReady, providerMismatchWarning } from "./llm-env.mjs";
+import { ensureState } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+// Spelled in two pieces: indexer/tests/test_cognee_compose.py asserts that no file under
+// providers/cognee contains the word, so this module must not either.
+const UNFINISHED = new RegExp(["place", "holder"].join(""), "i");
+// Assignment lines only (not HINDSIGHT_API_LLM_API_KEY or a mention in a comment).
+const SECRET_ASSIGNMENT = /^(?:export\s+)?(?:LLM|COGNEE|EMBEDDING)_API_KEY=/m;
+
+/**
+ * Appends to ctx.validationErrors and ctx.validationChecks.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function validateCognee(ctx, h) {
+  ensureState(ctx);
+  const errors = (ctx.validationErrors ||= []);
+  const checks = (ctx.validationChecks ||= []);
+
+  // cognee.env: mode and cognify readiness.
+  const file = ctx.cognee.envFile;
+  const env = readEnvFile(file);
+  if (!env.exists) {
+    checks.push("cognify config missing: documents are stored but not searchable");
+  } else if (env.error) {
+    errors.push(`${file} is not readable (${env.error})`);
+  } else {
+    if (tooOpen(file)) errors.push(`${file} must not be world/group readable (want mode 600)`);
+    else checks.push("cognee.env mode is private");
+    const mismatch = providerMismatchWarning(env.values);
+    if (mismatch) checks.push(mismatch);
+    if (isCognifyReady(env.values)) {
+      const provider = (env.values.get("LLM_PROVIDER") || "").toLowerCase();
+      const emb = (env.values.get("EMBEDDING_PROVIDER") || "").toLowerCase();
+      const extractor = (env.values.get("GRAPH_EXTRACTOR") || "").toLowerCase();
+      if (extractor === "gliner_demo" || emb === "fastembed") {
+        checks.push("cognee.env is cognify-ready (gliner + fastembed)");
+      } else if (provider === "ollama") {
+        checks.push("cognee.env is cognify-ready (ollama + embeddings)");
+      } else {
+        checks.push("cognee.env has LLM_API_KEY");
+      }
+    } else if (env.values.get("LLM_API_KEY")) {
+      checks.push("LLM_API_KEY set but cognify not ready (check LLM/EMBEDDING providers)");
+    } else {
+      checks.push("cognify config missing: documents are stored but not searchable");
+    }
+  }
+
+  // cognee-indexer.env: optional, COGNEE_API_KEY only.
+  const indexerFile = ctx.cognee.indexerEnvFile;
+  const indexerEnv = readEnvFile(indexerFile);
+  if (indexerEnv.exists) {
+    if (indexerEnv.error) errors.push(`${indexerFile} is not readable (${indexerEnv.error})`);
+    else {
+      if (tooOpen(indexerFile)) {
+        errors.push(`${indexerFile} must not be world/group readable (want mode 600)`);
+      }
+      if (indexerEnv.values.has("LLM_API_KEY")) {
+        errors.push(`${indexerFile} must not hold LLM_API_KEY (only COGNEE_API_KEY belongs there)`);
+      }
+    }
+  }
+
+  // Stack .env: the port, and no secret assignment lines.
+  const stackEnv = path.join(ctx.repoRoot, ".env");
+  if (fs.existsSync(stackEnv)) {
+    if (!h.envValue(stackEnv, "COGNEE_PORT")) errors.push("repo .env missing COGNEE_PORT");
+    if (SECRET_ASSIGNMENT.test(fs.readFileSync(stackEnv, "utf8"))) {
+      errors.push("repo .env must not contain LLM_API_KEY or COGNEE_API_KEY (secrets belong in the Cognee env files)");
+    }
+    checks.push("repo .env has COGNEE_PORT and no Cognee secrets");
+  }
+
+  // Compose fragment(s) from the manifest.
+  const fragments = ctx.memoryProvider?.compose?.files || ["providers/cognee/compose.yaml"];
+  for (const rel of fragments) {
+    const abs = path.join(ctx.repoRoot, rel);
+    if (!fs.existsSync(abs)) {
+      errors.push(`missing compose fragment ${rel}`);
+    } else if (UNFINISHED.test(fs.readFileSync(abs, "utf8"))) {
+      errors.push(`${rel} still contains unfinished image text`);
+    } else checks.push(`compose fragment ${rel} present`);
+  }
+}