@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/cli/mcp/context.mjs

@@ -0,0 +1,61 @@
+import path from "node:path";
+import { envValue } from "../../wizard/lib/paths.mjs";
+import { resolveMemoryProvider } from "../install-memory-mcp.mjs";
+import { resolveMem0ApiUrl, resolveMem0EnvFilePath } from "../../providers/mem0/lib/mcp-install.mjs";
+import { resolveCogneeApiUrl } from "../../providers/cognee/lib/cognee-mcp-install.mjs";
+import { readKey } from "../../providers/mem0/lib/env-file.mjs";
+
+const DEFAULT_HINDSIGHT_PORT = 8888;
+
+/**
+ * @param {{ home: string, stackRoot: string, env?: NodeJS.ProcessEnv }} opts
+ */
+export function resolveHindsightApiUrl({ home, stackRoot, env = process.env }) {
+  const candidates = [
+    env.HINDSIGHT_URL,
+    env.PM_HINDSIGHT_URL,
+    envValue(path.join(stackRoot, ".env"), "HINDSIGHT_URL"),
+    envValue(path.join(home, ".config/hindsight/wizard.conf"), "HINDSIGHT_URL"),
+  ];
+  const url = candidates.map((v) => String(v || "").trim()).find(Boolean);
+  if (url) return url.replace(/\/+$/, "");
+  const portCandidates = [
+    env.HINDSIGHT_PORT,
+    envValue(path.join(stackRoot, ".env"), "HINDSIGHT_PORT"),
+    envValue(path.join(home, ".config/hindsight/wizard.conf"), "HINDSIGHT_PORT"),
+  ];
+  const port = portCandidates.map((v) => String(v || "").trim()).find(Boolean) || String(DEFAULT_HINDSIGHT_PORT);
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * @param {{ home: string, stackRoot: string, repoRoot: string, env?: NodeJS.ProcessEnv }} opts
+ */
+export function resolveMcpContext(opts) {
+  const env = opts.env || process.env;
+  const home = opts.home;
+  const stackRoot = opts.stackRoot;
+  const provider = resolveMemoryProvider(home, env);
+  /** @type {{ provider: string, hindsightUrl?: string, mem0?: { baseUrl: string, apiKey?: string }, cognee?: { baseUrl: string, apiKey?: string } }} */
+  const ctx = { provider };
+  if (provider === "hindsight") {
+    ctx.hindsightUrl = resolveHindsightApiUrl({ home, stackRoot, env });
+  } else if (provider === "mem0") {
+    const baseUrl = resolveMem0ApiUrl({ home, stackRoot, env });
+    const envFile = resolveMem0EnvFilePath({ home, stackRoot, env });
+    let apiKey = String(env.MEM0_API_KEY || "").trim();
+    if (!apiKey) {
+      try {
+        apiKey = readKey(envFile) || "";
+      } catch {
+        apiKey = "";
+      }
+    }
+    ctx.mem0 = { baseUrl, apiKey: apiKey || undefined };
+  } else if (provider === "cognee") {
+    const baseUrl = resolveCogneeApiUrl({ home, stackRoot, repoRoot: opts.repoRoot, env });
+    const apiKey = String(env.COGNEE_API_KEY || "").trim() || undefined;
+    ctx.cognee = { baseUrl, apiKey };
+  }
+  return ctx;
+}

package/cli/mcp/export/cognee-dataset-name.mjs

@@ -0,0 +1,12 @@
+import crypto from "node:crypto";
+
+const SLUG_MAX = 40;
+
+/** Match `indexer/sinks/cognee.py` `dataset_name(bank)`. */
+export function cogneeDatasetName(bank) {
+  const raw = String(bank ?? "");
+  let slug = raw.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  slug = slug.slice(0, SLUG_MAX).replace(/^_+|_+$/g, "") || "bank";
+  const hash = crypto.createHash("sha256").update(raw).digest("hex").slice(0, 8);
+  return `${slug}_${hash}`;
+}

package/cli/mcp/export/cognee.mjs

@@ -0,0 +1,119 @@
+import { authHeaders } from "../../cognee-mcp.mjs";
+import { cogneeDatasetName } from "./cognee-dataset-name.mjs";
+
+const PAGE = 1000;
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function trimString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {string}
+ */
+function textFromRawData(raw) {
+  if (typeof raw === "string") return raw.trim();
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    return textFromRecord(raw);
+  }
+  return "";
+}
+
+/**
+ * Read `text`, `content`, or nested `raw_data` / `rawData` from a plain object.
+ * @param {unknown} obj
+ * @returns {string}
+ */
+function textFromRecord(obj) {
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return "";
+  const rec = /** @type {Record<string, unknown>} */ (obj);
+  for (const key of ["text", "content"]) {
+    const s = trimString(rec[key]);
+    if (s) return s;
+  }
+  const fromRaw = textFromRawData(rec.raw_data ?? rec.rawData);
+  if (fromRaw) return fromRaw;
+  return "";
+}
+
+/**
+ * Prefer full document bytes/text from a Cognee dataset data row over label-only fields.
+ * @param {Record<string, unknown>} item
+ * @returns {string}
+ */
+export function cogneeDataItemContent(item) {
+  const fromItem = textFromRecord(item);
+  if (fromItem) return fromItem;
+  const fromDoc = textFromRecord(item.document ?? item.doc);
+  if (fromDoc) return fromDoc;
+  return trimString(item.label) || trimString(item.name) || "";
+}
+
+/**
+ * @param {{ cognee?: { baseUrl: string, apiKey?: string } }} ctx
+ * @param {{ bank?: string }} args
+ * @param {typeof fetch} fetchFn
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export async function exportCognee(ctx, args, fetchFn, env = process.env) {
+  const base = ctx.cognee?.baseUrl?.replace(/\/+$/, "");
+  if (!base) throw new Error("Cognee API URL not configured");
+  const headers = { ...authHeaders(env) };
+  const bank = String(args.bank || "openmem-mcp").trim() || "openmem-mcp";
+  const datasetName = cogneeDatasetName(bank);
+
+  const listRes = await fetchFn(`${base}/api/v1/datasets`, { headers });
+  const listText = await listRes.text();
+  if (!listRes.ok) throw new Error(`GET /api/v1/datasets → ${listRes.status}: ${listText.slice(0, 400)}`);
+  let datasets;
+  try {
+    datasets = listText ? JSON.parse(listText) : [];
+  } catch {
+    throw new Error("GET /api/v1/datasets: invalid JSON");
+  }
+  const row = (Array.isArray(datasets) ? datasets : []).find(
+    (d) => d && typeof d === "object" && d.name === datasetName && d.id,
+  );
+  if (!row) {
+    return {
+      scope: { bank, dataset: datasetName },
+      records: [],
+      note: `No Cognee dataset named ${datasetName}; indexer may not have written to this bank yet.`,
+    };
+  }
+  const datasetId = String(row.id);
+  /** @type {object[]} */
+  const records = [];
+  let offset = 0;
+  while (true) {
+    const url = `${base}/api/v1/datasets/${encodeURIComponent(datasetId)}/data?limit=${PAGE}&offset=${offset}`;
+    const res = await fetchFn(url, { headers });
+    const text = await res.text();
+    if (!res.ok) throw new Error(`GET dataset data → ${res.status}: ${text.slice(0, 400)}`);
+    let page;
+    try {
+      page = text ? JSON.parse(text) : [];
+    } catch {
+      throw new Error("GET dataset data: invalid JSON");
+    }
+    if (!Array.isArray(page)) break;
+    for (const item of page) {
+      if (!item || typeof item !== "object") continue;
+      const meta = item.externalMetadata ?? item.external_metadata ?? {};
+      const body = cogneeDataItemContent(item);
+      records.push({
+        id: item.id != null ? String(item.id) : null,
+        content: body || `[cognee:${item.name || item.id}]`,
+        metadata: { cognee: { name: item.name ?? null, externalMetadata: meta } },
+        scope_key: bank,
+      });
+    }
+    if (page.length < PAGE) break;
+    offset += page.length;
+  }
+  return { scope: { bank, dataset: datasetName, dataset_id: datasetId }, records };
+}

