mr-memory 3.11.0 → 3.12.0

package/README.md

@@ -9,10 +9,10 @@ Use it when you want OpenClaw memory that does not restart from zero every sessi
 ## Install
 
 ```bash
-openclaw plugins install npm:mr-memory@3.8.0
+openclaw plugins install npm:mr-memory@3.12.0
 ```
 
-The explicit `npm:` source and version make the audited install deterministic. `mr-memory@3.8.0` is published on npm. A ClawHub listing has not been verified and is not required for this path.
+The explicit `npm:` source and version make the audited install deterministic. `mr-memory@3.12.0` is published on npm. A ClawHub listing has not been verified and is not required for this path.
 
 ## Setup
 
@@ -53,6 +53,16 @@ openclaw mr import --dismiss             # permanently silence the import nudge
 
 Guarantees: the extract is validated locally (four fields per record, `openclaw:` prefixed ids, epoch-ms timestamps); the CLI shows record count, date range, estimated tokens, and the server price quote and requires explicit approval before any write; the import id is content-derived and every batch carries an Idempotency-Key, so re-running after any interruption replays committed batches for free and resumes. Duplicates are never re-billed. The memory key never appears in the prompt or the extract file. When a vault is new, injected context includes a one-line import suggestion until an import completes or you `--dismiss`.
 
+## Agent Tools
+
+The plugin registers these tools for the agent:
+
+- `memory_search`: semantic search across the vault. Supports `tiers` and `importance` filters; only reflections (tiers 2 and 3) carry importance ratings.
+- `memory_date_search`: time-window retrieval for questions like "what happened last week" or "most important things this month". Takes concrete ISO `from`/`to` dates, optional `query` for in-window relevance ranking, plus `tiers` and `importance` filters.
+- `memory_get`: safe snippet read from local memory files.
+- `memory_reflect` / `memory_commit`: consolidate raw memories into reflections (checkout and commit pair).
+- `memory_inspect`: read-only consolidation lineage for a memory id.
+
 ## How It Works
 
 When enabled, relay hooks retrieve memory before agent/model input and capture the direct user-to-assistant conversation at `agent_end`. Inference and provider API keys remain inside OpenClaw; the plugin does not route provider calls through MemoryRouter and is not a provider-key proxy.

package/auto-consolidate.js

@@ -212,6 +212,10 @@ export async function runAutoConsolidate(options) {
                     sessionKey,
                     message: consolidationMessage(tier),
                     deliver: false,
+                    // The gateway's `agent` method requires idempotencyKey on some
+                    // deployments (and auto-generates it on others); always send a
+                    // fresh one per run attempt so both validate.
+                    idempotencyKey: randomUUID(),
                 });
                 const waited = await options.runtime.waitForRun({ runId, timeoutMs: RUN_TIMEOUT_MS });
                 status = waited.status;

package/auto-consolidate.ts

@@ -49,7 +49,7 @@ export type ReflectionDebtBlock = {
 };
 
 type SubagentRuntime = {
-  run: (params: { sessionKey: string; message: string; deliver?: boolean; lane?: string }) => Promise<{ runId: string }>;
+  run: (params: { sessionKey: string; message: string; deliver?: boolean; lane?: string; idempotencyKey?: string }) => Promise<{ runId: string }>;
   waitForRun: (params: { runId: string; timeoutMs?: number }) => Promise<{ status: string; error?: string }>;
   deleteSession: (params: { sessionKey: string; deleteTranscript?: boolean }) => Promise<void>;
 };
@@ -215,6 +215,10 @@ export async function runAutoConsolidate(options: AutoConsolidateOptions): Promi
           sessionKey,
           message: consolidationMessage(tier),
           deliver: false,
+          // The gateway's `agent` method requires idempotencyKey on some
+          // deployments (and auto-generates it on others); always send a
+          // fresh one per run attempt so both validate.
+          idempotencyKey: randomUUID(),
         });
         const waited = await options.runtime.waitForRun({ runId, timeoutMs: RUN_TIMEOUT_MS });
         status = waited.status;

