@eleboucher/opencode-memini 0.6.9 → 0.6.11

package/README.md

@@ -53,12 +53,23 @@ Pass options inline via the `[name, options]` form:
 | `recall_limit`      | `MEMINI_RECALL_LIMIT`            | `3`                     | max memories injected per turn                                                                                                         |
 | `recall_max_tokens` | `MEMINI_INJECT_RECALL_MAX_TOK`   | `0`                     | hard ceiling on the recall-block tokens (`0` = unbounded); the tail is dropped with a `[… N item(s) truncated by token budget]` footer |
 | `recall_min_score`  | `MEMINI_INJECT_RECALL_MIN_SCORE` | `0`                     | fused-score floor (>=) sent as `min_score` to `/v1/search`                                                                             |
-| `timeout_ms`        | `MEMINI_TIMEOUT_MS`              | `30000`                 | per-request timeout                                                                                                                    |
+| `recall_budget_ms`  | `MEMINI_RECALL_BUDGET_MS`        | `2000`                  | how long a turn waits for recall before proceeding without it (`0` = wait for the full `timeout_ms`)                                   |
+| `timeout_ms`        | `MEMINI_TIMEOUT_MS`              | `30000`                 | per-request timeout (recall past its budget keeps running in the background under this bound)                                          |
 | `fallback_on_error` | `MEMINI_FALLBACK`                | on                      | `false` surfaces errors instead of degrading silently                                                                                  |
 | —                   | `MEMINI_INJECT_LABELS`           | —                       | comma-separated label toggles for each bullet: `tier`, `confidence`, `age`, `reason`                                                   |
 | —                   | `MEMINI_API_KEY`                 | —                       | bearer token, if memini needs auth (env only — secret; alias: `MEMINI_TOKEN`)                                                          |
 | —                   | `MEMINI_REQUIRE_HTTPS`           | —                       | `1` refuses to send the token over plaintext HTTP                                                                                      |
 
+opencode awaits `chat.message` before the model sees the message, so a slow or
+unreachable memini would otherwise freeze the turn for the full `timeout_ms`.
+Instead, recall races `recall_budget_ms`: if the search hasn't answered in time,
+the turn proceeds without memories and the search keeps running in the
+background — results that arrive late are injected on the session's next
+message instead of being dropped. The plugin also pings `/healthz` once at
+startup to warm the connection, so the first recall doesn't pay the
+DNS/TLS cold-start. Set `recall_budget_ms: 0` to restore fully blocking
+same-turn injection.
+
 Inline options win over the env vars. Secrets stay in the environment: set
 `MEMINI_API_KEY` (sent as `Authorization: Bearer …`), and optionally
 `MEMINI_REQUIRE_HTTPS=1` to refuse plaintext HTTP, in the shell that launches

package/memini.js

@@ -23,9 +23,13 @@ import { homedir } from "node:os";
 
 const DEFAULT_BASE_URL = "http://localhost:8080";
 const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_RECALL_BUDGET_MS = 2000;
 const DEFAULT_RECALL_LIMIT = 3;
 const DEFAULT_NAMESPACE = "opencode";
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+// Race sentinel: distinguishes "the recall budget expired" from any value the
+// search itself could resolve to (including null on a degraded failure).
+const BUDGET_EXPIRED = Symbol("memini-recall-budget-expired");
 
 function envBool(value, fallback) {
   if (value === undefined || value === null || value === "") return fallback;
@@ -252,6 +256,17 @@ export function resolveConfig(env, options, worktree, opts = {}) {
     }
     return DEFAULT_RECALL_LIMIT;
   })();
+  // How long chat.message waits for recall before letting the turn proceed
+  // without it; 0 disables the race (fully blocking recall). The ""-skip
+  // matters: Number("") === 0, so an empty env var would silently go blocking.
+  const recall_budget_ms = (() => {
+    for (const v of [o.recall_budget_ms, e.MEMINI_RECALL_BUDGET_MS, DEFAULT_RECALL_BUDGET_MS]) {
+      if (v === undefined || v === null || v === "") continue;
+      const n = Number(v);
+      if (Number.isFinite(n) && n >= 0) return n;
+    }
+    return DEFAULT_RECALL_BUDGET_MS;
+  })();
   // home: the caller's personal namespace, sent as X-Memini-Home. Same
   // env-only resolution style as namespace's MEMINI_NAMESPACE (option wins
   // over env), but no config-file/derivation fallback — unset means "no home