package/cli/mcp/export/hindsight.mjs

@@ -0,0 +1,48 @@
+import { listBanks, listMemories } from "../../notebooklm-mcp.mjs";
+
+const PAGE = 500;
+
+/**
+ * @param {{ hindsightUrl?: string }} ctx
+ * @param {{ bank?: string }} args
+ * @param {typeof fetch} fetchFn
+ */
+export async function exportHindsight(ctx, args, fetchFn) {
+  const base = ctx.hindsightUrl;
+  if (!base) throw new Error("Hindsight API URL not configured");
+  const bankFilter = String(args.bank || "").trim();
+  const bankRows = await listBanks(base, fetchFn);
+  const bankIds = bankRows
+    .map((b) => b.bank_id || b.id || b.name || "")
+    .filter(Boolean);
+  const banks = bankFilter ? bankIds.filter((id) => id === bankFilter) : bankIds;
+  if (bankFilter && !banks.length) {
+    throw new Error(`bank not found: ${bankFilter}`);
+  }
+  /** @type {object[]} */
+  const records = [];
+  for (const bank of banks) {
+    let offset = 0;
+    while (true) {
+      const page = await listMemories(base, bank, "", { limit: PAGE, offset }, fetchFn);
+      const items = Array.isArray(page?.items) ? page.items : [];
+      for (const m of items) {
+        const content = String(m.text ?? m.content ?? "").trim();
+        if (!content) continue;
+        records.push({
+          id: m.id ?? m.memory_id ?? null,
+          content,
+          metadata: { type: m.type ?? null, ...(m.metadata && typeof m.metadata === "object" ? m.metadata : {}) },
+          scope_key: bank,
+        });
+      }
+      const total = Number.isFinite(page?.total) ? page.total : items.length;
+      offset += items.length;
+      if (!items.length || items.length < PAGE || offset >= total) break;
+    }
+  }
+  return {
+    scope: bankFilter ? { bank: bankFilter } : { all_banks: true, bank_count: banks.length },
+    records,
+  };
+}

