mr-memory 3.8.0 → 3.9.1

package/index.js

@@ -8,7 +8,7 @@
  * BYOK — provider API keys never touch MemoryRouter.
  */
 import { readFile, lstat, writeFile, copyFile, mkdir } from "node:fs/promises";
-import { deleteMemories, getMemoryStats, ingestMemory, prepareMemory, searchMemory, warmupMemory } from "./memoryrouter-api.js";
+import { commitReflections, consolidateCheckout, dateSearch, deleteMemories, deleteMemoryIds, getMemoryStats, ingestMemory, inspectMemory, prepareMemory, searchMemory, warmupMemory } from "./memoryrouter-api.js";
 import { join, resolve, relative, isAbsolute, sep, dirname } from "node:path";
 import os from "node:os";
 const DEFAULT_ENDPOINT = "https://api.memoryrouter.ai";
@@ -55,6 +55,15 @@ function stripOldMemory(text) {
 function jsonToolResult(payload) {
     return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], details: payload };
 }
+function buildDebtNudgeLine(reflection) {
+    if (!reflection || !reflection.suggestion)
+        return null;
+    const rawTokens = reflection.unconsolidated?.raw?.est_tokens ?? 0;
+    const tier2Tokens = reflection.unconsolidated?.tier2?.est_tokens ?? 0;
+    const totalTokens = rawTokens + tier2Tokens;
+    const kTokens = Math.max(1, Math.round(totalTokens / 1000));
+    return `[MemoryRouter] Consolidation suggested: ${kTokens}k unconsolidated tokens. Use the memory_reflect tool to consolidate them now.`;
+}
 // ── memory_get helpers (copied from OpenClaw source — pure filesystem, no embeddings)
 function isFileMissingError(err) {
     return Boolean(err && typeof err === "object" && "code" in err && err.code === "ENOENT");
@@ -731,7 +740,11 @@ If setting up MemoryRouter for another agent:
                         api.logger.info?.(`memoryrouter: injected ${data.memories_found || 0} memories (${data.memory_tokens || 0} tokens, ${elapsed}ms) [llm_input]`);
                         if (elapsed > 2000 && data.metrics)
                             log(`memoryrouter: prepare metrics ${JSON.stringify(data.metrics)}`);
-                        const wrapped = wrapForInjection(data.context);
+                        let contextText = data.context;
+                        const nudge = buildDebtNudgeLine(data.reflection);
+                        if (nudge)
+                            contextText = `${contextText}\n\n${nudge}`;
+                        const wrapped = wrapForInjection(contextText);
                         return { appendSystemContext: wrapped };
                     }
                 }
@@ -836,7 +849,11 @@ If setting up MemoryRouter for another agent:
                         api.logger.info?.(`memoryrouter: injected ${data.memories_found || 0} memories (${data.memory_tokens || 0} tokens, ${elapsed}ms)`);
                         if (elapsed > 2000 && data.metrics)
                             log(`memoryrouter: prepare metrics ${JSON.stringify(data.metrics)}`);
-                        const wrapped = wrapForInjection(data.context);
+                        let contextText = data.context;
+                        const nudge = buildDebtNudgeLine(data.reflection);
+                        if (nudge)
+                            contextText = `${contextText}\n\n${nudge}`;
+                        const wrapped = wrapForInjection(contextText);
                         return { appendSystemContext: wrapped };
                     }
                 }
@@ -963,6 +980,17 @@ If setting up MemoryRouter for another agent:
                             query: { type: "string" },
                             maxResults: { type: "number" },
                             minScore: { type: "number" },
+                            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.",
+                            },
+                            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.",
+                            },
                         },
                         required: ["query"],
                     },
@@ -973,8 +1001,20 @@ If setting up MemoryRouter for another agent:
                         if (!query)
                             return jsonToolResult({ results: [], error: "query required" });
                         const limit = typeof params.maxResults === "number" ? params.maxResults : 50;
