@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/providers/cognee/manifest.json

@@ -0,0 +1,56 @@
+{
+  "id": "cognee",
+  "label": "Cognee",
+  "status": "supported",
+  "notes": "Self-hosted graph/RAG memory run as a pinned cognee/cognee image (single container, SQLite + LanceDB + Ladybug) on a loopback port in single-user mode (no authentication). Ingestion is asynchronous: the indexer adds documents, then requests cognify once per changed dataset, so a document is searchable only after the graph is built. Default cognify path is local GLiNER + FastEmbed (no API key); alternatives are LLM_PROVIDER=ollama or an OpenAI-compatible LLM_API_KEY. No coding-agent plugin — agents use the REST API on the loopback port (/docs).",
+  "settings": {
+    "nativeDocs": "https://docs.cognee.ai/",
+    "nativeConfigPaths": [
+      "~/.config/personal-memory/cognee.env",
+      "~/.config/personal-memory/cognee-indexer.env"
+    ],
+    "wizardOwns": [
+      "compose profile 'cognee', the loopback host port (COGNEE_PORT, default 8766) and the stack .env entries",
+      "GRAPH_EXTRACTOR / EMBEDDING_* (default GLiNER + FastEmbed) and optional LLM_* settings in cognee.env (mode 600, outside the repo)",
+      "the smoke test (health, dataset, multipart add, list, delete; recall is skipped because ingestion is asynchronous)",
+      "index.yml sources (shared indexer)",
+      "Cognee dataset mapping from indexer banks (the indexer sink maps each bank to a dataset)"
+    ]
+  },
+  "compose": {
+    "services": ["cognee", "indexer"],
+    "healthService": "cognee",
+    "logServices": ["cognee"],
+    "healthPath": "/health",
+    "hostPortEnv": "COGNEE_PORT",
+    "defaultHostPort": 8766,
+    "profile": "cognee",
+    "files": ["providers/cognee/compose.yaml"]
+  },
+  "indexer": {
+    "apiUrlEnv": "COGNEE_API_URL",
+    "sink": "cognee",
+    "sinkDriver": "cognee-rest"
+  },
+  "codingAgent": {
+    "pluginPackage": null,
+    "configTemplate": null,
+    "notes": "No plugin package. setupCodingAgent prints REST paths and registers the read-only Cognee MCP (cognee_health / cognee_search) in ~/.cursor/mcp.json."
+  },
+  "wizardHooks": {
+    "module": "wizard.mjs",
+    "delegates": {}
+  },
+  "wizard": {
+    "smokeBank": "wizard-smoke",
+    "retainMethod": "POST",
+    "retainPath": "/api/v1/add",
+    "retainBody": "multipart/form-data: datasetName=wizard_smoke, data=wizard-smoke.md (done by the smoke hook)",
+    "recallMethod": "POST",
+    "recallPath": "/api/v1/search",
+    "recallBody": "{\"searchType\":\"GRAPH_COMPLETION\",\"query\":\"What is the project codename?\",\"datasets\":[\"wizard_smoke\"]}",
+    "recallHint": "check {compose} logs cognee and cognify settings (GLiNER/FastEmbed, Ollama, or LLM_API_KEY)",
+    "deleteMethod": "DELETE",
+    "deletePath": "/api/v1/datasets/{bank}"
+  }
+}

package/providers/cognee/wizard.mjs

