@agentprojectcontext/apx 1.25.0 → 1.27.2

package/src/core/memory/broker.js

@@ -0,0 +1,144 @@
+// Memory Broker (Pieza 4) — runs before each super-agent turn and assembles the
+// [MEMORIA RELEVANTE] block injected into the system prompt.
+//
+//   incoming message
+//     → embed it + RAG retriever (Pieza 2) → top-K relevant chunks
+//     → read the last N entries of memory.md
+//     → merge, dedupe, format as a [MEMORIA RELEVANTE] block
+//
+// Silent and bounded: the whole thing races an 800 ms budget. If RAG is slow
+// (Ollama lagging), the block still returns with whatever memory.md gave us —
+// it NEVER blocks the reply or throws into the request path.
+
+import fs from "node:fs";
+import { embedOne } from "./embeddings.js";
+import { SELF_MEMORY_PATH, parseSelfMemoryEntries } from "../agent/self-memory.js";
+
+const DEFAULT_BUDGET_MS = 800;
+const DEFAULT_TOP_K = 5;
+const BULLET_CAP = 160; // chars per bullet line
+const MIN_SCORE = { ollama: 0.35, tf: 0.08 }; // floor per embedder family
+
+function withTimeout(promise, ms, fallback) {
+  return new Promise((resolve) => {
+    let done = false;
+    const timer = setTimeout(() => {
+      if (!done) {
+        done = true;
+        resolve(fallback);
+      }
+    }, ms);
+    promise.then(
+      (v) => {
+        if (!done) {
+          done = true;
+          clearTimeout(timer);
+          resolve(v);
+        }
+      },
+      () => {
+        if (!done) {
+          done = true;
+          clearTimeout(timer);
+          resolve(fallback);
+        }
+      }
+    );
+  });
+}
+
+function dateOf(ts) {
+  return ts ? String(ts).slice(0, 10) : "";
+}
+
+function clean(text) {
+  return String(text || "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function trunc(text, n = BULLET_CAP) {
+  const t = clean(text);
+  return t.length > n ? t.slice(0, n - 1).trimEnd() + "…" : t;
+}
+
+// Last N entries of memory.md, newest first, as {date, channel, text}.
+function lastMemoryEntries(memoryPath, n) {
+  try {
+    const text = fs.readFileSync(memoryPath, "utf8");
+    const entries = parseSelfMemoryEntries(text);
+    return entries.slice(-n).reverse();
+  } catch {
+    return [];
+  }
+}
+
+function bulletFor({ date, channel, text }) {
+  const d = date ? `[${date}]` : "";
+  const c = channel && channel !== "memory" ? `[${channel}]` : channel === "memory" ? "[memory]" : "";
+  return `• ${d}${c} ${trunc(text)}`.replace(/\s+/g, " ").trim();
+}
+
+// Build the [MEMORIA RELEVANTE] block. Returns "" when there's nothing useful.
+//
+// opts: { store, config, memoryPath, budgetMs, topK, channel, embed }
+export async function buildMemoryBlock(message, opts = {}) {
+  const memoryPath = opts.memoryPath || SELF_MEMORY_PATH;
+  const budgetMs = opts.budgetMs || DEFAULT_BUDGET_MS;
+  const topK = opts.topK || DEFAULT_TOP_K;
+  const store = opts.store || null;
+  const query = clean(message);
+
+  // memory.md entries are read synchronously and always make the deadline.
+  const memEntries = lastMemoryEntries(memoryPath, 10);
+
+  // RAG retrieval is the slow part — race it against the budget.
+  let hits = [];
+  if (store && query) {
+    const rag = (async () => {
+      const { vector, embedder, dim } = await embedOne(query, opts.embed || {});
+      const family = embedder.startsWith("ollama") ? "ollama" : "tf";
+      const floor = MIN_SCORE[family] ?? 0;
+      const results = store.search(vector, { embedder, k: topK + 3 });
+      return results.filter((r) => r.score >= floor && (r.dim ?? dim) === dim);
+    })();
+    hits = await withTimeout(rag, budgetMs, []);
+  }
+
+  // Merge RAG hits + recent memory entries, dedupe by normalised text.
+  const seen = new Set();
+  const bullets = [];
+  const push = (entry) => {
+    const key = clean(entry.text).toLowerCase().slice(0, 80);
+    if (!key || seen.has(key)) return;
+    // Don't echo the user's own incoming message back at them.
+    if (key && query.toLowerCase().includes(key) && key.length > 30) return;
+    seen.add(key);
+    bullets.push(bulletFor(entry));
+  };
+
+  for (const h of hits.slice(0, topK)) {
+    push({
+      date: dateOf(h.ts),
+      channel: h.tag === "memory" ? "memory" : h.channel,
+      text: h.text.replace(/^\[tool result: [^\]]+\]\s*/, ""),
+    });
+  }
+  for (const e of memEntries) {
+    if (bullets.length >= topK + 5) break;
+    push({ date: e.date, channel: e.channel || "memory", text: e.text });
+  }
+
+  if (bullets.length === 0) return "";
+
+  return [
+    "# Memoria relevante (cross-channel)",
+    "Contexto recuperado de tu memoria y del historial de todos los canales. Tratá",
+    "como hechos conocidos; si arrancás una sesión nueva y algo de acá sigue abierto,",
+    "mencionalo naturalmente (\"ayer estuvimos con X, ¿seguimos?\") sin que te pregunten.",
+    "",
+    "[MEMORIA RELEVANTE]",
+    ...bullets,
+    "[/MEMORIA RELEVANTE]",
+  ].join("\n");
+}