+                        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;
                         try {
-                            const res = await searchMemory(endpoint, toolKey, { query, limit, embeddings });
+                            const res = await searchMemory(endpoint, toolKey, {
+                                query,
+                                limit,
+                                ...(tiers && tiers.length > 0 && { tiers }),
+                                ...(importance !== undefined && { importance }),
+                                embeddings,
+                            });
                             if (!res.ok) {
                                 const errBody = await res.text().catch(() => "");
                                 return jsonToolResult({ results: [], error: `Search failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
@@ -988,6 +1028,8 @@ If setting up MemoryRouter for another agent:
                                 role: m.role,
                                 window: m.window,
                                 date: m.timestampHuman,
+                                ...(m.tier !== undefined && { tier: m.tier }),
+                                ...(m.importance !== undefined && m.importance !== null && { importance: m.importance }),
                             }));
                             return jsonToolResult({
                                 results,
@@ -1003,6 +1045,203 @@ If setting up MemoryRouter for another agent:
                     },
                 };
             });
+            // ==================================================================
+            // Tools: memory_reflect + memory_commit (consolidation, two-tool shape)
+            // Mirrors the MCP consolidate_memories / commit_reflections pair.
+            // Invariants: source_ids are stripped, the model never sees row IDs,
+            // and contract instructions are transmitted verbatim.
+            // ==================================================================
+            // memory_reflect: checkout wrapper (nothing is modified until memory_commit)
+            api.registerTool((ctx) => {
+                const toolKey = resolveKey(ctx);
+                return {
+                    label: "Memory Reflect",
+                    name: "memory_reflect",
+                    description: "Consolidate unconsolidated memories into reflections. Use when memory responses indicate consolidation is available, or when the user asks to organize or reflect on memory. Checks out a batch of memories under a 15 minute lease and returns their texts plus server instructions for writing reflection entries. Follow the instructions, then call memory_commit with the batch_id. Nothing is modified until commit.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            tier: {
+                                type: "integer",
+                                enum: [1, 2],
+                                description: "1 consolidates raw memories into reflections; 2 consolidates reflections into high-level reflections. Default 1.",
+                            },
+                            max_tokens: {
+                                type: "integer",
+                                minimum: 1000,
+                                description: "Token budget for the checked-out batch. Defaults to 50000. No connector-side cap.",
+                            },
+                        },
+                        required: [],
+                    },
+                    execute: async (_toolCallId, params) => {
+                        if (!toolKey)
+                            return jsonToolResult({ error: "No memory key configured for this agent" });
+                        const tier = params.tier === 2 ? 2 : 1;
+                        const maxTokens = typeof params.max_tokens === "number" && params.max_tokens >= 1000
+                            ? Math.floor(params.max_tokens)
+                            : 50000;
+                        try {
+                            const res = await consolidateCheckout(endpoint, toolKey, {
+                                tier: tier,
+                                max_tokens: maxTokens,
+                                ...(embeddings && { embeddings }),
+                            });
+                            if (!res.ok) {
+                                const errBody = await res.text().catch(() => "");
+                                return jsonToolResult({ error: `Checkout failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+                            }
+                            const data = await res.json();
+                            if (!data.batch_id) {
+                                return jsonToolResult({ batch_id: null, count: 0, message: "Nothing to consolidate at this tier right now." });
+                            }
+                            // Contract instructions are server-authored and passed through verbatim.
+                            // If neither contract form is present, refuse; never author a local prompt.
+                            const instructions = data.reflection_contract?.instructions ?? data.tier_definitions?.instruction;
+                            if (!instructions) {
+                                return jsonToolResult({ error: "Checkout response carried no reflection contract. Cannot consolidate without server instructions." });
+                            }
+                            // source_ids stripped: the model never sees memory row IDs.
+                            return jsonToolResult({
+                                batch_id: data.batch_id,
+                                lease_expires_at: data.lease_expires_at ?? null,
+                                count: data.count ?? 0,
+                                est_tokens: data.est_tokens ?? 0,
+                                instructions,
+                                memories: (data.memories || []).map((m) => ({ text: m.text, date: m.date })),
+                                message: `When your entries are ready, call memory_commit with batch_id ${data.batch_id} before ${data.lease_expires_at ?? "the lease expires"}.`,
+                            });
+                        }
+                        catch (err) {
+                            return jsonToolResult({ error: err instanceof Error ? err.message : String(err) });
+                        }
+                    },
+                };
+            });
+            // memory_commit: commit wrapper (idempotent; 409 means the lease expired)
+            api.registerTool((ctx) => {
+                const toolKey = resolveKey(ctx);
+                return {
+                    label: "Memory Commit",
+                    name: "memory_commit",
+                    description: "Commit reflection entries for a batch checked out with memory_reflect. Each entry is standalone text plus an importance rating from 1 to 10. Safe to retry: committing the same batch twice reports success without duplicating.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            batch_id: { type: "string", description: "The batch_id returned by memory_reflect." },
+                            entries: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        text: { type: "string", description: "Standalone reflection prose, 1 to 8000 chars. No IDs or scores inline." },
+                                        importance: { type: "integer", minimum: 1, maximum: 10 },
+                                    },
+                                    required: ["text", "importance"],
+                                    additionalProperties: false,
+                                },
+                                minItems: 1,
+                                maxItems: 100,
+                            },
+                        },
+                        required: ["batch_id", "entries"],
+                    },
+                    execute: async (_toolCallId, params) => {
+                        if (!toolKey)
+                            return jsonToolResult({ error: "No memory key configured for this agent" });
+                        const batchId = typeof params.batch_id === "string" ? params.batch_id.trim() : "";
+                        if (!batchId)
+                            return jsonToolResult({ error: "batch_id required" });
+                        const rawEntries = Array.isArray(params.entries) ? params.entries : [];
+                        if (rawEntries.length < 1 || rawEntries.length > 100) {
+                            return jsonToolResult({ error: "entries must contain between 1 and 100 items" });
+                        }
+                        const entries = [];
+                        for (let i = 0; i < rawEntries.length; i++) {
+                            const e = rawEntries[i];
+                            if (!e || typeof e !== "object")
+                                return jsonToolResult({ error: `entry ${i + 1} is not an object` });
+                            const extraKeys = Object.keys(e).filter((k) => k !== "text" && k !== "importance");
+                            if (extraKeys.length > 0) {
+                                // Position-reference impossibility: entries are text plus importance only.
+                                return jsonToolResult({ error: `entry ${i + 1} has unsupported fields: ${extraKeys.join(", ")}. Entries are text plus importance only; coverage is always the whole batch.` });
+                            }
+                            const text = typeof e.text === "string" ? e.text : "";
+                            if (!text || text.length > 8000)
+                                return jsonToolResult({ error: `entry ${i + 1} text must be 1 to 8000 chars` });
+                            const importance = typeof e.importance === "number" && Number.isInteger(e.importance) && e.importance >= 1 && e.importance <= 10
+                                ? e.importance
+                                : null;
+                            if (importance === null)
+                                return jsonToolResult({ error: `entry ${i + 1} importance must be an integer 1 to 10` });
+                            entries.push({ text, importance });
+                        }
+                        try {
+                            const res = await commitReflections(endpoint, toolKey, {
+                                batch_id: batchId,
+                                entries,
+                                ...(embeddings && { embeddings }),
+                            });
+                            if (res.status === 409) {
+                                return jsonToolResult({ error: "lease expired, call memory_reflect again" });
+                            }
+                            if (!res.ok) {
+                                const errBody = await res.text().catch(() => "");
+                                return jsonToolResult({ error: `Commit failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+                            }
+                            const data = await res.json();
+                            // Created UUIDs dropped: the model never sees memory row IDs.
+                            return jsonToolResult({
+                                committed: data.committed ?? false,
+                                already_committed: data.already_committed ?? false,
+                                entries_created: data.created?.length ?? 0,
+                                sources_consolidated: data.sources_consolidated ?? 0,
+                                debt: data.reflection?.suggestion ?? null,
+                            });
+                        }
+                        catch (err) {
+                            return jsonToolResult({ error: err instanceof Error ? err.message : String(err) });
+                        }
+                    },
+                };
+            });
+            // memory_inspect: read-only lineage drill-down (curation surface, ids allowed)
+            api.registerTool((ctx) => {
+                const toolKey = resolveKey(ctx);
+                return {
+                    label: "Memory Inspect",
+                    name: "memory_inspect",
+                    description: "Inspect a memory's consolidation lineage by memory_id: its tier, the batch it came from, the sources it consolidated, and what it was consolidated into. Read-only.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            memory_id: { type: "string", description: "The memory id to inspect." },
+                        },
+                        required: ["memory_id"],
+                    },
+                    execute: async (_toolCallId, params) => {
+                        if (!toolKey)
+                            return jsonToolResult({ error: "No memory key configured for this agent" });
+                        const memoryId = typeof params.memory_id === "string" ? params.memory_id.trim() : "";
+                        if (!memoryId)
+                            return jsonToolResult({ error: "memory_id required" });
+                        try {
+                            const res = await inspectMemory(endpoint, toolKey, {
+                                memory_id: memoryId,
+                                ...(embeddings && { embeddings }),
+                            });
+                            if (!res.ok) {
+                                const errBody = await res.text().catch(() => "");
+                                return jsonToolResult({ error: `Inspect failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+                            }
+                            return jsonToolResult(await res.json());
+                        }
+                        catch (err) {
+                            return jsonToolResult({ error: err instanceof Error ? err.message : String(err) });
+                        }
+                    },
+                };
+            });
             // memory_get — exact copy of OpenClaw's implementation (pure local file read)
             api.registerTool((ctx) => {
                 const workspaceDir = ctx.workspaceDir || "";
@@ -1278,7 +1517,9 @@ If setting up MemoryRouter for another agent:
                 }
             });
             mr.command("delete")