package/index.js

@@ -1016,7 +1016,7 @@ If setting up MemoryRouter for another agent:
                 return {
                     label: "Memory Search",
                     name: "memory_search",
-                    description: "Search memories from past conversations and your workspace. Use when relevant.",
+                    description: "Search memories from past conversations and your workspace by meaning. Use when relevant. For questions like 'what are the most important things' set importance to 7 or higher with tiers [2, 3], since only reflections carry importance ratings. For time-window questions like 'what happened last week' or 'lately' use memory_date_search instead.",
                     parameters: {
                         type: "object",
                         properties: {
@@ -1026,13 +1026,13 @@ If setting up MemoryRouter for another agent:
                             tiers: {
                                 type: "array",
                                 items: { type: "integer", enum: [1, 2, 3] },
-                                description: "Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Omit to search all tiers blended.",
+                                description: "Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Only tiers 2 and 3 carry importance ratings. Omit to search all tiers blended.",
                             },
                             importance: {
                                 type: "integer",
                                 minimum: 1,
                                 maximum: 10,
-                                description: "Only return memories rated at least this important (1 to 10). Only reflections carry ratings, so this filters to tier 2 and 3 content.",
+                                description: "Minimum importance threshold, 1 to 10. Only reflections (tiers 2 and 3) carry ratings, so raw memories are excluded whenever this is set. For 'most important' questions use 7 or higher with tiers [2, 3].",
                             },
                         },
                         required: ["query"],
@@ -1088,6 +1088,104 @@ If setting up MemoryRouter for another agent:
                     },
                 };
             });