@@ -281,6 +296,7 @@ export function resolveConfig(env, options, worktree, opts = {}) {
       o.recall_min_score !== undefined
         ? Number(o.recall_min_score) || 0
         : floatEnv("MEMINI_INJECT_RECALL_MIN_SCORE", 0),
+    recall_budget_ms,
     timeout_ms: Number(o.timeout_ms || e.MEMINI_TIMEOUT_MS || DEFAULT_TIMEOUT_MS),
     fallback_on_error:
       o.fallback_on_error !== undefined
@@ -592,6 +608,7 @@ export function describeSettings(env, options, worktree) {
       recall_limit: cfg.recall_limit,
       recall_max_tokens: cfg.recall_max_tokens,
       recall_min_score: cfg.recall_min_score,
+      recall_budget_ms: cfg.recall_budget_ms,
       labels: [...labelsEnv()],
     },
     paths: { overrides: overridesPath(e) },
@@ -638,6 +655,7 @@ export function renderStatus(report) {
   L.push(`  ${padTo("recall_limit", 26)} ${memory.recall_limit}`);
   L.push(`  ${padTo("recall_max_tokens", 26)} ${memory.recall_max_tokens || "uncapped"}`);
   L.push(`  ${padTo("recall_min_score", 26)} ${memory.recall_min_score}`);
+  L.push(`  ${padTo("recall_budget_ms", 26)} ${memory.recall_budget_ms === 0 ? "0 (blocking)" : memory.recall_budget_ms}`);
   L.push(`  ${padTo("labels", 26)} ${memory.labels.length ? memory.labels.join(",") : "(none)"}`);
   L.push("");
 
@@ -750,27 +768,85 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
 
   const cfg = resolveConfig(process.env, options, worktree || directory);
   const rest = createClient(cfg, log);
+  // Warm the connection (DNS/TCP/TLS) in opencode's embedded bun so a cold
+  // start doesn't eat the first recall budget. Silent: even a 404 warms the
+  // path, and an ingress that only routes /v1 legitimately has no /healthz.
+  if (cfg.recall || cfg.capture) {
+    try {
+      fetch(`${rest.baseUrl}/healthz`, { signal: AbortSignal.timeout(3000) }).catch(() => {});
+    } catch {
+      /* ignore */
+    }
+  }
   // Assistant message ids already captured, so repeated session.idle events for
-  // the same turn don't write duplicates.
+  // the same turn don't write duplicates. Repeats only concern recent turns,
+  // so cap the window instead of growing one entry per turn forever.
   const captured = new Set();
+  const MAX_CAPTURED = 200;
+  const rememberCaptured = (id) => {
+    captured.add(id);
+    while (captured.size > MAX_CAPTURED) {
+      const oldest = captured.values().next().value;
+      if (oldest === undefined) break;
+      captured.delete(oldest);
+    }
+  };
+  // boundedPut inserts key -> value and evicts the oldest entries, so a
+  // long-lived host can't grow a per-session map without limit.
+  const MAX_TRACKED_SESSIONS = 200;
+  const boundedPut = (map, key, value) => {
+    map.set(key, value);
+    while (map.size > MAX_TRACKED_SESSIONS) {
+      const oldest = map.keys().next().value;
+      if (oldest === undefined) break;
+      map.delete(oldest);
+    }
+  };
   // Memory ids each session has already been shown (mirrors the pi plugin):
   // the injected synthetic part is persisted into the session, so re-injecting
   // an unchanged match every turn stacks identical blocks in the context.
-  // Bounded so long-lived hosts can't grow the map without limit.
+  // The inner cap keeps a stable session — which never ages out of the outer
+  // map — from growing its Set for the process lifetime.
   const injectedBySession = new Map();
-  const MAX_TRACKED_SESSIONS = 200;
+  const MAX_INJECTED_PER_SESSION = 200;
   const rememberInjected = (session, ids) => {
     let seen = injectedBySession.get(session);
     if (!seen) {
       seen = new Set();
-      injectedBySession.set(session, seen);
-      while (injectedBySession.size > MAX_TRACKED_SESSIONS) {
-        const oldest = injectedBySession.keys().next().value;
-        if (oldest === undefined) break;
-        injectedBySession.delete(oldest);
-      }
+      boundedPut(injectedBySession, session, seen);
     }
     for (const id of ids) if (id) seen.add(id);
+    while (seen.size > MAX_INJECTED_PER_SESSION) {
+      const oldest = seen.values().next().value;
+      if (oldest === undefined) break;
+      seen.delete(oldest);
+    }
+  };
+  // Recall results that arrived after the injection budget expired, keyed by
+  // session and injected on that session's next chat.message. Latest-replace:
+  // a second late recall for the same session supersedes the first.
+  const pendingBySession = new Map();
+  // /v1/search drops exclude_ids before ranking and the limit, so an
+  // already-shown hit frees its slot for the next-best match. Older servers
+  // 400 on the unknown field: when a request carrying it fails and the retry
+  // without it succeeds, stop sending it. The client-side filter stays.
+  let serverExcludeIds = true;
+  const searchExcluding = async (body, excludeIds) => {
+    if (!serverExcludeIds || excludeIds.length === 0) {
+      return rest.postJson("/v1/search", body);
+    }
+    try {
+      const result = await rest.postJson("/v1/search", { ...body, exclude_ids: excludeIds });
+      if (result !== null) return result;
+    } catch {
+      // With fallback_on_error=false the 400 arrives as a throw, not null.
+    }
+    const retry = await rest.postJson("/v1/search", body);
+    if (retry !== null) {
+      serverExcludeIds = false;
+      log.warn("memini: server does not accept exclude_ids; using client-side dedupe only");
+    }
+    return retry;
   };
 
   // opencode runs chat.message via an unguarded Effect.promise (a throw aborts the
@@ -844,13 +920,61 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
       // the Claude Code plugin's pre-tool-use hook uses; client-side re-filter
       // is a belt-and-braces guard against score-normalization edge cases.
       if (cfg.recall_min_score > 0) body.min_score = cfg.recall_min_score;
-      const result = await rest.postJson("/v1/search", body);
+      // Already-shown ids go along as exclude_ids so a suppressed hit doesn't
+      // waste a recall_limit slot.
+      const excludeIds = sessionID ? [...(injectedBySession.get(sessionID) ?? [])] : [];
+      // opencode awaits this hook before the model sees the message, so the
+      // turn only waits recall_budget_ms for the search; the fetch itself keeps
+      // cfg.timeout_ms as its bound and runs on in the background. A slow or
+      // unreachable memini degrades to "no memories this turn" instead of a
+      // frozen turn, and late results carry over to the session's next message.
+      const fetchPromise = searchExcluding(body, excludeIds);
+      // Once the budget expires nothing awaits this promise, and with
+      // fallback_on_error off postJson rethrows — catch here or a late
+      // rejection surfaces as an unhandled rejection in the host.
+      const settled = fetchPromise.catch((error) => {
+        log.warn(`memini: ${String(error)}`);
+        return null;
+      });
+      let result;
+      if (cfg.recall_budget_ms > 0) {
+        let timer;
+        const budget = new Promise((resolve) => {
+          timer = setTimeout(() => resolve(BUDGET_EXPIRED), cfg.recall_budget_ms);
+        });
+        result = await Promise.race([settled, budget]);
+        clearTimeout(timer);
+        if (result === BUDGET_EXPIRED) {
+          log.warn(
+            `recall exceeded its ${cfg.recall_budget_ms}ms budget; late results will inject next turn`,
+          );
+          if (sessionID) {
+            settled.then((late) => {
+              const hits = Array.isArray(late && late.results) ? late.results : [];
+              if (hits.length) boundedPut(pendingBySession, sessionID, hits);
+            });
+          }
+          result = null;
+        }
+      } else {
+        result = await settled;
+      }
       // Client-side score floor: filter the raw hit list before formatting so
       // the bullet array only contains hits the operator asked for. Without
       // this, the server's default floor could leak low-quality hits in
       // regardless of cfg.recall_min_score.
       const floor = cfg.recall_min_score > 0 ? cfg.recall_min_score : 0;
       let rawHits = Array.isArray(result && result.results) ? result.results : [];
+      // Merge in results that arrived late on a previous turn: fresh hits
+      // first (they answer the current query), deduped by memory id.
+      if (sessionID) {
+        const pending = pendingBySession.get(sessionID);
+        if (pending && pending.length) {
+          pendingBySession.delete(sessionID);
+          const fresh = new Set(rawHits.map((r) => r?.memory?.id).filter(Boolean));
+          rawHits = rawHits.concat(pending.filter((r) => !fresh.has(r?.memory?.id)));
+        }
+      }
       // Suppress memories this session has already been shown — the injected
       // part persists in the session, so a repeat adds nothing but noise.
       if (sessionID) {
@@ -869,7 +993,16 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
       const fit = fitByTokens(hits, cfg.recall_max_tokens);
       if (fit.items.length === 0) return;
       if (sessionID) {
-        rememberInjected(sessionID, filtered.map((r) => r?.memory?.id).filter(Boolean));
+        // Mark only the slice formatResults actually renders: with carryover
+        // merged in, `filtered` can exceed recall_limit, and marking unshown
+        // hits as seen would suppress them forever.
+        rememberInjected(
+          sessionID,
+          filtered
+            .slice(0, cfg.recall_limit || DEFAULT_RECALL_LIMIT)
+            .map((r) => r?.memory?.id)
+            .filter(Boolean),
+        );
       }
       const lines = [
         `Relevant long-term memory from memini (background context — prefer ` +
@@ -909,7 +1042,7 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
         tags: ["opencode"],
         metadata,
       });
-      if (stored !== null && assistantID) captured.add(assistantID);
+      if (stored !== null && assistantID) rememberCaptured(assistantID);
     }),
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eleboucher/opencode-memini",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "description": "Automatic cross-session memory for opencode via memini — recall before each turn, capture after.",
   "keywords": [
     "memini",