-                .description("Clear all memories from vault")
+                .description("Clear all memories from vault, or delete specific memories with --ids")
+                .option("--ids <ids>", "Comma-separated memory ids to delete (instead of the whole vault)")
+                .option("--yes", "Confirm deletion (required with --ids)")
                 .option("--key <key>", "Override memory key (for subagent vaults)")
                 .action(async (opts) => {
                 const effectiveKey = opts.key || memoryKey;
@@ -1286,6 +1527,34 @@ If setting up MemoryRouter for another agent:
                     console.error("Not configured. Run: openclaw mr <key> or pass --key <key>");
                     return;
                 }
+                if (opts.ids) {
+                    const ids = opts.ids.split(",").map((s) => s.trim()).filter(Boolean);
+                    if (ids.length === 0) {
+                        console.error("No ids provided.");
+                        return;
+                    }
+                    console.log(`The following ${ids.length} memor${ids.length === 1 ? "y" : "ies"} will be PERMANENTLY deleted:`);
+                    for (const id of ids)
+                        console.log(`  • ${id}`);
+                    if (!opts.yes) {
+                        console.error("\nRefusing to delete without --yes. Re-run with --yes to confirm.");
+                        return;
+                    }
+                    try {
+                        const res = await deleteMemoryIds(endpoint, effectiveKey, { ids, ...(embeddings && { embeddings }) });
+                        if (!res.ok) {
+                            const errBody = await res.text().catch(() => "");
+                            console.error(`Delete failed: HTTP ${res.status}${errBody ? `: ${errBody.slice(0, 200)}` : ""}`);
+                            return;
+                        }
+                        const data = (await res.json());
+                        console.log(`✓ Deleted ${data.deleted ?? 0} of ${data.requested ?? ids.length} (not found: ${data.not_found ?? 0})`);
+                    }
+                    catch (err) {
+                        console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    return;
+                }
                 try {
                     const res = await deleteMemories(endpoint, effectiveKey, embeddings);
                     const data = (await res.json());
@@ -1296,6 +1565,46 @@ If setting up MemoryRouter for another agent:
                     console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
                 }
             });