+            // memory_date_search: calls MR /v1/memory/date-search (time-window retrieval)
+            api.registerTool((ctx) => {
+                const toolKey = resolveKey(ctx);
+                return {
+                    label: "Memory Date Search",
+                    name: "memory_date_search",
+                    description: "Retrieve memories from a specific time window. Use for questions like 'what happened last week' or 'most important things this month or lately'. For importance questions set importance to 7 or higher with tiers [2, 3], since only reflections carry importance ratings. Omit query for a chronological review; include query to rank by relevance within the window. Resolve relative phrases like 'lately' to concrete ISO dates before calling.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            from: {
+                                type: "string",
+                                description: "Window start, ISO 8601 date or datetime (e.g. 2026-08-10 or 2026-08-10T00:00:00Z). Required. Must be a concrete date, not a relative phrase.",
+                            },
+                            to: {
+                                type: "string",
+                                description: "Window end, ISO 8601 date or datetime. Optional, defaults to now.",
+                            },
+                            query: {
+                                type: "string",
+                                description: "Optional relevance query. Omit for a pure chronological browse; include to rank results within the window.",
+                            },
+                            tiers: {
+                                type: "array",
+                                items: { type: "integer", enum: [1, 2, 3] },
+                                description: "Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Only tiers 2 and 3 carry importance ratings. Omit to include all tiers.",
+                            },
+                            importance: {
+                                type: "integer",
+                                minimum: 1,
+                                maximum: 10,
+                                description: "Minimum importance threshold, 1 to 10. Only reflections (tiers 2 and 3) carry ratings, so raw memories are excluded whenever this is set. For 'most important' questions use 7 or higher with tiers [2, 3].",
+                            },
+                            maxTokens: {
+                                type: "integer",
+                                minimum: 1000,
+                                maximum: 200000,
+                                description: "Token budget for returned results. Server default 50000; use a smaller value like 5000 for a quick look.",
+                            },
+                        },
+                        required: ["from"],
+                    },
+                    execute: async (_toolCallId, params) => {
+                        if (!toolKey)
+                            return jsonToolResult({ results: [], error: "No memory key configured for this agent" });
+                        const from = typeof params.from === "string" ? params.from.trim() : "";
+                        if (!from)
+                            return jsonToolResult({ results: [], error: "from required (ISO 8601 date or datetime)" });
+                        const to = typeof params.to === "string" && params.to.trim() ? params.to.trim() : undefined;
+                        const query = typeof params.query === "string" && params.query.trim() ? params.query.trim() : undefined;
+                        const tiers = Array.isArray(params.tiers)
+                            ? params.tiers.filter((t) => typeof t === "number" && [1, 2, 3].includes(t))
+                            : undefined;
+                        const importance = typeof params.importance === "number" && params.importance >= 1 && params.importance <= 10
+                            ? Math.floor(params.importance)
+                            : undefined;
+                        const maxTokens = typeof params.maxTokens === "number" && Number.isFinite(params.maxTokens)
+                            ? Math.max(1000, Math.min(200000, Math.floor(params.maxTokens)))
+                            : undefined;
+                        try {
+                            const res = await dateSearch(endpoint, toolKey, {
+                                from,
+                                ...(to !== undefined && { to }),
+                                ...(query !== undefined && { query }),
+                                ...(tiers && tiers.length > 0 && { tiers }),
+                                ...(importance !== undefined && { importance }),
+                                ...(maxTokens !== undefined && { max_tokens: maxTokens }),
+                                ...(embeddings && { embeddings }),
+                            });
+                            if (!res.ok) {
+                                const errBody = await res.text().catch(() => "");
+                                return jsonToolResult({ results: [], error: `Date search failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+                            }
+                            const data = await res.json();
+                            const results = (data.results || []).map((m) => ({
+                                snippet: m.content,
+                                date: m.date,
+                                role: m.role,
+                                tier: m.tier,
+                                ...(m.score !== undefined && { score: m.score }),
+                                ...(m.importance !== undefined && m.importance !== null && { importance: m.importance }),
+                            }));
+                            return jsonToolResult({
+                                results,
+                                totalFound: results.length,
+                                window: data.returned ?? null,
+                                truncated: data.truncated ?? false,
+                                ...(data.next_to !== undefined && { next_to: data.next_to }),
+                                ...(data.next_from !== undefined && { next_from: data.next_from }),
+                                provider: "memoryrouter",
+                            });
+                        }
+                        catch (err) {
+                            return jsonToolResult({ results: [], error: err instanceof Error ? err.message : String(err) });
+                        }
+                    },
+                };
+            });
             // ==================================================================
             // Tools: memory_reflect + memory_commit (consolidation, two-tool shape)
             // Mirrors the MCP consolidate_memories / commit_reflections pair.
@@ -1346,7 +1444,7 @@ If setting up MemoryRouter for another agent:
                         console.error(`  ⚠ Could not disable native memory search: ${err instanceof Error ? err.message : String(err)}`);
                     }
                     console.log(`✓ MemoryRouter enabled. Key: ${key.slice(0, 6)}...${key.slice(-3)}`);
-                    console.log(`  • memory_search + memory_get tools registered via plugin`);
+                    console.log(`  • memory_search + memory_date_search + memory_get tools registered via plugin`);
                     console.log(`\nRun: openclaw mr upload    to upload your memories`);
                 }
                 catch (err) {

package/index.ts

@@ -1095,7 +1095,7 @@ If setting up MemoryRouter for another agent:
         return {
           label: "Memory Search",
           name: "memory_search",
-          description: "Search memories from past conversations and your workspace. Use when relevant.",
+          description: "Search memories from past conversations and your workspace by meaning. Use when relevant. For questions like 'what are the most important things' set importance to 7 or higher with tiers [2, 3], since only reflections carry importance ratings. For time-window questions like 'what happened last week' or 'lately' use memory_date_search instead.",
           parameters: {
             type: "object",
             properties: {
@@ -1105,13 +1105,13 @@ If setting up MemoryRouter for another agent:
               tiers: {
                 type: "array",
                 items: { type: "integer", enum: [1, 2, 3] },
-                description: "Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Omit to search all tiers blended.",
+                description: "Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Only tiers 2 and 3 carry importance ratings. Omit to search all tiers blended.",
               },
               importance: {
                 type: "integer",
                 minimum: 1,
                 maximum: 10,
-                description: "Only return memories rated at least this important (1 to 10). Only reflections carry ratings, so this filters to tier 2 and 3 content.",
+                description: "Minimum importance threshold, 1 to 10. Only reflections (tiers 2 and 3) carry ratings, so raw memories are excluded whenever this is set. For 'most important' questions use 7 or higher with tiers [2, 3].",
               },
             },
             required: ["query"],
@@ -1169,6 +1169,109 @@ If setting up MemoryRouter for another agent:
         };
       });
 
+      // memory_date_search: calls MR /v1/memory/date-search (time-window retrieval)
+      api.registerTool((ctx) => {
+        const toolKey = resolveKey(ctx);
+        return {
+          label: "Memory Date Search",
+          name: "memory_date_search",
+          description: "Retrieve memories from a specific time window. Use for questions like 'what happened last week' or 'most important things this month or lately'. For importance questions set importance to 7 or higher with tiers [2, 3], since only reflections carry importance ratings. Omit query for a chronological review; include query to rank by relevance within the window. Resolve relative phrases like 'lately' to concrete ISO dates before calling.",
+          parameters: {
+            type: "object",
+            properties: {
+              from: {
+                type: "string",
+                description: "Window start, ISO 8601 date or datetime (e.g. 2026-08-10 or 2026-08-10T00:00:00Z). Required. Must be a concrete date, not a relative phrase.",
+              },
+              to: {
+                type: "string",
+                description: "Window end, ISO 8601 date or datetime. Optional, defaults to now.",
+              },
+              query: {
+                type: "string",
+                description: "Optional relevance query. Omit for a pure chronological browse; include to rank results within the window.",
+              },
+              tiers: {
+                type: "array",
+                items: { type: "integer", enum: [1, 2, 3] },
+                description: "Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Only tiers 2 and 3 carry importance ratings. Omit to include all tiers.",
+              },
+              importance: {
+                type: "integer",
+                minimum: 1,
+                maximum: 10,
+                description: "Minimum importance threshold, 1 to 10. Only reflections (tiers 2 and 3) carry ratings, so raw memories are excluded whenever this is set. For 'most important' questions use 7 or higher with tiers [2, 3].",
+              },
+              maxTokens: {
+                type: "integer",
+                minimum: 1000,
+                maximum: 200000,
+                description: "Token budget for returned results. Server default 50000; use a smaller value like 5000 for a quick look.",
+              },
+            },
+            required: ["from"],
+          } as any,
+          execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+            if (!toolKey) return jsonToolResult({ results: [], error: "No memory key configured for this agent" });
+            const from = typeof params.from === "string" ? params.from.trim() : "";
+            if (!from) return jsonToolResult({ results: [], error: "from required (ISO 8601 date or datetime)" });
+            const to = typeof params.to === "string" && params.to.trim() ? params.to.trim() : undefined;
+            const query = typeof params.query === "string" && params.query.trim() ? params.query.trim() : undefined;
+            const tiers = Array.isArray(params.tiers)
+              ? (params.tiers as unknown[]).filter((t): t is number => typeof t === "number" && [1, 2, 3].includes(t))
+              : undefined;
+            const importance = typeof params.importance === "number" && params.importance >= 1 && params.importance <= 10
+              ? Math.floor(params.importance)
+              : undefined;
+            const maxTokens = typeof params.maxTokens === "number" && Number.isFinite(params.maxTokens)
+              ? Math.max(1000, Math.min(200000, Math.floor(params.maxTokens)))
+              : undefined;
+            try {
+              const res = await dateSearch(endpoint, toolKey, {
+                from,
+                ...(to !== undefined && { to }),
+                ...(query !== undefined && { query }),
+                ...(tiers && tiers.length > 0 && { tiers }),
+                ...(importance !== undefined && { importance }),
+                ...(maxTokens !== undefined && { max_tokens: maxTokens }),
+                ...(embeddings && { embeddings }),
+              });
+              if (!res.ok) {
+                const errBody = await res.text().catch(() => "");
+                return jsonToolResult({ results: [], error: `Date search failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+              }
+              const data = await res.json() as {
+                results?: Array<{ tier: number; content: string; date: string; role: string; score?: number; importance?: number }>;
+                returned?: { from: string | null; to: string | null };
+                truncated?: boolean;
+                est_tokens_in_window?: number;
+                next_to?: string;
+                next_from?: string;
+              };
+              const results = (data.results || []).map((m) => ({
+                snippet: m.content,
+                date: m.date,
+                role: m.role,
+                tier: m.tier,
+                ...(m.score !== undefined && { score: m.score }),
+                ...(m.importance !== undefined && m.importance !== null && { importance: m.importance }),
+              }));
+              return jsonToolResult({
+                results,
+                totalFound: results.length,
+                window: data.returned ?? null,
+                truncated: data.truncated ?? false,
+                ...(data.next_to !== undefined && { next_to: data.next_to }),
+                ...(data.next_from !== undefined && { next_from: data.next_from }),
+                provider: "memoryrouter",
+              });
+            } catch (err) {
+              return jsonToolResult({ results: [], error: err instanceof Error ? err.message : String(err) });
+            }
+          },
+        };
+      });
+
       // ==================================================================
       // Tools: memory_reflect + memory_commit (consolidation, two-tool shape)
       // Mirrors the MCP consolidate_memories / commit_reflections pair.