package/cli/mcp/export/index.mjs

@@ -0,0 +1,26 @@
+/** Provider PMM export adapters (orchestrator: cli/mcp/portability.mjs). */
+
+import { exportCognee } from "./cognee.mjs";
+import { exportHindsight } from "./hindsight.mjs";
+import { exportMem0 } from "./mem0.mjs";
+
+export { exportHindsight } from "./hindsight.mjs";
+export { exportMem0 } from "./mem0.mjs";
+export { exportCognee } from "./cognee.mjs";
+export { cogneeDatasetName } from "./cognee-dataset-name.mjs";
+
+/**
+ * @param {string} provider
+ * @param {Record<string, unknown>} ctx
+ * @param {Record<string, unknown>} args
+ * @param {typeof fetch} fetchFn
+ */
+export async function runProviderExport(provider, ctx, args, fetchFn) {
+  if (provider === "mem0") {
+    const scopeBank = String(args.bank || "openmem-mcp").trim() || "openmem-mcp";
+    return exportMem0(ctx, { user_id: scopeBank }, fetchFn);
+  }
+  if (provider === "hindsight") return exportHindsight(ctx, args, fetchFn);
+  if (provider === "cognee") return exportCognee(ctx, args, fetchFn);
+  throw new Error(`export not supported for provider ${provider}`);
+}

package/cli/mcp/export/mem0.mjs

