agenr 0.8.21 → 0.8.23

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.8.22] - 2026-02-23
+
+### Changed
+- feat(openclaw-plugin): replace thin-prompt/stash session-start recall with three-phase
+  cross-session context injection (issue #205)
+  - Phase 1A (always): reads last 7 user+assistant turns from most recently modified
+    session JSONL file in ~/.openclaw/agents/<agentId>/sessions/
+  - Phase 1B (always): runs agenr recall --browse --since 1d --limit 20, picks up
+    importance:10 handoff entry written at /new time
+  - Phase 2 (conditional): semantic recall seeded from Phase 1A turns + first user
+    message if >= 5 words; results deduplicated against Phase 1B by entry id
+  - Handoff entries retired after first use (one-time read)
+- feat(openclaw-plugin): added findPreviousSessionFile, extractRecentTurns,
+  buildSemanticSeed to src/openclaw-plugin/session-query.ts
+- feat(openclaw-plugin): findPreviousSessionFile uses parallel stat() calls for
+  performance on large sessions dirs
+- feat(openclaw-plugin): sessionsDir configurable via AgenrPluginConfig.sessionsDir;
+  defaults to ~/.openclaw/agents/<agentId>/sessions using ctx.agentId with "main"
+  fallback
+- feat(openclaw-plugin): RunRecallOptions extended with limit?: number to support
+  --limit flag in browse recall
+- refactor(openclaw-plugin): removed isThinPrompt, resolveSessionQuery,
+  sessionTopicStash, stashSessionTopic, shouldStashTopic, sweepInterval, clearStash,
+  readLatestArchivedUserMessages
+
+### Tests
+- test(openclaw-plugin): added unit tests for findPreviousSessionFile, extractRecentTurns,
+  buildSemanticSeed in session-query.test.ts
+- test(openclaw-plugin): added integration tests for three-phase before_prompt_build flow,
+  Phase 2 deduplication, and isFirstInSession guard in index.test.ts
+- test(openclaw-plugin): added second-message guard test (isFirstInSession prevents
+  re-injection on subsequent messages in same session)
+
 ## [0.8.19] - 2026-02-23
 
 ### Changed

package/dist/openclaw-plugin/index.d.ts

@@ -76,7 +76,6 @@ declare const plugin: {
     register(api: PluginApi): void;
 };
 declare const __testing: {
-    SESSION_TOPIC_TTL_MS: number;
     clearState(): void;
 };
 

package/dist/openclaw-plugin/index.js

@@ -8,6 +8,8 @@ import {
 
 // src/openclaw-plugin/index.ts
 import { Type } from "@sinclair/typebox";
+import os from "os";
+import path3 from "path";
 
 // src/openclaw-plugin/recall.ts
 import { spawn } from "child_process";
@@ -45,6 +47,9 @@ async function runRecall(agenrPath, budget, project, query, options) {
     }
     const isBrowse = options?.context === "browse";
     const args = isBrowse ? ["recall", "--browse", "--since", options?.since ?? "1d", "--json"] : ["recall", "--context", "session-start", "--budget", String(budget), "--json"];
+    if (isBrowse && options?.limit !== void 0) {
+      args.push("--limit", String(options.limit));
+    }
     if (project) {
       args.push("--project", project);
     }
@@ -143,15 +148,15 @@ function formatRecallAsMarkdown(result) {
 }
 
 // src/openclaw-plugin/session-query.ts
-import { readFile, readdir, stat } from "fs/promises";
+import { createReadStream } from "fs";
+import { readdir, stat } from "fs/promises";
 import path2 from "path";
-var SESSION_TOPIC_TTL_MS = 60 * 60 * 1e3;
-var SESSION_TOPIC_MIN_LENGTH = 40;
-var ARCHIVED_SESSION_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
-var SESSION_QUERY_LOOKBACK = 3;
+import { createInterface } from "readline";
 var EXCHANGE_TEXT_MAX_CHARS = 200;
 var EXCHANGE_USER_TURN_LIMIT = 5;
-var sessionTopicStash = /* @__PURE__ */ new Map();
+var RECENT_TURN_MAX_CHARS = 150;
+var SEMANTIC_SEED_PREVIOUS_TURNS_MAX_CHARS = 400;
+var DEFAULT_RECENT_TURN_LIMIT = 7;
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -209,13 +214,8 @@ function extractTextFromAssistantMessage(message) {
   }
   return textParts.join(" ").trim();
 }
-function truncateMessageText(text) {
-  return text.length > EXCHANGE_TEXT_MAX_CHARS ? text.slice(0, EXCHANGE_TEXT_MAX_CHARS) : text;
-}
-var OPENCLAW_BARE_RESET_PREFIX = "a new session was started via /new";
-function isThinPrompt(prompt) {
-  const trimmed = prompt.trim().toLowerCase();
-  return trimmed === "" || trimmed === "/new" || trimmed === "/reset" || trimmed.startsWith(OPENCLAW_BARE_RESET_PREFIX);
+function truncateMessageText(text, maxChars = EXCHANGE_TEXT_MAX_CHARS) {
+  return text.length > maxChars ? text.slice(0, maxChars) : text;
 }
 function stripPromptMetadata(raw) {
   if (!raw) {
@@ -236,25 +236,6 @@ function stripPromptMetadata(raw) {
     return "";
   }
 }
-function extractLastUserText(messages) {
-  try {
-    const collected = [];
-    for (let index = messages.length - 1; index >= 0; index -= 1) {
-      const extracted = extractTextFromUserMessage(messages[index]);
-      if (!extracted) {
-        continue;
-      }
-      collected.push(extracted);
-      if (collected.length >= SESSION_QUERY_LOOKBACK) {
-        break;
-      }
-    }
-    const joined = collected.reverse().join(" ").trim();
-    return joined || "";
-  } catch {
-    return "";
-  }
-}
 function extractLastExchangeText(messages, maxTurns = EXCHANGE_USER_TURN_LIMIT) {
   try {
     if (!Array.isArray(messages) || messages.length === 0) {
@@ -292,74 +273,124 @@ function extractLastExchangeText(messages, maxTurns = EXCHANGE_USER_TURN_LIMIT)
     return "";
   }
 }
-function shouldStashTopic(text) {
-  if (text.length < SESSION_TOPIC_MIN_LENGTH) {
-    return false;
-  }
-  const wordCount = text.split(/\s+/).filter(Boolean).length;
-  return wordCount >= 5;
-}
-function sweepExpiredStash() {
-  const now = Date.now();
-  for (const [key, entry] of sessionTopicStash) {
-    if (now - entry.storedAt > SESSION_TOPIC_TTL_MS) {
-      sessionTopicStash.delete(key);
+async function findPreviousSessionFile(sessionsDir, currentSessionId, logger) {
+  try {
+    const normalizedSessionId = currentSessionId?.trim();
+    const currentSessionFileName = normalizedSessionId ? `${normalizedSessionId}.jsonl` : void 0;
+    const entries = await readdir(sessionsDir, { withFileTypes: true });
+    const candidatePaths = [];
+    for (const entry of entries) {
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (!entry.name.endsWith(".jsonl")) {
+        continue;
+      }
+      if (entry.name.includes(".deleted.")) {
+        continue;
+      }
+      if (currentSessionFileName && entry.name === currentSessionFileName) {
+        continue;
+      }
+      candidatePaths.push(path2.join(sessionsDir, entry.name));
     }
-  }
-}
-var sweepInterval = setInterval(sweepExpiredStash, 5 * 60 * 1e3);
-if (sweepInterval !== void 0 && typeof sweepInterval.unref === "function") {
-  sweepInterval.unref();
-}
-function stripResetPrefix(prompt) {
-  const lower = prompt.toLowerCase();
-  for (const cmd of ["/new", "/reset"]) {
-    if (lower.startsWith(cmd + " ")) {
-      return prompt.slice(cmd.length).trim();
+    if (candidatePaths.length === 0) {
+      return null;
     }
-  }
-  return prompt;
-}
-function resolveSessionQuery(prompt, sessionKey) {
-  let stashedText;
-  if (sessionKey) {
-    const entry = sessionTopicStash.get(sessionKey);
-    if (entry) {
-      sessionTopicStash.delete(sessionKey);
-      const expired = Date.now() - entry.storedAt > SESSION_TOPIC_TTL_MS;
-      if (!expired && entry.text.length > 0) {
-        stashedText = entry.text;
-      }
+    const statResults = await Promise.all(
+      candidatePaths.map(async (filePath) => {
+        try {
+          const fileStats = await stat(filePath);
+          return { filePath, mtimeMs: fileStats.mtimeMs };
+        } catch {
+          return null;
+        }
+      })
+    );
+    const candidates = statResults.filter(
+      (result) => result !== null
+    );
+    if (candidates.length === 0) {
+      return null;
     }
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return candidates[0]?.filePath ?? null;
+  } catch (err) {
+    logger?.debug?.(
+      `[agenr] findPreviousSessionFile: failed to read sessions dir "${sessionsDir}": ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
   }
-  const normalized = (prompt ?? "").trim();
-  if (!isThinPrompt(normalized)) {
-    const stripped = stripResetPrefix(normalized);
-    if (!stashedText) {
-      return stripped;
+}
+async function extractRecentTurns(filePath, maxTurns = DEFAULT_RECENT_TURN_LIMIT) {
+  try {
+    if (!filePath) {
+      return "";
     }
-    if (shouldStashTopic(stripped)) {
-      return `${stashedText} ${stripped}`;
+    const parsedMaxTurns = Number.isFinite(maxTurns) ? Math.max(0, Math.trunc(maxTurns)) : 0;
+    if (parsedMaxTurns === 0) {
+      return "";
     }
-    return stashedText;
+    const ring = [];
+    await new Promise((resolve, reject) => {
+      const rl = createInterface({
+        input: createReadStream(filePath, { encoding: "utf8" }),
+        crlfDelay: Infinity
+      });
+      rl.on("line", (line) => {
+        const trimmed = line.trim();
+        if (!trimmed) {
+          return;
+        }
+        let record;
+        try {
+          record = JSON.parse(trimmed);
+        } catch {
+          return;
+        }
+        if (!isRecord(record) || record["type"] !== "message") {
+          return;
+        }
+        const message = record["message"];
+        const userText = extractTextFromUserMessage(message);
+        if (userText) {
+          ring.push(`U: ${truncateMessageText(userText, RECENT_TURN_MAX_CHARS)}`);
+          if (ring.length > parsedMaxTurns) {
+            ring.shift();
+          }
+          return;
+        }
+        const assistantText = extractTextFromAssistantMessage(message);
+        if (assistantText) {
+          ring.push(`A: ${truncateMessageText(assistantText, RECENT_TURN_MAX_CHARS)}`);
+          if (ring.length > parsedMaxTurns) {
+            ring.shift();
+          }
+        }
+      });
+      rl.on("close", resolve);
+      rl.on("error", reject);
+    });
+    return ring.join(" | ");
+  } catch {
+    return "";
   }
-  return stashedText;
 }
-function stashSessionTopic(sessionKey, text) {
-  if (!shouldStashTopic(text)) {
-    return;
+function buildSemanticSeed(previousTurns, firstUserMessage) {
+  const stripped = stripPromptMetadata(firstUserMessage).trim();
+  const wordCount = stripped.split(/\s+/).filter(Boolean).length;
+  const messageHasSignal = wordCount >= 5;
+  const truncatedTurns = previousTurns.slice(0, SEMANTIC_SEED_PREVIOUS_TURNS_MAX_CHARS);
+  if (truncatedTurns && messageHasSignal) {
+    return `${truncatedTurns} ${stripped}`;
   }
-  sessionTopicStash.set(sessionKey, {
-    text,
-    storedAt: Date.now()
-  });
-}
-function clearStash() {
-  sessionTopicStash.clear();
-  if (sweepInterval !== void 0) {
-    clearInterval(sweepInterval);
-    sweepInterval = void 0;
+  if (truncatedTurns) {
+    return truncatedTurns;
+  }
+  if (messageHasSignal) {
+    return stripped;
   }
+  return void 0;
 }
 
 // src/db/signals.ts
@@ -967,51 +998,88 @@ var plugin = {
             const agenrPath = resolveAgenrPath(config);
             const budget = resolveBudget(config);
             const project = config?.project?.trim() || void 0;
-            const userPrompt = stripPromptMetadata(event.prompt ?? "");
-            const queryText = resolveSessionQuery(userPrompt, ctx.sessionKey);
-            let recallResult;
-            const isColdStart = isFirstInSession && queryText === void 0;
-            if (isColdStart) {
-              if (!ctx.agentId?.trim()) {
-                api.logger.debug?.("[agenr] cold-start: agentId not in ctx, defaulting to 'main'");
-              }
-              recallResult = await runRecall(agenrPath, budget, project, void 0, {
+            const agentId = ctx.agentId?.trim() || "main";
+            const sessionsDir = config?.sessionsDir ?? path3.join(os.homedir(), `.openclaw/agents/${agentId}/sessions`);
+            const [previousTurns, browseResult] = await Promise.all([
+              findPreviousSessionFile(sessionsDir, ctx.sessionId, api.logger).then(
+                (file) => file ? extractRecentTurns(file) : Promise.resolve("")
+              ),
+              runRecall(agenrPath, budget, project, void 0, {
                 context: "browse",
-                since: "1d"
-              });
-            } else {
-              recallResult = await runRecall(agenrPath, budget, project, queryText);
-            }
-            if (recallResult) {
-              const formatted = formatRecallAsMarkdown(recallResult);
-              if (formatted.trim()) {
-                markdown = formatted;
+                since: "1d",
+                limit: 20
+              })
+            ]);
+            const seed = buildSemanticSeed(previousTurns, event.prompt ?? "");
+            let semanticResult = null;
+            if (seed) {
+              const browseIds = /* @__PURE__ */ new Set();
+              for (const item of browseResult?.results ?? []) {
+                const id = typeof item.entry?.id === "string" && item.entry.id.trim() ? item.entry.id.trim() : null;
+                if (id) {
+                  browseIds.add(id);
+                }
               }
-              if (isColdStart) {
-                for (const item of recallResult.results) {
-                  const entry = item.entry;
-                  const subject = typeof entry.subject === "string" ? entry.subject : "";
-                  if (!subject.toLowerCase().startsWith("session handoff")) {
-                    continue;
+              const rawSemantic = await runRecall(agenrPath, budget, project, seed);
+              if (rawSemantic) {
+                rawSemantic.results = rawSemantic.results.filter((item) => {
+                  const id = typeof item.entry?.id === "string" && item.entry.id.trim() ? item.entry.id.trim() : null;
+                  if (!id) {
+                    return true;
                   }
-                  const entryId = typeof entry.id === "string" && entry.id.trim() ? entry.id.trim() : null;
-                  if (entryId) {
-                    await runRetireTool(agenrPath, {
+                  return !browseIds.has(id);
+                });
+                semanticResult = rawSemantic.results.length > 0 ? rawSemantic : null;
+              }
+            }
+            if (browseResult) {
+              const retirePromises = [];
+              for (const item of browseResult.results) {
+                const entry = item.entry;
+                const subject = typeof entry.subject === "string" ? entry.subject : "";
+                if (!subject.toLowerCase().startsWith("session handoff")) {
+                  continue;
+                }
+                const entryId = typeof entry.id === "string" && entry.id.trim() ? entry.id.trim() : null;
+                if (entryId) {
+                  retirePromises.push(
+                    runRetireTool(agenrPath, {
                       entry_id: entryId,
                       reason: "consumed at session start"
-                    }).catch((err) => {
+                    }).then(() => void 0).catch((err) => {
                       api.logger.debug?.(
                         `[agenr] session-start: retire handoff ${entryId} failed: ${err instanceof Error ? err.message : String(err)}`
                       );
-                    });
-                  } else {
-                    api.logger.debug?.(
-                      "[agenr] session-start: handoff entry missing id, skipping retire"
-                    );
-                  }
+                    })
+                  );
+                } else {
+                  api.logger.debug?.(
+                    "[agenr] session-start: handoff entry missing id, skipping retire"
+                  );
                 }
               }
+              await Promise.allSettled(retirePromises);
+            }
+            const sections = [];
+            if (previousTurns.trim()) {
+              sections.push(`## Recent session
+${previousTurns.trim()}`);
+            }
+            if (browseResult) {
+              const formatted = formatRecallAsMarkdown(browseResult);
+              if (formatted.trim()) {
+                sections.push(`## Recent memory
+${formatted.trim()}`);
+              }
             }
+            if (semanticResult) {
+              const formatted = formatRecallAsMarkdown(semanticResult);
+              if (formatted.trim()) {
+                sections.push(`## Relevant memory
+${formatted.trim()}`);
+              }
+            }
+            markdown = sections.length > 0 ? sections.join("\n\n") : void 0;
           }
           let signal;
           if (config?.signalsEnabled !== false) {
@@ -1054,10 +1122,6 @@ var plugin = {
         if (!Array.isArray(messages) || messages.length === 0) {
           return;
         }
-        const lastUserText = extractLastUserText(messages);
-        if (shouldStashTopic(lastUserText)) {
-          stashSessionTopic(sessionKey, lastUserText);
-        }
         const handoffText = extractLastExchangeText(messages);
         if (handoffText) {
           const agenrPath = resolveAgenrPath(config);
@@ -1086,7 +1150,7 @@ var plugin = {
         }
       } catch (err) {
         api.logger.warn(
-          `agenr plugin before_reset stash failed: ${err instanceof Error ? err.message : String(err)}`
+          `agenr plugin before_reset failed: ${err instanceof Error ? err.message : String(err)}`
         );
       }
     });
@@ -1242,9 +1306,7 @@ var plugin = {
   }
 };
 var __testing = {
-  SESSION_TOPIC_TTL_MS,
   clearState() {
-    clearStash();
     seenSessions.clear();
     sessionSignalState.clear();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenr",
-  "version": "0.8.21",
+  "version": "0.8.23",
   "openclaw": {
     "extensions": [
       "dist/openclaw-plugin/index.js"