@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/providers/hindsight/lib/ollama-compose.mjs

@@ -0,0 +1,51 @@
+/**
+ * After the stack is healthy: wait for compose Ollama and pull models the LiteLLM routes need.
+ */
+import { ollamaModelNames } from "./probe.mjs";
+import { ensureState } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+const HOST_TAGS = "http://127.0.0.1:11434/api/tags";
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function ensureComposeOllamaModels(ctx, h) {
+  ensureState(ctx);
+  if (ctx.backend !== "ollama" || !ctx.ollamaInCompose) return;
+  if (ctx.dry) {
+    h.info(`[dry-run] wait for compose Ollama, pull ${ctx.model}`);
+    return;
+  }
+
+  h.info("waiting for compose Ollama on 127.0.0.1:11434…");
+  let body = null;
+  for (let i = 0; i < 45; i++) {
+    body = h.curlJson(HOST_TAGS);
+    if (body) break;
+    if (i > 0 && i % 5 === 0) h.info(`… still waiting for Ollama (${i * 2}s)`);
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  if (!body) {
+    h.warn("compose Ollama did not answer on 127.0.0.1:11434; skip model pull");
+    return;
+  }
+  h.ok("compose Ollama is reachable on 127.0.0.1:11434");
+
+  const present = new Set(ollamaModelNames(body));
+  const needed = new Set();
+  if (ctx.model) needed.add(ctx.model);
+  if (ctx.reflectModel) needed.add(ctx.reflectModel);
+  for (const name of needed) {
+    if (present.has(name)) {
+      h.ok(`Ollama already has ${name}`);
+      continue;
+    }
+    const args = h.composeArgs(ctx, "exec", "-T", "ollama", "ollama", "pull", name);
+    await h.act(ctx, `pull ${name} into compose Ollama`, "docker", args, {
+      cwd: ctx.repoRoot,
+    });
+  }
+}

package/providers/hindsight/lib/ports.mjs

@@ -0,0 +1,30 @@
+/** Hindsight's two host ports: the API and the control plane. */
+import path from "node:path";
+import { ensureState } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+const ENV_VARS = ["HINDSIGHT_PORT", "HINDSIGHT_CP_PORT"];
+
+/**
+ * Pick the API and control-plane ports (env, then the stack .env, then 8888/9999) and
+ * export them in process.env for compose.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function resolvePorts(ctx, h) {
+  ensureState(ctx);
+  const stackEnv = path.join(ctx.repoRoot, ".env");
+  const api =
+    process.env.HINDSIGHT_PORT || h.envValue(stackEnv, "HINDSIGHT_PORT") || "8888";
+  const cp =
+    process.env.HINDSIGHT_CP_PORT || h.envValue(stackEnv, "HINDSIGHT_CP_PORT") || "9999";
+  if (!/^\d+$/.test(api) || !/^\d+$/.test(cp)) {
+    h.die("HINDSIGHT_PORT and HINDSIGHT_CP_PORT must be port numbers");
+  }
+  ctx.portApi = String(await h.choosePort(ctx, "Hindsight API", Number(api), { envVars: ENV_VARS }));
+  ctx.portCp = String(await h.choosePort(ctx, "control plane", Number(cp), { envVars: ENV_VARS }));
+  process.env.HINDSIGHT_PORT = ctx.portApi;
+  process.env.HINDSIGHT_CP_PORT = ctx.portCp;
+  ctx.hindsightUrl = `http://127.0.0.1:${ctx.portApi}`;
+}

package/providers/hindsight/lib/probe.mjs

@@ -0,0 +1,33 @@
+const TIMEOUT_MS = 8000;
+
+/**
+ * @param {string} url
+ * @returns {Promise<object|null>}
+ */
+export async function fetchJson(url) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/** @param {object|null} body OpenAI /v1/models or similar */
+export function openAiModelIds(body) {
+  if (!body || !Array.isArray(body.data)) return [];
+  return body.data.map((m) => m.id).filter(Boolean);
+}
+
+/** @param {object|null} body Ollama /api/tags */
+export function ollamaModelNames(body) {
+  if (!body || !Array.isArray(body.models)) return [];
+  return body.models.map((m) => m.name).filter(Boolean);
+}
+
+export function normalizeOpenAiBase(base) {
+  let b = base.trim().replace(/\/+$/, "");
+  if (!b.endsWith("/v1")) b += "/v1";
+  return b;
+}

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

@@ -0,0 +1,132 @@
+/**
+ * Hindsight's contribution to scripts/setup.mjs: the LiteLLM proxy secrets file, the
+ * LITELLM_CONFIG and port entries of the stack .env, and the hindsight.env migration.
+ * Runs as a plain Node script step (no wizard context), so it only reads process
+ * environment and the paths it is given.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { envValue } from "../../../wizard/lib/paths.mjs";
+
+/**
+ * @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;
+ *   report: KEY=value strings echoed in the "wrote .env" line
+ */
+export function prepareStackEnv({ repo, home, env }) {
+  const litellmEnv =
+    env.LITELLM_ENV_FILE || path.join(home, ".config/hindsight/litellm.env");
+  const overrideConfig = path.join(home, ".config/hindsight/litellm.yaml");
+  const backend = env.MEMORY_BACKEND || "lemond";
+
+  if (!["lemond", "ollama"].includes(backend)) {
+    throw new Error(`MEMORY_BACKEND must be lemond or ollama (got: ${backend})`);
+  }
+
+  if (!fs.existsSync(litellmEnv)) {
+    const key = crypto.randomBytes(24).toString("hex");
+    const body =
+      "# LiteLLM proxy secrets. Read by the litellm compose service. Do not commit.\n" +
+      `LITELLM_MASTER_KEY=sk-${key}\n` +
+      "# lemond ignores the key; any non-empty value works.\n" +
+      "LEMOND_API_KEY=placeholder\n" +
+      "# Hosted models: add the provider key here, e.g. ANTHROPIC_API_KEY=..., and reference it as os.environ/ANTHROPIC_API_KEY.\n";
+    fs.writeFileSync(litellmEnv, body, { mode: 0o600 });
+    console.log(`created ${litellmEnv} (mode 600)`);
+  }
+
+  const litellmConfig = fs.existsSync(overrideConfig)
+    ? overrideConfig
+    : path.join(repo, "config", `litellm.${backend}.yaml`);
+
+  const profiles = ["hindsight"];
+  if (env.MEMORY_OLLAMA_IN_COMPOSE === "1") profiles.push("ollama");
+  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 = [
+    ["LITELLM_CONFIG", litellmConfig],
+    ["COMPOSE_PROFILES", profiles.join(",")],
+  ];
+  const drop = ["LITELLM_CONFIG", "COMPOSE_PROFILES"];
+  if (env.HINDSIGHT_PORT) {
+    drop.push("HINDSIGHT_PORT");
+    entries.push(["HINDSIGHT_PORT", env.HINDSIGHT_PORT]);
+  }
+  if (env.HINDSIGHT_CP_PORT) {
+    drop.push("HINDSIGHT_CP_PORT");
+    entries.push(["HINDSIGHT_CP_PORT", env.HINDSIGHT_CP_PORT]);
+  }
+  return { entries, drop, report: [`LITELLM_CONFIG=${litellmConfig}`] };
+}
+
+/**
+ * Point hindsight.env at the LiteLLM proxy (backs the file up first; prints no values).
+ * @param {{ repo: string, home: string, env: NodeJS.ProcessEnv }} opts
+ */
+export function migrateEnv({ home, env }) {
+  const hindsightEnv =
+    env.HINDSIGHT_ENV_FILE || path.join(home, ".config/hindsight/hindsight.env");
+  const litellmEnv =
+    env.LITELLM_ENV_FILE || path.join(home, ".config/hindsight/litellm.env");
+  if (!fs.existsSync(hindsightEnv)) {
+    throw new Error(`no ${hindsightEnv} to migrate`);
+  }
+  const key = envValue(litellmEnv, "LITELLM_MASTER_KEY");
+  if (!key) {
+    throw new Error(`LITELLM_MASTER_KEY missing from ${litellmEnv}`);
+  }
+  const backup = `${hindsightEnv}.bak-${Date.now()}`;
+  fs.copyFileSync(hindsightEnv, backup);
+  const llmLines = [
+    "HINDSIGHT_API_LLM_PROVIDER=openai",
+    "HINDSIGHT_API_LLM_BASE_URL=http://litellm:4000/v1",
+    "HINDSIGHT_API_LLM_MODEL=memory-reflect",
+    `HINDSIGHT_API_LLM_API_KEY=${key}`,
+    "HINDSIGHT_API_RETAIN_LLM_MODEL=memory-retain",
+    "HINDSIGHT_API_REFLECT_LLM_MODEL=memory-reflect",
+    "HINDSIGHT_API_CONSOLIDATION_LLM_MODEL=memory-consolidate",
+    "HINDSIGHT_API_MENTAL_MODEL_REFRESH_LLM_MODEL=memory-reflect",
+  ];
+  const keys = llmLines.map((l) => l.split("=")[0]);
+  const keyRe = new RegExp(`^(${keys.join("|")})=`);
+  const rest = fs
+    .readFileSync(hindsightEnv, "utf8")
+    .split("\n")
+    .filter((l) => l && !keyRe.test(l));
+  fs.writeFileSync(hindsightEnv, `${[...rest, ...llmLines].join("\n")}\n`, { mode: 0o600 });
+  console.log(
+    `migrated ${hindsightEnv} to the LiteLLM proxy (backup: ${backup}). Values not printed.`,
+  );
+  console.log("Next: docker compose up -d   (recreates hindsight with the new env)");
+}
+
+/**
+ * Printed after the .env is written when hindsight.env still calls a model server directly.
+ * @param {{ home: string, env: NodeJS.ProcessEnv }} opts
+ * @returns {string[]}
+ */
+export function setupNotices({ home, env }) {
+  const hindsightEnv =
+    env.HINDSIGHT_ENV_FILE || path.join(home, ".config/hindsight/hindsight.env");
+  if (
+    fs.existsSync(hindsightEnv) &&
+    /^HINDSIGHT_API_LLM_BASE_URL=http:\/\/host\.docker\.internal:/m.test(
+      fs.readFileSync(hindsightEnv, "utf8"),
+    )
+  ) {
+    return [
+      `NOTE: ${hindsightEnv} still calls the model server directly.`,
+      "      Run: node scripts/setup.mjs --migrate-env   (backs up the file, rewrites only LLM lines)",
+    ];
+  }
+  return [];
+}

package/providers/hindsight/lib/state.mjs

@@ -0,0 +1,75 @@
+import path from "node:path";
+
+/** Models the shipped LiteLLM routes (config/litellm.<backend>.yaml) use for retain/consolidate. */
+export const LEMOND_DEFAULT_MODEL = "Gemma-4-E2B-it-GGUF";
+export const OLLAMA_DEFAULT_MODEL = "gemma4:e2b";
+
+/** LiteLLM api_base when Ollama runs on the host (default). */
+export const OLLAMA_HOST_API_BASE = "http://host.docker.internal:11434";
+/** LiteLLM api_base when Ollama is the compose `ollama` service. */
+export const OLLAMA_COMPOSE_API_BASE = "http://ollama:11434";
+
+export const BACKENDS = ["lemond", "ollama", "custom"];
+
+/**
+ * Fill the Hindsight fields of the wizard context. Idempotent: a field that is already
+ * set (a test) is kept.
+ * @param {Record<string, any>} ctx
+ */
+export function ensureState(ctx) {
+  const hs = ctx.hsDir || path.join(ctx.home || "", ".config/hindsight");
+  const defaults = {
+    envFile: path.join(hs, "hindsight.env"),
+    litellmEnv: path.join(hs, "litellm.env"),
+    litellmOverride: path.join(hs, "litellm.yaml"),
+    agentJson: path.join(ctx.home || "", ".hindsight/coding-agent.json"),
+    lemondBase: "http://127.0.0.1:13305",
+    ollamaBase: "http://127.0.0.1:11434",
+    lemondDefaultModel: LEMOND_DEFAULT_MODEL,
+    ollamaDefaultModel: OLLAMA_DEFAULT_MODEL,
+    customDefaultBase: "http://host.docker.internal:8080/v1",
+    backend: "",
+    model: "",
+    reflectModel: "",
+    apiBase: "",
+    lemondJson: null,
+    lemondNames: [],
+    ollamaJson: null,
+    ollamaNames: [],
+    /** True when Ollama runs as the compose profile `ollama` (no host install). */
+    ollamaInCompose: false,
+    portApi: "",
+    portCp: "",
+    hindsightUrl: "",
+  };
+  for (const [key, value] of Object.entries(defaults)) {
+    if (ctx[key] === undefined) ctx[key] = value;
+  }
+  return ctx;
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} h
+ * @param {string} key wizard.conf key
+ */
+export function confGet(ctx, h, key) {
+  return h.envValue(ctx.wizardConf, key);
+}
+
+/**
+ * The stored value for `key`, but only when wizard.conf was written for the same backend.
+ */
+export function storedOr(ctx, h, backend, key, fallback) {
+  if (confGet(ctx, h, "MEMORY_BACKEND") !== backend) return fallback;
+  return confGet(ctx, h, key) || fallback;
+}
+
+/** PM_BACKEND, then the saved MEMORY_BACKEND, then lemond. */
+export function backendDefault(ctx, h) {
+  const pm = process.env.PM_BACKEND;
+  if (BACKENDS.includes(pm)) return pm;
+  const saved = confGet(ctx, h, "MEMORY_BACKEND");
+  if (BACKENDS.includes(saved)) return saved;
+  return "lemond";
+}

package/providers/hindsight/lib/summary.mjs

@@ -0,0 +1,43 @@
+/** Hindsight's contribution to the wizard's closing summary. */
+import fs from "node:fs";
+import { composeCommandText } from "../../../wizard/lib/compose.mjs";
+import { 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 modelWhere =
+    ctx.backend === "ollama" && ctx.ollamaInCompose
+      ? "compose Ollama (profile ollama)"
+      : "the LiteLLM proxy (internal network)";
+  const running = [
+    `  Hindsight API      ${ctx.hindsightUrl}  (docs: ${ctx.hindsightUrl}/docs)`,
+    `  control plane      http://127.0.0.1:${ctx.portCp}`,
+    `  model              ${ctx.backend}, ${ctx.model} via ${modelWhere}`,
+  ];
+  if (ctx.ollamaInCompose) {
+    running.push(`  Ollama            http://127.0.0.1:11434 (compose service; LiteLLM uses http://ollama:11434)`);
+  }
+  const configFiles = [`  ${ctx.envFile}`];
+  if (fs.existsSync(ctx.litellmOverride)) {
+    configFiles.push(`  ${ctx.litellmOverride} (model routes; replaces config/litellm.*.yaml)`);
+  } else if (ctx.backend === "custom") {
+    configFiles.push(`  ${ctx.litellmOverride} (missing: custom backend needs it)`);
+  } else configFiles.push(`  config/litellm.${ctx.backend}.yaml (shipped routes)`);
+  const litellmUp = composeCommandText(ctx, "up", "-d", "litellm");
+  const notes = [
+    `Control plane (banks, ops, LLM queue): http://127.0.0.1:${ctx.portCp}`,
+    `Reflect needs a capable model (memory-reflect alias). On a weak or remote LLM, edit ${ctx.litellmOverride} and point memory-reflect at Meridian, an OpenAI-compatible host, or a stronger local model — then: ${litellmUp}`,
+    `Change later: rerun ./setup. For a route-only edit, run: ${litellmUp}`,
+  ];
+  if (ctx.smokeFailed) {
+    notes.unshift(
+      `Smoke retain/recall did not finish — stack is up; fix the model/LLM queue via http://127.0.0.1:${ctx.portCp} then re-run setup or: curl the wizard-smoke retain against ${ctx.hindsightUrl}`,
+    );
+  }
+  return { running, configFiles, notes, logServices: ["hindsight", "litellm"] };
+}

package/providers/hindsight/lib/validate.mjs

@@ -0,0 +1,75 @@
+/**
+ * Hindsight checks that run after the meta wizard's provider-neutral validation:
+ * wizard.conf backend keys, hindsight.env, litellm.env, the LiteLLM wiring, the stack
+ * .env's Hindsight keys, and a model override for a non-shipped model.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ensureState } from "./state.mjs";
+
+/** @typedef {import("../../../wizard/lib/provider-wizard/helpers.mjs").ProviderWizardHelpers} Helpers */
+
+/**
+ * Appends to ctx.validationErrors and ctx.validationChecks.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export function validateHindsight(ctx, h) {
+  ensureState(ctx);
+  const errors = (ctx.validationErrors ||= []);
+  const checks = (ctx.validationChecks ||= []);
+  const conf = (key) => h.envValue(ctx.wizardConf, key);
+
+  if (fs.existsSync(ctx.wizardConf)) {
+    for (const key of ["MEMORY_BACKEND", "MEMORY_MODEL"]) {
+      if (!conf(key)) errors.push(`wizard.conf missing ${key}`);
+      else checks.push(`wizard.conf ${key} set`);
+    }
+  }
+
+  if (!fs.existsSync(ctx.envFile)) errors.push(`missing ${ctx.envFile}`);
+  else {
+    if (fs.statSync(ctx.envFile).mode & 0o077) {
+      errors.push(`${ctx.envFile} must not be world/group readable (want mode 600)`);
+    }
+    checks.push("hindsight.env present");
+  }
+
+  if (!fs.existsSync(ctx.litellmEnv)) errors.push(`missing ${ctx.litellmEnv}`);
+  else {
+    if (fs.statSync(ctx.litellmEnv).mode & 0o077) {
+      errors.push(`${ctx.litellmEnv} must not be world/group readable (want mode 600)`);
+    }
+    if (!h.envValue(ctx.litellmEnv, "LITELLM_MASTER_KEY")) {
+      errors.push("litellm.env missing LITELLM_MASTER_KEY");
+    }
+    checks.push("litellm.env present");
+  }
+
+  const stackEnv = path.join(ctx.repoRoot, ".env");
+  if (fs.existsSync(stackEnv)) {
+    for (const key of ["LITELLM_CONFIG", "HINDSIGHT_PORT"]) {
+      if (!h.envValue(stackEnv, key)) errors.push(`repo .env missing ${key}`);
+    }
+    checks.push("repo .env ports and litellm config");
+  }
+
+  const llmBase = h.envValue(ctx.envFile, "HINDSIGHT_API_LLM_BASE_URL");
+  const llmKey = h.envValue(ctx.envFile, "HINDSIGHT_API_LLM_API_KEY");
+  const master = h.envValue(ctx.litellmEnv, "LITELLM_MASTER_KEY");
+  if (llmBase !== "http://litellm:4000/v1") {
+    errors.push("hindsight.env not wired to LiteLLM proxy (HINDSIGHT_API_LLM_BASE_URL)");
+  }
+  if (!llmKey || !master || llmKey !== master) {
+    errors.push("hindsight.env LLM API key must match LITELLM_MASTER_KEY");
+  }
+  checks.push("LiteLLM proxy wiring");
+
+  const backend = conf("MEMORY_BACKEND");
+  const model = conf("MEMORY_MODEL");
+  const shipped = backend === "ollama" ? ctx.ollamaDefaultModel : ctx.lemondDefaultModel;
+  const reflect = conf("MEMORY_REFLECT_MODEL");
+  if (backend !== "custom" && model !== shipped && !reflect && !fs.existsSync(ctx.litellmOverride)) {
+    errors.push("custom model without litellm.yaml override");
+  }
+}

package/providers/hindsight/manifest.json

@@ -0,0 +1,58 @@
+{
+  "id": "hindsight",
+  "label": "Hindsight",
+  "status": "supported",
+  "compose": {
+    "services": ["litellm", "hindsight", "indexer"],
+    "healthService": "hindsight",
+    "healthPath": "/health",
+    "hostPortEnv": "HINDSIGHT_PORT",
+    "defaultHostPort": 8888,
+    "logServices": ["hindsight", "litellm"],
+    "profile": "hindsight",
+    "files": []
+  },
+  "indexer": {
+    "apiUrlEnv": "HINDSIGHT_URL",
+    "sink": "hindsight",
+    "sinkDriver": "hindsight-rest-v1"
+  },
+  "codingAgent": {
+    "pluginPackage": "@vectorize-io/hindsight-coding-agents",
+    "configTemplate": "config/coding-agent.json"
+  },
+  "settings": {
+    "nativeDocs": "https://github.com/vectorize-io/hindsight",
+    "nativeConfigPaths": [
+      "~/.config/hindsight/hindsight.env",
+      "~/.config/hindsight/litellm.yaml",
+      "config/litellm.lemond.yaml"
+    ],
+    "wizardOwns": [
+      "compose stack and ports",
+      "index.yml sources",
+      "LiteLLM proxy wiring for Hindsight LLM aliases",
+      "coding-agent.json symlink"
+    ]
+  },
+  "wizardHooks": {
+    "module": "wizard.mjs",
+    "delegates": {}
+  },
+  "wizard": {
+    "smokeBank": "wizard-smoke",
+    "retainMethod": "POST",
+    "retainPath": "/v1/default/banks/{bank}/memories",
+    "retainBody": "{\"items\":[{\"content\":\"Wizard smoke test: the project codename is heron.\"}],\"async\":false}",
+    "recallMethod": "POST",
+    "recallPath": "/v1/default/banks/{bank}/memories/recall",
+    "recallBody": "{\"query\":\"What is the project codename?\"}",
+    "recallMustMatch": "heron",
+    "smokeRetainTimeoutSec": 90,
+    "smokeRecallTimeoutSec": 60,
+    "retainHint": "Open {controlPlane} (ops queue) and {api}/docs. LLM is shared (one retain at a time): cancel other banks' pending retains, or stop coding-agent/NotebookLM sync while smoking. If Ollama shows size_vram=0 it is on CPU — use GPU/ROCm or a faster model in ~/.config/hindsight/litellm.yaml, then: {compose} up -d litellm. Logs: {logs}",
+    "recallHint": "Open {controlPlane}; check memory-retain/reflect routes ({compose} logs litellm). Logs: {logs}",
+    "deleteMethod": "DELETE",
+    "deletePath": "/v1/default/banks/{bank}"
+  }
+}

package/providers/hindsight/wizard.mjs

@@ -0,0 +1,149 @@
+/**
+ * Hindsight sub-wizard (hook API v2). Owns everything Hindsight-specific that the meta
+ * wizard used to do inline: the lemond / Ollama / custom model flow and LiteLLM routes,
+ * hindsight.env and litellm.env, the HINDSIGHT_PORT / HINDSIGHT_CP_PORT pair, Hindsight
+ * validation, and the summary lines. 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 { applyConfigEnv, configToml as buildConfigToml } from "./lib/config.mjs";
+import { setupCodingAgent as linkCodingAgent } from "./lib/coding-agent.mjs";
+import { clackSetup as askInClack } from "./lib/clack.mjs";
+import { setupEnv as setupHindsightEnv, stackEnv as hindsightStackEnv } from "./lib/env-setup.mjs";
+import { chooseModelBackend } from "./lib/model-backend.mjs";
+import { ensureComposeOllamaModels } from "./lib/ollama-compose.mjs";
+import { resolvePorts as resolveHindsightPorts } from "./lib/ports.mjs";
+import { backendDefault, confGet, ensureState } from "./lib/state.mjs";
+import { summary as hindsightSummary } from "./lib/summary.mjs";
+import { validateHindsight } from "./lib/validate.mjs";
+
+// Called by scripts/setup.mjs (the stack .env writer), not by the wizard.
+export { migrateEnv, prepareStackEnv, setupNotices } from "./lib/stack-env.mjs";
+
+/** @typedef {import('../../wizard/lib/provider-wizard/helpers.mjs').ProviderWizardHelpers} Helpers */
+
+/**
+ * Quiet: fill Hindsight's context fields, map [stack]/[model] TOML defaults into the
+ * environment (including LEMOND_BASE from [model].lemond.host).
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function init(ctx, h) {
+  ensureState(ctx);
+  applyConfigEnv(ctx.pmMerged || {});
+  if (process.env.LEMOND_BASE) ctx.lemondBase = process.env.LEMOND_BASE;
+}
+
+/**
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function afterProvider(ctx, h) {
+  h.info("Hindsight uses LiteLLM aliases (memory-retain / reflect / consolidate).");
+}
+
+/**
+ * Step "3. Model backend": lemond, Ollama or a custom OpenAI-compatible URL behind the
+ * LiteLLM proxy.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function configureModelRouting(ctx, h) {
+  await chooseModelBackend(ctx, h);
+}
+
+/** Hindsight's API and control-plane ports. */
+export const resolvePorts = resolveHindsightPorts;
+
+/**
+ * Quiet: description and environment for the stack setup script (scripts/setup.mjs).
+ * @param {Record<string, any>} ctx
+ */
+export function stackEnv(ctx) {
+  return hindsightStackEnv(ctx);
+}
+
+/** hindsight.env, litellm.env wiring. */
+export const setupEnv = setupHindsightEnv;
+
+/**
+ * Quiet: reload the model choice from wizard.conf for `--up`.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function hydrate(ctx, h) {
+  ensureState(ctx);
+  ctx.backend = confGet(ctx, h, "MEMORY_BACKEND") || backendDefault(ctx, h);
+  ctx.model = confGet(ctx, h, "MEMORY_MODEL") || ctx.lemondDefaultModel;
+  ctx.apiBase = confGet(ctx, h, "MEMORY_API_BASE") || "";
+  ctx.reflectModel = confGet(ctx, h, "MEMORY_REFLECT_MODEL") || "";
+  ctx.ollamaInCompose = confGet(ctx, h, "MEMORY_OLLAMA_IN_COMPOSE") === "1";
+  applyComposeProfiles(ctx);
+}
+
+/**
+ * Ensure compose profile `ollama` is on the up command when MEMORY_OLLAMA_IN_COMPOSE=1.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} _h
+ */
+export async function beforeStack(ctx, _h) {
+  ensureState(ctx);
+  applyComposeProfiles(ctx);
+}
+
+/**
+ * Pull models into compose Ollama after the stack is up (host has no ollama CLI).
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function afterStackHealthy(ctx, h) {
+  await ensureComposeOllamaModels(ctx, h);
+}
+
+/** @param {Record<string, any>} ctx */
+function applyComposeProfiles(ctx) {
+  const extra = [...(ctx.extraComposeProfiles || [])];
+  if (ctx.ollamaInCompose && !extra.includes("ollama")) extra.push("ollama");
+  ctx.extraComposeProfiles = extra;
+}
+
+/**
+ * Quiet: tables merged into config.toml.
+ * @param {Record<string, any>} ctx
+ */
+export function configToml(ctx) {
+  ensureState(ctx);
+  return buildConfigToml(ctx);
+}
+
+/**
+ * Quiet: lines for the closing summary.
+ * @param {Record<string, any>} ctx
+ */
+export function summary(ctx) {
+  return hindsightSummary(ctx);
+}
+
+/**
+ * Appends to ctx.validationErrors / ctx.validationChecks after the shared checks.
+ * @param {Record<string, any>} ctx
+ * @param {Helpers} h
+ */
+export async function extendValidation(ctx, h) {
+  validateHindsight(ctx, h);
+}
+
+/** Link ~/.hindsight/coding-agent.json and check optInPaths. */
+export const setupCodingAgent = linkCodingAgent;
+
+/**
+ * Clack-only: ask the model questions, return the environment that makes the wizard
+ * skip its own (see WIZARD_SKIP_BACKEND_STEP).
+ * @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);
+}

package/providers/letta/manifest.json

@@ -0,0 +1,29 @@
+{
+  "id": "letta",
+  "label": "Letta",
+  "status": "planned",
+  "notes": "Placeholder manifest. Letta (formerly MemGPT) server integration is not wired; track via issues before changing status.",
+  "settings": {
+    "nativeDocs": "https://docs.letta.com/",
+    "nativeConfigPaths": [],
+    "wizardOwns": []
+  },
+  "compose": {
+    "profile": "letta",
+    "files": [],
+    "services": [],
+    "healthService": null,
+    "healthPath": null,
+    "hostPortEnv": null,
+    "defaultHostPort": null
+  },
+  "indexer": {
+    "apiUrlEnv": "LETTA_API_URL",
+    "sink": "letta"
+  },
+  "codingAgent": {
+    "pluginPackage": null,
+    "configTemplate": null
+  },
+  "wizard": {}
+}