+            mr.command("reflect")
+                .description("Show reflection debt status (consolidation runs via the agent's memory_reflect tool)")
+                .option("--key <key>", "Override memory key (for subagent vaults)")
+                .action(async (opts) => {
+                const effectiveKey = opts.key || memoryKey;
+                if (!effectiveKey) {
+                    console.error("Not configured. Run: openclaw mr <key> or pass --key <key>");
+                    return;
+                }
+                try {
+                    // Debt probe: an empty-window date-search returns the reflection
+                    // debt block with zero results and zero retrieval billing.
+                    const from = new Date(Date.now() - 1000).toISOString();
+                    const res = await dateSearch(endpoint, effectiveKey, { from, max_tokens: 1000, ...(embeddings && { embeddings }) });
+                    if (!res.ok) {
+                        const errBody = await res.text().catch(() => "");
+                        console.error(`Debt check failed: HTTP ${res.status}${errBody ? `: ${errBody.slice(0, 200)}` : ""}`);
+                        return;
+                    }
+                    const data = (await res.json());
+                    const debt = data.reflection;
+                    console.log("Reflection Debt");
+                    console.log("───────────────────────────");
+                    const raw = debt?.unconsolidated?.raw;
+                    const tier2 = debt?.unconsolidated?.tier2;
+                    console.log(`Raw unconsolidated:    ${raw?.units ?? 0} memories (~${raw?.est_tokens ?? 0} tokens)`);
+                    console.log(`Tier 2 unconsolidated: ${tier2?.count ?? 0} reflections (~${tier2?.est_tokens ?? 0} tokens)`);
+                    console.log(`Threshold:             ${debt?.threshold_tokens ?? 0} tokens`);
+                    if (debt?.suggestion) {
+                        console.log(`\nStatus: ${debt.suggestion}`);
+                        console.log("Consolidation runs through the agent. Ask your agent to consolidate memories (it uses the memory_reflect and memory_commit tools).");
+                    }
+                    else {
+                        console.log("\nStatus: nothing to consolidate right now.");
+                    }
+                }
+                catch (err) {
+                    console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            });
         }, { commands: ["mr"] });
         // ==================================================================
         // Service

package/index.ts

@@ -9,7 +9,7 @@
  */
 
 import { readFile, readdir, stat, lstat, writeFile, copyFile, mkdir } from "node:fs/promises";
-import { deleteMemories, getMemoryStats, ingestMemory, prepareMemory, searchMemory, warmupMemory } from "./memoryrouter-api.js";
+import { commitReflections, consolidateCheckout, dateSearch, deleteMemories, deleteMemoryIds, getMemoryStats, ingestMemory, inspectMemory, prepareMemory, searchMemory, warmupMemory } from "./memoryrouter-api.js";
 import { join, resolve, relative, isAbsolute, sep, dirname } from "node:path";
 import path from "node:path";
 import os from "node:os";
@@ -65,6 +65,25 @@ function jsonToolResult(payload: unknown) {
   return { content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }], details: payload };
 }
 
+// ── Reflection debt nudge (one line, appended to prepare injections whenever the server suggests it)
+type ReflectionDebt = {
+  suggestion?: string | null;
+  unconsolidated?: {
+    raw?: { units?: number; est_tokens?: number };
+    tier2?: { count?: number; importance?: number; est_tokens?: number };
+  };
+  threshold_tokens?: number;
+};
+
+function buildDebtNudgeLine(reflection: ReflectionDebt | undefined): string | null {
+  if (!reflection || !reflection.suggestion) return null;
+  const rawTokens = reflection.unconsolidated?.raw?.est_tokens ?? 0;
+  const tier2Tokens = reflection.unconsolidated?.tier2?.est_tokens ?? 0;
+  const totalTokens = rawTokens + tier2Tokens;
+  const kTokens = Math.max(1, Math.round(totalTokens / 1000));
+  return `[MemoryRouter] Consolidation suggested: ${kTokens}k unconsolidated tokens. Use the memory_reflect tool to consolidate them now.`;
+}
+
 // ── memory_get helpers (copied from OpenClaw source — pure filesystem, no embeddings)
 function isFileMissingError(err: unknown): boolean {
   return Boolean(err && typeof err === "object" && "code" in err && (err as any).code === "ENOENT");
@@ -768,13 +787,17 @@ If setting up MemoryRouter for another agent:
             tokens_billed?: number;
             memory_tokens?: number;
             metrics?: Record<string, unknown>;
+            reflection?: ReflectionDebt;
           };
 
           if (data.context) {
             const elapsed = Date.now() - startMs;
             api.logger.info?.(`memoryrouter: injected ${data.memories_found || 0} memories (${data.memory_tokens || 0} tokens, ${elapsed}ms) [llm_input]`);
             if (elapsed > 2000 && data.metrics) log(`memoryrouter: prepare metrics ${JSON.stringify(data.metrics)}`);
-            const wrapped = wrapForInjection(data.context);
+            let contextText = data.context;
+            const nudge = buildDebtNudgeLine(data.reflection);
+            if (nudge) contextText = `${contextText}\n\n${nudge}`;
+            const wrapped = wrapForInjection(contextText);
             return { appendSystemContext: wrapped };
           }
         } catch {
@@ -885,13 +908,17 @@ If setting up MemoryRouter for another agent:
             tokens_billed?: number;
             memory_tokens?: number;
             metrics?: Record<string, unknown>;
+            reflection?: ReflectionDebt;
           };
 
           if (data.context) {
             const elapsed = Date.now() - startMs;
             api.logger.info?.(`memoryrouter: injected ${data.memories_found || 0} memories (${data.memory_tokens || 0} tokens, ${elapsed}ms)`);
             if (elapsed > 2000 && data.metrics) log(`memoryrouter: prepare metrics ${JSON.stringify(data.metrics)}`);
-            const wrapped = wrapForInjection(data.context);
+            let contextText = data.context;
+            const nudge = buildDebtNudgeLine(data.reflection);
+            if (nudge) contextText = `${contextText}\n\n${nudge}`;
+            const wrapped = wrapForInjection(contextText);
             return { appendSystemContext: wrapped };
           }
         } catch (err) {
@@ -1025,6 +1052,17 @@ If setting up MemoryRouter for another agent:
               query: { type: "string" },
               maxResults: { type: "number" },
               minScore: { type: "number" },
+              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.",
+              },
+              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.",
+              },
             },
             required: ["query"],
           } as any,