@@ -0,0 +1,134 @@
+/**
+ * Cognee sub-wizard (hook API v2). Cognee runs as a pinned docker service on a loopback
+ * port in single-user mode; its secrets (LLM_API_KEY) live in an operator env file outside
+ * the repo (default ~/.config/personal-memory/cognee.env), never in the stack .env,
+ * wizard.conf, config.toml, the summary or an error message. See lib/ for the
+ * implementations and docs/provider-wizard-hooks.md for the hook contract.
+ *
+ * This module must not import wizard/lib/run-wizard.mjs; it receives `helpers`.
+ */
+import { applyConfig, configToml as buildConfigToml } from "./lib/config.mjs";
+import { clackSetup as askInClack } from "./lib/clack.mjs";
+import { setupCodingAgent as printRestAgentHelp } from "./lib/coding-agent.mjs";
+import { beforeStack as prepareEnvDirs, stackEnv as cogneeStackEnv } from "./lib/env-setup.mjs";
+import { captureSecrets, configureLlm } from "./lib/llm-env.mjs";
+import { resolvePorts as resolveCogneePorts } from "./lib/ports.mjs";
+import { runSmoke } from "./lib/smoke.mjs";
+import { ensureState } from "./lib/state.mjs";
+import { summary as cogneeSummary } from "./lib/summary.mjs";
+import { validateCognee } from "./lib/validate.mjs";
+
+// Called by scripts/setup.mjs (the stack .env writer), not by the wizard.
+export { prepareStackEnv, setupNotices } from "./lib/stack-env.mjs";
+
+/** @typedef {import('../../wizard/lib/provider-wizard/helpers.mjs').ProviderWizardHelpers} Helpers */
+
+/**
+ * Quiet: fill Cognee's context fields, map the `[memory.cognee]` TOML table (port,
+ * env_file, indexer_env_file) into the environment when the environment did not set it, and
+ * take the secret answers (PM_COGNEE_LLM_API_KEY and friends) out of `process.env`. This
+ * runs before the wizard's first docker call, so no child process inherits a key.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function init(ctx, h) {
+  applyConfig(ctx, h);
+  captureSecrets(ctx);
+}
+
+/**
+ * Quiet: nothing to restore. The saved port is picked up in `resolvePorts`, which runs
+ * before this hook; nothing secret is saved anywhere.
+ * @param {Record<string, any>} ctx
+ */
+export async function hydrate(ctx) {
+  ensureState(ctx);
+}
+
+/** The single host port (COGNEE_PORT, default 8766). */
+export const resolvePorts = resolveCogneePorts;
+
+/**
+ * Step "LLM / embeddings": write cognify settings (default GLiNER + FastEmbed, or Ollama /
+ * OpenAI answers given as PM_COGNEE_<NAME>) into the operator env file. Never fails for a
+ * missing cloud key: the default local path is cognify-ready without one.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function configureModelRouting(ctx, h) {
+  await configureLlm(ctx, h);
+}
+
+/**
+ * Quiet: description and environment for the stack setup script (scripts/setup.mjs).
+ * @param {Record<string, any>} ctx
+ */
+export function stackEnv(ctx) {
+  return cogneeStackEnv(ctx);
+}
+
+/**
+ * Create the env directories (mode 700) before the stack setup masks them; warn about
+ * loose modes.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function beforeStack(ctx, h) {
+  await prepareEnvDirs(ctx, h);
+}
+
+/**
+ * Replaces the manifest smoke test: health, create dataset, multipart add, list, delete.
+ * Recall is not checked (ingestion is asynchronous).
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function smoke(ctx, h) {
+  await runSmoke(ctx, h);
+}
+
+/**
+ * Appends to ctx.validationErrors / ctx.validationChecks after the shared checks.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function extendValidation(ctx, h) {
+  validateCognee(ctx, h);
+}
+
+/**
+ * Quiet: tables merged into config.toml (`[memory.cognee]`: port, env_file; no secrets).
+ * @param {Record<string, any>} ctx
+ */
+export function configToml(ctx) {
+  return buildConfigToml(ctx);
+}
+
+/**
+ * Quiet: lines for the closing summary.
+ * @param {Record<string, any>} ctx
+ */
+export function summary(ctx) {
+  return cogneeSummary(ctx);
+}
+
+/**
+ * Clack-only: choose OpenAI key vs Ollama; for OpenAI, ask with a hidden prompt. Answers
+ * reach the wizard as PM_COGNEE_* in its own process environment.
+ * @param {Record<string, any>} ctx
+ * @param {typeof import("@clack/prompts")} ui
+ * @param {Helpers} h
+ */
+export async function clackSetup(ctx, ui, h) {
+  return askInClack(ctx, ui, h);
+}
+
+/**
+ * After the generic coding-agent step (skipped: no pluginPackage): print how agents talk
+ * to Cognee over REST on the loopback port.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function setupCodingAgent(ctx, h) {
+  await printRestAgentHelp(ctx, h);
+}

package/providers/graphiti/manifest.json

@@ -0,0 +1,15 @@
+{
+  "id": "graphiti",
+  "label": "Graphiti",
+  "status": "planned",
+  "notes": "Placeholder for Zep Graphiti temporal knowledge graph backend.",
+  "settings": {
+    "nativeDocs": "https://help.getzep.com/graphiti",
+    "nativeConfigPaths": [],
+    "wizardOwns": []
+  },
+  "compose": { "profile": "graphiti", "files": [], "services": [] },
+  "indexer": { "apiUrlEnv": "GRAPHITI_API_URL", "sink": "graphiti" },
+  "codingAgent": { "pluginPackage": null, "configTemplate": null },
+  "wizard": {}
+}

package/providers/hindsight/lib/clack.mjs

@@ -0,0 +1,347 @@
+/**
+ * Hindsight's questions for the Clack setup UI: model backend, models, reflect model
+ * (or, for Meridian, its URL, key and the two Claude models).
+ * The meta UI asks the provider-neutral questions (action, provider) and then calls
+ * clackSetup; the returned environment is handed to the wizard so it skips its own
+ * model prompts (WIZARD_SKIP_BACKEND_STEP).
+ */
+import { applyConfigEnv } from "./config.mjs";
+import {
+  bridgeReport,
+  containerApiBase,
+  dockerBridgeIp,
+  existingMeridianKey,
+  MERIDIAN_DEFAULT_BASE,
+  MERIDIAN_GUIDE,
+  MERIDIAN_REFLECT_DEFAULT,
+  MERIDIAN_RETAIN_DEFAULT,
+  normalizeMeridianBase,
+  pickModel,
+  probeMeridian,
+} from "./meridian.mjs";
+import { fetchJson, normalizeOpenAiBase, ollamaModelNames, openAiModelIds } from "./probe.mjs";
+import {
+  LEMOND_DEFAULT_MODEL,
+  OLLAMA_COMPOSE_API_BASE,
+  OLLAMA_DEFAULT_MODEL,
+  OLLAMA_HOST_API_BASE,
+} from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * @param {{ repoRoot: string, home: string, wizardConf: 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 wizardConf = ctx.wizardConf;
+  if (ctx.pmMerged) applyConfigEnv(ctx.pmMerged);
+  /** @type {Record<string, string>} */
+  const handoff = {};
+
+  const lemondBase = process.env.LEMOND_BASE || "http://127.0.0.1:13305";
+  handoff.LEMOND_BASE = lemondBase;
+
+  const backendDefault =
+    process.env.PM_BACKEND ||
+    h.envValue(wizardConf, "MEMORY_BACKEND") ||
+    "lemond";
+
+  const backend = await ui.select({
+    message: "Model backend",
+    options: [
+      {
+        value: "lemond",
+        label: "Lemonade (lemond)",
+        hint: "local GGUFs on this host",
+      },
+      {
+        value: "ollama",
+        label: "Ollama",
+        hint: "local models on this host",
+      },
+      {
+        value: "custom",
+        label: "OpenAI-compatible URL",
+        hint: "hosted API, other",
+      },
+      {
+        value: "meridian",
+        label: "Claude subscription (Meridian)",
+        hint: "a Meridian proxy you already run on this host",
+      },
+    ],
+    initialValue: ["lemond", "ollama", "custom", "meridian"].includes(backendDefault)
+      ? backendDefault
+      : "lemond",
+  });
+  if (ui.isCancel(backend)) {
+    ui.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  let model = "";
+  let apiBase = "";
+  let reflectModel =
+    process.env.PM_REFLECT_MODEL ||
+    h.envValue(wizardConf, "MEMORY_REFLECT_MODEL") ||
+    "";
+
+  if (backend === "lemond") {
+    const spin = ui.spinner();
+    spin.start(`Checking lemond at ${lemondBase}`);
+    const body = await fetchJson(`${lemondBase}/v1/models`);
+    const ids = openAiModelIds(body);
+    spin.stop(
+      body ? `lemond answered (${ids.length} models)` : "lemond not reachable",
+    );
+    if (!body) {
+      ui.log.warn(
+        "Start lemonade (lemond) on this host, or pick custom / Ollama instead.",
+      );
+    }
+    const defaultModel =
+      h.envValue(wizardConf, "MEMORY_MODEL") ||
+      LEMOND_DEFAULT_MODEL;
+    if (ids.length > 0) {
+      const picked = await ui.select({
+        message: "Retain / consolidate model",
+        options: ids.map((id) => ({ value: id, label: id })),
+        initialValue: ids.includes(defaultModel) ? defaultModel : ids[0],
+      });
+      if (ui.isCancel(picked)) process.exit(0);
+      model = /** @type {string} */ (picked);
+    } else {
+      const typed = await ui.text({
+        message: "Retain / consolidate model id",
+        placeholder: defaultModel,
+        defaultValue: defaultModel,
+      });
+      if (ui.isCancel(typed)) process.exit(0);
+      model = /** @type {string} */ (typed);
+    }
+    apiBase = "http://host.docker.internal:13305/v1";
+  } else if (backend === "ollama") {
+    const ollamaBase = "http://127.0.0.1:11434";
+    const spin = ui.spinner();
+    spin.start(`Checking Ollama at ${ollamaBase}`);
+    const body = await fetchJson(`${ollamaBase}/api/tags`);
+    const names = ollamaModelNames(body);
+    spin.stop(
+      body ? `Ollama answered (${names.length} models)` : "Ollama not reachable",
+    );
+    let ollamaInCompose = false;
+    if (!body) {
+      const useDocker = await ui.confirm({
+        message: "Ollama is not on this host. Run it in Docker (compose profile ollama)?",
+        active: "yes",
+        inactive: "no",
+        initialValue: true,
+      });
+      if (ui.isCancel(useDocker)) process.exit(0);
+      ollamaInCompose = Boolean(useDocker);
+      if (ollamaInCompose) {
+        ui.log.info(
+          "LiteLLM will call http://ollama:11434; the wizard pulls the model after the stack starts.",
+        );
+      } else {
+        ui.log.warn(
+          "Start Ollama on this host (OLLAMA_HOST on the Docker bridge), or rerun and pick Docker.",
+        );
+      }
+    }
+    const defaultModel =
+      h.envValue(wizardConf, "MEMORY_MODEL") ||
+      OLLAMA_DEFAULT_MODEL;
+    if (names.length > 0) {
+      const picked = await ui.select({
+        message: "Retain / consolidate model",
+        options: names.map((n) => ({ value: n, label: n })),
+        initialValue: names.includes(defaultModel) ? defaultModel : names[0],
+      });
+      if (ui.isCancel(picked)) process.exit(0);
+      model = /** @type {string} */ (picked);
+    } else {
+      const typed = await ui.text({
+        message: "Retain / consolidate model",
+        placeholder: defaultModel,
+        defaultValue: defaultModel,
+      });
+      if (ui.isCancel(typed)) process.exit(0);
+      model = /** @type {string} */ (typed);
+    }
+    apiBase = ollamaInCompose ? OLLAMA_COMPOSE_API_BASE : OLLAMA_HOST_API_BASE;
+    if (ollamaInCompose) handoff.MEMORY_OLLAMA_IN_COMPOSE = "1";
+  } else if (backend === "meridian") {
+    const m = await askMeridian(ctx, ui, h);
+    model = m.model;
+    reflectModel = m.reflectModel;
+    apiBase = m.apiBase;
+    Object.assign(handoff, m.env);
+  } else {
+    const defaultBase = "http://host.docker.internal:3456/v1";
+    const defaultModel =
+      h.envValue(wizardConf, "MEMORY_MODEL") ||
+      LEMOND_DEFAULT_MODEL;
+    const baseInput = await ui.text({
+      message: "OpenAI-compatible base URL (host.docker.internal from containers)",
+      placeholder: defaultBase,
+      defaultValue: defaultBase,
+    });
+    if (ui.isCancel(baseInput)) process.exit(0);
+    apiBase = normalizeOpenAiBase(/** @type {string} */ (baseInput));
+
+    const spin = ui.spinner();
+    spin.start("Listing models");
+    const body = await fetchJson(`${apiBase}/models`);
+    const ids = openAiModelIds(body);
+    spin.stop(
+      ids.length
+        ? `Found ${ids.length} models`
+        : "Could not list models (enter id manually)",
+    );
+
+    if (ids.length > 0) {
+      const picked = await ui.select({
+        message: "Retain / consolidate model",
+        options: ids.map((id) => ({ value: id, label: id })),
+        initialValue: ids.includes(defaultModel) ? defaultModel : ids[0],
+      });
+      if (ui.isCancel(picked)) process.exit(0);
+      model = /** @type {string} */ (picked);
+    } else {
+      const typed = await ui.text({
+        message: "Retain / consolidate model id",
+        placeholder: defaultModel,
+        defaultValue: defaultModel,
+      });
+      if (ui.isCancel(typed)) process.exit(0);
+      model = /** @type {string} */ (typed);
+    }
+  }
+
+  if (backend !== "meridian") reflectModel = await askReflect(ui, model, reflectModel);
+
+  ui.note("Next: Docker, secrets, indexing, and starting the stack.", "Backend configured");
+
+  handoff.WIZARD_SKIP_BACKEND_STEP = "1";
+  handoff.PM_BACKEND = /** @type {string} */ (backend);
+  handoff.PM_DEFAULT_MODEL = model;
+  handoff.MEMORY_API_BASE = apiBase;
+  handoff.PM_REFLECT_MODEL = reflectModel;
+  return handoff;
+}
+
+/**
+ * @param {typeof import("@clack/prompts")} ui
+ * @param {string} model retain model
+ * @param {string} reflectModel stored or env reflect model
+ */
+async function askReflect(ui, model, reflectModel) {
+  const reflectChoice = await ui.select({
+    message: "Reflect model (needs tool calls; used for memory-reflect)",
+    options: [
+      {
+        value: "",
+        label: "Shipped default for this backend",
+        hint: "E4B route on lemond, etc.",
+      },
+      { value: "same", label: "Same as retain model" },
+      { value: "custom", label: "Pick another model id" },
+    ],
+    initialValue: reflectModel ? "custom" : "",
+  });
+  if (ui.isCancel(reflectChoice)) process.exit(0);
+
+  if (reflectChoice === "same") {
+    reflectModel = model;
+  } else if (reflectChoice === "custom") {
+    const typed = await ui.text({
+      message: "Reflect model id",
+      placeholder: model,
+      defaultValue: reflectModel || model,
+    });
+    if (ui.isCancel(typed)) process.exit(0);
+    reflectModel = /** @type {string} */ (typed);
+  } else {
+    reflectModel = "";
+  }
+  return reflectModel;
+}
+
+/**
+ * Meridian URL, key and models. Detect only: Meridian must already run.
+ * @param {{ home: string, wizardConf: string }} ctx
+ * @param {typeof import("@clack/prompts")} ui
+ * @param {Helpers} h
+ */
+async function askMeridian(ctx, ui, h) {
+  ui.log.info(`The wizard does not install or start Meridian; see ${MERIDIAN_GUIDE}.`);
+  const stored =
+    h.envValue(ctx.wizardConf, "MEMORY_BACKEND") === "meridian"
+      ? h.envValue(ctx.wizardConf, "MEMORY_MERIDIAN_URL")
+      : "";
+  const defaultBase = process.env.MERIDIAN_BASE || stored || MERIDIAN_DEFAULT_BASE;
+  const baseInput = await ui.text({
+    message: "Meridian URL from this host",
+    placeholder: defaultBase,
+    defaultValue: defaultBase,
+  });
+  if (ui.isCancel(baseInput)) process.exit(0);
+  const meridianBase = normalizeMeridianBase(/** @type {string} */ (baseInput));
+  const paths = {
+    meridianEnvFile: `${ctx.home}/.config/meridian/meridian.env`,
+    litellmEnv: `${ctx.home}/.config/hindsight/litellm.env`,
+  };
+  const existing = existingMeridianKey(paths, h);
+  const keyInput = await ui.password({
+    message: `MERIDIAN_API_KEY (blank uses ${existing.source || "no key"})`,
+  });
+  if (ui.isCancel(keyInput)) process.exit(0);
+  const typedKey = String(keyInput || "").trim();
+  const key = typedKey || existing.key;
+
+  const bridgeIp = dockerBridgeIp();
+  const spin = ui.spinner();
+  spin.start(`Checking Meridian at ${meridianBase}`);
+  const probe = await probeMeridian(meridianBase, key, bridgeIp);
+  spin.stop(
+    probe.answered ? `Meridian answered (${probe.ids.length} models)` : "Meridian not reachable",
+  );
+  if (!probe.answered) {
+    ui.log.warn(`Start Meridian first (${MERIDIAN_GUIDE}); the route uses the guide's default models.`);
+  } else if (probe.modelsStatus === 401 || probe.modelsStatus === 403) {
+    ui.log.warn(`Meridian rejected the key on /v1/models (HTTP ${probe.modelsStatus}).`);
+  }
+  const apiBase = containerApiBase(meridianBase);
+  const report = bridgeReport({ ...paths, meridianBase, apiBase, dockerBridgeIp: bridgeIp }, h.envValue, probe);
+  if (report) (report.level === "warn" ? ui.log.warn : ui.log.info)(report.text);
+
+  const choose = async (message, preferred, family, candidates) => {
+    const def = pickModel(probe.ids, preferred, family, candidates);
+    const picked = probe.ids.length
+      ? await ui.select({
+          message,
+          options: probe.ids.map((id) => ({ value: id, label: id })),
+          initialValue: def,
+        })
+      : await ui.text({ message, placeholder: def, defaultValue: def });
+    if (ui.isCancel(picked)) process.exit(0);
+    return /** @type {string} */ (picked);
+  };
+  const sameBackend = h.envValue(ctx.wizardConf, "MEMORY_BACKEND") === "meridian";
+  const model = await choose("Retain / consolidate model", MERIDIAN_RETAIN_DEFAULT, /haiku/, [
+    process.env.PM_DEFAULT_MODEL,
+    sameBackend ? h.envValue(ctx.wizardConf, "MEMORY_MODEL") : "",
+  ]);
+  const reflectModel = await choose("Reflect model (needs tool calls)", MERIDIAN_REFLECT_DEFAULT, /sonnet/, [
+    process.env.PM_REFLECT_MODEL,
+    sameBackend ? h.envValue(ctx.wizardConf, "MEMORY_REFLECT_MODEL") : "",
+  ]);
+  /** @type {Record<string, string>} */
+  const env = { MERIDIAN_BASE: meridianBase };
+  if (typedKey) env.MERIDIAN_API_KEY = typedKey;
+  return { model, reflectModel, apiBase, env };
+}