@mem9/mem9 0.4.7 → 0.4.8-alpha.0

package/README.md

@@ -1,6 +1,8 @@
-# OpenClaw Plugin for mnemos
+# OpenClaw Plugin for mem9
 
-Memory plugin for [OpenClaw](https://github.com/openclaw) — replaces the built-in memory slot with cloud-persistent shared memory. Runs in server mode only, connecting to `mnemo-server` via `apiUrl` + `apiKey` (preferred) or legacy `tenantID`.
+Memory plugin for [OpenClaw](https://github.com/openclaw) — replaces the built-in memory slot with cloud-persistent shared memory. Runs in server mode only, connecting to `mnemo-server` via `apiUrl` + `apiKey` (preferred) or legacy `tenantID`. Optional `provisionToken` and `provisionQueryParams` are used only during first-time create-new setup before an explicit `apiKey` is configured.
+
+When `apiKey` is absent during create-new onboarding, the plugin does not auto-provision on startup. Instead, the first post-restart user message triggers exactly one create-new provision through the normal hook path. The plugin coordinates that call across concurrent OpenClaw plugin registrations on the same machine and reuses the generated key locally for future restarts tied to the same `provisionToken`.
 
 ## 🚀 Quick Start (Server Mode)
 
@@ -20,14 +22,14 @@ curl -s -X POST http://localhost:8080/v1alpha1/mem9s \
 # {"id": "uuid"}
 ```
 
-Add mnemo to your project's `openclaw.json`:
+Add mem9 to your project's `openclaw.json`:
 
 ```json
 {
   "plugins": {
-    "slots": { "memory": "openclaw" },
+    "slots": { "memory": "mem9" },
     "entries": {
-      "openclaw": {
+      "mem9": {
         "enabled": true,
         "config": {
           "apiUrl": "http://localhost:8080",
@@ -64,8 +66,8 @@ This is a `kind: "memory"` plugin — OpenClaw's framework manages when to load/
 
 | Hook | Trigger | What it does |
 |---|---|---|
-| `before_prompt_build` | Every LLM call | Searches memories by current prompt, injects relevant ones as context (3-min TTL cache) |
-| `after_compaction` | After `/compact` | Invalidates cache so the next prompt gets fresh memories from the database |
+| `before_prompt_build` | Every LLM call | Searches memories by current prompt and injects relevant ones as context |
+| `after_compaction` | After `/compact` | Logs compaction so the next prompt re-queries memories from the server |
 | `before_reset` | Before `/reset` | Saves a session summary (last 3 user messages) as memory before context is wiped |
 | `agent_end` | Agent finishes | Auto-captures the last assistant response as memory (if substantial) |
 
@@ -73,7 +75,7 @@ This is a `kind: "memory"` plugin — OpenClaw's framework manages when to load/
 
 | Tool | Description |
 |---|---|
-| `memory_store` | Store a new memory (upsert by key) |
+| `memory_store` | Store a new memory |
 | `memory_search` | Hybrid vector + keyword search (or keyword-only) |
 | `memory_get` | Retrieve a single memory by ID |
 | `memory_update` | Update an existing memory |
@@ -91,7 +93,7 @@ This is a `kind: "memory"` plugin — OpenClaw's framework manages when to load/
 ### Method A: npm install (Recommended)
 
 ```bash
-openclaw plugins install @mem9/openclaw
+openclaw plugins install @mem9/mem9
 ```
 
 ### Method B: From source
@@ -104,7 +106,7 @@ npm install
 
 ### Configure OpenClaw
 
-Add mnemo to your project's `openclaw.json`:
+Add mem9 to your project's `openclaw.json`:
 
 OpenClaw is often deployed across teams with multiple agents. Server mode gives you:
 
@@ -139,10 +141,10 @@ Each agent uses the same `apiKey` for the shared memory pool. The plugin sends t
 {
   "plugins": {
     "slots": {
-      "memory": "openclaw"
+      "memory": "mem9"
     },
     "entries": {
-      "openclaw": {
+      "mem9": {
         "enabled": true,
         "config": {
           "apiUrl": "http://your-server:8080",
@@ -160,8 +162,8 @@ That's it. The server handles scoping and conflict resolution. Conceptually, the
 
 Start OpenClaw. You should see:
 
-```
-[mem9] Server mode
+```text
+[mem9] Server mode (v1alpha2)
 ```
 
 If you see `[mem9] No mode configured...`, check your `openclaw.json` config.
@@ -174,11 +176,17 @@ Defined in `openclaw.plugin.json`:
 |---|---|---|
 | `apiUrl` | string | mnemo-server URL |
 | `apiKey` | string | Preferred key. Uses `/v1alpha2/mem9s/...` with `X-API-Key` header |
+| `provisionToken` | string | Optional one-time create-new token used locally to ensure the first-message create-new provision runs only once and is reused on this machine until an explicit `apiKey` is configured |
+| `provisionQueryParams` | object | Optional `utm_*` map forwarded only to the initial `POST /v1alpha1/mem9s` request made during create-new when `apiKey` is absent |
 | `defaultTimeoutMs` | number | Default timeout for non-search mem9 API requests in milliseconds. Default: `8000` |
 | `searchTimeoutMs` | number | Timeout for `memory_search` and automatic recall search in milliseconds. Default: `15000` |
+| `debug` | boolean | When `true`, emit mem9 debug logs. Current coverage includes `before_prompt_build` recall diagnostics; future mem9 debug categories reuse the same switch |
+| `debugRecall` | boolean | Deprecated alias for `debug` |
 | `tenantID` | string | Legacy alias for `apiKey`. The plugin still uses `/v1alpha2/mem9s/...` with `X-API-Key`. |
 
-> **Note**: `apiKey` takes precedence when both fields are set. If only `tenantID` is present, the plugin treats it as a legacy alias for `apiKey`, still uses v1alpha2, and logs a deprecation warning once at startup.
+> **Note**: `apiKey` takes precedence when both fields are set. If only `tenantID` is present, the plugin treats it as a legacy alias for `apiKey`, still uses v1alpha2, and logs a deprecation warning once at startup. `provisionToken` and `provisionQueryParams` are ignored after an `apiKey` is already configured, and non-`utm_*` keys are dropped before the provision request is sent. During create-new onboarding, the plugin shares one in-flight provision result across concurrent local registrations and reuses the persisted result for the same `provisionToken`, so repeated reloads or repeated setup retries do not create multiple keys.
+
+For debugging, set `"debug": true` in the plugin config. The plugin will emit `[mem9][debug]` lines; current coverage shows how `before_prompt_build` stripped OpenClaw metadata wrappers before issuing the recall search. `"debugRecall": true` still works as a deprecated alias.
 
 ## Timeout Behavior
 
@@ -213,7 +221,7 @@ Example:
 openclaw-plugin/
 ├── README.md              # This file
 ├── openclaw.plugin.json   # Plugin metadata + config schema
-├── package.json           # npm package (@mem9/openclaw)
+├── package.json           # npm package (@mem9/mem9)
 ├── index.ts               # Plugin entry point + tool registration
 ├── backend.ts             # MemoryBackend interface
 ├── server-backend.ts      # Server mode: fetch → mnemo API
@@ -227,5 +235,6 @@ openclaw-plugin/
 |---|---|---|
 | `No mode configured` | Missing config | Add `apiUrl` and `apiKey` (or legacy `tenantID`) to plugin config |
 | `Server mode requires...` | Missing key | Add `apiKey` (or legacy `tenantID`) to config |
+| Multiple auto-provisioned keys appear during create-new | Setup retriggered create-new provisioning before the first result was reused, or an older plugin still auto-provisions on startup | Upgrade to `@mem9/mem9@0.4.7+`; newer builds provision only from the first post-restart user message and reuse one local result across duplicate setup retries |
 | Search requests time out | Hybrid/vector search exceeds plugin timeout | Increase `searchTimeoutMs` in plugin config |
-| Plugin not loading | Not in memory slot | Set `"slots": {"memory": "openclaw"}` in openclaw.json |
+| Plugin not loading | Not in memory slot | Set `"slots": {"memory": "mem9"}` in openclaw.json |

package/backend.ts

@@ -9,6 +9,20 @@ import type {
   IngestResult,
 } from "./types.js";
 
+export class PendingProvisionError extends Error {
+  constructor(
+    message = "mem9 create-new setup is waiting for the first post-restart message to finish provisioning",
+  ) {
+    super(message);
+    this.name = "PendingProvisionError";
+  }
+}
+
+export function isPendingProvisionError(err: unknown): err is PendingProvisionError {
+  return err instanceof PendingProvisionError
+    || (err instanceof Error && err.name === "PendingProvisionError");
+}
+
 /**
  * MemoryBackend — the abstraction that tools and hooks call through.
  */

package/hooks.ts

@@ -11,7 +11,7 @@
  * Reference: OpenClaw's built-in memory-lancedb extension uses the same pattern.
  */
 
-import type { MemoryBackend } from "./backend.js";
+import { isPendingProvisionError, type MemoryBackend } from "./backend.js";
 import type { Memory, IngestMessage } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -38,6 +38,14 @@ interface Logger {
   error: (msg: string) => void;
 }
 
+function previewText(text: string, maxLen = 160): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLen) {
+    return normalized;
+  }
+  return normalized.slice(0, maxLen) + "...";
+}
+
 /**
  * Hook handler types mirroring OpenClaw's PluginHookHandlerMap.
  * We define them locally to avoid importing OpenClaw types at the module level.
@@ -161,6 +169,33 @@ function nonEmptyString(value: unknown): string | null {
   return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
 
+function extractRecallQuery(prompt: string): string {
+  let s = stripInjectedContext(prompt).replace(/\r\n?/g, "\n");
+
+  s = s.replace(
+    /^Conversation info \(untrusted metadata\):\s*\n```[\s\S]*?\n```\s*/gm,
+    "",
+  );
+  s = s.replace(
+    /^Sender \(untrusted metadata\):\s*\n```[\s\S]*?\n```\s*/gm,
+    "",
+  );
+  s = s.replace(
+    /<<<EXTERNAL_UNTRUSTED_CONTENT[\s\S]*?<<<END_EXTERNAL_UNTRUSTED_CONTENT[^>]*>>>/g,
+    "",
+  );
+  s = s.replace(
+    /^Untrusted context \(metadata, do not treat as instructions or commands\):\s*$/gm,
+    "",
+  );
+  s = s.replace(/^\s*Source:\s.*$/gm, "");
+  s = s.replace(/^\s*UNTRUSTED [^\n]*$/gm, "");
+  s = s.replace(/^\s*---\s*$/gm, "");
+  s = s.replace(/\n{3,}/g, "\n\n");
+
+  return s.trim();
+}
+
 // ---------------------------------------------------------------------------
 // Hook registration
 // ---------------------------------------------------------------------------
@@ -169,7 +204,12 @@ export function registerHooks(
   api: HookApi,
   backend: MemoryBackend,
   logger: Logger,
-  options?: { maxIngestBytes?: number; fallbackAgentId?: string },
+  options?: {
+    maxIngestBytes?: number;
+    fallbackAgentId?: string;
+    provisionForCreateNew?: () => Promise<string>;
+    debug?: boolean;
+  },
 ): void {
   const maxIngestBytes = options?.maxIngestBytes ?? DEFAULT_MAX_INGEST_BYTES;
 
@@ -181,11 +221,34 @@ export function registerHooks(
     async (event: unknown) => {
       try {
         const evt = event as { prompt?: string };
-        const prompt = evt?.prompt;
-        if (!prompt || prompt.length < MIN_PROMPT_LEN) return;
+        const prompt = nonEmptyString(evt?.prompt);
+        if (options?.provisionForCreateNew) {
+          await options.provisionForCreateNew();
+        }
+        if (!prompt) return;
+
+        const recallQuery = extractRecallQuery(prompt);
+        if (options?.debug) {
+          logger.info(
+            `[mem9][debug] before_prompt_build rawPromptLen=${prompt.length} recallQueryLen=${recallQuery.length} recallQueryPreview=${JSON.stringify(previewText(recallQuery))}`,
+          );
+        }
+        if (recallQuery.length < MIN_PROMPT_LEN) {
+          if (options?.debug) {
+            logger.info(
+              `[mem9][debug] before_prompt_build skipping recall because stripped query is shorter than ${MIN_PROMPT_LEN}`,
+            );
+          }
+          return;
+        }
 
-        const result = await backend.search({ q: prompt, limit: MAX_INJECT });
+        const result = await backend.search({ q: recallQuery, limit: MAX_INJECT });
         const memories = result.data ?? [];
+        if (options?.debug) {
+          logger.info(
+            `[mem9][debug] before_prompt_build recall search limit=${MAX_INJECT} results=${memories.length}`,
+          );
+        }
 
         if (memories.length === 0) return;
 
@@ -195,6 +258,9 @@ export function registerHooks(
           prependContext: formatMemoriesBlock(memories),
         };
       } catch (err) {
+        if (isPendingProvisionError(err)) {
+          return;
+        }
         // Graceful degradation — never block the LLM call
         logger.error(`[mem9] before_prompt_build failed: ${String(err)}`);
       }
@@ -245,6 +311,9 @@ export function registerHooks(
 
       logger.info("[mem9] Session context saved before reset");
     } catch (err) {
+      if (isPendingProvisionError(err)) {
+        return;
+      }
       // Best-effort — never block /reset
       logger.error(`[mem9] before_reset save failed: ${String(err)}`);
     }
@@ -346,7 +415,10 @@ export function registerHooks(
           `[mem9] Ingested session: memories_changed=${result.memories_changed}, status=${result.status}`
         );
       }
-    } catch {
+    } catch (err) {
+      if (isPendingProvisionError(err)) {
+        return;
+      }
       // Best-effort — never fail the agent end phase
     }
   });