package/src/core/memory/compactor.js

@@ -0,0 +1,186 @@
+// Progressive history compaction (Pieza 3).
+//
+// When a channel chat accumulates more than `maxTurns` (60) conversational
+// turns in the rolling window, the oldest turns beyond `keepRecent` (40) are
+// collapsed into a dense summary by a light LLM (ollama:gemma2 → haiku
+// fallback) and persisted as a `type:"compact"` record in the channel JSONL.
+//
+// The reader (getRecentChannelTurnsFromFs) then prepends that summary as a
+// [RESUMEN COMPACTADO] system turn and drops the raw turns it covers, keeping
+// the model context bounded while preserving decisions / tasks / tool results.
+//
+// This runs OUT of the reply hot path (fire-and-forget) — generating a summary
+// costs an LLM call, so the current turn uses whatever compact already exists
+// and the next turn benefits. Best-effort: any failure logs and returns.
+
+import fs from "node:fs";
+import path from "node:path";
+import { GLOBAL_MESSAGES_DIR } from "../config.js";
+import { parseDayJsonl, appendGlobalMessage } from "../messages-store.js";
+import { callEngine } from "../engines/index.js";
+
+const DEFAULT_MAX_TURNS = 60;
+const DEFAULT_KEEP_RECENT = 40;
+const COMPACT_MAX_TOKENS = 1000; // ~800-token target + headroom
+
+const COMPACT_SYSTEM =
+  "Compactás conversaciones para continuidad de contexto de un agente. " +
+  "Otro modelo va a leer esto para seguir el trabajo: sé denso y factual.";
+
+function compactPrompt(transcript) {
+  return (
+    "Compactá estos turnos en un resumen estructurado de máximo 800 tokens, " +
+    "preservando: decisiones tomadas, tareas asignadas, resultados de tools, y " +
+    "datos acordados. Sin saludos ni meta-comentarios. Sólo los hechos.\n\n" +
+    "---\n\n" +
+    transcript
+  );
+}
+
+export function resolveCompactModels(config = {}) {
+  const mem = config.memory || {};
+  // Primary: a light, local-endpoint model (Ollama, incl. *-cloud models served
+  // via localhost). Fallback: whatever the user configured, else the APX
+  // default super-agent model — never silently a paid service the user didn't
+  // pick. A blank fallback resolves to super_agent.model at call time.
+  return {
+    primary: mem.compact_model || "ollama:gemma4:31b-cloud",
+    fallback: mem.compact_fallback_model || config.super_agent?.model || "",
+  };
+}
+
+// Read every record for a chat in the rolling window, oldest first.
+function readChatRecords({ channel, chat_id, max_age_hours, messagesDir }) {
+  const cutoff = new Date(Date.now() - max_age_hours * 3600_000)
+    .toISOString()
+    .replace(/\.\d{3}Z$/, "Z");
+  const dir = path.join(messagesDir, channel);
+  if (!fs.existsSync(dir)) return [];
+  const all = [];
+  for (const f of fs.readdirSync(dir).sort()) {
+    if (!/^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)) continue;
+    let text;
+    try {
+      text = fs.readFileSync(path.join(dir, f), "utf8");
+    } catch {
+      continue;
+    }
+    for (const m of parseDayJsonl(text)) {
+      if (m.ts < cutoff) continue;
+      if (String(m.meta?.chat_id ?? "") !== String(chat_id)) continue;
+      all.push(m);
+    }
+  }
+  all.sort((a, b) => (a.ts || "").localeCompare(b.ts || ""));
+  return all;
+}
+
+function renderTurn(m) {
+  if (m.type === "tool") {
+    const name = m.meta?.tool_name || m.meta?.tool || "tool";
+    return `[TOOL ${name}]\n${String(m.body || "").slice(0, 600)}`;
+  }
+  const who = m.type === "user" ? "USER" : "ASSISTANT";
+  return `[${who}]\n${String(m.body || "")}`;
+}
+
+async function summarize({ transcript, models, config }) {
+  for (const modelId of [models.primary, models.fallback]) {
+    if (!modelId) continue;
+    try {
+      const r = await callEngine({
+        modelId,
+        system: COMPACT_SYSTEM,
+        messages: [{ role: "user", content: compactPrompt(transcript) }],
+        config,
+        maxTokens: COMPACT_MAX_TOKENS,
+        temperature: 0.2,
+      });
+      const text = String(r.text || "").trim();
+      if (text) return { text, model: modelId };
+    } catch {
+      /* try next model */
+    }
+  }
+  return null;
+}
+
+// Compact one channel chat if it's over threshold. Returns a small status obj.
+// opts: { channel, chat_id, config, log, maxTurns, keepRecent, max_age_hours,
+//         messagesDir }  (messagesDir overridable for tests)
+export async function compactChannelIfNeeded(opts = {}) {
+  const channel = opts.channel || "telegram";
+  const chat_id = opts.chat_id;
+  const config = opts.config || {};
+  const log = typeof opts.log === "function" ? opts.log : () => {};
+  const maxTurns = opts.maxTurns ?? config.memory?.compact_threshold ?? DEFAULT_MAX_TURNS;
+  const keepRecent = opts.keepRecent ?? config.memory?.keep_recent ?? DEFAULT_KEEP_RECENT;
+  const max_age_hours = opts.max_age_hours ?? 24;
+  const messagesDir = opts.messagesDir || GLOBAL_MESSAGES_DIR;
+  if (!chat_id) return { skipped: "no chat_id" };
+
+  const records = readChatRecords({ channel, chat_id, max_age_hours, messagesDir });
+
+  // Find the latest existing compact and what it already covers.
+  let prevCompact = null;
+  for (const m of records) if (m.type === "compact") prevCompact = m;
+  const coverUntil = prevCompact ? prevCompact.meta?.covers_until_ts || prevCompact.ts : "";
+  const prevCount = prevCompact ? prevCompact.meta?.count || 0 : 0;
+
+  // Conversational turns not yet covered by a compact.
+  const fresh = records.filter(
+    (m) =>
+      (m.type === "user" || m.type === "agent" || m.type === "tool") &&
+      (!coverUntil || m.ts > coverUntil)
+  );
+  const realTurns = fresh.filter((m) => m.type === "user" || m.type === "agent");
+  if (realTurns.length <= maxTurns) {
+    return { skipped: "below threshold", turns: realTurns.length };
+  }
+
+  // Compact the oldest turns, leaving the most recent `keepRecent` real turns
+  // verbatim. We compact everything (incl. interleaved tools) up to the ts of
+  // the (realTurns.length - keepRecent)-th real turn.
+  const boundaryReal = realTurns[realTurns.length - keepRecent - 1];
+  const boundaryTs = boundaryReal.ts;
+  const toCompact = fresh.filter((m) => m.ts <= boundaryTs);
+  const compactedReal = toCompact.filter((m) => m.type === "user" || m.type === "agent").length;
+  if (compactedReal === 0) return { skipped: "nothing to compact" };
+
+  let transcript = toCompact.map(renderTurn).join("\n\n");
+  if (prevCompact && String(prevCompact.body || "").trim()) {
+    transcript =
+      `[RESUMEN PREVIO]\n${String(prevCompact.body).trim()}\n\n---\n\n` + transcript;
+  }
+
+  const models = resolveCompactModels(config);
+  const summary = await summarize({ transcript, models, config });
+  if (!summary) {
+    log(`memory: compaction for ${channel}/${chat_id} skipped — no model available`);
+    return { skipped: "no model" };
+  }
+
+  const totalCovered = prevCount + compactedReal;
+  appendGlobalMessage({
+    channel,
+    direction: "out",
+    type: "compact",
+    actor_id: "compact",
+    actor_kind: "compact",
+    author: "compact",
+    body: summary.text,
+    meta: {
+      chat_id,
+      compact: true,
+      range: [1, totalCovered],
+      count: totalCovered,
+      covers_until_ts: boundaryTs,
+      compacted_turns: compactedReal,
+      model: summary.model,
+    },
+  });
+  log(
+    `memory: compacted ${compactedReal} turn(s) for ${channel}/${chat_id} via ${summary.model} (covers 1-${totalCovered})`
+  );
+  return { compacted: true, turns: compactedReal, covers: totalCovered, model: summary.model };
+}