@@ -0,0 +1,31 @@
+/**
+ * @param {{ mem0?: { baseUrl: string, apiKey?: string } }} ctx
+ * @param {{ user_id: string }} scope
+ * @param {typeof fetch} fetchFn
+ */
+export async function exportMem0(ctx, scope, fetchFn) {
+  const base = ctx.mem0?.baseUrl;
+  const key = ctx.mem0?.apiKey;
+  if (!base) throw new Error("mem0 API URL not configured");
+  /** @type {Record<string, string>} */
+  const headers = {};
+  if (key) headers["X-API-Key"] = key;
+  const q = new URLSearchParams({ user_id: scope.user_id, top_k: "1000" });
+  const res = await fetchFn(`${base}/memories?${q}`, { headers });
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+    throw new Error(`GET /memories → ${res.status}: ${text.slice(0, 200)}`);
+  }
+  if (!res.ok) throw new Error(`GET /memories → ${res.status}: ${text.slice(0, 400)}`);
+  const raw = Array.isArray(json) ? json : json.results || json.memories || [];
+  const records = raw.map((row) => ({
+    id: row.id ?? row.memory_id ?? null,
+    content: row.memory ?? row.text ?? row.content ?? JSON.stringify(row),
+    metadata: row.metadata ?? {},
+    scope_key: scope.user_id,
+  }));
+  return { scope, records };
+}

package/cli/mcp/knowledge.mjs