@@ -1033,14 +1071,26 @@ If setting up MemoryRouter for another agent:
             const query = typeof params.query === "string" ? params.query.trim() : "";
             if (!query) return jsonToolResult({ results: [], error: "query required" });
             const limit = typeof params.maxResults === "number" ? params.maxResults : 50;
+            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;
             try {
-              const res = await searchMemory(endpoint, toolKey, { query, limit, embeddings });
+              const res = await searchMemory(endpoint, toolKey, {
+                query,
+                limit,
+                ...(tiers && tiers.length > 0 && { tiers }),
+                ...(importance !== undefined && { importance }),
+                embeddings,
+              });
               if (!res.ok) {
                 const errBody = await res.text().catch(() => "");
                 return jsonToolResult({ results: [], error: `Search failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
               }
               const data = await res.json() as {
-                memories?: Array<{ content: string; score: number; role: string; window: string; timestampHuman: string }>;
+                memories?: Array<{ content: string; score: number; role: string; window: string; timestampHuman: string; tier?: number; importance?: number }>;
                 totalMemories?: number;
                 tokenCount?: number;
               };
@@ -1052,6 +1102,8 @@ If setting up MemoryRouter for another agent:
                 role: m.role,
                 window: m.window,
                 date: m.timestampHuman,
+                ...(m.tier !== undefined && { tier: m.tier }),
+                ...(m.importance !== undefined && m.importance !== null && { importance: m.importance }),
               }));
               return jsonToolResult({
                 results,
@@ -1067,6 +1119,211 @@ If setting up MemoryRouter for another agent:
         };
       });
 
+      // ==================================================================
+      // Tools: memory_reflect + memory_commit (consolidation, two-tool shape)
+      // Mirrors the MCP consolidate_memories / commit_reflections pair.
+      // Invariants: source_ids are stripped, the model never sees row IDs,
+      // and contract instructions are transmitted verbatim.
+      // ==================================================================
+
+      // memory_reflect: checkout wrapper (nothing is modified until memory_commit)
+      api.registerTool((ctx) => {
+        const toolKey = resolveKey(ctx);
+        return {
+          label: "Memory Reflect",
+          name: "memory_reflect",
+          description: "Consolidate unconsolidated memories into reflections. Use when memory responses indicate consolidation is available, or when the user asks to organize or reflect on memory. Checks out a batch of memories under a 15 minute lease and returns their texts plus server instructions for writing reflection entries. Follow the instructions, then call memory_commit with the batch_id. Nothing is modified until commit.",
+          parameters: {
+            type: "object",
+            properties: {
+              tier: {
+                type: "integer",
+                enum: [1, 2],
+                description: "1 consolidates raw memories into reflections; 2 consolidates reflections into high-level reflections. Default 1.",
+              },
+              max_tokens: {
+                type: "integer",
+                minimum: 1000,
+                description: "Token budget for the checked-out batch. Defaults to 50000. No connector-side cap.",
+              },
+            },
+            required: [],
+          } as any,
+          execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+            if (!toolKey) return jsonToolResult({ error: "No memory key configured for this agent" });
+            const tier = params.tier === 2 ? 2 : 1;
+            const maxTokens = typeof params.max_tokens === "number" && params.max_tokens >= 1000
+              ? Math.floor(params.max_tokens)
+              : 50000;
+            try {
+              const res = await consolidateCheckout(endpoint, toolKey, {
+                tier: tier as 1 | 2,
+                max_tokens: maxTokens,
+                ...(embeddings && { embeddings }),
+              });
+              if (!res.ok) {
+                const errBody = await res.text().catch(() => "");
+                return jsonToolResult({ error: `Checkout failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+              }
+              const data = await res.json() as {
+                batch_id?: string | null;
+                tier?: number;
+                count?: number;
+                est_tokens?: number;
+                lease_expires_at?: string | null;
+                memories?: Array<{ text: string; date: string }>;
+                reflection_contract?: { version?: number; instructions?: string };
+                tier_definitions?: { target_tier?: number; instruction?: string };
+              };
+              if (!data.batch_id) {
+                return jsonToolResult({ batch_id: null, count: 0, message: "Nothing to consolidate at this tier right now." });
+              }
+              // Contract instructions are server-authored and passed through verbatim.
+              // If neither contract form is present, refuse; never author a local prompt.
+              const instructions = data.reflection_contract?.instructions ?? data.tier_definitions?.instruction;
+              if (!instructions) {
+                return jsonToolResult({ error: "Checkout response carried no reflection contract. Cannot consolidate without server instructions." });
+              }
+              // source_ids stripped: the model never sees memory row IDs.
+              return jsonToolResult({
+                batch_id: data.batch_id,
+                lease_expires_at: data.lease_expires_at ?? null,
+                count: data.count ?? 0,
+                est_tokens: data.est_tokens ?? 0,
+                instructions,
+                memories: (data.memories || []).map((m) => ({ text: m.text, date: m.date })),
+                message: `When your entries are ready, call memory_commit with batch_id ${data.batch_id} before ${data.lease_expires_at ?? "the lease expires"}.`,
+              });
+            } catch (err) {
+              return jsonToolResult({ error: err instanceof Error ? err.message : String(err) });
+            }
+          },
+        };
+      });
+
+      // memory_commit: commit wrapper (idempotent; 409 means the lease expired)
+      api.registerTool((ctx) => {
+        const toolKey = resolveKey(ctx);
+        return {
+          label: "Memory Commit",
+          name: "memory_commit",
+          description: "Commit reflection entries for a batch checked out with memory_reflect. Each entry is standalone text plus an importance rating from 1 to 10. Safe to retry: committing the same batch twice reports success without duplicating.",
+          parameters: {
+            type: "object",
+            properties: {
+              batch_id: { type: "string", description: "The batch_id returned by memory_reflect." },
+              entries: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    text: { type: "string", description: "Standalone reflection prose, 1 to 8000 chars. No IDs or scores inline." },
+                    importance: { type: "integer", minimum: 1, maximum: 10 },
+                  },
+                  required: ["text", "importance"],
+                  additionalProperties: false,
+                },
+                minItems: 1,
+                maxItems: 100,
+              },
+            },
+            required: ["batch_id", "entries"],
+          } as any,
+          execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+            if (!toolKey) return jsonToolResult({ error: "No memory key configured for this agent" });
+            const batchId = typeof params.batch_id === "string" ? params.batch_id.trim() : "";
+            if (!batchId) return jsonToolResult({ error: "batch_id required" });
+            const rawEntries = Array.isArray(params.entries) ? params.entries as Array<Record<string, unknown>> : [];
+            if (rawEntries.length < 1 || rawEntries.length > 100) {
+              return jsonToolResult({ error: "entries must contain between 1 and 100 items" });
+            }
+            const entries: Array<{ text: string; importance: number }> = [];
+            for (let i = 0; i < rawEntries.length; i++) {
+              const e = rawEntries[i];
+              if (!e || typeof e !== "object") return jsonToolResult({ error: `entry ${i + 1} is not an object` });
+              const extraKeys = Object.keys(e).filter((k) => k !== "text" && k !== "importance");
+              if (extraKeys.length > 0) {
+                // Position-reference impossibility: entries are text plus importance only.
+                return jsonToolResult({ error: `entry ${i + 1} has unsupported fields: ${extraKeys.join(", ")}. Entries are text plus importance only; coverage is always the whole batch.` });
+              }
+              const text = typeof e.text === "string" ? e.text : "";
+              if (!text || text.length > 8000) return jsonToolResult({ error: `entry ${i + 1} text must be 1 to 8000 chars` });
+              const importance = typeof e.importance === "number" && Number.isInteger(e.importance) && e.importance >= 1 && e.importance <= 10
+                ? e.importance
+                : null;
+              if (importance === null) return jsonToolResult({ error: `entry ${i + 1} importance must be an integer 1 to 10` });
+              entries.push({ text, importance });
+            }
+            try {
+              const res = await commitReflections(endpoint, toolKey, {
+                batch_id: batchId,
+                entries,
+                ...(embeddings && { embeddings }),
+              });
+              if (res.status === 409) {
+                return jsonToolResult({ error: "lease expired, call memory_reflect again" });
+              }
+              if (!res.ok) {
+                const errBody = await res.text().catch(() => "");
+                return jsonToolResult({ error: `Commit failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+              }
+              const data = await res.json() as {
+                committed?: boolean;
+                already_committed?: boolean;
+                created?: Array<{ id: string; importance: number }>;
+                sources_consolidated?: number;
+                reflection?: ReflectionDebt;
+              };
+              // Created UUIDs dropped: the model never sees memory row IDs.
+              return jsonToolResult({
+                committed: data.committed ?? false,
+                already_committed: data.already_committed ?? false,
+                entries_created: data.created?.length ?? 0,
+                sources_consolidated: data.sources_consolidated ?? 0,
+                debt: data.reflection?.suggestion ?? null,
+              });
+            } catch (err) {
+              return jsonToolResult({ error: err instanceof Error ? err.message : String(err) });
+            }
+          },
+        };
+      });
+
+      // memory_inspect: read-only lineage drill-down (curation surface, ids allowed)
+      api.registerTool((ctx) => {
+        const toolKey = resolveKey(ctx);
+        return {
+          label: "Memory Inspect",
+          name: "memory_inspect",
+          description: "Inspect a memory's consolidation lineage by memory_id: its tier, the batch it came from, the sources it consolidated, and what it was consolidated into. Read-only.",
+          parameters: {
+            type: "object",
+            properties: {
+              memory_id: { type: "string", description: "The memory id to inspect." },
+            },
+            required: ["memory_id"],
+          } as any,
+          execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+            if (!toolKey) return jsonToolResult({ error: "No memory key configured for this agent" });
+            const memoryId = typeof params.memory_id === "string" ? params.memory_id.trim() : "";
+            if (!memoryId) return jsonToolResult({ error: "memory_id required" });
+            try {
+              const res = await inspectMemory(endpoint, toolKey, {
+                memory_id: memoryId,
+                ...(embeddings && { embeddings }),
+              });
+              if (!res.ok) {
+                const errBody = await res.text().catch(() => "");
+                return jsonToolResult({ error: `Inspect failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+              }
+              return jsonToolResult(await res.json());
+            } catch (err) {
+              return jsonToolResult({ error: err instanceof Error ? err.message : String(err) });
+            }
+          },
+        };
+      });
+
       // memory_get — exact copy of OpenClaw's implementation (pure local file read)
       api.registerTool((ctx) => {
         const workspaceDir = ctx.workspaceDir || "";
@@ -1353,11 +1610,36 @@ If setting up MemoryRouter for another agent:
           });
 
         mr.command("delete")
