@xdarkicex/openclaw-memory-libravdb 1.9.9 → 1.9.10-beta.2

package/dist/context-engine.js

@@ -204,11 +204,11 @@ function normalizeKernelContent(content, options = {}) {
  * code must explicitly import the symbol to call the hook.
  */
 export const FLUSH_ASYNC_INGESTION = Symbol("flushAsyncIngestion");
-let maxOptimizationMemoCacheSize = 1000;
+let maxOptimizationMemoCacheSize = 50000;
 const metadataEnvelopeCache = new Map();
 const metadataEnvelopeRetainCache = new Map();
 export function setOptimizationMemoCacheSize(size) {
-    maxOptimizationMemoCacheSize = size > 0 ? size : 1000;
+    maxOptimizationMemoCacheSize = size > 0 ? size : 50000;
 }
 /**
  * Evicts the oldest half of entries from a Map when it exceeds maxSize.
@@ -1750,17 +1750,32 @@ export function buildContextEngineFactory(runtime, cfg, logger = console) {
             // BeforeTurnKernel: semantic memory retrieval against the current user query.
             // Skip for automated triggers (heartbeat, cron, memory, overflow) — saves
             // an embedding call and RPC round trip on non-interactive turns.
+            const btLog = cfg.beforeTurnDebug
+                ? (msg) => logger.info?.(msg)
+                : (_msg) => { };
             let beforeTurnPredictions = null;
             let beforeTurnQueryHint = null;
-            if (cfg.beforeTurnEnabled !== false && isInteractiveTrigger(sessionId)) {
+            if (cfg.beforeTurnEnabled === false) {
+                btLog(`BeforeTurnKernel disabled by config sessionId=${sessionId}`);
+            }
+            else if (!isInteractiveTrigger(sessionId)) {
+                btLog(`BeforeTurnKernel skipped: non-interactive trigger sessionId=${sessionId}`);
+            }
+            else {
                 beforeTurnQueryHint = extractQueryHint(messages, (text) => typeof text === "string" ? text.replace(OPENCLAW_LEADING_TIMESTAMP_PREFIX_RE, "").trim() : text);
-                if (beforeTurnQueryHint && !isNewUserTurn(messages)) {
+                if (!beforeTurnQueryHint) {
+                    btLog(`BeforeTurnKernel skipped: no query hint extracted sessionId=${sessionId}`);
+                }
+                else if (!isNewUserTurn(messages)) {
+                    btLog(`BeforeTurnKernel skipped: not a new user turn sessionId=${sessionId}`);
                     beforeTurnQueryHint = null;
                 }
                 if (beforeTurnQueryHint && isBeforeTurnCircuitOpen(sessionId)) {
+                    btLog(`BeforeTurnKernel skipped: circuit open sessionId=${sessionId}`);
                     beforeTurnQueryHint = null;
                 }
                 if (beforeTurnQueryHint) {
+                    btLog(`BeforeTurnKernel calling sessionId=${sessionId} hint=${beforeTurnQueryHint.slice(0, 50)}`);
                     // Include message count in cache key so identical queries
                     // in different turns don't return stale predictions.
                     const turnScopedHint = `${messages.length}:${beforeTurnQueryHint}`;

package/dist/index.js

@@ -35657,11 +35657,11 @@ function normalizeKernelContent(content, options = {}) {
   });
 }
 var FLUSH_ASYNC_INGESTION = /* @__PURE__ */ Symbol("flushAsyncIngestion");
-var maxOptimizationMemoCacheSize = 1e3;
+var maxOptimizationMemoCacheSize = 5e4;
 var metadataEnvelopeCache = /* @__PURE__ */ new Map();
 var metadataEnvelopeRetainCache = /* @__PURE__ */ new Map();
 function setOptimizationMemoCacheSize(size) {
-  maxOptimizationMemoCacheSize = size > 0 ? size : 1e3;
+  maxOptimizationMemoCacheSize = size > 0 ? size : 5e4;
 }
 function evictOldestHalf(map, maxSize) {
   if (map.size < maxSize) return;
@@ -36984,20 +36984,31 @@ function buildContextEngineFactory(runtime, cfg, logger = console) {
           );
         }
       }
+      const btLog = cfg.beforeTurnDebug ? (msg) => logger.info?.(msg) : (_msg) => {
+      };
       let beforeTurnPredictions = null;
       let beforeTurnQueryHint = null;