@@ -0,0 +1,333 @@
+/**
+ * Provider-neutral knowledge tools: pages, initiatives, ingest status.
+ * Hindsight is the reference implementation (knowledge-base + operations API); other providers
+ * answer "unsupported" from PROVIDER_CAPABILITIES so prompts keep working across `switch`.
+ */
+
+import { providerSupports } from "../coding-agent/capabilities.mjs";
+
+const DEFAULT_BANK = "openmem-mcp";
+const PAGE_MAX_TOKENS = 4096;
+const PAGE_SEARCH_LIMIT = 5;
+const INITIATIVES_FOLDER = "Initiatives";
+const INITIATIVE_TAG = "knowledge:feature-work";
+const ACTIVE_STATUSES = ["pending", "processing"];
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled", "error"]);
+const CODING_AGENT_PREFIX = "coding-agent::";
+
+const BANK_PROP = {
+  type: "string",
+  description: "Hindsight bank (use memory_project_scope for the project bank; default openmem-mcp)",
+};
+
+export const KNOWLEDGE_MCP_TOOLS = [
+  {
+    name: "memory_pages_list",
+    title: "List knowledge pages",
+    description:
+      "List a bank's knowledge pages (ids, names, folders; no bodies). Hindsight only.",
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    inputSchema: { type: "object", properties: { bank: BANK_PROP }, additionalProperties: false },
+  },
+  {
+    name: "memory_pages_search",
+    title: "Search knowledge pages",
+    description:
+      "Search knowledge pages: past decisions and conventions. Check them before fixing a bug, changing a test or building something; " +
+      "verify claims against the code. Hindsight only.",
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "What you need to know" },
+        bank: BANK_PROP,
+        limit: { type: "number", description: "Max page hits (default 5)" },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "memory_pages_read",
+    title: "Read a knowledge page",
+    description:
+      "Read one knowledge page by id (from a page listing, search, or [[page:<id>]] link). Hindsight only.",
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        page_id: { type: "string", description: "Knowledge page id (kp-…)" },
+        bank: BANK_PROP,
+      },
+      required: ["page_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "memory_capture_initiative",
+    title: "Capture an initiative",
+    description:
+      "Record an approved feature plan as a knowledge page before writing code; relates_to_page_id records a plan change. " +
+      "Skip bug fixes and small tweaks. Hindsight only.",
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Short, specific initiative name (reuse it on updates)" },
+        summary: { type: "string", description: "Two or three sentences: what is being built and why, current intent" },
+        relates_to_page_id: { type: "string", description: "Existing initiative page id when recording a change" },
+        bank: BANK_PROP,
+      },
+      required: ["title", "summary"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "memory_status",
+    title: "Ingest status",
+    description:
+      "Report whether async ingest has drained (ready, active and failed counts, memory_add operation ids). " +
+      "Check before recalling just-stored content. Hindsight only; mem0 is always ready.",
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        bank: BANK_PROP,
+        operation_ids: { type: "array", items: { type: "string" }, description: "Operation ids to check" },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+export const KNOWLEDGE_TOOL_NAMES = new Set(KNOWLEDGE_MCP_TOOLS.map((t) => t.name));
+
+const TOOL_FEATURE = {
+  memory_pages_list: "knowledge_pages",
+  memory_pages_search: "knowledge_pages",
+  memory_pages_read: "knowledge_pages",
+  memory_capture_initiative: "initiatives",
+  memory_status: "ingest_status",
+};
+
+/** Scope clause appended to a page's source query (Hindsight coding-agent wording). */
+export function pageScopeRule(project) {
+  return (
+    ` Scope this page to ${project} ITSELF: the bank also holds facts about external tools, libraries and services that ${project} ` +
+    `merely uses, configures, deploys or discusses, and those belong to somebody else's codebase. Include something only when its ` +
+    `subject is ${project}'s own code, configuration or process; when it is about a dependency, leave it out however well-evidenced it ` +
+    `looks — including any commit SHA or identifier that belongs to that dependency's repository rather than this one.`
+  );
+}
+
+/** Hourly refresh at a minute derived from bank + page name, so pages do not all refresh at once. */
+export function initiativeTrigger(bank, name) {
+  let h = 0;
+  for (const ch of `${bank}\0${name}`) h = (h * 31 + ch.codePointAt(0)) >>> 0;
+  return { fact_types: ["world", "experience", "observation"], tags_match: "all", refresh_cron: `${h % 60} * * * *` };
+}
+
+export function slugify(s) {
+  return (
+    String(s)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 60) || "initiative"
+  );
+}
+
+function projectOf(bank) {
+  return bank.startsWith(CODING_AGENT_PREFIX) ? bank.slice(CODING_AGENT_PREFIX.length) : bank;
+}
+
+function unsupported(provider, name) {
+  return { provider, supported: false, tool: name, reason: `${provider} has no ${TOOL_FEATURE[name]} support in OpenMem` };
+}
+
+/**
+ * @param {string} url
+ * @param {RequestInit} init
+ * @param {typeof fetch} fetchFn
+ * @param {number[]} [allow] non-2xx statuses returned as { status } instead of thrown
+ */
+async function hsJson(url, init, fetchFn, allow = []) {
+  const res = await fetchFn(url, init);
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = text;
+  }
+  if (!res.ok) {
+    if (allow.includes(res.status)) return { status: res.status, json };
+    throw new Error(`${init.method || "GET"} ${url} → ${res.status}: ${String(typeof json === "string" ? json : JSON.stringify(json)).slice(0, 400)}`);
+  }
+  return { status: res.status ?? 200, json };
+}
+
+function flattenPages(nodes, folder, out = []) {
+  for (const n of nodes || []) {
+    if (!n?.id || !n?.name) continue;
+    if (n.kind === "page") {
+      out.push({ id: n.id, name: n.name, ...(n.description ? { description: n.description } : {}), ...(folder ? { folder } : {}) });
+    }
+    if (n.children?.length) flattenPages(n.children, n.kind === "folder" ? n.name : folder, out);
+  }
+  return out;
+}
+
+async function ensureFolder(bankUrl, name, fetchFn) {
+  const tree = await hsJson(`${bankUrl}/knowledge-base/tree`, { method: "GET" }, fetchFn);
+  const hit = (tree.json?.roots || []).find((n) => n.kind === "folder" && String(n.name || "").toLowerCase() === name.toLowerCase());
+  if (hit?.id) return hit.id;
+  const created = await hsJson(
+    `${bankUrl}/knowledge-base/folders`,
+    { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ name }) },
+    fetchFn,
+  );
+  return created.json?.id;
+}
+
+async function countOps(bankUrl, status, fetchFn) {
+  const r = await hsJson(`${bankUrl}/operations?status=${status}&limit=1`, { method: "GET" }, fetchFn);
+  return Number(r.json?.total ?? r.json?.operations?.length ?? 0);
+}
+
+/**
+ * @param {ReturnType<import("./context.mjs").resolveMcpContext>} ctx
+ * @param {string} name
+ * @param {Record<string, unknown>} args
+ * @param {typeof fetch} fetchFn
+ */
+export async function callKnowledgeTool(ctx, name, args, fetchFn) {
+  if (ctx.provider === "mem0" && name === "memory_status") {
+    return { provider: "mem0", supported: true, ready: true, note: "mem0 ingest is synchronous (infer: false)" };
+  }
+  if (!providerSupports(ctx.provider, TOOL_FEATURE[name])) return unsupported(ctx.provider, name);
+  if (!ctx.hindsightUrl) throw new Error("Hindsight API URL not configured");
+
+  const bank = String(args.bank || DEFAULT_BANK).trim() || DEFAULT_BANK;
+  const bankUrl = `${ctx.hindsightUrl}/v1/default/banks/${encodeURIComponent(bank)}`;
+
+  if (name === "memory_pages_list") {
+    const r = await hsJson(`${bankUrl}/knowledge-base/tree`, { method: "GET" }, fetchFn, [404]);
+    return { provider: "hindsight", bank, pages: r.status === 404 ? [] : flattenPages(r.json?.roots) };
+  }
+  if (name === "memory_pages_search") {
+    const query = String(args.query || "").trim();
+    if (!query) throw new Error("query is required");
+    const limit = Number(args.limit) > 0 ? Number(args.limit) : PAGE_SEARCH_LIMIT;
+    const r = await hsJson(
+      `${bankUrl}/knowledge-base/search?q=${encodeURIComponent(query)}&limit=${limit}`,
+      { method: "GET" },
+      fetchFn,
+      [404],
+    );
+    const hits = r.status === 404 ? [] : (r.json?.results || []).map((x) => ({
+      id: x.id,
+      name: x.name,
+      snippet: x.snippet ?? "",
+      score: x.score ?? 0,
+    }));
+    return { provider: "hindsight", bank, query, hits };
+  }
+  if (name === "memory_pages_read") {
+    const pageId = String(args.page_id || "").trim();
+    if (!pageId) throw new Error("page_id is required");
+    const r = await hsJson(`${bankUrl}/knowledge-base/pages/${encodeURIComponent(pageId)}`, { method: "GET" }, fetchFn, [404]);
+    if (r.status === 404) throw new Error(`knowledge page not found: ${pageId}`);
+    const p = r.json || {};
+    const body = typeof p.body === "string" && p.body.trim() ? p.body : p.markdown;
+    return {
+      provider: "hindsight",
+      bank,
+      page: { id: p.id, name: p.name, ...(p.tags?.length ? { tags: p.tags } : {}), ...(p.timestamp ? { last_updated_at: p.timestamp } : {}), body },
+    };
+  }
+  if (name === "memory_capture_initiative") {
+    const title = String(args.title || "").trim();
+    const summary = String(args.summary || "").trim();
+    if (!title || !summary) throw new Error("title and summary are required");
+    const relatesTo = String(args.relates_to_page_id || "").trim();
+    let pageId = relatesTo;
+    if (!pageId) {
+      const folderId = await ensureFolder(bankUrl, INITIATIVES_FOLDER, fetchFn);
+      const r = await hsJson(
+        `${bankUrl}/knowledge-base/pages`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            name: title,
+            source_query:
+              `Summarize the "${title}" initiative: what is being built or changed and why, and its current state — drawn from the project's memory.` +
+              pageScopeRule(projectOf(bank)),
+            ...(folderId ? { parent_id: folderId } : {}),
+            tags: [INITIATIVE_TAG],
+            max_tokens: PAGE_MAX_TOKENS,
+            trigger: initiativeTrigger(bank, title),
+          }),
+        },
+        fetchFn,
+      );
+      pageId = String(r.json?.page_id || r.json?.id || "").trim();
+      if (!pageId) {
+        throw new Error(`Hindsight created no page id for initiative "${title}"; no marker retained. Check memory_pages_list before retrying.`);
+      }
+    }
+    const verb = relatesTo ? "Update to an existing initiative" : "New initiative";
+    const retained = await hsJson(
+      `${bankUrl}/memories`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          async: true,
+          items: [
+            {
+              content: `${verb}: ${title}. ${summary}`,
+              context: `initiative marker for [[page:${pageId}]]`,
+              document_id: `initiative-marker-${slugify(pageId)}${relatesTo ? "-update" : ""}`,
+              tags: [INITIATIVE_TAG],
+              metadata: { relatedPageId: pageId },
+            },
+          ],
+        }),
+      },
+      fetchFn,
+    );
+    return { provider: "hindsight", bank, page_id: pageId, updated: Boolean(relatesTo), operation_id: retained.json?.operation_id ?? null };
+  }
+  if (name === "memory_status") {
+    const [pending, processing, failed] = await Promise.all(
+      [...ACTIVE_STATUSES, "failed"].map((s) => countOps(bankUrl, s, fetchFn)),
+    );
+    const ids = Array.isArray(args.operation_ids) ? args.operation_ids.map(String).filter(Boolean) : [];
+    const operations = {};
+    for (const id of ids) {
+      const r = await hsJson(`${bankUrl}/operations/${encodeURIComponent(id)}`, { method: "GET" }, fetchFn, [404]);
+      operations[id] = r.status === 404 ? "not_found" : String(r.json?.status || "unknown").toLowerCase();
+    }
+    const statuses = Object.values(operations);
+    return {
+      provider: "hindsight",
+      bank,
+      supported: true,
+      active: pending + processing,
+      pending,
+      processing,
+      failed,
+      ...(ids.length
+        ? {
+            operations,
+            // ingested: every requested op completed; a failed or unknown op is never counted as stored.
+            ingested: statuses.every((s) => s === "completed"),
+          }
+        : {}),
+      ready: ids.length ? statuses.every((s) => TERMINAL_STATUSES.has(s)) : pending + processing === 0,
+    };
+  }
+  throw new Error(`unknown tool: ${name}`);
+}