package/src/core/memory/embed-engines/gemini.js

@@ -0,0 +1,62 @@
+// Google Gemini embeddings adapter (default: text-embedding-004, 768 dims).
+// Free tier available with a Gemini API key. Reuses engines.gemini.api_key.
+
+import { l2normalize } from "../embeddings.js";
+
+const DEFAULT_MODEL = "text-embedding-004";
+const BASE = "https://generativelanguage.googleapis.com/v1beta";
+
+function getKey(config = {}, parentEnginesCfg) {
+  return (
+    config.api_key ||
+    parentEnginesCfg?.gemini?.api_key ||
+    process.env.GEMINI_API_KEY ||
+    process.env.GOOGLE_API_KEY ||
+    ""
+  );
+}
+
+export default {
+  id: "gemini",
+
+  async isAvailable(config = {}, parentEnginesCfg) {
+    return Boolean(getKey(config, parentEnginesCfg));
+  },
+
+  async embed({ text, config = {}, parentEnginesCfg, timeoutMs = 8000, signal }) {
+    const key = getKey(config, parentEnginesCfg);
+    if (!key) throw new Error("gemini embeddings: no api_key");
+    const model = config.model || DEFAULT_MODEL;
+    const ctrl = new AbortController();
+    const onParentAbort = () => ctrl.abort();
+    if (signal) signal.addEventListener("abort", onParentAbort, { once: true });
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetch(
+        `${BASE}/models/${model}:embedContent?key=${encodeURIComponent(key)}`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            model: `models/${model}`,
+            content: { parts: [{ text }] },
+          }),
+          signal: ctrl.signal,
+        }
+      );
+      if (!res.ok) {
+        const err = await res.text().catch(() => "");
+        throw new Error(`gemini embeddings ${res.status}: ${err.slice(0, 200)}`);
+      }
+      const json = await res.json();
+      const vector = json?.embedding?.values;
+      if (!Array.isArray(vector) || vector.length === 0) {
+        throw new Error("gemini embeddings: empty vector");
+      }
+      return { vector: l2normalize(vector), embedder: `gemini:${model}`, dim: vector.length };
+    } finally {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onParentAbort);
+    }
+  },
+};