-          .description("Clear all memories from vault")
+          .description("Clear all memories from vault, or delete specific memories with --ids")
+          .option("--ids <ids>", "Comma-separated memory ids to delete (instead of the whole vault)")
+          .option("--yes", "Confirm deletion (required with --ids)")
           .option("--key <key>", "Override memory key (for subagent vaults)")
-          .action(async (opts: { key?: string }) => {
+          .action(async (opts: { ids?: string; yes?: boolean; key?: string }) => {
             const effectiveKey = opts.key || memoryKey;
             if (!effectiveKey) { console.error("Not configured. Run: openclaw mr <key> or pass --key <key>"); return; }
+            if (opts.ids) {
+              const ids = opts.ids.split(",").map((s) => s.trim()).filter(Boolean);
+              if (ids.length === 0) { console.error("No ids provided."); return; }
+              console.log(`The following ${ids.length} memor${ids.length === 1 ? "y" : "ies"} will be PERMANENTLY deleted:`);
+              for (const id of ids) console.log(`  • ${id}`);
+              if (!opts.yes) {
+                console.error("\nRefusing to delete without --yes. Re-run with --yes to confirm.");
+                return;
+              }
+              try {
+                const res = await deleteMemoryIds(endpoint, effectiveKey, { ids, ...(embeddings && { embeddings }) });
+                if (!res.ok) {
+                  const errBody = await res.text().catch(() => "");
+                  console.error(`Delete failed: HTTP ${res.status}${errBody ? `: ${errBody.slice(0, 200)}` : ""}`);
+                  return;
+                }
+                const data = (await res.json()) as { requested?: number; deleted?: number; not_found?: number };
+                console.log(`✓ Deleted ${data.deleted ?? 0} of ${data.requested ?? ids.length} (not found: ${data.not_found ?? 0})`);
+              } catch (err) {
+                console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
+              }
+              return;
+            }
             try {
               const res = await deleteMemories(endpoint, effectiveKey, embeddings);
               const data = (await res.json()) as { message?: string };
@@ -1367,6 +1649,42 @@ If setting up MemoryRouter for another agent:
               console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
             }
           });
+
+        mr.command("reflect")
+          .description("Show reflection debt status (consolidation runs via the agent's memory_reflect tool)")
+          .option("--key <key>", "Override memory key (for subagent vaults)")
+          .action(async (opts: { key?: string }) => {
+            const effectiveKey = opts.key || memoryKey;
+            if (!effectiveKey) { console.error("Not configured. Run: openclaw mr <key> or pass --key <key>"); return; }
+            try {
+              // Debt probe: an empty-window date-search returns the reflection
+              // debt block with zero results and zero retrieval billing.
+              const from = new Date(Date.now() - 1000).toISOString();
+              const res = await dateSearch(endpoint, effectiveKey, { from, max_tokens: 1000, ...(embeddings && { embeddings }) });
+              if (!res.ok) {
+                const errBody = await res.text().catch(() => "");
+                console.error(`Debt check failed: HTTP ${res.status}${errBody ? `: ${errBody.slice(0, 200)}` : ""}`);
+                return;
+              }
+              const data = (await res.json()) as { reflection?: ReflectionDebt };
+              const debt = data.reflection;
+              console.log("Reflection Debt");
+              console.log("───────────────────────────");
+              const raw = debt?.unconsolidated?.raw;
+              const tier2 = debt?.unconsolidated?.tier2;
+              console.log(`Raw unconsolidated:    ${raw?.units ?? 0} memories (~${raw?.est_tokens ?? 0} tokens)`);
+              console.log(`Tier 2 unconsolidated: ${tier2?.count ?? 0} reflections (~${tier2?.est_tokens ?? 0} tokens)`);
+              console.log(`Threshold:             ${debt?.threshold_tokens ?? 0} tokens`);
+              if (debt?.suggestion) {
+                console.log(`\nStatus: ${debt.suggestion}`);
+                console.log("Consolidation runs through the agent. Ask your agent to consolidate memories (it uses the memory_reflect and memory_commit tools).");
+              } else {
+                console.log("\nStatus: nothing to consolidate right now.");
+              }
+            } catch (err) {
+              console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+          });
       },
       { commands: ["mr"] },
     );

package/memoryrouter-api.js

@@ -27,7 +27,75 @@ export async function searchMemory(endpoint, key, payload) {
             "Content-Type": "application/json",
             ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
         },
-        body: JSON.stringify({ query: payload.query, limit: payload.limit }),
+        body: JSON.stringify({
+            query: payload.query,
+            limit: payload.limit,
+            ...(payload.tiers !== undefined && { tiers: payload.tiers }),
+            ...(payload.importance !== undefined && { importance: payload.importance }),
+        }),
+    });
+}
+export async function consolidateCheckout(endpoint, key, payload) {
+    return fetch(`${endpoint}/v1/memory/consolidate/checkout`, {
+        method: "POST",
+        headers: {
+            ...JSON_HEADERS,
+            Authorization: `Bearer ${key}`,
+            ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+        },
+        body: JSON.stringify({
+            tier: payload.tier,
+            max_tokens: payload.max_tokens ?? 50000,
+        }),
+    });
+}
+export async function commitReflections(endpoint, key, payload) {
+    return fetch(`${endpoint}/v1/memory/consolidate/commit`, {
+        method: "POST",
+        headers: {
+            ...JSON_HEADERS,
+            Authorization: `Bearer ${key}`,
+            ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+        },
+        body: JSON.stringify({ batch_id: payload.batch_id, entries: payload.entries }),
+    });
+}
+export async function inspectMemory(endpoint, key, payload) {
+    return fetch(`${endpoint}/v1/memory/inspect`, {
+        method: "POST",
+        headers: {
+            ...JSON_HEADERS,
+            Authorization: `Bearer ${key}`,
+            ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+        },
+        body: JSON.stringify({ memory_id: payload.memory_id }),
+    });
+}
+export async function deleteMemoryIds(endpoint, key, payload) {
+    return fetch(`${endpoint}/v1/memory/delete-ids`, {
+        method: "POST",
+        headers: {
+            ...JSON_HEADERS,
+            Authorization: `Bearer ${key}`,
+            ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+        },
+        body: JSON.stringify({ ids: payload.ids }),
+    });
+}
+export async function dateSearch(endpoint, key, payload) {
+    return fetch(`${endpoint}/v1/memory/date-search`, {
+        method: "POST",
+        headers: {
+            ...JSON_HEADERS,
+            Authorization: `Bearer ${key}`,
+            ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+        },
+        body: JSON.stringify({
+            from: payload.from,
+            ...(payload.to !== undefined && { to: payload.to }),
+            ...(payload.query !== undefined && { query: payload.query }),
+            ...(payload.max_tokens !== undefined && { max_tokens: payload.max_tokens }),
+        }),
     });
 }
 export async function getMemoryStats(endpoint, key, embeddings) {
@@ -47,7 +115,6 @@ export async function deleteMemories(endpoint, key, embeddings) {
         headers: { Authorization: `Bearer ${key}` },
     });
 }
