@eleboucher/opencode-memini 0.7.11 → 0.7.13

package/README.md

@@ -15,8 +15,8 @@ What it wires (two hooks):
   excludes this session's own captured turns (already in the live context), so
   they aren't echoed back as memory a turn behind; past sessions still recall.
 - **`event` (`session.idle`)** — once the session goes idle, stores the
-  completed user/assistant turn back into memini (episodic, tagged with the
-  session id) so it can be recalled later.
+  completed user/assistant turn back into memini (tagged with the session id) so
+  it can be recalled later.
 
 ### Install
 
@@ -60,6 +60,10 @@ The same options and env vars below apply. Recall injects into the request's
 > `core/src/plugin/host.ts`. Until then, stay on the v1 entry above with the
 > stable `opencode` binary.
 
+The v2 plugin sends diagnostics through the structured `ctx.app.log` logger when
+available. Logging is best-effort and remains silent when that logger is absent
+or unavailable.
+
 ### Configure
 
 Pass options inline via the `[name, options]` form:
@@ -77,13 +81,14 @@ Pass options inline via the `[name, options]` form:
 | `home`                    | `MEMINI_HOME`                    | unset                   | caller's personal namespace, sent as `X-Memini-Home`; unset = no home leg                                                                                            |
 | `recall`                  | `MEMINI_RECALL`                  | on                      | `false` disables recall-before-turn                                                                                                                                  |
 | `capture`                 | `MEMINI_CAPTURE`                 | on                      | `false` disables capture-after-turn                                                                                                                                  |