package/src/core/memory/embed-engines/index.js

@@ -0,0 +1,148 @@
+// Embeddings engine registry for the cross-channel memory RAG. Mirrors the TTS
+// engine selector at src/core/voice/engines/index.js so configuring an
+// embeddings provider feels identical to configuring TTS/STT.
+//
+// Config lives at config.memory.embeddings:
+//   provider: "auto" | "ollama" | "openai" | "gemini" | "tf"
+//   mode:     "chain" (ordered fallback router) | "single" (use provider verbatim)
+//   order:    custom chain order (ids); the rest of AUTO_PREFERENCE is appended
+//   <id>:     per-engine settings ({ model, api_key, base_url, timeout_ms })
+//
+// Two selection modes:
+//   "chain"  — walk the order, skip engines turned off (<id>.enabled === false),
+//              pick the first whose isAvailable() returns true. "tf" is always
+//              kept as the final guaranteed fallback.
+//   "single" — use exactly memory.embeddings.provider, no fallback.
+//
+// An explicit `provider` argument always wins (used by the "test embedding" UI).
+// Cosine similarity is only meaningful within one embedder space, so every
+// vector is tagged with its `embedder` and the store filters search() on it —
+// switching provider strands the old index until it is re-embedded.
+
+import ollama from "./ollama.js";
+import openai from "./openai.js";
+import gemini from "./gemini.js";
+import tf from "./tf.js";
+
+const ADAPTERS = { ollama, openai, gemini, tf };
+export const EMBED_ENGINE_IDS = Object.keys(ADAPTERS);
+
+// Local-first, then free-with-key, then paid, then offline fallback.
+export const AUTO_PREFERENCE = ["ollama", "gemini", "openai", "tf"];
+
+export function getEmbedAdapter(provider) {
+  const a = ADAPTERS[provider];
+  if (!a) {
+    throw new Error(
+      `unknown embeddings provider "${provider}". Known: ${EMBED_ENGINE_IDS.join(", ")}`
+    );
+  }
+  return a;
+}
+
+export function embeddingsConfig(globalConfig) {
+  const mem = globalConfig?.memory || {};
+  // Back-compat: older configs only had the flat memory.embed_* keys. Fold them
+  // into a synthetic ollama engine config so they keep working unchanged.
+  const section = mem.embeddings || {};
+  if (!section.ollama && (mem.embed_model || mem.embed_base_url || mem.embed_timeout_ms)) {
+    return {
+      provider: section.provider || "auto",
+      mode: section.mode,
+      order: section.order,
+      ...section,
+      ollama: {
+        model: mem.embed_model || "nomic-embed-text",
+        base_url: mem.embed_base_url || "",
+        timeout_ms: mem.embed_timeout_ms || 4000,
+      },
+    };
+  }
+  return section;
+}
+
+function providerConfig(globalConfig, provider) {
+  return embeddingsConfig(globalConfig)?.[provider] || {};
+}
+
+function isEnabled(embedCfg, id) {
+  return embedCfg?.[id]?.enabled !== false;
+}
+
+/** Effective routing mode for the chain/single decision. */
+export function resolveMode(embedCfg) {
+  if (embedCfg?.mode === "chain" || embedCfg?.mode === "single") return embedCfg.mode;
+  const p = embedCfg?.provider;
+  return p && p !== "auto" ? "single" : "chain";
+}
+
+/** Full chain order: user's custom order (known ids only) then the rest; tf last. */
+export function resolveChainOrder(embedCfg) {
+  const custom = Array.isArray(embedCfg?.order)
+    ? embedCfg.order.filter((id) => EMBED_ENGINE_IDS.includes(id))
+    : [];
+  const rest = AUTO_PREFERENCE.filter((id) => !custom.includes(id));
+  const full = [...custom, ...rest];
+  if (!full.includes("tf")) full.push("tf");
+  return full;
+}
+
+/**
+ * Resolve which embeddings engine should handle this call.
+ * Returns { provider, adapter, engineConfig }.
+ */
+export async function selectEmbedEngine({ globalConfig, provider }) {
+  const embedCfg = embeddingsConfig(globalConfig);
+
+  // 1. Explicit override (tester / API caller) always wins.
+  if (provider && provider !== "auto") {
+    const adapter = getEmbedAdapter(provider);
+    return { provider, adapter, engineConfig: providerConfig(globalConfig, provider) };
+  }
+
+  const mode = resolveMode(embedCfg);
+
+  // 2. Single mode: use the configured engine verbatim, no fallback.
+  if (mode === "single") {
+    const id = embedCfg?.provider;
+    if (id && id !== "auto") {
+      const adapter = getEmbedAdapter(id);
+      return { provider: id, adapter, engineConfig: providerConfig(globalConfig, id) };
+    }
+    // Misconfigured single mode → fall through to chain.
+  }
+
+  // 3. Chain mode: probe the (enabled) order, first available wins.
+  for (const id of resolveChainOrder(embedCfg)) {
+    if (id !== "tf" && !isEnabled(embedCfg, id)) continue;
+    const adapter = ADAPTERS[id];
+    const cfg = providerConfig(globalConfig, id);
+    try {
+      if (await adapter.isAvailable(cfg, globalConfig?.engines)) {
+        return { provider: id, adapter, engineConfig: cfg };
+      }
+    } catch { /* probe failures fall through */ }
+  }
+  return { provider: "tf", adapter: tf, engineConfig: providerConfig(globalConfig, "tf") };
+}
+
+/** Discover which engines are configured/available right now. */
+export async function listAvailableEmbedEngines(globalConfig) {
+  const embedCfg = embeddingsConfig(globalConfig);
+  const out = [];
+  for (const id of EMBED_ENGINE_IDS) {
+    const adapter = ADAPTERS[id];
+    const cfg = providerConfig(globalConfig, id);
+    let available = false;
+    try {
+      available = await adapter.isAvailable(cfg, globalConfig?.engines);
+    } catch { available = false; }
+    out.push({
+      id,
+      available,
+      configured: Object.keys(cfg).filter((k) => k !== "enabled").length > 0,
+      enabled: isEnabled(embedCfg, id),
+    });
+  }
+  return out;
+}