-
 export async function warmupMemory(endpoint, key, embeddings) {
     return fetch(`${endpoint}/v1/memory/warmup`, {
         method: "POST",

package/memoryrouter-api.ts

@@ -28,7 +28,7 @@ export function ingestMemory(endpoint: string, key: string, payload: { messages:
   });
 }
 
-export async function searchMemory(endpoint: string, key: string, payload: { query: string; limit: number; embeddings?: string }): Promise<Response> {
+export async function searchMemory(endpoint: string, key: string, payload: { query: string; limit: number; tiers?: number[]; importance?: number; embeddings?: string }): Promise<Response> {
   return fetch(`${endpoint}/v1/memory/search`, {
     method: "POST",
     headers: {
@@ -36,7 +36,80 @@ export async function searchMemory(endpoint: string, key: string, payload: { que
       "Content-Type": "application/json",
       ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
     },
-    body: JSON.stringify({ query: payload.query, limit: payload.limit }),
+    body: JSON.stringify({
+      query: payload.query,
+      limit: payload.limit,
+      ...(payload.tiers !== undefined && { tiers: payload.tiers }),
+      ...(payload.importance !== undefined && { importance: payload.importance }),
+    }),
+  });
+}
+
+export async function consolidateCheckout(endpoint: string, key: string, payload: { tier: 1 | 2; max_tokens?: number; embeddings?: string }): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/consolidate/checkout`, {
+    method: "POST",
+    headers: {
+      ...JSON_HEADERS,
+      Authorization: `Bearer ${key}`,
+      ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+    },
+    body: JSON.stringify({
+      tier: payload.tier,
+      max_tokens: payload.max_tokens ?? 50000,
+    }),
+  });
+}
+
+export async function commitReflections(endpoint: string, key: string, payload: { batch_id: string; entries: Array<{ text: string; importance: number }>; embeddings?: string }): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/consolidate/commit`, {
+    method: "POST",
+    headers: {
+      ...JSON_HEADERS,
+      Authorization: `Bearer ${key}`,
+      ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+    },
+    body: JSON.stringify({ batch_id: payload.batch_id, entries: payload.entries }),
+  });
+}
+
+export async function inspectMemory(endpoint: string, key: string, payload: { memory_id: string; embeddings?: string }): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/inspect`, {
+    method: "POST",
+    headers: {
+      ...JSON_HEADERS,
+      Authorization: `Bearer ${key}`,
+      ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+    },
+    body: JSON.stringify({ memory_id: payload.memory_id }),
+  });
+}
+
+export async function deleteMemoryIds(endpoint: string, key: string, payload: { ids: string[]; embeddings?: string }): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/delete-ids`, {
+    method: "POST",
+    headers: {
+      ...JSON_HEADERS,
+      Authorization: `Bearer ${key}`,
+      ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+    },
+    body: JSON.stringify({ ids: payload.ids }),
+  });
+}
+
+export async function dateSearch(endpoint: string, key: string, payload: { from: string; to?: string; query?: string; max_tokens?: number; embeddings?: string }): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/date-search`, {
+    method: "POST",
+    headers: {
+      ...JSON_HEADERS,
+      Authorization: `Bearer ${key}`,
+      ...(payload.embeddings && { "X-Embedding-Model": payload.embeddings }),
+    },
+    body: JSON.stringify({
+      from: payload.from,
+      ...(payload.to !== undefined && { to: payload.to }),
+      ...(payload.query !== undefined && { query: payload.query }),
+      ...(payload.max_tokens !== undefined && { max_tokens: payload.max_tokens }),
+    }),
   });
 }
 

package/package.json

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