-      if (cfg.beforeTurnEnabled !== false && isInteractiveTrigger(sessionId)) {
+      if (cfg.beforeTurnEnabled === false) {
+        btLog(`BeforeTurnKernel disabled by config sessionId=${sessionId}`);
+      } else if (!isInteractiveTrigger(sessionId)) {
+        btLog(`BeforeTurnKernel skipped: non-interactive trigger sessionId=${sessionId}`);
+      } else {
         beforeTurnQueryHint = extractQueryHint(
           messages,
           (text) => typeof text === "string" ? text.replace(OPENCLAW_LEADING_TIMESTAMP_PREFIX_RE, "").trim() : text
         );
-        if (beforeTurnQueryHint && !isNewUserTurn(messages)) {
+        if (!beforeTurnQueryHint) {
+          btLog(`BeforeTurnKernel skipped: no query hint extracted sessionId=${sessionId}`);
+        } else if (!isNewUserTurn(messages)) {
+          btLog(`BeforeTurnKernel skipped: not a new user turn sessionId=${sessionId}`);
           beforeTurnQueryHint = null;
         }
         if (beforeTurnQueryHint && isBeforeTurnCircuitOpen(sessionId)) {
+          btLog(`BeforeTurnKernel skipped: circuit open sessionId=${sessionId}`);
           beforeTurnQueryHint = null;
         }
         if (beforeTurnQueryHint) {
+          btLog(`BeforeTurnKernel calling sessionId=${sessionId} hint=${beforeTurnQueryHint.slice(0, 50)}`);
           const turnScopedHint = `${messages.length}:${beforeTurnQueryHint}`;
           const cached = turnCache.get(sessionId, turnScopedHint);
           if (cached?.predictions) {

package/dist/types.d.ts

@@ -131,6 +131,8 @@ export interface PluginConfig {
     grpcEndpointTlsMode?: "auto" | "tls" | "insecure";
     /** Whether BeforeTurnKernel retrieval is enabled. Default: true */
     beforeTurnEnabled?: boolean;
+    /** Enable verbose BeforeTurnKernel diagnostic logging. Default: false */
+    beforeTurnDebug?: boolean;
     /** Timeout in milliseconds for the BeforeTurnKernel gRPC call. Default: 5000 */
     beforeTurnTimeoutMs?: number;
     /** Timeout in milliseconds for the AssembleContextInternal gRPC call. Default: 30000 */

package/docs/debugging-tool-loop-regression.md

@@ -0,0 +1,386 @@
+# Tool Call Loop Regression: v1.8.9 → v1.9.7
+
+## Symptoms
+- LLM outputs verbatim text twice in a single turn
+- LLM executes the same tool call (image gen) twice in a single turn
+- **Intermittent** — does NOT reproduce on every turn; ~50% hit rate
+- **Tool-call-gated** — only occurs on turns involving tool calls (image gen, file ops, etc.). Plain text conversations never trigger it.
+- "Didn't used to happen" — confirmed clean in v1.8.7–1.8.9
+- First observed after v1.9.0 perf rewrite + v1.9.1 live tool protocol changes
+- Affects provider models broadly (MiniMax M2.7 confirmed); Qwen 3.5 32B INT4 was the target model for the live tool protocol harness
+
+**Intermittent nature → race condition, not deterministic logic bug. Tool-only gating → the race specifically affects turns where the daemon's context replay contains tool protocol from the prior turn.**
+
+## Observations
+
+### O1: ~50% hit rate, tool calls only
+Duplication happens roughly half the time on tool call turns. It never triggers on plain text conversations. This narrows the scope to the tool protocol code paths — specifically the cursor-based gates that only activate when `hasKernelToolCallBlock` or `isToolResultRole` match.
+
+### O2: Async ingestion timing window
+The 50/50 split is consistent with a two-processor race: the LLM provider response time (variable, 2-8s) vs the daemon `afterTurn` ingestion time (variable, 0.5-3s). When the provider is slow and ingestion is fast, the async queue drains before the next `assemble()` — no race. When the provider is fast and the daemon is busy (compaction, embedding), the queue hasn't drained — race triggers.
+
+### O3: Regular conversation is immune
+Text-only turns have no tool protocol to classify. The live tool protocol gates (`consumeLiveToolAtCursor`, `findLiveToolSourceInCurrentTurn`) are never entered. The provider replay dedup handles plain text correctly. The race only matters when tool protocol exists in the transcript.
+
+## Timeline
+
+| Version | Key Change | Author |
+|---------|-----------|--------|
+| v1.8.9 | Last known-good | — |
+| v1.9.0 | Perf rewrite: async ingestion, O(1) indexing, memoization caches | Juan |
+| v1.9.1 | Live tool protocol preservation (`78da771`, 164 loc) | Juan |
+| v1.9.4 | Provider replay dedup with source-index awareness | xDarkicex |
+| v1.9.5 | Tool result annotation fix: `[^\n]*` → `\s*` | xDarkicex |
+| v1.9.7 | Assemble deadline (30s) | xDarkicex |
+
+## Theory: Live Tool Protocol Harness Feeds Tool Output Back to Model
+
+The primary suspect is commit `78da771` ("preserve live tool protocol during context assembly", v1.9.0 → v1.9.1). It added a cursor-guarded tool protocol preservation system that re-injects the current turn's tool calls and results from the source transcript into the assembled context, bypassing the provider replay dedup.
+
+**Mechanism:** When the daemon's `assemble()` returns context messages that include historical tool protocol from a prior turn, the `consumeLiveToolAtCursor` and `findLiveToolSourceInCurrentTurn` functions match these against the source transcript. If they match, the original (unsanitized) source message is pushed into context **directly, bypassing the provider-replay dedup** (line 1921).
+
+This works for Qwen 3.5 32B INT4 which needed full tool context to avoid orphaned tools. But for other models, injecting the full tool call JSON + tool result JSON from a prior turn into the next turn's context causes the model to treat it as a new instruction — re-executing the tool and repeating the output.
+
+## Code Comparison
+
+### Message Processing Loop
+
+**v1.8.9** — Simple, flat. One tool gate, then provider replay or memory:
+```typescript
+// v1.8.9 — src/context-engine.ts ~line 1525
+if (Array.isArray(result.messages)) {
+  for (const message of result.messages) {
+    const content = normalizeKernelContent(message.content);
+    const historicalToolSource = getHistoricalToolSource(message.role, message.content, content);
+    let isRealTranscript = false;
+
+    if (sourceMessages) {
+      // O(n²) linear scan — simple, correct
+      isRealTranscript = sourceMessages.some((sm) => {
+        if (message.id && sm.id === message.id) return true;
+        if (sm.role === message.role && normalizeKernelContent(sm.content) === content) return true;
+        return false;
+      });
+    } else {
+      isRealTranscript = message.role === "user" || message.role === "assistant";
+    }
+
+    // SINGLE tool gate — preserve or drop, simple boolean
+    if (isLiveToolProtocolMessage(message, content, sourceMessages)) {
+      messages.push(preserveLiveToolProtocolMessage(message));
+    } else if (isRealTranscript && !historicalToolSource && isProviderReplayRole(message.role)) {
+      // Provider replay — NO dedup, simple push
+      const sanitizedContent = sanitizeToolCallPatterns(content, {
+        stripOpenClawDirectives: message.role === "assistant",
+      });
+      if (isHistoricalAssistantActionPromise(message.role, sanitizedContent)) {
+        continue;
+      }
+      // Push without dedup — works because daemon doesn't duplicate
+      messages.push({
+        role: message.role,
+        content: sanitizedContent,
+        ...(typeof message.id === "string" ? { id: message.id } : {}),
+      });
+    } else {
+      // Memory items only
+      if (content.trim().length > 0) {
+        const sanitizedContent = sanitizeToolCallPatterns(content, {
+          stripOpenClawDirectives: message.role !== "user",
+        });
+        if (sanitizedContent.trim().length > 0 &&
+            shouldRetainHistoricalToolMemory(message.role, historicalToolSource, sanitizedContent)) {
+          pushMemoryItem({ content: sanitizedContent, role: message.role, provenance: ... });
+        }
+      }
+    }
+  }
+}
+```
+
+**v1.9.7** — Complex, cursor-guarded. THREE tool gates, source-index-aware dedup:
+```typescript
+// v1.9.7 — src/context-engine.ts ~line 1894
+if (Array.isArray(result.messages)) {
+  const lastUserIndex = sourceMessages ? findLastUserMessageIndex(sourceMessages) : -1;
+  let liveSourceCursor = sourceMessages ? lastUserIndex + 1 : undefined;
+  let providerReplaySourceCursor: number | undefined = sourceMessages ? 0 : undefined;
+  for (const message of result.messages) {
+    const content = normalizeKernelContent(message.content);
+    const historicalToolSource = getHistoricalToolSource(message.role, message.content, content);
+    let isRealTranscript = false;
+    if (sourceMessages) {
+      isRealTranscript = findMatchingSourceMessageIndex(message, content, sourceMessages) >= 0;
+    } else {
+      isRealTranscript = message.role === "user" || message.role === "assistant";
+    }
+
+    // GATE 1: consumeLiveToolAtCursor — cursor-guarded, pushes source message directly
+    const liveToolProtocolSource = consumeLiveToolAtCursor(
+      message, content, sourceMessages, liveSourceCursor,
+      lastUserIndex >= 0 ? lastUserIndex : undefined,
+    );
+    if (liveToolProtocolSource) {
+      // ⚠️ PUSHES DIRECTLY — bypasses provider-replay dedup entirely (line 1921)
+      messages.push(preserveLiveToolProtocolMessage(liveToolProtocolSource.message));
+      liveSourceCursor = liveToolProtocolSource.index + 1;
+    }
+    // GATE 2: findLiveToolSourceInCurrentTurn — additional skip gate
+    else if (findLiveToolSourceInCurrentTurn(message, content, sourceMessages, undefined,
+             lastUserIndex >= 0 ? lastUserIndex : undefined) >= 0) {
+      // ⚠️ Silently skips — message is dropped
+      if (liveSourceCursor !== undefined && sourceMessages) {
+        const idx = findMatchingSourceMessageIndex(message, content, sourceMessages, liveSourceCursor);
+        if (idx >= liveSourceCursor) liveSourceCursor = idx + 1;
+      }
+      continue;
+    }
+    // GATE 3: Historical tool derived — filters assistant replies after tool protocol
+    else if (isRealTranscript && !historicalToolSource && isProviderReplayRole(message.role)) {
+      if (isHistoricalToolDerivedAssistantReply(message, content, sourceMessages)) {
+        // ... cursor advance, continue
+      }
+      const sanitizedContent = sanitizeToolCallPatterns(content, {
+        stripOpenClawDirectives: message.role === "assistant",
+      });
+      if (isHistoricalAssistantActionPromise(message.role, sanitizedContent)) {
+        // ... cursor advance, continue
+      }
+      // ⚠️ pushProviderReplayMessage — has dedup, but only for provider replay path
+      const providerReplaySourceIndex = sourceMessages
+        ? findMatchingSourceMessageIndex(message, content, sourceMessages, providerReplaySourceCursor)
+        : undefined;
+      pushProviderReplayMessage(
+        { role: message.role, content: sanitizedContent, ... },
+        providerReplaySourceIndex,
+      );
+    }
+    else {
+      // Memory items
+      // ...
+    }
+  }
+}
+```
+
+### Live Tool Protocol Functions
+
+**v1.8.9** — Simple boolean check:
+```typescript
+function isLiveToolProtocolMessage(
+  message: { role: string; content?: unknown; id?: string },
+  normalizedContent: string,
+  sourceMessages: OpenClawCompatibleMessage[] | undefined,
+): boolean {
+  if (!sourceMessages) return false;
+  if (!isToolResultRole(message.role) && !hasKernelToolCallBlock(message.content)) return false;
+
+  const lastUserIndex = findLastUserMessageIndex(sourceMessages);
+  const sourceIndex = findMatchingSourceMessageIndex(
+    message, normalizedContent, sourceMessages, lastUserIndex + 1,
+  );
+  if (sourceIndex < 0) return false;
+  if (sourceIndex <= lastUserIndex) return false;
+  if (hasCompletedAssistantResponseAfter(sourceMessages, sourceIndex)) return false;
+  if (hasKernelToolCallBlock(message.content)) return true;
+  return hasLiveToolCallBefore(sourceMessages, lastUserIndex, sourceIndex, getToolResultCallId(message));
+}
+```
+
+**v1.9.7** — Cursor-guarded, returns source message + index for position tracking:
+```typescript
+function findLiveToolSourceInCurrentTurn(
+  message: { role: string; content?: unknown; id?: string; [key: string]: unknown },
+  normalizedContent: string,
+  sourceMessages: OpenClawCompatibleMessage[] | undefined,
+  preferredStartIndex?: number,
+  providedLastUserIndex?: number,
+): number {
+  if (!sourceMessages) return -1;
+  // ⚠️ Allow assistant messages through — daemon flattens structured toolCall blocks into
+  // [tool:name] text, which no longer triggers hasKernelToolCallBlock
+  if (!isToolResultRole(message.role) && message.role !== "assistant" && !hasKernelToolCallBlock(message.content)) {
+    return -1;
+  }
+
+  const lastUserIndex = providedLastUserIndex ?? findLastUserMessageIndex(sourceMessages);
+  if (lastUserIndex < 0) return -1;
+  const searchStartIndex = preferredStartIndex === undefined
+    ? lastUserIndex + 1
+    : Math.max(lastUserIndex + 1, preferredStartIndex);
+  const sourceIndex = findMatchingSourceMessageIndex(message, content, sourceMessages, searchStartIndex);
+  if (sourceIndex < searchStartIndex) return -1;
+  if (hasCompletedAssistantResponseAfter(sourceMessages, sourceIndex)) return -1;
+
+  const sourceMessage = sourceMessages[sourceIndex];
+  if (!sourceMessage) return -1;
+  if (sourceMessage.role === "assistant" && hasKernelToolCallBlock(sourceMessage.content)) {
+    return sourceIndex;
+  }
+  if (isToolResultRole(sourceMessage.role)) {
+    const toolCallId = getToolResultCallId(sourceMessage) ?? getToolResultCallId(message);
+    if (hasLiveToolCallBefore(sourceMessages, lastUserIndex, sourceIndex, toolCallId)) {
+      return sourceIndex;
+    }
+  }
+  return -1;
+}
+```
+
+Key difference: v1.9.7 added `message.role !== "assistant"` as an allow condition — daemon-flattened `[tool:name]` text from assistant messages now passes through where v1.8.9's `hasKernelToolCallBlock` would have filtered them.
+
+## Theories
+
+### T0: Async ingestion races with next assemble() — cursor base shifts (HIGHEST)
+
+v1.9.0 (commit `20dc976`, PR #329) made `afterTurn` ingestion asynchronous — it's enqueued via `enqueueAsyncIngestion()` instead of `await`ed inline. The daemon call that ingests the assistant's tool call response may complete AFTER the next `assemble()` starts.
+
+When this race hits:
+1. Turn N finishes. LLM generated "An army of me" + `[tool:image_gen]`.
+2. `afterTurn` is enqueued but hasn't completed yet.
+3. Turn N+1 starts. User sends next message. `assemble()` runs.
+4. The source transcript passed to `normalizeAssembleResult` does NOT yet include the assistant's tool call response from turn N.
+5. `consumeLiveToolAtCursor` and `findLiveToolSourceInCurrentTurn` compute cursors against a stale transcript.
+6. When the async afterTurn FINALLY completes, the next `assemble()` NOW sees the tool protocol in the transcript — cursor behavior changes.
+7. Depending on provider latency and message cadence, the race hits ~30-50% of turns.
+
+This explains the intermittency perfectly. Before v1.9.0, `afterTurn` was synchronous — the daemon call completed before the LLM response started streaming. The source transcript was always up-to-date. The cursor was always computed against a complete transcript.
+
+**Evidence for T0:**
+- Intermittent, ~50% hit rate → timing-dependent, not a code path always taken
+- Only occurs on tool call turns (O1) → the race specifically affects cursor-based tool protocol classification
+- Regular conversations are immune (O3) → `consumeLiveToolAtCursor` / `findLiveToolSourceInCurrentTurn` are only entered when tool protocol exists
+- 50/50 split matches two-variable race window (O2) — provider latency 2-8s vs daemon ingest latency 0.5-3s
+- v1.8.9 was synchronous → `afterTurn` always completed before next `assemble()` → no race, clean
+- v1.9.0 introduced async ingestion → race introduced
+- v1.9.1 added cursor-based tool protocol → race affects tool call classification specifically
+
+### T1: Daemon-flattened assistant tool calls leak through (HIGH)
+
+In v1.9.7, the `findLiveToolSourceInCurrentTurn` function allows `message.role === "assistant"` through (line ~489). The comment says "Daemon flattens structured toolCall blocks into [tool:name] text, which no longer triggers hasKernelToolCallBlock."
+
+When the daemon returns a previous turn's assistant response that contained a tool call, the flattened `[tool:image_gen]` text matches against the source transcript. The function finds the source message, gates 1 or 2 fire, and:
+- Gate 1 pushes the original (unsanitized) source message directly
+- Gate 2 drops it with `continue`
+
+BUT: Gate 1 pushes **unsanitized** source messages. If the source message contains the full structured tool call JSON block, the model sees the complete tool call syntax and re-executes it.
+
+**T1 is gated on T0** — the race determines whether the source transcript is in a state where this match occurs.
+
+### T2: consumeLiveToolAtCursor pushes message that provider replay also matches (MEDIUM)
+
+Gate 1 pushes via `preserveLiveToolProtocolMessage` and advances `liveSourceCursor`. But if the SAME message appears again in the daemon's output (e.g., daemon returns it twice — once from session_raw, once from session_summary), the second occurrence won't match gate 1 (cursor advanced past it) but COULD fall through to gate 3 (provider replay) and get pushed again.
+
+The `pushProviderReplayMessage` dedup should catch this, but only if the sanitized content matches exactly. If the source message and daemon message have different formats, the keys won't match.
+
+**T2 is gated on T0** — the transcript state affects whether daemon returns duplicate entries.
+
+## Comparison: lossless-claw Tool Dedup Approach
+
+The `lossless-claw` plugin (in `/tmp/lossless-claw`) implements a more robust approach to tool call deduplication that our plugin lacks.
+
+### What lossless-claw does differently
+
+**1. Tool-use ID-based dedup** (`filterAssistantToolUseBlocks`, transcript-repair.ts:211-254)
+```typescript
+function filterAssistantToolUseBlocks(msg, seenToolUseIds, options) {
+  for (const block of content) {
+    const id = extractToolCallId(rec);
+    if (isToolUse && id) {
+      if (dropAll || seenToolUseIds.has(id)) {
+        dropped.push({ id, reason: dropAll ? "terminal" : "duplicate" });
+        continue; // ← drops duplicate tool_use blocks by ID
+      }
+      if (record) seenToolUseIds.add(id);
+    }
+    kept.push(block);
+  }
+}
+```
+Tracks tool call IDs in a `Set`. If the same `tool_use` block ID appears in a second assistant message, it's dropped immediately. **Our plugin has no tool-ID-based dedup at all** — it relies on content hashing which fails when the same tool call is formatted differently between daemon-flattened and source-message forms.
+
+**2. Tool-result ID-based dedup** (`pushToolResult`, transcript-repair.ts:311-322)
+```typescript
+const pushToolResult = (msg) => {
+  const id = extractToolResultId(msg);
+  if (id && seenToolResultIds.has(id)) {
+    droppedDuplicateCount += 1; // ← drops duplicate tool results by ID
+    return;
+  }
+  if (id) seenToolResultIds.add(id);
+  out.push(msg);
+};
+```
+Duplicated tool results (same `toolCallId`) are dropped. Our plugin pushes tool results as provider replay messages with no tool-ID tracking — the content-based dedup key `${role}\0${content}` doesn't know about tool call IDs at all.
+
+**3. Transcript repair** (`sanitizeToolUseResultPairing`, transcript-repair.ts:286-538)
+- Moves `toolResult` messages directly after their matching assistant `tool_use` turn
+- Inserts synthetic error `toolResult` for missing tool call IDs
+- Drops orphaned `toolResult` messages with no matching `tool_use`
+- Drops duplicate `toolResult` messages (same ID)
+- Handles error/aborted turns via `dropAll: true, record: false` mode
+
+Our plugin has **no transcript repair at all**. If the daemon returns tool results out of order or orphaned, our plugin passes them through as-is.
+
+**4. Content-hash dedup with ordinal tracking** (`buildMessageContentDuplicateClusters`, assembler.ts:1198-1209)
+```typescript
+function buildMessageContentDuplicateClusters(items) {
+  for (const item of items) {
+    const hash = hashText(item.text);
+    const existing = clusters.get(hash) ?? [];
+    existing.push(item);
+    clusters.set(hash, existing);
+  }
+  return formatDuplicateClusters(clusters, () => "message-content");
+}
+```
+Groups messages by content hash, then reports clusters with >1 item as duplicates. This is diagnostic-only (used for overflow reporting), not active dedup — but it surfaces when the same content appears multiple times.
+
+**5. Replay-ID dedup** (`extractPlainToolReplayTextsById`, engine.ts:521-534)
+```typescript
+function extractPlainToolReplayTextsById(message) {
+  const textsById = new Map();
+  const duplicateIds = new Set();
+  const addText = (replayId, text) => {
+    if (duplicateIds.has(replayId)) return;           // ← already known duplicate
+    if (textsById.has(replayId)) {
+      textsById.delete(replayId);                     // ← second sighting = duplicate
+      duplicateIds.add(replayId);
+      return;
+    }
+    textsById.set(replayId, text);
+  };
+  // ... extracts tool replay texts keyed by toolCallId
+}
+```
+Tracks replay IDs. First occurrence is stored. Second occurrence marks it as duplicate and removes from output. Third+ occurrences are dropped silently. This is applied during `afterTurn` ingestion to prevent duplicate tool results from being stored.
+
+### Gap analysis: what our plugin is missing
+
+| Capability | lossless-claw | libravdb-memory (ours) | Impact |
+|---|---|---|---|
+| Tool-use ID dedup | `filterAssistantToolUseBlocks` — `Set<string>` by ID | None — content-based only | Same tool call with different formatting leaks through |
+| Tool-result ID dedup | `pushToolResult` — `Set<string>` by ID | None — content-based only | Same tool result appears twice in context |
+| Transcript repair | `sanitizeToolUseResultPairing` — reorder, fill gaps, drop orphans | None | Out-of-order tool protocol confuses model |
+| Content hash clusters | `buildMessageContentDuplicateClusters` — diagnostic | None | Can't detect when dedup fails |
+| Replay-ID dedup | `extractPlainToolReplayTextsById` — at ingest time | None | Duplicate tool results stored in daemon |
+| AfterTurn batch dedup | `deduplicateAfterTurnBatch` — tail/suffix match | None | Redundant ingestion of already-stored turns |
+
+### Why this matters for the looping bug
+
+The live tool protocol system (`78da771`) injects source-format tool messages into context without tracking tool call IDs. If the daemon's context replay includes the same tool call message twice (once from `session_raw`, once from `session_summary`), both instances get pushed because:
+
+1. `consumeLiveToolAtCursor` pushes the first instance directly (bypasses dedup)
+2. The second instance falls through to provider replay path
+3. `pushProviderReplayMessage` checks `${role}\0${content}` — but the daemon-flattened `[tool:image_gen]` format differs from the source-format structured tool call JSON
+4. Keys don't match → both are pushed → model sees duplicate tool instruction
+
+Lossless-claw would catch this because `filterAssistantToolUseBlocks` tracks the actual tool call ID, not the text representation.
+
+## Next Steps
+
+1. **Verify T0 (async race)**: Add a debug log at `assemble()` entry showing `sourceMessages.length`, `lastUserIndex`, and whether async ingestion queue has pending items. If duplicated turns correlate with stale transcript length (e.g., missing the last assistant response), T0 is confirmed.
+
+2. **Mitigation — drain async queue before assemble**: In `assemble()`, `await` the session's async ingestion queue before computing cursors. The `FLUSH_ASYNC_INGESTION` Symbol hook already exists. If blocking on ingest adds too much latency, add a short deadline (2s).
+
+3. **Hardening — make cursor computation tolerate stale transcripts**: If the source transcript is incomplete (async ingest pending), `findLiveToolSourceInCurrentTurn` and `consumeLiveToolAtCursor` should treat unconfirmed messages as historical, not live. Currently they treat anything findable after `lastUserIndex` as live.

package/docs/subagent-finds.md

@@ -0,0 +1,241 @@
+# Subagent Memory Access — Design Analysis
+
+## Status
+
+**Architectural gap identified.** `contextMode: "fork"` is dead code. Subagents cannot currently access parent session memories.
+
+---
+
+## Current Implementation
+
+### Subagent Token Budget
+
+```typescript
+// context-engine.ts:2040-2044
+function normalizeSubagentTokenBudget(value: unknown): number {
+  if (typeof value !== "number") return 8000;
+  if (!Number.isFinite(value) || value < 0) return 8000;
+  return Math.floor(value);
+}
+```
+
+- Default: 8000 tokens
+- `0` disables `memory_expand` entirely
+- Budget tracked by `childSessionKey` in `Map<string, BudgetEntry>`
+
+### prepareSubagentSpawn (Dead Code)
+
+```typescript
+// context-engine.ts:3173-3205
+async prepareSubagentSpawn(params: {
+  parentSessionKey: string;
+  childSessionKey: string;
+  contextMode?: "isolated" | "fork";  // DEFINED BUT NEVER USED
+  parentSessionId?: string;
+  parentSessionFile?: string;
+  childSessionId?: string;
+  childSessionFile?: string;
+  ttlMs?: number;
+}) {
+  const budget = normalizeSubagentTokenBudget(cfg.subagentTokenBudget);
+  const key = subagentKey(params.childSessionKey);
+  subagentBudgets.set(key, { remaining: budget, total: budget, expiresAt: ... });
+  // contextMode is never read — no fork/isolate logic exists
+}
+```
+
+### Session Isolation
+
+```typescript
+// memory-runtime.ts:229-253
+function resolveSearchCollections(cfg, userId, sessionId, corpus) {
+  if (corpus === "sessions") {
+    return sessionId ? [resolveSessionSearchCollection(cfg, sessionId)] : [];
+  }
+  // ...
+  // Subagent session collection = session:${subagentSessionId}
+  // Parent session collection = session:${parentSessionId}
+  // They are DIFFERENT collections — no cross-access
+}
+```
+
+---
+
+## Lossless-Claw Approach (Reference)
+
+### Session Key Pattern
+
+```
+agent:<agentId>:session:<sessionId>      // main agent
+agent:<agentId>:subagent:<uuid>          // subagent
+```
+
+### Parent Context Passing
+
+```typescript
+// Subagent session key encodes parent agentId
+const childSessionKey = `agent:${requesterAgentId}:subagent:${crypto.randomUUID()}`
+```
+
+### Delegation Grant System
+
+Grants are scoped to specific conversation IDs and bound to the child session key.
+
+### Fork Mode Bootstrap
+
+> "For forked child sessions, LCM treats a host-copied parent JSONL branch as a first-time bootstrap source and imports only the newest messages that fit within `bootstrapMaxTokens`."
+
+---
+
+## Required Implementation
+
+### 1. Session Key Format
+
+Adopt lossless-claw pattern for consistent agent/session encoding:
+
+```
+session-key:agent:<agentId>:session:<sessionId>      // main agent
+session-key:agent:<agentId>:subagent:<uuid>          // subagent
+```
+
+Or simpler (preserve current format but encode parent relationship):
+
+```
+<current-session-key>:fork:<parent-session-key>      // fork mode child
+```
+
+### 2. Implement contextMode: "fork"
+
+When `contextMode === "fork"`:
+
+1. Store `parentSessionId` in subagent budget entry
+2. In `resolveSearchCollections()`, if fork mode and `sessionId` is a child:
+   - Include parent's session collection in search scope
+3. Subagent can bootstrap from parent's session_summary and session_raw
+
+```typescript
+// In subagentBudgets Map
+interface SubagentBudgetEntry {
+  remaining: number;
+  total: number;
+  expiresAt: number;
+  parentSessionId?: string;  // Added for fork mode
+  contextMode: "isolated" | "fork";
+}
+
+// In resolveSearchCollections
+if (entry.contextMode === "fork" && entry.parentSessionId) {
+  collections.push(resolveSessionSearchCollection(cfg, entry.parentSessionId));
+}
+```
+
+### 3. Per-Agent Config
+
+```typescript
+// openclaw.plugin.json configSchema addition
+{
+  "agentOverrides": {
+    "type": "object",
+    "additionalProperties": true,
+    "description": "Per-agent configuration overrides keyed by agentId"
+  }
+}
+```
+
+Config resolution:
+
+```typescript
+function resolveAgentConfig(cfg: PluginConfig, agentId?: string): Partial<PluginConfig> {
+  if (!agentId || !cfg.agentOverrides?.[agentId]) {
+    return {};
+  }
+  return cfg.agentOverrides[agentId];
+}
+```
+
+Usage in budget normalization:
+
+```typescript
+function getEffectiveSubagentTokenBudget(cfg: PluginConfig, agentId?: string): number {
+  const overrides = resolveAgentConfig(cfg, agentId);
+  const value = overrides.subagentTokenBudget ?? cfg.subagentTokenBudget;
+  return normalizeSubagentTokenBudget(value);
+}
+```
+
+### 4. Subagent Session Key Encoding
+
+When OpenClaw spawns a subagent, it provides:
+- `ctx.sessionKey` — the child's session key
+- `ctx.agentId` — may be different from parent or undefined
+
+We can detect subagent via:
+- Session key suffix pattern (if OpenClaw encodes it)
+- Parent-child relationship via lifecycle hooks
+
+Current detection (not implemented):
+
+```typescript
+// context-engine.ts
+function isSubagentSessionKey(sessionKey: string): boolean {
+  // Pattern: detect if this is a subagent spawn vs main agent
+  // Depends on OpenClaw's session key format for subagents
+}
+```
+
+---
+
+## OpenClaw Agent Flag
+
+OpenClaw supports `--agent <id>` for multi-agent deployments. The plugin receives `agentId` via `OpenClawPluginToolContext`.
+
+Current handling:
+- `LIBRAVDB_AGENT_ID` env var for container/CI override
+- `cfg.tenantId` for explicit DB isolation
+- `resolveTenantKey()` priority: `tenantId` > `LIBRAVDB_AGENT_ID` > `userId`
+
+For per-agent memory isolation:
+- Different `--agent` values → different `agentId` → different collection namespaces
+- Agent's subagents inherit same `agentId` in session key pattern
+
+---
+
+## Implementation Priority
+
+| Priority | Item | Description |
+|----------|------|-------------|
+| P0 | Session key pattern | Define how parent/child relationship is encoded |
+| P1 | contextMode: "fork" | Implement parent session access for fork mode |
+| P2 | Per-agent config | Add `agentOverrides` to configSchema |
+| P3 | Bootstrap token limit | Prevent parent import from exceeding budget |
+
+---
+
+## Files to Modify
+
+- `src/context-engine.ts` — implement fork mode in `prepareSubagentSpawn` and `resolveSearchCollections`
+- `src/memory-scopes.ts` — add subagent session key parsing
+- `src/openclaw.plugin.json` — add `agentOverrides` to configSchema
+- `src/plugin-runtime.ts` — pass agentId to config resolution
+- `src/tools/memory-recall.ts` — include parent session in grep when fork mode
+
+---
+
+## Rejected Approaches
+
+### excludeAgents / excludeSubagents
+
+Peetie's proposal to exclude agents from memory injection is a blunt instrument that:
+1. Bypasses proper isolation (agents are already isolated by session collection)
+2. Cannot grant selective access (all-or-nothing)
+3. Doesn't solve the fork use case (subagent needs parent access, not exclusion)
+
+The correct solution is proper fork mode, not exclusion lists.
+
+---
+
+## References
+
+- Lossless-claw: `src/plugin/index.ts:44-59` (session key parsing)
+- Lossless-claw: `src/focus-briefs.ts:737` (child session key creation)
+- Lossless-claw: `docs/architecture.md:215-224` (fork bootstrap)

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Persistent vector memory with three-tier hybrid scoring",
-  "version": "1.9.9",
+  "version": "1.9.10-beta.2",
   "kind": [
     "memory",
     "context-engine"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.9.9",
+  "version": "1.9.10-beta.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",