@mem9/mem9 0.4.1 → 0.4.3

package/README.md

@@ -1,6 +1,6 @@
-# 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 `provisionQueryParams` can forward `utm_*` attribution only during first-time auto-provisioning.
 
 ## 🚀 Quick Start (Server Mode)
 
@@ -20,14 +20,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 +64,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 +73,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 +91,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 +104,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 +139,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 +160,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 +174,12 @@ Defined in `openclaw.plugin.json`:
 |---|---|---|
 | `apiUrl` | string | mnemo-server URL |
 | `apiKey` | string | Preferred key. Uses `/v1alpha2/mem9s/...` with `X-API-Key` header |
+| `provisionQueryParams` | object | Optional `utm_*` map forwarded only to the initial `POST /v1alpha1/mem9s` auto-provision request 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` |
 | `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. `provisionQueryParams` is ignored after an `apiKey` is already configured, and non-`utm_*` keys are dropped before the provision request is sent.
 
 ## Timeout Behavior
 
@@ -213,7 +214,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
@@ -228,4 +229,4 @@ 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 |
 | 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/index.test.ts

@@ -0,0 +1,193 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import mnemoPlugin from "./index.js";
+
+interface StubApi {
+  pluginConfig?: unknown;
+  logger: {
+    info: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+  };
+  registerTool: () => void;
+  registerCapability?: (slot: string, capability: unknown) => void;
+  on: () => void;
+}
+
+function createStubApi(
+  pluginConfig: unknown,
+  options?: {
+    onRegisterCapability?: (slot: string, capability: unknown) => void;
+    infoLogs?: string[];
+    errorLogs?: string[];
+  },
+): StubApi {
+  const infoLogs = options?.infoLogs ?? [];
+  const errorLogs = options?.errorLogs ?? [];
+
+  return {
+    pluginConfig,
+    logger: {
+      info: (...args: unknown[]) => {
+        infoLogs.push(args.map(String).join(" "));
+      },
+      error: (...args: unknown[]) => {
+        errorLogs.push(args.map(String).join(" "));
+      },
+    },
+    registerTool: () => {},
+    registerCapability: options?.onRegisterCapability,
+    on: () => {},
+  };
+}
+
+async function flushAsyncWork(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+test("register eagerly auto-provisions when apiKey is absent", async () => {
+  const originalFetch = globalThis.fetch;
+  const requests: string[] = [];
+  const infoLogs: string[] = [];
+  const errorLogs: string[] = [];
+
+  globalThis.fetch = async (input) => {
+    requests.push(String(input));
+
+    return new Response(JSON.stringify({ id: "space-1" }), {
+      status: 201,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+  };
+
+  try {
+    mnemoPlugin.register(
+      createStubApi(
+        {
+          apiUrl: "https://api.mem9.ai",
+          provisionQueryParams: {
+            utm_source: "bosn",
+          },
+        },
+        { infoLogs, errorLogs },
+      ),
+    );
+
+    await flushAsyncWork();
+
+    assert.deepEqual(errorLogs, []);
+    assert.equal(requests.length, 1);
+    assert.equal(
+      requests[0],
+      "https://api.mem9.ai/v1alpha1/mem9s?utm_source=bosn",
+    );
+    assert.equal(
+      infoLogs.includes("[mem9] apiKey not configured; starting auto-provision"),
+      true,
+    );
+    assert.equal(
+      infoLogs.some((msg) => msg.includes("*** Auto-provisioned apiKey=space-1 ***")),
+      true,
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("search retries auto-provision after an eager startup failure", async () => {
+  const originalFetch = globalThis.fetch;
+  const infoLogs: string[] = [];
+  const errorLogs: string[] = [];
+  let provisionAttempts = 0;
+  let searchRequests = 0;
+  let capability: {
+    search: (query: string, opts?: { limit?: number }) => Promise<{ data: unknown[]; total: number }>;
+  } | null = null;
+
+  globalThis.fetch = async (input, init) => {
+    const url = String(input);
+
+    if (url.includes("/v1alpha1/mem9s")) {
+      provisionAttempts += 1;
+
+      if (provisionAttempts === 1) {
+        return new Response(JSON.stringify({ error: "boom" }), {
+          status: 500,
+          headers: {
+            "Content-Type": "application/json",
+          },
+        });
+      }
+
+      return new Response(JSON.stringify({ id: "space-2" }), {
+        status: 201,
+        headers: {
+          "Content-Type": "application/json",
+        },
+      });
+    }
+
+    if (url.includes("/v1alpha2/mem9s/memories")) {
+      searchRequests += 1;
+      const headers = init?.headers as Record<string, string> | undefined;
+      assert.equal(headers?.["X-API-Key"], "space-2");
+
+      return new Response(
+        JSON.stringify({
+          memories: [],
+          total: 0,
+          limit: 20,
+          offset: 0,
+        }),
+        {
+          status: 200,
+          headers: {
+            "Content-Type": "application/json",
+          },
+        },
+      );
+    }
+
+    throw new Error(`unexpected fetch: ${url}`);
+  };
+
+  try {
+    mnemoPlugin.register(
+      createStubApi(
+        {
+          apiUrl: "https://api.mem9.ai",
+        },
+        {
+          infoLogs,
+          errorLogs,
+          onRegisterCapability: (_slot, registeredCapability) => {
+            capability = registeredCapability as typeof capability;
+          },
+        },
+      ),
+    );
+
+    await flushAsyncWork();
+
+    assert.equal(provisionAttempts, 1);
+    assert.equal(
+      errorLogs.some((msg) => msg.includes("auto-provision failed: mem9s provision failed (500):")),
+      true,
+    );
+    assert.notEqual(capability, null);
+
+    const result = await capability!.search("hello");
+
+    assert.deepEqual(result, { data: [], total: 0 });
+    assert.equal(provisionAttempts, 2);
+    assert.equal(searchRequests, 1);
+    assert.equal(
+      infoLogs.some((msg) => msg.includes("*** Auto-provisioned apiKey=space-2 ***")),
+      true,
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

package/index.ts

@@ -75,6 +75,10 @@ function jsonResult(data: unknown) {
   }
 }
 
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
 interface MemoryCapability {
   search: (query: string, opts?: { limit?: number }) => Promise<{ data: Memory[]; total: number }>;
   store: (content: string, opts?: { tags?: string[]; source?: string }) => Promise<unknown>;
@@ -303,6 +307,7 @@ const mnemoPlugin = {
     const cfg = (api.pluginConfig ?? {}) as PluginConfig;
     const effectiveApiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
     const timeoutConfig = resolveTimeouts(cfg, api.logger);
+    const hookAgentId = cfg.agentName ?? "agent";
     if (!cfg.apiUrl) {
       api.logger.info(`[mem9] apiUrl not configured, using default ${DEFAULT_API_URL}`);
     }
@@ -314,7 +319,15 @@ const mnemoPlugin = {
       api.logger.info("[mem9] tenantID is deprecated; treating it as apiKey for v1alpha2");
     }
     const registerTenant = async (agentName: string): Promise<string> => {
-      const backend = new ServerBackend(effectiveApiUrl, "", agentName, timeoutConfig);
+      const backend = new ServerBackend(
+        effectiveApiUrl,
+        "",
+        agentName,
+        {
+          timeouts: timeoutConfig,
+          provisionQueryParams: cfg.provisionQueryParams ?? {},
+        },
+      );
       const result = await backend.register();
       api.logger.info(
         `[mem9] *** Auto-provisioned apiKey=${result.id} *** Save this to your config as apiKey`
@@ -325,14 +338,22 @@ const mnemoPlugin = {
     const resolveAPIKey = (agentName: string): Promise<string> => {
       if (configuredApiKey) return Promise.resolve(configuredApiKey);
       if (!registrationPromise) {
-        registrationPromise = registerTenant(agentName);
+        registrationPromise = registerTenant(agentName).catch((err) => {
+          registrationPromise = null;
+          throw err;
+        });
       }
       return registrationPromise;
     };
 
     api.logger.info("[mem9] Server mode (v1alpha2)");
 
-    const hookAgentId = cfg.agentName ?? "agent";
+    if (!configuredApiKey) {
+      api.logger.info("[mem9] apiKey not configured; starting auto-provision");
+      void resolveAPIKey(hookAgentId).catch((err) => {
+        api.logger.error(`[mem9] auto-provision failed: ${errorMessage(err)}`);
+      });
+    }
 
     const factory: ToolFactory = (ctx: ToolContext) => {
       const agentId = ctx.agentId ?? cfg.agentName ?? "agent";
@@ -390,15 +411,24 @@ const toolNames = [
 ];
 
 class LazyServerBackend implements MemoryBackend {
+  private apiUrl: string;
+  private apiKeyProvider: () => Promise<string>;
+  private agentId: string;
+  private timeouts: BackendTimeouts;
   private resolved: ServerBackend | null = null;
   private resolving: Promise<ServerBackend> | null = null;
 
   constructor(
-    private apiUrl: string,
-    private apiKeyProvider: () => Promise<string>,
-    private agentId: string,
-    private timeouts: BackendTimeouts,
-  ) {}
+    apiUrl: string,
+    apiKeyProvider: () => Promise<string>,
+    agentId: string,
+    timeouts: BackendTimeouts,
+  ) {
+    this.apiUrl = apiUrl;
+    this.apiKeyProvider = apiKeyProvider;
+    this.agentId = agentId;
+    this.timeouts = timeouts;
+  }
 
   private async resolve(): Promise<ServerBackend> {
     if (this.resolved) return this.resolved;
@@ -406,7 +436,9 @@ class LazyServerBackend implements MemoryBackend {
 
     this.resolving = this.apiKeyProvider().then((apiKey) =>
       Promise.resolve().then(() => {
-        this.resolved = new ServerBackend(this.apiUrl, apiKey, this.agentId, this.timeouts);
+        this.resolved = new ServerBackend(this.apiUrl, apiKey, this.agentId, {
+          timeouts: this.timeouts,
+        });
         return this.resolved;
       })
     ).catch((err) => {

package/openclaw.plugin.json

@@ -14,6 +14,13 @@
         "type": "string",
         "description": "mem9 API key (secret — do not share)"
       },
+      "provisionQueryParams": {
+        "type": "object",
+        "description": "Optional utm_* params forwarded only during first-time auto-provisioning",
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
       "defaultTimeoutMs": {
         "type": "number",
         "minimum": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem9/mem9",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "OpenClaw shared memory plugin — cloud-persistent memory with hybrid vector + keyword search via mnemo-server",
   "type": "module",
   "license": "Apache-2.0",
@@ -34,6 +34,7 @@
     "access": "public"
   },
   "scripts": {
+    "test": "rm -rf ./dist-test && tsc -p ./tsconfig.test.json && node --test ./dist-test/*.test.js",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck"
   },
@@ -42,6 +43,7 @@
   },
   "dependencies": {},
   "devDependencies": {
+    "@types/node": "^22.15.30",
     "typescript": "^5.5.0"
   },
   "openclaw": {

package/server-backend.test.ts

@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { ServerBackend } from "./server-backend.js";
+
+test("register forwards only utm_* params during auto-provision", async () => {
+  const originalFetch = globalThis.fetch;
+  let requestedURL = "";
+
+  globalThis.fetch = async (input, init) => {
+    requestedURL = String(input);
+    assert.equal(init?.method, "POST");
+
+    return new Response(JSON.stringify({ id: "space-1" }), {
+      status: 201,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+  };
+
+  try {
+    const backend = new ServerBackend("https://api.mem9.ai", "", "agent-1", {
+      provisionQueryParams: {
+        utm_source: "bosn",
+        foo: "bar",
+        utm_campaign: "spring",
+        utm_medium: "",
+      },
+    });
+
+    const result = await backend.register();
+    assert.equal(result.id, "space-1");
+
+    const url = new URL(requestedURL);
+    assert.equal(url.origin + url.pathname, "https://api.mem9.ai/v1alpha1/mem9s");
+    assert.equal(url.searchParams.get("utm_source"), "bosn");
+    assert.equal(url.searchParams.get("utm_campaign"), "spring");
+    assert.equal(url.searchParams.has("foo"), false);
+    assert.equal(url.searchParams.has("utm_medium"), false);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("normal memory requests do not append provision query params", async () => {
+  const originalFetch = globalThis.fetch;
+  let requestedURL = "";
+
+  globalThis.fetch = async (input) => {
+    requestedURL = String(input);
+
+    return new Response(
+      JSON.stringify({
+        id: "mem-1",
+        content: "remember this",
+        created_at: "2026-04-05T00:00:00Z",
+        updated_at: "2026-04-05T00:00:00Z",
+      }),
+      {
+        status: 200,
+        headers: {
+          "Content-Type": "application/json",
+        },
+      },
+    );
+  };
+
+  try {
+    const backend = new ServerBackend("https://api.mem9.ai", "space-key", "agent-1", {
+      provisionQueryParams: {
+        utm_source: "bosn",
+      },
+    });
+
+    await backend.store({ content: "remember this" });
+
+    assert.equal(requestedURL, "https://api.mem9.ai/v1alpha2/mem9s/memories");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

package/server-backend.ts

@@ -22,6 +22,11 @@ export interface BackendTimeouts {
   searchTimeoutMs?: number;
 }
 
+interface ServerBackendOptions {
+  timeouts?: BackendTimeouts;
+  provisionQueryParams?: Record<string, string>;
+}
+
 interface RequestOptions {
   timeoutMs?: number;
 }
@@ -30,25 +35,37 @@ export class ServerBackend implements MemoryBackend {
   private baseUrl: string;
   private apiKey: string;
   private agentName: string;
+  private provisionQueryParams: Record<string, string>;
   private timeouts: Required<BackendTimeouts>;
 
   constructor(
     apiUrl: string,
     apiKey: string,
     agentName: string,
-    timeouts: BackendTimeouts = {},
+    options: ServerBackendOptions = {},
   ) {
     this.baseUrl = apiUrl.replace(/\/+$/, "");
     this.apiKey = apiKey;
     this.agentName = agentName;
+    this.provisionQueryParams = options.provisionQueryParams ?? {};
     this.timeouts = {
-      defaultTimeoutMs: timeouts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS,
-      searchTimeoutMs: timeouts.searchTimeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS,
+      defaultTimeoutMs: options.timeouts?.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+      searchTimeoutMs: options.timeouts?.searchTimeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS,
     };
   }
 
   async register(): Promise<ProvisionMem9sResponse> {
-    const resp = await fetch(this.baseUrl + "/v1alpha1/mem9s", {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(this.provisionQueryParams)) {
+      if (!key.startsWith("utm_") || typeof value !== "string" || value === "") {
+        continue;
+      }
+
+      query.set(key, value);
+    }
+
+    const qs = query.toString();
+    const resp = await fetch(this.baseUrl + "/v1alpha1/mem9s" + (qs ? `?${qs}` : ""), {
       method: "POST",
       signal: AbortSignal.timeout(this.timeouts.defaultTimeoutMs),
     });

package/types.ts

@@ -2,6 +2,7 @@ export interface PluginConfig {
   // Server mode (apiUrl present → server)
   apiUrl?: string;
   apiKey?: string;
+  provisionQueryParams?: Record<string, string>;
   tenantID?: string;
   defaultTimeoutMs?: number;
   searchTimeoutMs?: number;