package/src/core/memory/embed-engines/ollama.js

@@ -0,0 +1,55 @@
+// Ollama embeddings adapter (default: nomic-embed-text). Local, no API key.
+// base_url falls back to config.engines.ollama.base_url, then env, then
+// localhost:11434 — the same endpoint that serves local + Ollama-cloud models.
+
+import { l2normalize } from "../embeddings.js";
+
+const DEFAULT_MODEL = "nomic-embed-text";
+
+function resolveBaseUrl(config = {}, parentEnginesCfg) {
+  const base =
+    config.base_url ||
+    parentEnginesCfg?.ollama?.base_url ||
+    process.env.APX_EMBED_URL ||
+    process.env.OLLAMA_HOST ||
+    "http://localhost:11434";
+  return String(base).replace(/\/$/, "");
+}
+
+export default {
+  id: "ollama",
+
+  // Local Ollama is "available" as a configured choice without probing a
+  // network round-trip here — the embed() call itself falls back to tf on any
+  // connection error, so the chain selector stays fast.
+  async isAvailable() {
+    return true;
+  },
+
+  async embed({ text, config = {}, parentEnginesCfg, timeoutMs = 4000, signal }) {
+    const model = config.model || DEFAULT_MODEL;
+    const base = resolveBaseUrl(config, parentEnginesCfg);
+    const ctrl = new AbortController();
+    const onParentAbort = () => ctrl.abort();
+    if (signal) signal.addEventListener("abort", onParentAbort, { once: true });
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${base}/api/embeddings`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ model, prompt: text }),
+        signal: ctrl.signal,
+      });
+      if (!res.ok) throw new Error(`ollama embeddings ${res.status}`);
+      const json = await res.json();
+      const vector = json.embedding;
+      if (!Array.isArray(vector) || vector.length === 0) {
+        throw new Error("ollama embeddings: empty vector");
+      }
+      return { vector: l2normalize(vector), embedder: `ollama:${model}`, dim: vector.length };
+    } finally {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onParentAbort);
+    }
+  },
+};

package/src/core/memory/embed-engines/openai.js

@@ -0,0 +1,64 @@
+// OpenAI embeddings adapter (default: text-embedding-3-small, 1536 dims).
+// Reuses engines.openai.api_key + base_url; per-section overrides live under
+// memory.embeddings.openai. Works with any OpenAI-compatible /embeddings
+// endpoint (OpenAI, OpenRouter, local LiteLLM) by overriding base_url.
+
+import { l2normalize } from "../embeddings.js";
+
+const DEFAULT_MODEL = "text-embedding-3-small";
+const DEFAULT_BASE = "https://api.openai.com/v1";
+
+function getKey(config = {}, parentEnginesCfg) {
+  return (
+    config.api_key ||
+    parentEnginesCfg?.openai?.api_key ||
+    process.env.OPENAI_API_KEY ||
+    ""
+  );
+}
+
+function getBase(config = {}, parentEnginesCfg) {
+  return String(
+    config.base_url || parentEnginesCfg?.openai?.base_url || DEFAULT_BASE
+  ).replace(/\/$/, "");
+}
+
+export default {
+  id: "openai",
+
+  async isAvailable(config = {}, parentEnginesCfg) {
+    return Boolean(getKey(config, parentEnginesCfg));
+  },
+
+  async embed({ text, config = {}, parentEnginesCfg, timeoutMs = 8000, signal }) {
+    const key = getKey(config, parentEnginesCfg);
+    if (!key) throw new Error("openai embeddings: no api_key");
+    const model = config.model || DEFAULT_MODEL;
+    const base = getBase(config, parentEnginesCfg);
+    const ctrl = new AbortController();
+    const onParentAbort = () => ctrl.abort();
+    if (signal) signal.addEventListener("abort", onParentAbort, { once: true });
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${base}/embeddings`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+        body: JSON.stringify({ model, input: text }),
+        signal: ctrl.signal,
+      });
+      if (!res.ok) {
+        const err = await res.text().catch(() => "");
+        throw new Error(`openai embeddings ${res.status}: ${err.slice(0, 200)}`);
+      }
+      const json = await res.json();
+      const vector = json?.data?.[0]?.embedding;
+      if (!Array.isArray(vector) || vector.length === 0) {
+        throw new Error("openai embeddings: empty vector");
+      }
+      return { vector: l2normalize(vector), embedder: `openai:${model}`, dim: vector.length };
+    } finally {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onParentAbort);
+    }
+  },
+};

package/src/core/memory/embed-engines/tf.js

@@ -0,0 +1,20 @@
+// Offline term-frequency fallback embedder. Deterministic, dependency-free,
+// always available. NOT as good as a real embedding model, but it keeps the
+// retriever working when no provider is reachable — the memory system must
+// degrade gracefully, never throw into the daemon's request path. This is the
+// guaranteed final link in the chain (the embeddings analogue of TTS "mock").
+
+import { tfEmbed } from "../embeddings.js";
+
+export default {
+  id: "tf",
+
+  async isAvailable() {
+    return true;
+  },
+
+  async embed({ text }) {
+    const vector = tfEmbed(text);
+    return { vector, embedder: "tf", dim: vector.length };
+  },
+};