package/cli/mcp/llm-synthesize.mjs

@@ -0,0 +1,50 @@
+import path from "node:path";
+import { envValue } from "../../wizard/lib/paths.mjs";
+
+/** OpenAI-compatible chat URL for cross-provider reflect synthesis (optional). */
+export function resolveLlmChatUrl({ home, stackRoot, env = process.env }) {
+  const direct = String(env.PM_LLM_URL || env.OPENAI_API_BASE || "").trim();
+  if (direct) return direct.replace(/\/+$/, "").replace(/\/v1$/, "") + (direct.includes("/v1") ? "" : "/v1");
+  const fromEnv = envValue(path.join(stackRoot, ".env"), "LITELLM_URL");
+  if (fromEnv) return fromEnv.replace(/\/+$/, "");
+  const port = envValue(path.join(stackRoot, ".env"), "LITELLM_PORT") || "4000";
+  return `http://127.0.0.1:${String(port).trim()}/v1`;
+}
+
+export function resolveLlmModel(env = process.env) {
+  return String(env.PM_LLM_MODEL || env.PM_REFLECT_MODEL || "memory-reflect").trim() || "memory-reflect";
+}
+
+export function resolveLlmApiKey(env = process.env) {
+  return String(env.PM_LLM_API_KEY || env.LITELLM_MASTER_KEY || env.OPENAI_API_KEY || "").trim();
+}
+
+/**
+ * @param {{ query: string, context: string, model?: string, baseUrl: string, apiKey?: string }} opts
+ * @param {typeof fetch} fetchFn
+ */
+export async function synthesizeReflectAnswer(opts, fetchFn = fetch) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const url = `${base}/chat/completions`;
+  const headers = { "content-type": "application/json" };
+  if (opts.apiKey) headers.authorization = `Bearer ${opts.apiKey}`;
+  const body = {
+    model: opts.model || resolveLlmModel(),
+    messages: [
+      {
+        role: "system",
+        content:
+          "Summarize the following memory search hits as concise session context for a coding agent. " +
+          "Do not invent facts not present in the hits.",
+      },
+      { role: "user", content: `Question: ${opts.query}\n\nMemory hits:\n${opts.context}` },
+    ],
+    max_tokens: 1024,
+    temperature: 0.2,
+  };
+  const res = await fetchFn(url, { method: "POST", headers, body: JSON.stringify(body) });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`LLM synthesize → ${res.status}: ${text.slice(0, 300)}`);
+  const json = JSON.parse(text);
+  return json?.choices?.[0]?.message?.content?.trim() || text;
+}