@agentprojectcontext/apx 1.80.2 → 1.89.1

package/src/core/memory/compactor.js

@@ -161,10 +161,26 @@ export async function compactChannelIfNeeded(opts = {}) {
   });
 
   const models = resolveCompactModels(config);
-  const summary = await summarizeStructured({ prompt, models, config });
+  const prevSummaryText = prevCompact ? String(prevCompact.body || "").trim() : "";
+  const summary = await summarizeStructured({
+    prompt,
+    models,
+    config,
+    // The new summary must subsume this one; if it comes back smaller than the
+    // state it replaces, it dropped things and is refused.
+    prevSummary: prevSummaryText,
+    onReject: ({ model, reason }) =>
+      log(`memory: compaction for ${channel}/${chat_id} refused ${model}'s summary — ${reason}`),
+  });
   if (!summary) {
-    log(`memory: compaction for ${channel}/${chat_id} skipped — no model available`);
-    return { skipped: "no model" };
+    // Deliberately writing NOTHING. A compact record replaces the turns it
+    // covers, so a bad one is permanent amnesia while no record at all just
+    // means the raw history stays and the next turn tries again.
+    log(
+      `memory: compaction for ${channel}/${chat_id} skipped — no usable summary; ` +
+      `keeping ${compactedReal} raw turn(s)`
+    );
+    return { skipped: "no usable summary" };
   }
 
   const totalCovered = prevCount + compactedReal;

package/src/core/memory/consolidate.js

@@ -196,8 +196,8 @@ export function revertConsolidation(opts = {}) {
   return { removed, path: SELF_MEMORY_PATH };
 }
 
