agenr 0.8.15 → 0.8.19

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [0.8.19] - 2026-02-23
+
+### Changed
+- feat(openclaw-plugin): `before_reset` handoff store content now uses a structured recent exchange summary (`U:`/`A:` turns) instead of user-only fragments, improving cross-session handoff clarity while keeping stash-based recall seeding unchanged (issue #196)
+- feat(openclaw-plugin): added `extractLastExchangeText(messages, maxTurns?)` in `src/openclaw-plugin/session-query.ts` to collect the last 5 user-turn windows with interleaved assistant context, per-turn truncation (200 chars), and chronological `U:`/`A:` formatting
+- chore(openclaw-plugin): exported `SESSION_QUERY_LOOKBACK` from `session-query.ts` for direct test assertions
+
+### Tests
+- test(openclaw-plugin): added `extractLastExchangeText` coverage for empty input, U/A formatting, per-message truncation, 5-user-turn collection window, and no-extractable-content behavior
+- test(openclaw-plugin): updated handoff-store integration assertion to verify stored content includes exchange context prefixes (`U:`/`A:`) rather than flattened user-only text
+
+## [0.8.18] - 2026-02-23
+
+### Changed
+- feat(openclaw-plugin): `before_prompt_build` now uses browse-mode recall (`--browse --since 1d`) for cold session starts where no stash/query seed is available, and keeps embed/query recall for substantive or stash-seeded starts (issue #196)
+- chore(openclaw-plugin): removed archived-session fallback query synthesis from session-start recall seeding, simplifying thin-prompt startup behavior to browse vs stash/embed paths only (issue #196)
+- feat(openclaw-plugin): `before_reset` now stores a fire-and-forget `event` memory entry (`session handoff ...`) with the latest user context to support next-session handoff continuity (issue #196)
+- feat(openclaw-plugin): session-start browse results now auto-retire surfaced handoff entries after context injection to avoid repeated carryover (`reason: consumed at session start`) (issue #196)
+- feat(openclaw-plugin): `runRecall` in `src/openclaw-plugin/recall.ts` now accepts an optional context options object and maps browse context to CLI browse args while preserving existing default/session-start call behavior for unchanged callers (issue #196)
+
+### Tests
+- test(openclaw-plugin): updated query-seeding coverage for new cold-start browse path and removed archive-fallback-specific expectations (issue #196)
+- test(openclaw-plugin): added regression coverage for before-reset handoff storage and session-start handoff auto-retire success, non-handoff skip, missing-id skip, and retire-failure resilience (issue #196)
+- test(openclaw-plugin): added plugin recall browse-args unit coverage to assert `runRecall` browse flag construction and query omission behavior (issue #196)
+
+## [0.8.17] - 2026-02-23
+
+### Changed
+- chore: rebuild dist to include browse mode CLI flag inadvertently omitted from 0.8.16 publish
+
+## [0.8.16] - 2026-02-23
+
+### Added
+- feat(recall): new temporal browse mode for recall via `agenr recall --browse` and MCP `agenr_recall` with `context="browse"` (issue #190)
+- docs(recall): added `docs/usage/recall.md` with browse-mode CLI and MCP usage examples
+
+### Changed
+- recall browse mode now uses a SQL-only path that requires no query and performs zero embedding/OpenAI API calls
+- browse mode does not increment recall metadata (`recall_count`, `last_recalled_at`, `recall_intervals`)
+- OpenClaw plugin tool wiring now maps `context="browse"` to the CLI `--browse` flag (and omits query/context positional args appropriately)
+
+### Tests
+- test(recall): added browse-mode coverage in DB recall, CLI command recall, MCP server recall, and OpenClaw plugin recall tool argument wiring
+
 ## [0.8.15] - 2026-02-23
 
 ### Fixed

package/dist/cli-main.js

@@ -3873,6 +3873,13 @@ function scoreEntryWithBreakdown(entry, vectorSim, ftsMatch, now, freshnessNow =
 function scoreEntry(entry, vectorSim, ftsMatch, now) {
   return scoreEntryWithBreakdown(entry, vectorSim, ftsMatch, now).score;
 }
+function scoreBrowseEntry(entry, now) {
+  const daysOld = parseDaysBetween(now, entry.created_at);
+  const HALF_LIFE_DAYS = 30;
+  const recencyFactor = Math.exp(-(daysOld / HALF_LIFE_DAYS) * Math.LN2);
+  const impScore = importanceScore(entry.importance);
+  return clamp01(impScore * recencyFactor);
+}
 function shapeRecallText(text2, context) {
   const trimmedText = text2.trim();
   if (!trimmedText) {
@@ -4020,6 +4027,97 @@ async function fetchSessionCandidates(db, limit, context, platform, project, exc
     };
   });
 }
+async function fetchBrowseCandidates(db, query, limit, now) {
+  const normalizedProject = parseProjectList(query.project);
+  const normalizedExclude = parseProjectList(query.excludeProject);
+  const projectSql = buildProjectFilter({
+    column: "project",
+    strict: Boolean(query.projectStrict && normalizedProject.length > 0),
+    project: normalizedProject.length > 0 ? normalizedProject : void 0,
+    excludeProject: normalizedExclude.length > 0 ? normalizedExclude : void 0
+  });
+  const whereClauses = [
+    "superseded_by IS NULL",
+    "retired = 0"
+  ];
+  if (projectSql.clause.trim()) {
+    whereClauses.push(projectSql.clause.trim().replace(/^AND\s+/i, ""));
+  }
+  const args = [...projectSql.args];
+  const since = parseSince(query.since, now);
+  if (since) {
+    whereClauses.push("created_at >= ?");
+    args.push(since.toISOString());
+  }
+  const until = parseSince(query.until, now);
+  if (until) {
+    whereClauses.push("created_at <= ?");
+    args.push(until.toISOString());
+  }
+  if (query.minImportance !== void 0) {
+    whereClauses.push("importance >= ?");
+    args.push(Math.max(1, Math.min(10, Math.round(query.minImportance))));
+  }
+  if (query.types && query.types.length > 0) {
+    const placeholders = query.types.map(() => "?").join(", ");
+    whereClauses.push(`type IN (${placeholders})`);
+    args.push(...query.types);
+  }
+  if (query.platform) {
+    whereClauses.push("platform = ?");
+    args.push(query.platform);
+  }
+  args.push(limit);
+  const whereClause = whereClauses.length > 0 ? "WHERE " + whereClauses.join(" AND ") : "";
+  const result = await db.execute({
+    sql: `
+      SELECT
+        id,
+        type,
+        subject,
+        canonical_key,
+        content,
+        importance,
+        expiry,
+        scope,
+        platform,
+        project,
+        source_file,
+        source_context,
+        embedding,
+        created_at,
+        updated_at,
+        last_recalled_at,
+        recall_count,
+        recall_intervals,
+        confirmations,
+        contradictions,
+        superseded_by,
+        retired,
+        retired_at,
+        retired_reason,
+        suppressed_contexts
+      FROM entries
+      ${whereClause}
+      -- SQL pre-sort is a best-effort approximation only.
+      -- Final order is determined by scoreBrowseEntry() (importance * recency decay)
+      -- which re-sorts post-fetch. The over-fetch buffer (limit*3, min 50)
+      -- ensures the final top-N are present in the candidate pool.
+      ORDER BY importance DESC, created_at DESC
+      LIMIT ?
+    `,
+    args
+  });
+  const ids = result.rows.map((row) => toStringValue2(row.id)).filter((id) => id.length > 0);
+  const tagsByEntryId = await getTagsForEntryIds(db, ids);
+  return result.rows.map((row) => {
+    const entryId = toStringValue2(row.id);
+    return {
+      entry: mapStoredEntry(row, tagsByEntryId.get(entryId) ?? []),
+      vectorSim: 0
+    };
+  });
+}
 async function runFts(db, text2, platform, project, excludeProject, projectStrict) {
   if (!text2.trim()) {
     return /* @__PURE__ */ new Set();
@@ -4085,10 +4183,10 @@ async function recall(db, query, apiKey, options = {}) {
   const excludeProject = query.excludeProject;
   const projectStrict = query.projectStrict === true;
   const isSessionStart = context === "session-start";
-  if (!text2 && context !== "session-start") {
+  if (!text2 && context !== "session-start" && query.browse !== true) {
     throw new Error("Query text is required unless --context session-start is used.");
   }
-  if (!text2 && query.noBoost) {
+  if (!text2 && query.noBoost && query.browse !== true) {
     throw new Error("--no-boost requires query text.");
   }
   const normalizedTags = normalizeTags(query.tags);
@@ -4113,6 +4211,41 @@ async function recall(db, query, apiKey, options = {}) {
     );
   }
   const allowedScopes = resolveScopeSet(query.scope);
+  if (query.browse === true) {
+    if (text2) {
+      process.stderr.write(
+        "[agenr] Warning: --browse mode ignores query text. Remove the query or use agenr recall <query> for semantic search.\n"
+      );
+    }
+    if (query.noBoost) {
+      throw new Error("--no-boost is not applicable in browse mode.");
+    }
+    const requestedLimit = Number.isFinite(query.limit) && (query.limit ?? 0) > 0 ? Math.floor(query.limit) : DEFAULT_LIMIT;
+    const browseLimit = Math.max(requestedLimit * 3, 50);
+    const browseCandidates = await fetchBrowseCandidates(db, query, browseLimit, now);
+    const filtered2 = browseCandidates.filter(
+      (candidate) => passesFilters(candidate.entry, query, cutoff, ceiling, allowedScopes, normalizedTags, false)
+    );
+    const scored2 = filtered2.map((candidate) => {
+      const score = scoreBrowseEntry(candidate.entry, now);
+      return {
+        entry: candidate.entry,
+        score,
+        scores: {
+          vector: 0,
+          recency: recency(parseDaysBetween(now, candidate.entry.created_at), candidate.entry.expiry),
+          importance: importanceScore(candidate.entry.importance),
+          recall: 0,
+          freshness: 1,
+          todoPenalty: 1,
+          fts: 0,
+          spacing: 1
+        }
+      };
+    });
+    scored2.sort((a, b) => b.score - a.score);
+    return scored2.slice(0, requestedLimit);
+  }
   const hasDateBounds = cutoff !== void 0 || ceiling !== void 0;
   let candidates;
   let effectiveText = text2;
@@ -15777,8 +15910,8 @@ var TOOL_DEFINITIONS = [
         },
         context: {
           type: "string",
-          description: "Recall context. Use 'session-start' for fast bootstrap without embedding (no query needed).",
-          enum: ["default", "session-start"]
+          description: "Recall context. Use 'session-start' for fast bootstrap (no query needed). Use 'browse' for temporal browsing sorted by date+importance without semantic search (no query needed, zero API calls).",
+          enum: ["default", "session-start", "browse"]
         },
         limit: {
           type: "integer",
@@ -16161,6 +16294,27 @@ function formatRecallText(query, results) {
   }
   return lines.join("\n");
 }
+function formatBrowseText(results) {
+  if (results.length === 0) {
+    return "No entries found in the specified time window.";
+  }
+  const lines = [`Found ${results.length} entries (browse mode):`, ""];
+  for (let i = 0; i < results.length; i += 1) {
+    const result = results[i];
+    if (!result) {
+      continue;
+    }
+    const dateStr = new Date(result.entry.created_at).toISOString().slice(0, 10);
+    lines.push(
+      `[${i + 1}] [id=${result.entry.id}] [${dateStr}] importance=${result.entry.importance} type=${result.entry.type}`
+    );
+    lines.push(result.entry.content);
+    if (i < results.length - 1) {
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
 function formatStoreSummary(result) {
   const total = result.added + result.updated + result.skipped + result.superseded;
   const parts = [`${result.added} new`, `${result.updated} updated`, `${result.skipped} duplicates skipped`];
@@ -16312,12 +16466,12 @@ function createMcpServer(options = {}, deps = {}) {
   async function callRecallTool(args) {
     const contextRaw = typeof args.context === "string" ? args.context.trim().toLowerCase() : "default";
     const context = contextRaw || "default";
-    if (context !== "default" && context !== "session-start") {
-      throw new RpcError(JSON_RPC_INVALID_PARAMS, "context must be one of: default, session-start");
+    if (context !== "default" && context !== "session-start" && context !== "browse") {
+      throw new RpcError(JSON_RPC_INVALID_PARAMS, "context must be one of: default, session-start, browse");
     }
     const query = typeof args.query === "string" ? args.query.trim() : "";
-    if (!query && context !== "session-start") {
-      throw new RpcError(JSON_RPC_INVALID_PARAMS, "query is required unless context is session-start");
+    if (!query && context === "default") {
+      throw new RpcError(JSON_RPC_INVALID_PARAMS, "query is required unless context is session-start or browse");
     }
     const limit = parsePositiveInt5(args.limit, 10, "limit");
     const threshold = parseThreshold(args.threshold);
@@ -16368,7 +16522,26 @@ function createMcpServer(options = {}, deps = {}) {
     }
     const db = await ensureDb();
     let results;
-    if (context === "session-start") {
+    if (context === "browse") {
+      results = await resolvedDeps.recallFn(
+        db,
+        {
+          text: void 0,
+          context: "browse",
+          browse: true,
+          limit,
+          types,
+          since,
+          until,
+          platform: platform ?? void 0,
+          project,
+          projectStrict: projectStrict ? true : void 0,
+          scope: "private",
+          noUpdate: true
+        },
+        ""
+      );
+    } else if (context === "session-start") {
       const grouped = await sessionStartRecall(db, {
         query: {
           context,
@@ -16415,6 +16588,9 @@ function createMcpServer(options = {}, deps = {}) {
         result.entry.last_recalled_at = nowIso;
       }
     }
+    if (context === "browse") {
+      return formatBrowseText(filtered);
+    }
     return formatRecallText(query || context, filtered);
   }
   async function callStoreTool(args) {
@@ -16883,6 +17059,24 @@ ${ui.bold(section.title)}`, clackOutput);
     index += 1;
   }
 }
+function printBrowseResults(results, elapsedMs) {
+  const clackOutput = { output: process.stderr };
+  clack6.log.info(`${ui.bold(String(results.length))} entries (browse mode, ${elapsedMs}ms)`, clackOutput);
+  if (results.length === 0) {
+    clack6.log.info("No entries found in the specified time window.", clackOutput);
+    return;
+  }
+  let index = 1;
+  for (const result of results) {
+    const dateStr = new Date(result.entry.created_at).toISOString().slice(0, 10);
+    clack6.log.info(
+      `${index}. [${dateStr}] [importance=${result.entry.importance}] (${result.entry.type}) ${result.entry.subject}: ${result.entry.content}`,
+      clackOutput
+    );
+    clack6.log.info(`   tags: ${result.entry.tags.length > 0 ? result.entry.tags.join(", ") : "none"}`, clackOutput);
+    index += 1;
+  }
+}
 async function runRecallCommand(queryInput, options, deps) {
   const resolvedDeps = {
     readConfigFn: deps?.readConfigFn ?? readConfig,
@@ -16900,12 +17094,24 @@ async function runRecallCommand(queryInput, options, deps) {
   const queryText = queryInput?.trim() ?? "";
   const context = options.context?.trim() || "default";
   const isSessionStart = context === "session-start";
-  if (!queryText && !isSessionStart) {
-    throw new Error("Provide a query or use --context session-start.");
+  const isBrowse = options.browse === true;
+  if (isBrowse && isSessionStart) {
+    throw new Error("--browse and --context session-start cannot be combined.");
+  }
+  if (!queryText && !isSessionStart && !isBrowse) {
+    throw new Error("Provide a query, use --context session-start, or use --browse.");
+  }
+  if (options.noBoost && isBrowse) {
+    throw new Error("--no-boost is not applicable in browse mode.");
   }
   if (options.noBoost && !queryText) {
     throw new Error("--no-boost requires a query.");
   }
+  if (isBrowse && queryText) {
+    process.stderr.write(
+      "[agenr] Warning: --browse mode ignores query text. Remove the query or use agenr recall <query> for semantic search.\n"
+    );
+  }
   const limit = parsePositiveInt6(options.limit, DEFAULT_LIMIT4, "--limit");
   const budget = options.budget !== void 0 ? parsePositiveInt6(options.budget, DEFAULT_LIMIT4, "--budget") : void 0;
   const parsedTypes = parseCsv(options.type);
@@ -16960,7 +17166,7 @@ async function runRecallCommand(queryInput, options, deps) {
   const sinceIso = parseSinceToIso(options.since, now, "Invalid --since value. Use 1h, 7d, 1m, 1y, or an ISO date.");
   const untilIso = parseSinceToIso(options.until, now, "Invalid --until value. Use 1h, 7d, 1m, 1y, or an ISO date.");
   const queryForRecall = {
-    text: queryText ? shapeRecallText(queryText, context) : void 0,
+    text: queryText && !isBrowse ? shapeRecallText(queryText, context) : void 0,
     limit,
     types: types.length > 0 ? types : void 0,
     tags: tags.length > 0 ? tags : void 0,
@@ -16976,18 +17182,23 @@ async function runRecallCommand(queryInput, options, deps) {
     noBoost: options.noBoost === true,
     noUpdate: true,
     context,
-    budget
+    budget,
+    browse: isBrowse
   };
   const config = resolvedDeps.readConfigFn(process.env);
   const dbPath = options.db?.trim() || config?.db?.path;
   const db = resolvedDeps.getDbFn(dbPath);
   try {
     await resolvedDeps.initDbFn(db);
-    const apiKey = queryText ? resolvedDeps.resolveEmbeddingApiKeyFn(config, process.env) : "";
+    const apiKey = queryText && !isBrowse ? resolvedDeps.resolveEmbeddingApiKeyFn(config, process.env) : "";
     const startedAt = Date.now();
     let finalResults = [];
     let budgetUsed = 0;
-    if (isSessionStart) {
+    if (isBrowse) {
+      const baseResults = await resolvedDeps.recallFn(db, queryForRecall, apiKey);
+      finalResults = baseResults.map((result) => ({ ...result }));
+      budgetUsed = finalResults.reduce((sum, item) => sum + estimateEntryTokens(item), 0);
+    } else if (isSessionStart) {
       const grouped = await sessionStartRecall(db, {
         query: queryForRecall,
         apiKey,
@@ -17008,7 +17219,7 @@ async function runRecallCommand(queryInput, options, deps) {
         finalResults = consumed.selected.map((result) => ({ ...result }));
       }
     }
-    if (!options.noUpdate && finalResults.length > 0) {
+    if (!isBrowse && !options.noUpdate && finalResults.length > 0) {
       const ids = finalResults.map((result) => result.entry.id);
       await resolvedDeps.updateRecallMetadataFn(db, ids, now);
       const nowIso = now.toISOString();
@@ -17019,7 +17230,7 @@ async function runRecallCommand(queryInput, options, deps) {
     }
     const stripped = finalResults.map((result) => stripEmbedding(result));
     const payload = {
-      query: queryText,
+      query: isBrowse ? "[browse]" : queryText,
       results: stripped,
       total: stripped.length,
       budget_used: budgetUsed,
@@ -17030,7 +17241,11 @@ async function runRecallCommand(queryInput, options, deps) {
       process.stdout.write(`${JSON.stringify(payload, null, 2)}
 `);
     } else {
-      printHumanResults(stripped, elapsedMs, now, isSessionStart);
+      if (isBrowse) {
+        printBrowseResults(stripped, elapsedMs);
+      } else {
+        printHumanResults(stripped, elapsedMs, now, isSessionStart);
+      }
     }
     clack6.outro(void 0, clackOutput);
     return {
@@ -19447,7 +19662,7 @@ function createProgram() {
       process.exitCode = result.exitCode;
     }
   );
-  program.command("recall").description("Recall knowledge from the local database").argument("[query]", "Natural language query").option("--limit <n>", "Maximum number of results", parseIntOption, 10).option("--type <types>", "Filter by comma-separated entry types").option("--tags <tags>", "Filter by comma-separated tags").option("--min-importance <n>", "Minimum importance: 1-10").option("--since <duration>", "Filter by recency (1h, 7d, 30d, 1y) or ISO timestamp").option("--until <date>", "Only entries at or before this time (ISO date or relative, e.g. 7d, 1m)").option("--expiry <level>", "Filter by expiry: core|permanent|temporary").option("--platform <name>", "Filter by platform: openclaw, claude-code, codex, plaud").option("--project <name>", "Filter by project (repeatable)", (val, prev) => [...prev, val], []).option("--exclude-project <name>", "Exclude entries from project (repeatable)", (val, prev) => [...prev, val], []).option("--strict", "Exclude NULL-project entries from results", false).option("--json", "Output JSON", false).option("--db <path>", "Database path override").option("--budget <tokens>", "Approximate token budget", parseIntOption).option("--context <mode>", "Context mode: default|session-start|topic:<query>", "default").option("--scope <level>", "Visibility scope: private|personal|public", "private").option("--no-boost", "Disable scoring boosts and use raw vector similarity", false).option("--no-update", "Do not increment recall metadata", false).action(async (query, opts) => {
+  program.command("recall").description("Recall knowledge from the local database").argument("[query]", "Natural language query").option("--limit <n>", "Maximum number of results", parseIntOption, 10).option("--type <types>", "Filter by comma-separated entry types").option("--tags <tags>", "Filter by comma-separated tags").option("--min-importance <n>", "Minimum importance: 1-10").option("--since <duration>", "Filter by recency (1h, 7d, 30d, 1y) or ISO timestamp").option("--until <date>", "Only entries at or before this time (ISO date or relative, e.g. 7d, 1m)").option("--expiry <level>", "Filter by expiry: core|permanent|temporary").option("--platform <name>", "Filter by platform: openclaw, claude-code, codex, plaud").option("--project <name>", "Filter by project (repeatable)", (val, prev) => [...prev, val], []).option("--exclude-project <name>", "Exclude entries from project (repeatable)", (val, prev) => [...prev, val], []).option("--strict", "Exclude NULL-project entries from results", false).option("--json", "Output JSON", false).option("--db <path>", "Database path override").option("--budget <tokens>", "Approximate token budget", parseIntOption).option("--context <mode>", "Context mode: default|session-start|topic:<query>", "default").option("--scope <level>", "Visibility scope: private|personal|public", "private").option("--browse", "Skip semantic search and return entries sorted by importance and date", false).option("--no-boost", "Disable scoring boosts and use raw vector similarity", false).option("--no-update", "Do not increment recall metadata", false).action(async (query, opts) => {
     const result = await runRecallCommand(query, {
       limit: opts.limit,
       type: opts.type,
@@ -19465,6 +19680,7 @@ function createProgram() {
       budget: opts.budget,
       context: opts.context,
       scope: opts.scope,
+      browse: opts.browse === true,
       noBoost: opts.noBoost === true,
       noUpdate: opts.noUpdate === true
     });

package/dist/openclaw-plugin/index.js

@@ -573,16 +573,19 @@ async function runRecallTool(agenrPath, params, defaultProject) {
   const args = ["recall", "--json"];
   const query = asString(params.query);
   const context = asString(params.context);
+  const isBrowse = context === "browse";
   const limit = asNumber(params.limit);
   const types = asString(params.types);
   const since = asString(params.since);
   const until = asString(params.until);
   const platform = asString(params.platform);
   const project = asString(params.project) || defaultProject;
-  if (query) {
+  if (isBrowse) {
+    args.push("--browse");
+  } else if (query) {
     args.push(query);
   }
-  if (context) {
+  if (context && !isBrowse) {
     args.push("--context", context);
   }
   if (limit !== void 0) {
@@ -1045,8 +1048,10 @@ var plugin = {
             query: Type.Optional(Type.String({ description: "What to search for." })),
             context: Type.Optional(
               Type.Union(
-                [Type.Literal("default"), Type.Literal("session-start")],
-                { description: "Use session-start for fast bootstrap without embedding." }
+                [Type.Literal("default"), Type.Literal("session-start"), Type.Literal("browse")],
+                {
+                  description: "Use session-start for fast bootstrap without embedding. Use browse for temporal browsing (date+importance, no query needed, no semantic search)."
+                }
               )
             ),
             limit: Type.Optional(Type.Number({ description: "Max results (default: 10)." })),

package/package.json

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