mr-memory 3.13.1 → 3.13.2

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.12.0
+openclaw plugins install npm:mr-memory@3.13.2
 ```
 
-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.
+The explicit `npm:` source and version make the audited install deterministic. `mr-memory@3.13.2` is published on npm. A ClawHub listing has not been verified and is not required for this path.
 
 ## Setup
 
@@ -30,8 +30,17 @@ openclaw mr upload --brain ~/.notopenclaw   # Upload from a different agent
 openclaw mr off              # Disable
 openclaw mr delete           # Clear vault
 openclaw mr <key>            # Enable with key
+openclaw mr low              # Up to 21 memories (12 raw + 6 tier 2 + 3 tier 3)
+openclaw mr medium           # Up to 43 memories (25 + 12 + 6), balanced default
+openclaw mr high             # Up to 87 memories (50 + 25 + 12)
 ```
 
+## Memory Density
+
+The current density choices are `low`, `medium`, and `high`. New installs and configs without an explicit density use `medium`, the balanced default. Existing explicit `low` or `high` settings are unchanged. Legacy `xhigh` configs remain valid so upgrades do not break the gateway, but the plugin normalizes `xhigh` to `high` and no longer advertises it as a current option.
+
+The totals are tier-aware retrieval budgets, not raw-memory-only limits. Actual results can be lower when fewer relevant memories match.
+
 ## Upload Options
 
 ```bash

package/index.js

@@ -290,6 +290,25 @@ const WORKSPACE_FILES = [
     "IDENTITY.md", "USER.md", "MEMORY.md", "HEARTBEAT.md",
     "TOOLS.md", "AGENTS.md", "SOUL.md", "BOOTSTRAP.md",
 ];
+// ──────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────
+/** Current densities are low, medium, and high. Legacy xhigh remains valid in
+ * existing configs but is deliberately hidden from current choices and sent
+ * to MemoryRouter as high. Missing or invalid values use the balanced medium
+ * default. */
+function normalizeMemoryDensity(value) {
+    switch (value) {
+        case "low":
+        case "medium":
+        case "high":
+            return value;
+        case "xhigh":
+            return "high";
+        default:
+            return "medium";
+    }
+}
 function openClawConfigPath() {
     return process.env.OPENCLAW_CONFIG_PATH || process.env.OPENCLAW_CONFIG || join(os.homedir(), ".openclaw", "openclaw.json");
 }
@@ -474,7 +493,7 @@ const memoryRouterPlugin = {
         const cfg = api.pluginConfig;
         const endpoint = cfg?.endpoint?.replace(/\/v1\/?$/, "") || DEFAULT_ENDPOINT;
         const memoryKey = cfg?.key;
-        const density = cfg?.density || "high";
+        const density = normalizeMemoryDensity(cfg?.density);
         const mode = cfg?.mode || "relay";
         const logging = cfg?.logging ?? false;
         const embeddings = cfg?.embeddings; // undefined = bge (default), "qwen" = qwen3-8b
@@ -688,6 +707,8 @@ If setting up MemoryRouter for another agent:
             // On stock OpenClaw, the return value is ignored (fire-and-forget).
             // When PR #24122 merges, OpenClaw will use the returned prependContext.
             // This gives forward compatibility — no plugin update needed.
+            // Current stock SDK typings still mark llm_input as observation-only;
+            // runtime builds that support returned context consume this value.
             api.on("llm_input", async (event, ctx) => {
                 // Auto-consolidation runs are single-purpose tool sessions: no memory
                 // injection (their prompt must stay exactly the consolidation
@@ -1499,11 +1520,12 @@ If setting up MemoryRouter for another agent:
                 console.log("Then restart gateway:");
                 console.log("  openclaw gateway restart");
             });
-            // Density commands
+            // Current density commands. Legacy xhigh configs still load as high,
+            // but xhigh is intentionally not advertised as a command.
             for (const [name, desc] of [
-                ["xhigh", "Set density to xhigh (160 results, ~50k tokens)"],
-                ["high", "Set density to high (80 results, ~24k tokens) [default]"],
-                ["low", "Set density to low (40 results, ~12k tokens)"],
+                ["low", "Set density to low: up to 21 memories (12 raw + 6 tier 2 + 3 tier 3)"],
+                ["medium", "Set density to medium: up to 43 memories (25 raw + 12 tier 2 + 6 tier 3) [default, balanced]"],
+                ["high", "Set density to high: up to 87 memories (50 raw + 25 tier 2 + 12 tier 3)"],
             ]) {
                 mr.command(name)
                     .description(desc)

package/index.ts

@@ -9,7 +9,7 @@
  */
 
 import { readFile, readdir, stat, lstat, writeFile, copyFile, mkdir } from "node:fs/promises";
-import { commitReflections, consolidateCheckout, dateSearch, deleteMemories, deleteMemoryIds, getMemoryStats, ingestMemory, inspectMemory, prepareMemory, searchMemory, warmupMemory } from "./memoryrouter-api.js";
+import { commitReflections, consolidateCheckout, dateSearch, deleteMemories, deleteMemoryIds, getMemoryStats, ingestMemory, inspectMemory, prepareMemory, searchMemory, warmupMemory, type MemoryDensity } from "./memoryrouter-api.js";
 import { isAutoConsolidationSession, maybeTriggerAutoConsolidate } from "./auto-consolidate.js";
 import { join, resolve, relative, isAbsolute, sep, dirname } from "node:path";
 import path from "node:path";
@@ -316,7 +316,8 @@ const WORKSPACE_FILES = [
 type MemoryRouterConfig = {
   key: string;
   endpoint?: string;
-  density?: "low" | "high" | "xhigh";
+  /** xhigh is accepted only for backward compatibility and normalizes to high. */
+  density?: MemoryDensity | "xhigh";
   mode?: "relay" | "proxy";
   logging?: boolean;
   embeddings?: string;
@@ -334,6 +335,23 @@ type MemoryRouterConfig = {
 // Helpers
 // ──────────────────────────────────────────────────────
 
+/** Current densities are low, medium, and high. Legacy xhigh remains valid in
+ * existing configs but is deliberately hidden from current choices and sent
+ * to MemoryRouter as high. Missing or invalid values use the balanced medium
+ * default. */
+function normalizeMemoryDensity(value?: MemoryRouterConfig["density"]): MemoryDensity {
+  switch (value) {
+    case "low":
+    case "medium":
+    case "high":
+      return value;
+    case "xhigh":
+      return "high";
+    default:
+      return "medium";
+  }
+}
+
 type CompatApi = OpenClawPluginApi & {
   updatePluginConfig?: (config: Record<string, unknown>) => Promise<void>;
   updatePluginEnabled?: (enabled: boolean) => Promise<void>;
@@ -525,7 +543,7 @@ const memoryRouterPlugin = {
     const cfg = api.pluginConfig as MemoryRouterConfig | undefined;
     const endpoint = cfg?.endpoint?.replace(/\/v1\/?$/, "") || DEFAULT_ENDPOINT;
     const memoryKey = cfg?.key;
-    const density = cfg?.density || "high";
+    const density = normalizeMemoryDensity(cfg?.density);
     const mode = cfg?.mode || "relay";
     const logging = cfg?.logging ?? false;
     const embeddings = cfg?.embeddings; // undefined = bge (default), "qwen" = qwen3-8b
@@ -744,7 +762,9 @@ If setting up MemoryRouter for another agent:
       // On stock OpenClaw, the return value is ignored (fire-and-forget).
       // When PR #24122 merges, OpenClaw will use the returned prependContext.
       // This gives forward compatibility — no plugin update needed.
-      api.on("llm_input", async (event, ctx) => {
+      // Current stock SDK typings still mark llm_input as observation-only;
+      // runtime builds that support returned context consume this value.
+      (api as any).on("llm_input", async (event: any, ctx: any) => {
         // Auto-consolidation runs are single-purpose tool sessions: no memory
         // injection (their prompt must stay exactly the consolidation
         // mission) and no re-trigger loops.
@@ -1590,11 +1610,12 @@ If setting up MemoryRouter for another agent:
             console.log("  openclaw gateway restart");
           });
 
-        // Density commands
+        // Current density commands. Legacy xhigh configs still load as high,
+        // but xhigh is intentionally not advertised as a command.
         for (const [name, desc] of [
-          ["xhigh", "Set density to xhigh (160 results, ~50k tokens)"],
-          ["high", "Set density to high (80 results, ~24k tokens) [default]"],
-          ["low", "Set density to low (40 results, ~12k tokens)"],
+          ["low", "Set density to low: up to 21 memories (12 raw + 6 tier 2 + 3 tier 3)"],
+          ["medium", "Set density to medium: up to 43 memories (25 raw + 12 tier 2 + 6 tier 3) [default, balanced]"],
+          ["high", "Set density to high: up to 87 memories (50 raw + 25 tier 2 + 12 tier 3)"],
         ] as const) {
           mr.command(name)
             .description(desc)

package/memoryrouter-api.ts

@@ -1,8 +1,10 @@
 const JSON_HEADERS = { "Content-Type": "application/json" };
 
+export type MemoryDensity = "low" | "medium" | "high";
+
 type PreparePayload = {
   messages: Array<{ role: string; content: string }>;
-  density: string;
+  density: MemoryDensity;
   embeddings?: string;
 };
 

package/openclaw.plugin.json

@@ -18,9 +18,9 @@
     },
     "density": {
       "label": "Memory Density",
-      "placeholder": "high",
+      "placeholder": "medium",
       "advanced": true,
-      "help": "Amount of memory to inject: low (40), high (80), xhigh (160)"
+      "help": "Current choices: low, up to 21 memories (12 raw + 6 tier 2 + 3 tier 3); medium, up to 43 (25 + 12 + 6), balanced default; high, up to 87 (50 + 25 + 12)."
     },
     "keepWarmMs": {
       "label": "Keep Warm Window (ms)",
@@ -48,7 +48,9 @@
       },
       "density": {
         "type": "string",
-        "enum": ["low", "high", "xhigh"]
+        "pattern": "^(low|medium|high|xhigh)$",
+        "default": "medium",
+        "description": "Current densities are low, medium, and high. Legacy xhigh configs remain valid and are treated as high."
       },
       "logging": {
         "type": "boolean"

package/package.json

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