@@ -1434,7 +1537,7 @@ If setting up MemoryRouter for another agent:
               console.error(`  ⚠ Could not disable native memory search: ${err instanceof Error ? err.message : String(err)}`);
             }
             console.log(`✓ MemoryRouter enabled. Key: ${key.slice(0, 6)}...${key.slice(-3)}`);
-            console.log(`  • memory_search + memory_get tools registered via plugin`);
+            console.log(`  • memory_search + memory_date_search + memory_get tools registered via plugin`);
             console.log(`\nRun: openclaw mr upload    to upload your memories`);
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/memoryrouter-api.js

@@ -94,6 +94,8 @@ export async function dateSearch(endpoint, key, payload) {
             from: payload.from,
             ...(payload.to !== undefined && { to: payload.to }),
             ...(payload.query !== undefined && { query: payload.query }),
+            ...(payload.tiers !== undefined && { tiers: payload.tiers }),
+            ...(payload.importance !== undefined && { importance: payload.importance }),
             ...(payload.max_tokens !== undefined && { max_tokens: payload.max_tokens }),
         }),
     });

package/memoryrouter-api.ts

@@ -96,7 +96,7 @@ export async function deleteMemoryIds(endpoint: string, key: string, payload: {
   });
 }
 
-export async function dateSearch(endpoint: string, key: string, payload: { from: string; to?: string; query?: string; max_tokens?: number; embeddings?: string }): Promise<Response> {
+export async function dateSearch(endpoint: string, key: string, payload: { from: string; to?: string; query?: string; tiers?: number[]; importance?: number; max_tokens?: number; embeddings?: string }): Promise<Response> {
   return fetch(`${endpoint}/v1/memory/date-search`, {
     method: "POST",
     headers: {
@@ -108,6 +108,8 @@ export async function dateSearch(endpoint: string, key: string, payload: { from:
       from: payload.from,
       ...(payload.to !== undefined && { to: payload.to }),
       ...(payload.query !== undefined && { query: payload.query }),
+      ...(payload.tiers !== undefined && { tiers: payload.tiers }),
+      ...(payload.importance !== undefined && { importance: payload.importance }),
       ...(payload.max_tokens !== undefined && { max_tokens: payload.max_tokens }),
     }),
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-memory",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Persistent memory for OpenClaw, powered by MemoryRouter. Relay-based AI agent memory across sessions, compaction, and model changes.",
   "type": "module",
   "files": [