+| `capture_child_sessions`  | `MEMINI_CAPTURE_CHILD_SESSIONS`  | off                     | capture child sessions; off skips children and unknown ancestry (fail-closed), on records ancestry metadata                                                          |
 | `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`                                                                                                           |
 | `inject_cooldown_ms`      | `MEMINI_INJECT_COOLDOWN_MS`      | `1800000`               | repeat-injection cooldown, **time** window (ms): an already-injected memory is held back this long before it may re-serve; `0` disables the time dimension           |
 | `inject_cooldown_prompts` | `MEMINI_INJECT_COOLDOWN_PROMPTS` | `3`                     | repeat-injection cooldown, **prompt** window (counted per user message); `0` disables the prompt dimension; both cooldown knobs `0` = suppress for the whole session |
 | `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)                                                                        |
+| `timeout_ms`              | `MEMINI_TIMEOUT_MS`              | `30000`                 | per-request timeout for memini requests                                                                                                                              |
 | `fallback_on_error`       | `MEMINI_FALLBACK`                | on                      | `false` surfaces errors instead of degrading silently                                                                                                                |
 | `auto_update`             | `MEMINI_AUTO_UPDATE`             | on                      | `false` disables npm auto-update checks (opencode never re-fetches cached plugins otherwise)                                                                         |
 | —                         | `MEMINI_INJECT_LABELS`           | —                       | comma-separated label toggles for each bullet: `tier`, `confidence`, `age`, `reason`                                                                                 |
@@ -93,13 +98,20 @@ Pass options inline via the `[name, options]` form:
 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
+the turn proceeds without memories and eventual results are discarded. Errors
+from the background request are still logged. 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.
 
+Automatic captures leave tier selection to the server. Before retrieving
+messages, the plugin resolves session ancestry. Root sessions are captured by
+default; child sessions and sessions whose ancestry cannot be resolved are
+skipped by default. Set `capture_child_sessions` (or
+`MEMINI_CAPTURE_CHILD_SESSIONS=1`) to opt in; captures then include
+`metadata.session_type` (`root`, `child`, or `unknown`) and child captures also
+include `metadata.parent_session_id`.
+
 ### Repeat-injection cooldown
 
 The two `inject_cooldown_*` knobs are the windowed **repeat-injection

package/memini-v2.js

@@ -48,11 +48,13 @@ import {
   injectedIdentity,
   injectedSuppressed,
   postSearchWithFloor,
+  resolveSessionAncestry,
 } from "./memini.js";
 
 const INJECT_PREAMBLE =
   "Relevant long-term memory from memini (background context — prefer " +
   "current workspace state and the user's instructions):";
+const BUDGET_EXPIRED = Symbol("memini-recall-budget-expired");
 
 // messageText pulls the plain text out of one v2 request message, tolerating the
 // shapes the beta may hand us: `content` as a string, `content` as an array of
@@ -142,16 +144,17 @@ export async function setup(ctx) {
   // opencode runs the plugin in the project root, so cwd is the project dir —
   // the same input resolveConfig/deriveNamespace expect.
   const dir = process.cwd();
+  const emitLog = async (level, message) => {
+    try {
+      if (typeof ctx?.app?.log !== "function") return;
+      await ctx.app.log({ body: { service: "memini", level, message } });
+    } catch {
+      // Logging is best-effort and must never affect plugin behavior.
+    }
+  };
   const log = {
     warn: (message) => {
-      // ctx is essentially a server client; mirror v1's structured logger and
-      // fall back to stderr.
-      try {
-        ctx?.app?.log?.({ body: { service: "memini", level: "warn", message } });
-      } catch {
-        /* ignore logging failures */
-      }
-      console.error(`[memini] ${message}`);
+      void emitLog("warn", message);
     },
   };
 
@@ -259,11 +262,33 @@ export async function setup(ctx) {
         // fail-soft, and on an older server's 400 it retries once with
         // min_rank_score stripped (v2 sends no exclude_ids), so a slow or
         // out-of-date memini degrades to no memory this turn, never a throw.
-        const { data: result, rankFloorStripped } = await postSearchWithFloor(
+        const searchPromise = postSearchWithFloor(
           rest.postJson,
           body,
           live.namespace,
         );
+        // Keep the rejection handler attached even after the request budget
+        // expires: late results are discarded, but late errors remain visible.
+        const settled = searchPromise.catch((error) => {
+          log.warn(`memini: ${String(error)}`);
+          return { data: null, rankFloorStripped: false };
+        });
+        let search;
+        if (live.recall_budget_ms > 0) {
+          let timer;
+          const budget = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(BUDGET_EXPIRED), live.recall_budget_ms);
+          });
+          search = await Promise.race([settled, budget]);
+          clearTimeout(timer);
+          if (search === BUDGET_EXPIRED) {
+            log.warn(`recall exceeded its ${live.recall_budget_ms}ms budget; late results discarded`);
+            return;
+          }
+        } else {
+          search = await settled;
+        }
+        const { data: result, rankFloorStripped } = search;
 
         // Client composite floor is a fallback ONLY: it runs when the knob was
         // clamped to client-only (>= 1) or the retry stripped min_rank_score. A
@@ -371,11 +396,13 @@ export async function setup(ctx) {
     const sessionID =
       (event && event.properties && event.properties.sessionID) || (event && event.sessionID);
     if (!sessionID) return;
+    const ancestry = await resolveSessionAncestry(ctx.session, sessionID);
+    if (ancestry.session_type !== "root" && !live.capture_child_sessions) return;
     const messages = await fetchSessionMessages(ctx, sessionID);
     const { userText, assistantText, assistantID } = extractLastTurn(messages);
     if (!userText || !assistantText) return;
     if (assistantID && captured.has(assistantID)) return;
-    const metadata = { source: "opencode", session_id: sessionID, format: "turn" };
+    const metadata = { source: "opencode", session_id: sessionID, format: "turn", ...ancestry };
     if (lastAssistantFailed(messages)) metadata.failed = true;
     const stored = await rest.postJson(
       "/v1/memories",

package/memini.js

@@ -6,7 +6,7 @@
  *   - chat.message: recall memories relevant to the incoming user message and
  *     inject them as a synthetic context part before the turn runs.
  *   - event (session.idle): capture the completed user/assistant turn into
- *     memini as episodic memory once the session goes idle.
+ *     memini once the session goes idle.
  *
  * Talks to memini over REST (/v1/search, /v1/memories), scoped by the
  * X-Memini-Namespace header. Default endpoint http://localhost:8080.
@@ -365,6 +365,9 @@ export function resolveConfig(env, options, worktree) {
   // guess. Not layered from the server: it is a purely local, per-caller knob.
   const homeRaw = o.home !== undefined ? o.home : e.MEMINI_HOME;
   const home = homeRaw && String(homeRaw).trim() ? String(homeRaw).trim() : undefined;
+  const capture_child_sessions = o.capture_child_sessions !== undefined
+    ? envBool(o.capture_child_sessions, false)
+    : envBool(e.MEMINI_CAPTURE_CHILD_SESSIONS, false);
 
   // Windowed injection-cooldown knobs. 0 is MEANINGFUL (it disables that
   // dimension; both 0 restores the legacy suppress-forever behavior), so a
@@ -387,6 +390,7 @@ export function resolveConfig(env, options, worktree) {
     home,
     recall: o.recall !== undefined ? o.recall !== false : envBool(e.MEMINI_RECALL, true),
     capture: o.capture !== undefined ? o.capture !== false : envBool(e.MEMINI_CAPTURE, true),
+    capture_child_sessions,
     recall_limit,
     recall_max_tokens:
       o.recall_max_tokens !== undefined
@@ -791,6 +795,33 @@ export function buildTurnCapture(userText, assistantText, userMax, assistantMax)
   return `${truncateForCapture(userText, userMax)}\n\n${truncateForCapture(assistantText, assistantMax)}`;
 }
 
+// Resolve ancestry before reading messages. Hosts have exposed several session
+// accessors over time; an unavailable accessor is distinguishable from a root
+// session so the default capture policy can fail closed.
+export async function resolveSessionAncestry(session, sessionID) {
+  if (!session || !sessionID) return { session_type: "unknown" };
+  const attempts = [
+    () => session.get && session.get({ path: { id: sessionID } }),
+    () => session.info && session.info({ path: { id: sessionID } }),
+    () => session.get && session.get(sessionID),
+  ];
+  for (const attempt of attempts) {
+    try {
+      const response = await attempt();
+      if (response?.error) continue;
+      const info = response?.data || response?.session || response;
+      if (!info || typeof info !== "object" || Array.isArray(info) || info.error) continue;
+      const recordID = info.id || info.sessionID || info.sessionId;
+      if (!recordID || String(recordID) !== String(sessionID)) continue;
+      const parent = info.parentID || info.parentId || info.parent_session_id || info.parentSessionId;
+      return parent ? { session_type: "child", parent_session_id: parent } : { session_type: "root" };
+    } catch {
+      // Try the next host shape.
+    }
+  }
+  return { session_type: "unknown" };
+}
+
 /**
  * Truncate to `max` bytes, suffix with a marker. Same shape as the Claude
  * Code plugin's truncate helper.
@@ -1249,10 +1280,6 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
       state.ids.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
@@ -1377,9 +1404,9 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
         : [];
       // opencode awaits this hook before the model sees the message, so the
       // turn only waits live.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
+      // cfg.timeout_ms as its bound and runs 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.
+      // frozen turn; results arriving after the budget are discarded.
       const fetchPromise = searchExcluding(body, excludeIds, live.namespace);
       // Once the budget expires nothing awaits this promise, and with
       // fallback_on_error off postJson rethrows — catch here or a late
@@ -1397,15 +1424,7 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
         result = await Promise.race([settled, budget]);
         clearTimeout(timer);
         if (result === BUDGET_EXPIRED) {
-          log.info(
-            `recall exceeded its ${live.recall_budget_ms}ms budget; late results will inject next turn`,
-          );
-          if (sessionID) {
-            settled.then((late) => {
-              const hits = Array.isArray(late && late.data && late.data.results) ? late.data.results : [];
-              if (hits.length) boundedPut(pendingBySession, sessionID, hits);
-            });
-          }
+          log.info(`recall exceeded its ${live.recall_budget_ms}ms budget; late results discarded`);
           result = null;
         }
       } else {
@@ -1419,16 +1438,6 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
       const serverEnforcedFloor = rankFloorInRange && !(result && result.rankFloorStripped);
       const floor = live.recall_min_score > 0 && !serverEnforcedFloor ? live.recall_min_score : 0;
       let rawHits = Array.isArray(searchData && searchData.results) ? searchData.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 was already shown and that are still in
       // cooldown — judged PER HIT against its content identity, so an
       // in-window unchanged hit is dropped, a lapsed one passes through and
@@ -1453,8 +1462,7 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
       const fit = fitByTokens(hits, live.recall_max_tokens);
       if (fit.items.length === 0) return;
       if (seen) {
-        // Mark only the slice formatResults actually renders: with carryover
-        // merged in, `filtered` can exceed recall_limit, and marking unshown
+        // Mark only the slice formatResults actually renders; marking unshown
         // hits as seen would suppress what was never injected.
         rememberInjected(seen, filtered.slice(0, live.recall_limit || DEFAULT_RECALL_LIMIT));
       }
@@ -1526,11 +1534,13 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
       if (!live.capture || !event || event.type !== "session.idle") return;
       const sessionID = event.properties && event.properties.sessionID;
       if (!sessionID) return;
+      const ancestry = await resolveSessionAncestry(client.session, sessionID);
+      if (ancestry.session_type !== "root" && !live.capture_child_sessions) return;
       const res = await client.session.messages({ path: { id: sessionID } });
       const { userText, assistantText, assistantID } = extractLastTurn(res && res.data);
       if (!userText || !assistantText) return;
       if (assistantID && captured.has(assistantID)) return;
-      const metadata = { source: "opencode", session_id: sessionID, format: "turn" };
+      const metadata = { source: "opencode", session_id: sessionID, format: "turn", ...ancestry };
       if (lastAssistantFailed(res && res.data)) metadata.failed = true;
       const stored = await rest.postJson(
         "/v1/memories",

package/package.json

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