-/** Drop day headings left with no bullets under them. */
-function stripEmptyDays(lines) {
+/** Drop day headings left with no bullets under them. Shared with prune.js. */
+export function stripEmptyDays(lines) {
   const out = [];
   for (let i = 0; i < lines.length; i++) {
     const isHeading = /^##\s+\d{4}-\d{2}-\d{2}/.test(lines[i].trim());

package/src/core/memory/dated-log.js

@@ -0,0 +1,66 @@
+// The shape every dated note file in APX shares: one `## YYYY-MM-DD` heading
+// per day, one `- [HH:MM][channel] note` bullet per note, oldest day first.
+//
+// Three files are written this way — the super-agent's notebook
+// (`~/.apx/memory.md`), a project's memory (`<repo>/.apc/memory.md`) and a
+// routine's memory — and the fiddly part is the same in all three: a note
+// written today belongs at the END of TODAY'S block, not at the end of the
+// file. Get that wrong and the day splits into two headings the moment
+// anything else is appended. It had been written correctly once and
+// approximately twice more; this is the one copy.
+//
+// Pure — the caller owns the file I/O.
+import { dayStamp, hourStamp } from "#core/util/time.js";
+
+/**
+ * Append one note to a dated markdown log and return the new body.
+ *
+ * @param existing  current file body ("" for a file that doesn't exist yet)
+ * @param note      the note; newlines are flattened, one bullet per call
+ * @param opts.channel  tags the bullet "[HH:MM][channel] …" so the broker and
+ *                      the RAG indexer can attribute it. Omitted → plain "- note".
+ * @param opts.time     override the HH:MM tag (tests, backfills)
+ * @param opts.date     override the day heading (tests, backfills)
+ * @param opts.header   "# …" title used only when creating the file
+ */
+export function appendDatedBullet(existing, note, opts = {}) {
+  const text = String(note || "").trim();
+  if (!text) throw new Error("nothing to remember (empty note)");
+
+  const { channel = "", time = "", header = "" } = opts;
+  const date = opts.date || dayStamp();
+  const heading = `## ${date}`;
+  const oneLine = text.replace(/\n+/g, " ").trim();
+  const ch = String(channel || "").trim().toLowerCase();
+  const bullet = `- ${ch ? `[${time || hourStamp()}][${ch}] ` : ""}${oneLine}`;
+
+  const body = String(existing || "");
+  if (!body.trim()) {
+    return header ? `${header}\n\n${heading}\n${bullet}\n` : `${heading}\n${bullet}\n`;
+  }
+
+  const lines = body.split("\n");
+  // lastIndexOf, not includes(): a heading that merely *contains* today's date
+  // ("## 2026-01-01 — release") is not today's block, and treating it as one
+  // used to splice the bullet under whatever heading happened to come first.
+  const idx = lines.lastIndexOf(heading);
+  if (idx < 0) {
+    const sep = body.endsWith("\n") ? "" : "\n";
+    return `${body}${sep}\n${heading}\n${bullet}\n`;
+  }
+
+  // End of today's block: the next heading, or EOF. Trailing blank lines inside
+  // the block stay below the new bullet.
+  let insertAt = lines.length;
+  for (let i = idx + 1; i < lines.length; i++) {
+    if (lines[i].startsWith("## ")) {
+      insertAt = i;
+      break;
+    }
+  }
+  while (insertAt > idx + 1 && lines[insertAt - 1].trim() === "") insertAt--;
+
+  lines.splice(insertAt, 0, bullet);
+  const next = lines.join("\n");
+  return next.endsWith("\n") ? next : `${next}\n`;
+}

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

@@ -0,0 +1,59 @@
+// Custom OpenAI-compatible embeddings adapter. Backs every user-added provider
+// (config.memory.embeddings.custom.<slug>, surfaced as id "custom:<slug>") — a
+// local or self-hosted /embeddings endpoint such as a Zen server, LiteLLM, or a
+// llama.cpp server. Distinct from the built-in `openai` adapter in two ways:
+//   1. the API key is OPTIONAL (local servers are often keyless), and it never
+//      borrows engines.openai.api_key — a custom endpoint gets only its own key;
+//   2. every vector is tagged with the provider's OWN id (`custom:<slug>:model`)
+//      so two custom endpoints never collide in the index's cosine space.
+
+import { l2normalize } from "../embeddings.js";
+
+const DEFAULT_MODEL = "text-embedding-3-small";
+
+export default {
+  id: "custom",
+
+  // Available once it has a base_url — the endpoint to POST to. A key is only
+  // required if the server itself demands one (checked at call time by the 401).
+  async isAvailable(config = {}) {
+    return Boolean(config.base_url);
+  },
+
+  async embed({ text, config = {}, timeoutMs = 8000, signal }) {
+    const base = String(config.base_url || "").replace(/\/$/, "");
+    if (!base) throw new Error("custom embeddings: no base_url");
+    const key = config.api_key || "";
+    const model = config.model || DEFAULT_MODEL;
+    // The provider's own id, injected by the registry — the index-space tag.
+    const tag = config._embedder_id || "custom";
+    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: {
+          ...(key ? { 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(`custom 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("custom embeddings: empty vector");
+      }
+      return { vector: l2normalize(vector), embedder: `${tag}:${model}`, dim: vector.length };
+    } finally {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onParentAbort);
+    }
+  },
+};

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

@@ -1,9 +1,15 @@
-// Google Gemini embeddings adapter (default: text-embedding-004, 768 dims).
-// Free tier available with a Gemini API key. Reuses engines.gemini.api_key.
+// Google Gemini embeddings adapter. Free tier available with a Gemini API key,
+// and it reuses engines.gemini.api_key rather than asking for a second one.
+//
+// The default used to be `text-embedding-004`, which Google has since retired:
+// the endpoint answers 404 "not found for API version v1beta", embedOne swallows
+// it as a provider error, and every vector silently comes back from the offline
+// `tf` fallback instead. Pin a model that is actually served, and override it
+// with memory.embeddings.gemini.model when Google moves again.
 
 import { l2normalize } from "../embeddings.js";
 
-const DEFAULT_MODEL = "text-embedding-004";
+const DEFAULT_MODEL = "gemini-embedding-001";
 const BASE = "https://generativelanguage.googleapis.com/v1beta";
 
 function getKey(config = {}, parentEnginesCfg) {

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

@@ -22,6 +22,7 @@
 import ollama from "./ollama.js";
 import openai from "./openai.js";
 import gemini from "./gemini.js";
+import custom from "./custom.js";
 import tf from "./tf.js";
 
 const ADAPTERS = { ollama, openai, gemini, tf };
@@ -30,7 +31,29 @@ 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"];
 
+// ── Custom providers ────────────────────────────────────────────────────────
+// Users can add any number of OpenAI-compatible /embeddings endpoints (a local
+// Zen / LiteLLM / llama.cpp server). They live under memory.embeddings.custom
+// .<slug> and surface with id "custom:<slug>", all backed by the custom adapter.
+// Mirrors the TTS engine registry (src/core/voice/engines/index.js).
+export const CUSTOM_PREFIX = "custom:";
+
+export function isCustomId(id) {
+  return typeof id === "string" && id.startsWith(CUSTOM_PREFIX);
+}
+function slugOf(id) {
+  return isCustomId(id) ? id.slice(CUSTOM_PREFIX.length) : id;
+}
+function customEngineIds(embedCfg) {
+  return Object.keys(embedCfg?.custom || {}).map((slug) => CUSTOM_PREFIX + slug);
+}
+function knownIds(embedCfg) {
+  return [...EMBED_ENGINE_IDS, ...customEngineIds(embedCfg)];
+}
+
 export function getEmbedAdapter(provider) {
+  // Every custom provider is OpenAI-compatible → the custom adapter.
+  if (isCustomId(provider)) return custom;
   const a = ADAPTERS[provider];
   if (!a) {
     throw new Error(
@@ -42,8 +65,8 @@ export function getEmbedAdapter(provider) {
 
 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.
+  // memory.embed_* are the flat defaults every config ships with. With no
+  // explicit `embeddings.ollama` block, fold them into a synthetic one.
   const section = mem.embeddings || {};
   if (!section.ollama && (mem.embed_model || mem.embed_base_url || mem.embed_timeout_ms)) {
     return {
@@ -62,10 +85,17 @@ export function embeddingsConfig(globalConfig) {
 }
 
 function providerConfig(globalConfig, provider) {
-  return embeddingsConfig(globalConfig)?.[provider] || {};
+  const emb = embeddingsConfig(globalConfig);
+  // A custom provider's config lives under .custom.<slug>; inject its own id so
+  // the adapter tags vectors with `custom:<slug>:model` (a distinct cosine space).
+  if (isCustomId(provider)) {
+    return { ...(emb?.custom?.[slugOf(provider)] || {}), _embedder_id: provider };
+  }
+  return emb?.[provider] || {};
 }
 
 function isEnabled(embedCfg, id) {
+  if (isCustomId(id)) return embedCfg?.custom?.[slugOf(id)]?.enabled !== false;
   return embedCfg?.[id]?.enabled !== false;
 }
 
@@ -76,15 +106,17 @@ export function resolveMode(embedCfg) {
   return p && p !== "auto" ? "single" : "chain";
 }
 
-/** Full chain order: user's custom order (known ids only) then the rest; tf last. */
+/** Full chain order: user's saved order (known ids only) then the rest, with tf
+ *  ALWAYS last (the guaranteed offline floor). "Known" now includes every
+ *  custom:<slug> so added providers can be reordered. */
 export function resolveChainOrder(embedCfg) {
-  const custom = Array.isArray(embedCfg?.order)
-    ? embedCfg.order.filter((id) => EMBED_ENGINE_IDS.includes(id))
+  const known = knownIds(embedCfg);
+  const ordered = Array.isArray(embedCfg?.order)
+    ? embedCfg.order.filter((id) => known.includes(id) && id !== "tf")
     : [];
-  const rest = AUTO_PREFERENCE.filter((id) => !custom.includes(id));
-  const full = [...custom, ...rest];
-  if (!full.includes("tf")) full.push("tf");
-  return full;
+  const rest = [...AUTO_PREFERENCE.filter((id) => id !== "tf"), ...customEngineIds(embedCfg)]
+    .filter((id) => !ordered.includes(id));
+  return [...ordered, ...rest, "tf"];
 }
 
 /**
@@ -115,7 +147,7 @@ export async function selectEmbedEngine({ globalConfig, provider }) {
   // 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 adapter = getEmbedAdapter(id);
     const cfg = providerConfig(globalConfig, id);
     try {
       if (await adapter.isAvailable(cfg, globalConfig?.engines)) {
@@ -126,12 +158,50 @@ export async function selectEmbedEngine({ globalConfig, provider }) {
   return { provider: "tf", adapter: tf, engineConfig: providerConfig(globalConfig, "tf") };
 }
 
-/** Discover which engines are configured/available right now. */
+/**
+ * The ORDERED list of engines embedOne should try this call, first to last,
+ * before the guaranteed tf floor. Unlike selectEmbedEngine (which picks ONE by
+ * isAvailable), this returns every enabled+available engine in chain order so
+ * embedOne can fall through to the next one when a call FAILS at runtime — a
+ * rate-limited (429) or down provider, not just a keyless one. tf is omitted
+ * here; embedOne appends it as the final fallback.
+ * Returns [{ provider, adapter, engineConfig }].
+ */
+export async function selectEmbedChain({ globalConfig }) {
+  const embedCfg = embeddingsConfig(globalConfig);
+
+  // Single mode: exactly the configured engine, no fallback (matches the mode's
+  // contract; embedOne still drops to tf if that one engine errors).
+  if (resolveMode(embedCfg) === "single") {
+    const id = embedCfg?.provider;
+    if (id && id !== "auto" && (ADAPTERS[id] || isCustomId(id))) {
+      return [{ provider: id, adapter: getEmbedAdapter(id), engineConfig: providerConfig(globalConfig, id) }];
+    }
+  }
+
+  const out = [];
+  for (const id of resolveChainOrder(embedCfg)) {
+    if (id === "tf") continue;
+    if (!isEnabled(embedCfg, id)) continue;
+    let adapter;
+    try { adapter = getEmbedAdapter(id); } catch { continue; }
+    const cfg = providerConfig(globalConfig, id);
+    try {
+      if (await adapter.isAvailable(cfg, globalConfig?.engines)) {
+        out.push({ provider: id, adapter, engineConfig: cfg });
+      }
+    } catch { /* probe failures skip the engine */ }
+  }
+  return out;
+}
+
+/** Discover which engines are configured/available right now — built-ins plus
+ *  every user-added custom:<slug> provider. */
 export async function listAvailableEmbedEngines(globalConfig) {
   const embedCfg = embeddingsConfig(globalConfig);
   const out = [];
-  for (const id of EMBED_ENGINE_IDS) {
-    const adapter = ADAPTERS[id];
+  for (const id of knownIds(embedCfg)) {
+    const adapter = getEmbedAdapter(id);
     const cfg = providerConfig(globalConfig, id);
     let available = false;
     try {
@@ -140,8 +210,10 @@ export async function listAvailableEmbedEngines(globalConfig) {
     out.push({
       id,
       available,
-      configured: Object.keys(cfg).filter((k) => k !== "enabled").length > 0,
+      // `_embedder_id` is injected for custom blocks, not user-set config.
+      configured: Object.keys(cfg).filter((k) => k !== "enabled" && k !== "_embedder_id").length > 0,
       enabled: isEnabled(embedCfg, id),
+      ...(isCustomId(id) ? { custom: true, label: cfg.label || slugOf(id) } : {}),
     });
   }
   return out;

package/src/core/memory/embeddings.js

@@ -19,7 +19,7 @@
 // NOTE: this module is the leaf the engine adapters import (l2normalize /
 // tfEmbed). It also imports the registry — ESM live bindings make this safe
 // because selectEmbedEngine is only referenced at call time, never at init.
-import { selectEmbedEngine } from "./embed-engines/index.js";
+import { selectEmbedEngine, selectEmbedChain } from "./embed-engines/index.js";
 
 const TF_DIM = 256;
 
@@ -85,35 +85,57 @@ function tfResult(text) {
   return { vector: v, embedder: "tf", dim: v.length };
 }
 
+// The provider id inside an embedder tag ("ollama:nomic-embed-text" → "ollama",
+// "tf" → "tf"). Used to pin a batch to whatever actually answered.
+export function embedderProvider(embedder) {
+  return String(embedder || "tf").split(":")[0];
+}
+
+async function tryEmbed({ adapter, engineConfig }, clean, opts) {
+  const timeoutMs = opts.timeoutMs || engineConfig?.timeout_ms || 4000;
+  const out = await adapter.embed({
+    text: clean,
+    config: engineConfig || {},
+    parentEnginesCfg: opts.globalConfig?.engines,
+    timeoutMs,
+    signal: opts.signal,
+  });
+  if (!out || !Array.isArray(out.vector) || out.vector.length === 0) {
+    throw new Error("empty vector");
+  }
+  return out;
+}
+
 export async function embedOne(text, opts = {}) {
   const clean = String(text || "").slice(0, 8000);
   if (!clean.trim()) return tfResult("");
   if (opts.forceTf) return tfResult(clean);
 
-  let adapter, engineConfig;
-  try {
-    ({ adapter, engineConfig } = await selectEmbedEngine({
-      globalConfig: opts.globalConfig,
-      provider: opts.provider,
-    }));
-  } catch {
-    return tfResult(clean);
+  // Explicit provider (test UI, batch fast-path): exactly that engine, no chain
+  // fallback — tf only if it errors. This keeps the tester honest about one
+  // provider and lets a batch pin to the engine that already won.
+  if (opts.provider && opts.provider !== "auto") {
+    try {
+      const picked = await selectEmbedEngine({ globalConfig: opts.globalConfig, provider: opts.provider });
+      return await tryEmbed(picked, clean, opts);
+    } catch {
+      return tfResult(clean);
+    }
   }
 
-  const timeoutMs = opts.timeoutMs || engineConfig?.timeout_ms || 4000;
-  try {
-    const out = await adapter.embed({
-      text: clean,
-      config: engineConfig || {},
-      parentEnginesCfg: opts.globalConfig?.engines,
-      timeoutMs,
-      signal: opts.signal,
-    });
-    if (!out || !Array.isArray(out.vector) || out.vector.length === 0) return tfResult(clean);
-    return out;
-  } catch {
-    return tfResult(clean);
+  // Chain: walk every enabled+available engine in order and fall through to the
+  // NEXT one whenever a call fails at runtime — a rate-limited (429) or down
+  // provider, not just a keyless one. This is the "falls back to the next if one
+  // fails" the UI promises; before, a 429 on the first engine dropped straight
+  // to the offline tf floor and skipped a working local Ollama behind it.
+  let chain = [];
+  try { chain = await selectEmbedChain({ globalConfig: opts.globalConfig }); } catch { /* → tf */ }
+  for (const engine of chain) {
+    try {
+      return await tryEmbed(engine, clean, opts);
+    } catch { /* try the next engine in the chain */ }
   }
+  return tfResult(clean);
 }
 
 // Embed many strings. Probes the provider once with the first item; if that
@@ -124,9 +146,15 @@ export async function embedBatch(texts, opts = {}) {
   if (list.length === 0) return [];
   const first = await embedOne(list[0], opts);
   const out = [first];
-  const forceTf = first.embedder === "tf" ? { ...opts, forceTf: true } : opts;
+  // Pin the rest to whatever actually answered. Without this, a chain that fell
+  // past a rate-limited gemini to ollama would re-probe (and re-429) gemini for
+  // every remaining item — slow and quota-burning. tf → forceTf; a real engine →
+  // call it directly (no chain re-walk).
+  const restOpts = first.embedder === "tf"
+    ? { ...opts, forceTf: true }
+    : { ...opts, provider: embedderProvider(first.embedder) };
   for (let i = 1; i < list.length; i++) {
-    out.push(await embedOne(list[i], forceTf));
+    out.push(await embedOne(list[i], restOpts));
   }
   return out;
 }

package/src/core/memory/index.js

@@ -41,7 +41,17 @@ let _indexing = false;
 function indexOnce(note) {
   if (_indexing || !_store) return Promise.resolve();
   _indexing = true;
-  return indexNewMessages(_store, { embed: embedOptsFromConfig(_cfg), projects: _projects, log: note })
+  return indexNewMessages(_store, {
+    embed: embedOptsFromConfig(_cfg),
+    projects: _projects,
+    log: note,
+    // How many chunks one pass may embed. A local embedder happily takes the
+    // default; a hosted one on a free tier does not — 1000 embed calls a minute
+    // is a 429, and a rate-limited provider degrades to `tf`, which the
+    // consistency guard then (correctly) refuses to write. Smaller passes, more
+    // of them: `memory.index_batch`.
+    ...(Number(_cfg?.memory?.index_batch) > 0 ? { limit: Number(_cfg.memory.index_batch) } : {}),
+  })
     .catch(() => {})
     .finally(() => {
       _indexing = false;
@@ -54,8 +64,8 @@ export function memoryEnabled(config) {
 
 // The embeddings provider is resolved from config.memory.embeddings inside
 // embedOne/embedBatch via the engine registry — so all we forward here is the
-// live config. (Legacy memory.embed_* keys are still honored by the registry's
-// back-compat shim in embed-engines/index.js.)
+// live config. (The flat memory.embed_* defaults are folded into a synthetic
+// ollama block by embed-engines/index.js.)
 function embedOptsFromConfig(config) {
   return { globalConfig: config };
 }

package/src/core/memory/indexer.js

@@ -238,24 +238,66 @@ function collectAgentMemoryChunks(store, apxHome) {
 
 // Project memory (.apc/memory.md) for every registered project. Needs the
 // registry to map id → repo path. Scoped by channel "project:<id>".
+//
+// BOTH halves are indexed under the same scope: the curated `.apc/memory.md` and
+// the local `~/.apx/projects/<id>/memory.md` the agent writes. They differ in who
+// may write them and whether git carries them — not in whether they are true, and
+// retrieval that saw only the committed half would miss everything the agent has
+// learned since the owner last curated.
 function collectProjectMemoryChunks(store, projects) {
   const fresh = [];
   const list = typeof projects?.list === "function" ? projects.list() : Array.isArray(projects) ? projects : [];
   for (const entry of list) {
     const root = entry?.path;
     if (!root) continue; // the default project (id 0) has no repo root
-    const body = readIfExists(apcMemoryFile(root));
-    if (body == null) continue;
+    const files = [
+      ["projmem", readIfExists(apcMemoryFile(root))],
+      ["projlocalmem", entry?.storage_path || entry?.storagePath
+        ? readIfExists(path.join(entry.storage_path || entry.storagePath, "memory.md"))
+        : null],
+    ];
     const channel = `project:${entry.id}`;
-    for (const block of chunkFreeMarkdown(body)) {
-      const id = `projmem:${entry.id}:${fnv1aHex(block)}`;
-      if (store.hasId(id)) continue;
-      fresh.push({ id, source: "project-memory", channel, ts: "", tag: "project-memory", text: block });
+    for (const [prefix, body] of files) {
+      if (body == null) continue;
+      for (const block of chunkFreeMarkdown(body)) {
+        const id = `${prefix}:${entry.id}:${fnv1aHex(block)}`;
+        if (store.hasId(id)) continue;
+        fresh.push({ id, source: "project-memory", channel, ts: "", tag: "project-memory", text: block });
+      }
     }
   }
   return fresh;
 }
 
+// The offline fallback embedder. Everything else is a real provider space.
+const TF_FAMILY = "tf";
+
+/**
+ * Provider family of an embedder id ("ollama:nomic-embed-text" → "ollama").
+ * Vectors are only comparable within one family.
+ */
+export function embedderFamily(embedder) {
+  const id = String(embedder || TF_FAMILY);
+  const cut = id.indexOf(":");
+  return cut === -1 ? id : id.slice(0, cut);
+}
+
+/**
+ * What to do when the live embedder does not match the one the store was built
+ * with. Pure, so the policy is testable without a reachable provider.
+ *
+ *   "ok"      — same space (or an empty store); index normally.
+ *   "reindex" — moving into a real provider space; wipe and re-embed history.
+ *   "skip"    — the provider is down and we would fall back to `tf`; leave the
+ *               good store alone rather than mix spaces.
+ *
+ * @returns {"ok"|"reindex"|"skip"}
+ */
+export function reconcileEmbedder(stored, family, hasRows) {
+  if (!stored || stored === family || !hasRows) return "ok";
+  return family === TF_FAMILY ? "skip" : "reindex";
+}
+
 // Run one incremental indexing pass. Returns { indexed, backend }.
 // `opts.embed` overrides embedding options (baseUrl/model/timeoutMs) for tests.
 export async function indexNewMessages(store, opts = {}) {
@@ -270,32 +312,46 @@ export async function indexNewMessages(store, opts = {}) {
   cursor.channels = cursor.channels || {};
 
   // Embedder-consistency guard. Cosine only works within one embedder space, so
-  // the whole store must share an embedder family ("ollama" vs "tf"). Probe the
-  // currently-active embedder and reconcile:
-  //   - upgrade (tf → ollama, i.e. Ollama came back): wipe + full re-index so
-  //     the history is re-embedded in the better space.
-  //   - downgrade (ollama → tf, i.e. Ollama went down): skip this pass entirely
-  //     so we never pollute a good nomic store with TF rows.
+  // the whole store must share an embedder family. Probe the currently-active
+  // embedder and reconcile:
+  //   - moving into a REAL provider space (from tf, or from another provider):
+  //     wipe + full re-index so the history lives in one comparable space.
+  //   - falling back to `tf` (the offline embedder — the provider is down):
+  //     skip this pass entirely rather than pollute a good store with tf rows.
+  //
+  // The family used to be a boolean, "ollama" vs everything-else-is-tf. That
+  // made Gemini and OpenAI indistinguishable from the degraded fallback, so
+  // putting Gemini first while Ollama was down read as a downgrade and indexing
+  // stopped forever instead of re-indexing into the Gemini space.
   const probe = await embedOne("apx memory embedder probe", embedOpts);
-  const family = probe.embedder.startsWith("ollama") ? "ollama" : "tf";
+  const family = embedderFamily(probe.embedder);
   const stored = cursor.embedder || null;
-  if (stored && stored !== family && store.count() > 0) {
-    if (family === "ollama") {
-      try {
-        store.clear?.();
-      } catch {
-        /* ignore */
-      }
-      cursor.channels = {};
-      log(`memory: embedder ${stored}→ollama — full re-index`);
-    } else {
-      log("memory: Ollama unavailable — skipping index to keep embedder consistent");
-      cursor.embedder = stored; // keep the good signature
-      writeCursor(cursorPath, cursor);
-      return { indexed: 0, backend: store.backend, skipped: "embedder-downgrade" };
+  const verdict = reconcileEmbedder(stored, family, store.count() > 0);
+  if (verdict === "reindex") {
+    try {
+      store.clear?.();
+    } catch {
+      /* ignore */
     }
+    cursor.channels = {};
+    log(`memory: embedder ${stored}→${family} — full re-index`);
+  } else if (verdict === "skip") {
+    log(
+      `memory: embedding provider unavailable (would fall back to ${TF_FAMILY}) — ` +
+      `skipping index to keep the ${stored} store consistent`
+    );
+    cursor.embedder = stored; // keep the good signature
+    writeCursor(cursorPath, cursor);
+    return { indexed: 0, backend: store.backend, skipped: "embedder-downgrade" };
   }
+  // Persist the embedder signature NOW, before doing any work. It is separate
+  // state from the per-channel cursors: those may only advance on a complete
+  // pass, but the signature describes the store as it already is. Writing it at
+  // the end meant a CAPPED pass never recorded it — so the next pass still read
+  // the old family, wiped the store, re-embedded the same first `limit` chunks,
+  // capped again, and looped forever without the index ever growing.
   cursor.embedder = family;
+  writeCursor(cursorPath, cursor);
 
   const { fresh: msgChunks, maxTsByChannel } = collectMessageChunks(store, cursor, messagesDir);
   const memChunks = collectMemoryChunks(store, memoryPath);