@mem9/mem9 0.3.7 → 0.4.0-rc.0

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,18 +20,19 @@ 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",
-          "apiKey": "uuid"
+          "apiKey": "uuid",
+          "searchTimeoutMs": 15000
         }
       }
     }
@@ -63,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) |
 
@@ -72,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 |
@@ -90,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
@@ -103,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:
 
@@ -138,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",
@@ -159,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.
@@ -173,9 +174,39 @@ 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
+
+The plugin uses two timeout buckets:
+
+- `searchTimeoutMs` applies to `memory_search` and the automatic recall search in `before_prompt_build`
+- `defaultTimeoutMs` applies to all other mem9 HTTP requests, including register, store, get, update, delete, and ingest
+
+Example:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw": {
+        "enabled": true,
+        "config": {
+          "apiUrl": "http://your-server:8080",
+          "apiKey": "uuid",
+          "defaultTimeoutMs": 8000,
+          "searchTimeoutMs": 15000
+        }
+      }
+    }
+  }
+}
+```
 
 ## File Structure
 
@@ -183,7 +214,7 @@ Defined in `openclaw.plugin.json`:
 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
@@ -197,4 +228,5 @@ 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 |
-| Plugin not loading | Not in memory slot | Set `"slots": {"memory": "openclaw"}` in openclaw.json |
+| 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": "mem9"}` in openclaw.json |

package/hooks.ts

@@ -3,7 +3,7 @@
  *
  * Provides automatic memory recall and capture via OpenClaw's hook system:
  * - before_prompt_build: inject relevant memories into every LLM call
- *   (grouped by type: pinned → insights)
+ *   (preserving the server/backend recall order)
  * - after_compaction: (no-op placeholder for future use)
  * - before_reset: save session context before /reset wipes it
  * - agent_end: auto-capture via smart pipeline with size-aware message selection
@@ -57,6 +57,8 @@ interface HookContext {
   sessionId?: string;
   /** Legacy alias for sessionId used by older OpenClaw versions. */
   sessionKey?: string;
+  /** What initiated this agent run: "user", "heartbeat", "cron", or "memory". */
+  trigger?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -105,27 +107,11 @@ function escapeForPrompt(text: string): string {
 }
 
 /**
- * Format memories for injection, grouped by type for maximum comprehension:
- * 1. Pinned memories first (user-explicit preferences)
- * 2. Insights (extracted facts)
+ * Format memories for injection while preserving the backend recall order.
  */
 function formatMemoriesBlock(memories: Memory[]): string {
   if (memories.length === 0) return "";
 
-  // Group by memory_type, falling back to "pinned" for legacy memories
-  const pinned: Memory[] = [];
-  const insights: Memory[] = [];
-  const other: Memory[] = [];
-
-  for (const m of memories) {
-    const mtype = m.memory_type ?? "pinned";
-    switch (mtype) {
-      case "pinned": pinned.push(m); break;
-      case "insight": insights.push(m); break;
-      default: other.push(m); break;
-    }
-  }
-
   const lines: string[] = [];
   let idx = 1;
 
@@ -140,18 +126,8 @@ function formatMemoriesBlock(memories: Memory[]): string {
     return `${idx++}.${sep}${escapeForPrompt(content)}`;
   };
 
-  if (pinned.length > 0) {
-    lines.push("[Preferences]");
-    for (const m of pinned) lines.push(formatMem(m));
-  }
-  if (insights.length > 0) {
-    if (lines.length > 0) lines.push("");
-    lines.push("[Knowledge]");
-    for (const m of insights) lines.push(formatMem(m));
-  }
-  if (other.length > 0) {
-    if (lines.length > 0) lines.push("");
-    for (const m of other) lines.push(formatMem(m));
+  for (const memory of memories) {
+    lines.push(formatMem(memory));
   }
 
   return [
@@ -292,6 +268,12 @@ export function registerHooks(
       const hookCtx = (context ?? {}) as HookContext;
       if (!evt?.success || !evt.messages || evt.messages.length === 0) return;
 
+      // Skip cron/heartbeat-triggered runs — they produce low-value messages
+      if (hookCtx.trigger === "cron" || hookCtx.trigger === "heartbeat") {
+        logger.info(`[mem9] Skipping auto-ingest for ${hookCtx.trigger}-triggered run`);
+        return;
+      }
+
       // Format raw messages into IngestMessage format
       const formatted: IngestMessage[] = [];
       for (const msg of evt.messages) {
@@ -300,6 +282,11 @@ export function registerHooks(
         const role = typeof m.role === "string" ? m.role : "";
         if (!role) continue;
 
+        // Skip cron tool results — structured JSON job definitions with no memory value
+        if (role === "toolResult" && typeof m.toolName === "string" && m.toolName === "cron") {
+          continue;
+        }
+
         let content = "";
         if (typeof m.content === "string") {
           content = m.content;

package/index.ts

@@ -1,5 +1,10 @@
 import type { MemoryBackend } from "./backend.js";
-import { ServerBackend } from "./server-backend.js";
+import {
+  DEFAULT_SEARCH_TIMEOUT_MS,
+  DEFAULT_TIMEOUT_MS,
+  ServerBackend,
+  type BackendTimeouts,
+} from "./server-backend.js";
 import { registerHooks } from "./hooks.js";
 import type {
   PluginConfig,
@@ -12,8 +17,49 @@ import type {
 } from "./types.js";
 
 const DEFAULT_API_URL = "https://api.mem9.ai";
-const MEM9_MEMORY_PATH_PREFIX = "mem9/";
-const MEM9_MEMORY_PROVIDER = "mem9";
+const TIMEOUT_FIELDS = ["defaultTimeoutMs", "searchTimeoutMs"] as const;
+
+function normalizeTimeoutMs(
+  value: unknown,
+  field: (typeof TIMEOUT_FIELDS)[number],
+  fallback: number,
+  logger: OpenClawPluginApi["logger"],
+): number {
+  if (value == null) return fallback;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    logger.info(`[mem9] invalid ${field}; using ${fallback}ms`);
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
+function resolveTimeouts(
+  cfg: PluginConfig,
+  logger: OpenClawPluginApi["logger"],
+): Required<BackendTimeouts> {
+  const timeouts = {
+    defaultTimeoutMs: normalizeTimeoutMs(
+      cfg.defaultTimeoutMs,
+      "defaultTimeoutMs",
+      DEFAULT_TIMEOUT_MS,
+      logger,
+    ),
+    searchTimeoutMs: normalizeTimeoutMs(
+      cfg.searchTimeoutMs,
+      "searchTimeoutMs",
+      DEFAULT_SEARCH_TIMEOUT_MS,
+      logger,
+    ),
+  };
+
+  if (TIMEOUT_FIELDS.some((field) => cfg[field] != null)) {
+    logger.info(
+      `[mem9] timeout config: defaultTimeoutMs=${timeouts.defaultTimeoutMs}, searchTimeoutMs=${timeouts.searchTimeoutMs}`,
+    );
+  }
+
+  return timeouts;
+}
 
 function jsonResult(data: unknown) {
   // Older OpenClaw versions may assume tool results have a normalized
@@ -29,69 +75,6 @@ function jsonResult(data: unknown) {
   }
 }
 
-function buildMemoryPath(id: string): string {
-  return `${MEM9_MEMORY_PATH_PREFIX}${id}`;
-}
-
-function normalizeMemoryLookup(value: string): string {
-  const trimmed = value.trim();
-  return trimmed.startsWith(MEM9_MEMORY_PATH_PREFIX)
-    ? trimmed.slice(MEM9_MEMORY_PATH_PREFIX.length)
-    : trimmed;
-}
-
-function normalizeSnippet(text: string, maxLength = 240): string {
-  const flattened = text.replace(/\s+/g, " ").trim();
-  if (flattened.length <= maxLength) {
-    return flattened;
-  }
-  return `${flattened.slice(0, maxLength - 3)}...`;
-}
-
-function countLines(text: string): number {
-  if (!text) {
-    return 1;
-  }
-  return text.split(/\r?\n/).length;
-}
-
-function buildPromptSection(params: {
-  availableTools: Set<string>;
-  citationsMode?: string;
-}): string[] {
-  const hasMemorySearch = params.availableTools.has("memory_search");
-  const hasMemoryGet = params.availableTools.has("memory_get");
-
-  if (!hasMemorySearch && !hasMemoryGet) {
-    return [];
-  }
-
-  let toolGuidance: string;
-  if (hasMemorySearch && hasMemoryGet) {
-    toolGuidance =
-      "Before answering anything about prior work, decisions, dates, people, preferences, or todos: run `memory_search` first, then use `memory_get` to pull only the needed memory. If low confidence after search, say you checked.";
-  } else if (hasMemorySearch) {
-    toolGuidance =
-      "Before answering anything about prior work, decisions, dates, people, preferences, or todos: run `memory_search` first and answer from the matching results. If low confidence after search, say you checked.";
-  } else {
-    toolGuidance =
-      "Before answering anything about prior work, decisions, dates, people, preferences, or todos that already point to a specific memory: run `memory_get` to pull only the needed memory. If low confidence after reading it, say you checked.";
-  }
-
-  const lines = ["## Memory Recall", toolGuidance];
-  if (params.citationsMode === "off") {
-    lines.push(
-      "Citations are disabled: do not mention memory identifiers unless the user explicitly asks.",
-    );
-  } else {
-    lines.push(
-      "Citations: include the memory identifier only when it helps the user verify recalled memory.",
-    );
-  }
-  lines.push("");
-  return lines;
-}
-
 interface MemoryCapability {
   search: (query: string, opts?: { limit?: number }) => Promise<{ data: Memory[]; total: number }>;
   store: (content: string, opts?: { tags?: string[]; source?: string }) => Promise<unknown>;
@@ -99,71 +82,6 @@ interface MemoryCapability {
   remove: (id: string) => Promise<boolean>;
 }
 
-interface MemoryPromptSectionBuilder {
-  (params: { availableTools: Set<string>; citationsMode?: string }): string[];
-}
-
-interface MemorySearchResult {
-  path: string;
-  startLine: number;
-  endLine: number;
-  score: number;
-  snippet: string;
-  source: "memory";
-  citation?: string;
-}
-
-interface MemoryProviderStatus {
-  backend: "builtin" | "qmd";
-  provider: string;
-  requestedProvider?: string;
-  custom?: Record<string, unknown>;
-}
-
-interface MemorySearchManager {
-  search: (
-    query: string,
-    opts?: { maxResults?: number; minScore?: number; sessionKey?: string },
-  ) => Promise<MemorySearchResult[]>;
-  readFile: (params: {
-    relPath: string;
-    from?: number;
-    lines?: number;
-  }) => Promise<{ text: string; path: string }>;
-  status: () => MemoryProviderStatus;
-  sync?: (params?: {
-    reason?: string;
-    force?: boolean;
-    sessionFiles?: string[];
-    progress?: (update: { completed: number; total: number; label?: string }) => void;
-  }) => Promise<void>;
-  probeEmbeddingAvailability: () => Promise<{ ok: boolean; error?: string }>;
-  probeVectorAvailability: () => Promise<boolean>;
-  close?: () => Promise<void>;
-}
-
-interface MemoryRuntime {
-  getMemorySearchManager: (params: {
-    cfg?: unknown;
-    agentId: string;
-    purpose?: "default" | "status";
-  }) => Promise<{ manager: MemorySearchManager | null; error?: string }>;
-  resolveMemoryBackendConfig: (params: { cfg?: unknown; agentId: string }) => {
-    backend: "builtin" | "qmd";
-    provider: string;
-    requestedProvider?: string;
-    custom?: Record<string, unknown>;
-  };
-  closeAllMemorySearchManagers?: () => Promise<void>;
-}
-
-interface MemorySlotCapability {
-  promptBuilder?: MemoryPromptSectionBuilder;
-  runtime?: MemoryRuntime;
-  flushPlanResolver?: unknown;
-  publicArtifacts?: unknown;
-}
-
 interface OpenClawPluginApi {
   pluginConfig?: unknown;
   logger: {
@@ -174,9 +92,6 @@ interface OpenClawPluginApi {
     factory: ToolFactory | (() => AnyAgentTool[]),
     opts: { names: string[] }
   ) => void;
-  registerMemoryCapability?: (capability: MemorySlotCapability) => void;
-  registerMemoryPromptSection?: (builder: MemoryPromptSectionBuilder) => void;
-  registerMemoryRuntime?: (runtime: MemoryRuntime) => void;
   registerCapability?: (slot: string, capability: MemoryCapability) => void;
   on: (hookName: string, handler: (...args: unknown[]) => unknown, opts?: { priority?: number }) => void;
 }
@@ -202,146 +117,6 @@ interface AnyAgentTool {
   execute: (_id: string, params: unknown) => Promise<unknown>;
 }
 
-class Mem9MemorySearchManager implements MemorySearchManager {
-  constructor(
-    private backend: MemoryBackend,
-    private apiUrl: string,
-  ) {}
-
-  async search(
-    query: string,
-    opts?: { maxResults?: number; minScore?: number; sessionKey?: string },
-  ): Promise<MemorySearchResult[]> {
-    void opts?.sessionKey;
-    const result = await this.backend.search({
-      q: query,
-      limit: opts?.maxResults,
-    });
-    return (result.data ?? [])
-      .map((memory, index) => {
-        const startLine = 1;
-        const endLine = countLines(memory.content);
-        const score =
-          typeof memory.score === "number"
-            ? memory.score
-            : Math.max(0, 1 - index / Math.max(result.data.length, 1));
-        return {
-          path: buildMemoryPath(memory.id),
-          startLine,
-          endLine,
-          score,
-          snippet: normalizeSnippet(memory.content),
-          source: "memory" as const,
-          citation: `${buildMemoryPath(memory.id)}#L${startLine}`,
-        };
-      })
-      .filter((entry) => opts?.minScore == null || entry.score >= opts.minScore);
-  }
-
-  async readFile(params: {
-    relPath: string;
-    from?: number;
-    lines?: number;
-  }): Promise<{ text: string; path: string }> {
-    const lookup = normalizeMemoryLookup(params.relPath);
-    const memory = await this.backend.get(lookup);
-    if (!memory) {
-      return { text: "", path: params.relPath };
-    }
-
-    const contentLines = memory.content.split(/\r?\n/);
-    const fromLine = Math.max(1, params.from ?? 1);
-    const lineCount = params.lines == null ? contentLines.length : Math.max(0, params.lines);
-    const sliced =
-      params.lines == null
-        ? contentLines.slice(fromLine - 1)
-        : contentLines.slice(fromLine - 1, fromLine - 1 + lineCount);
-
-    return {
-      text: sliced.join("\n"),
-      path: buildMemoryPath(memory.id),
-    };
-  }
-
-  status(): MemoryProviderStatus {
-    return {
-      backend: "builtin",
-      provider: MEM9_MEMORY_PROVIDER,
-      requestedProvider: MEM9_MEMORY_PROVIDER,
-      custom: {
-        mode: "remote",
-        apiUrl: this.apiUrl,
-      },
-    };
-  }
-
-  async sync(): Promise<void> {}
-
-  async probeEmbeddingAvailability(): Promise<{ ok: boolean; error?: string }> {
-    try {
-      await this.backend.search({ q: "mem9-healthcheck", limit: 1 });
-      return { ok: true };
-    } catch (err) {
-      return {
-        ok: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
-  }
-
-  async probeVectorAvailability(): Promise<boolean> {
-    const probe = await this.probeEmbeddingAvailability();
-    return probe.ok;
-  }
-
-  async close(): Promise<void> {}
-}
-
-function createMemoryRuntime(params: {
-  apiUrl: string;
-  fallbackAgentId: string;
-  createBackend: (agentId: string) => MemoryBackend;
-}): MemoryRuntime {
-  const managers = new Map<string, Mem9MemorySearchManager>();
-
-  const getOrCreateManager = (agentId: string): Mem9MemorySearchManager => {
-    const resolvedAgentId = agentId.trim() || params.fallbackAgentId;
-    const existing = managers.get(resolvedAgentId);
-    if (existing) {
-      return existing;
-    }
-    const next = new Mem9MemorySearchManager(
-      params.createBackend(resolvedAgentId),
-      params.apiUrl,
-    );
-    managers.set(resolvedAgentId, next);
-    return next;
-  };
-
-  return {
-    async getMemorySearchManager({ agentId }) {
-      return { manager: getOrCreateManager(agentId) };
-    },
-    resolveMemoryBackendConfig() {
-      return {
-        backend: "builtin",
-        provider: MEM9_MEMORY_PROVIDER,
-        requestedProvider: MEM9_MEMORY_PROVIDER,
-        custom: {
-          mode: "remote",
-          apiUrl: params.apiUrl,
-        },
-      };
-    },
-    async closeAllMemorySearchManagers() {
-      for (const manager of managers.values()) {
-        await manager.close?.();
-      }
-      managers.clear();
-    },
-  };
-}
-
 function buildTools(backend: MemoryBackend): AnyAgentTool[] {
   return [
     {
@@ -395,10 +170,6 @@ function buildTools(backend: MemoryBackend): AnyAgentTool[] {
         type: "object",
         properties: {
           q: { type: "string", description: "Search query" },
-          query: {
-            type: "string",
-            description: "Search query alias for hosts that expect `query` instead of `q`",
-          },
           tags: {
             type: "string",
             description: "Comma-separated tags to filter by (AND)",
@@ -418,19 +189,9 @@ function buildTools(backend: MemoryBackend): AnyAgentTool[] {
       },
       async execute(_id: string, params: unknown) {
         try {
-          const input = { ...((params ?? {}) as SearchInput) };
-          if (!input.q && typeof (params as { query?: unknown } | null)?.query === "string") {
-            input.q = (params as { query: string }).query;
-          }
+          const input = (params ?? {}) as SearchInput;
           const result = await backend.search(input);
-          return jsonResult({
-            ok: true,
-            ...result,
-            data: (result.data ?? []).map((memory) => ({
-              ...memory,
-              path: buildMemoryPath(memory.id),
-            })),
-          });
+          return jsonResult({ ok: true, ...result });
         } catch (err) {
           return jsonResult({
             ok: false,
@@ -448,31 +209,16 @@ function buildTools(backend: MemoryBackend): AnyAgentTool[] {
         type: "object",
         properties: {
           id: { type: "string", description: "Memory id (UUID)" },
-          path: {
-            type: "string",
-            description: "Memory lookup path alias, e.g. mem9/<id>",
-          },
         },
-        required: [],
+        required: ["id"],
       },
       async execute(_id: string, params: unknown) {
         try {
-          const raw = params as { id?: string; path?: string };
-          const lookup = typeof raw.id === "string" ? raw.id : raw.path;
-          if (!lookup) {
-            return jsonResult({ ok: false, error: "memory id or path is required" });
-          }
-          const id = normalizeMemoryLookup(lookup);
+          const { id } = params as { id: string };
           const result = await backend.get(id);
           if (!result)
             return jsonResult({ ok: false, error: "memory not found" });
-          return jsonResult({
-            ok: true,
-            data: {
-              ...result,
-              path: buildMemoryPath(result.id),
-            },
-          });
+          return jsonResult({ ok: true, data: result });
         } catch (err) {
           return jsonResult({
             ok: false,
@@ -552,12 +298,11 @@ const mnemoPlugin = {
   name: "Mnemo Memory",
   description:
     "AI agent memory — server mode (mnemo-server) with hybrid vector + keyword search.",
-  // Static hint for hosts that inspect entry metadata before runtime registration.
-  capabilities: ["memory"],
 
   register(api: OpenClawPluginApi) {
     const cfg = (api.pluginConfig ?? {}) as PluginConfig;
     const effectiveApiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
+    const timeoutConfig = resolveTimeouts(cfg, api.logger);
     if (!cfg.apiUrl) {
       api.logger.info(`[mem9] apiUrl not configured, using default ${DEFAULT_API_URL}`);
     }
@@ -569,7 +314,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);
+      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`
@@ -589,52 +342,32 @@ const mnemoPlugin = {
 
     const hookAgentId = cfg.agentName ?? "agent";
 
-    const createBackend = (agentId: string): MemoryBackend =>
-      new LazyServerBackend(
+    const factory: ToolFactory = (ctx: ToolContext) => {
+      const agentId = ctx.agentId ?? cfg.agentName ?? "agent";
+      const backend = new LazyServerBackend(
         effectiveApiUrl,
         () => resolveAPIKey(agentId),
         agentId,
+        timeoutConfig,
       );
-
-    const factory: ToolFactory = (ctx: ToolContext) => {
-      const agentId = ctx.agentId ?? cfg.agentName ?? "agent";
-      const backend = createBackend(agentId);
       return buildTools(backend);
     };
 
     api.registerTool(factory, { names: toolNames });
 
     // Shared lazy backend for hooks and capability registration.
-    const hookBackend = createBackend(hookAgentId);
-    const memoryRuntime = createMemoryRuntime({
-      apiUrl: effectiveApiUrl,
-      fallbackAgentId: hookAgentId,
-      createBackend,
-    });
-
-    // OpenClaw's memory slot API has evolved across versions:
-    // - current hosts prefer registerMemoryCapability({ promptBuilder, runtime })
-    // - 2026.4.2 uses registerMemoryPromptSection/registerMemoryRuntime
-    // - older compatibility shims may still expose registerCapability("memory", ...)
-    if (typeof api.registerMemoryCapability === "function") {
-      api.registerMemoryCapability({
-        promptBuilder: buildPromptSection,
-        runtime: memoryRuntime,
-      });
-    } else {
-      if (typeof api.registerMemoryPromptSection === "function") {
-        api.registerMemoryPromptSection(buildPromptSection);
-      }
-      if (typeof api.registerMemoryRuntime === "function") {
-        api.registerMemoryRuntime(memoryRuntime);
-      }
-    }
+    const hookBackend = new LazyServerBackend(
+      effectiveApiUrl,
+      () => resolveAPIKey(hookAgentId),
+      hookAgentId,
+      timeoutConfig,
+    );
 
-    if (
-      typeof api.registerMemoryCapability !== "function" &&
-      typeof api.registerMemoryRuntime !== "function" &&
-      typeof api.registerCapability === "function"
-    ) {
+    // Register memory capability so OpenClaw 2026.4.2+ binds this plugin to
+    // the memory slot. Without this, the plugin is treated as a legacy
+    // hook-only plugin and automatic context injection won't work.
+    // Guard with typeof check for backward compatibility with older hosts.
+    if (typeof api.registerCapability === "function") {
       api.registerCapability("memory", {
         search: async (query, opts) => {
           const result = await hookBackend.search({ q: query, limit: opts?.limit });
@@ -672,6 +405,7 @@ class LazyServerBackend implements MemoryBackend {
     private apiUrl: string,
     private apiKeyProvider: () => Promise<string>,
     private agentId: string,
+    private timeouts: BackendTimeouts,
   ) {}
 
   private async resolve(): Promise<ServerBackend> {
@@ -680,7 +414,9 @@ class LazyServerBackend implements MemoryBackend {
 
     this.resolving = this.apiKeyProvider().then((apiKey) =>
       Promise.resolve().then(() => {
-        this.resolved = new ServerBackend(this.apiUrl, apiKey, this.agentId);
+        this.resolved = new ServerBackend(this.apiUrl, apiKey, this.agentId, {
+          timeouts: this.timeouts,
+        });
         return this.resolved;
       })
     ).catch((err) => {

package/openclaw.plugin.json

@@ -14,6 +14,23 @@
         "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,
+        "description": "Default timeout in milliseconds for non-search mem9 API requests (default 8000)"
+      },
+      "searchTimeoutMs": {
+        "type": "number",
+        "minimum": 1,
+        "description": "Timeout in milliseconds for memory search and automatic recall search (default 15000)"
+      },
       "tenantID": {
         "type": "string",
         "description": "Deprecated: use apiKey"
@@ -30,6 +47,14 @@
       "placeholder": "key...",
       "sensitive": true
     },
+    "defaultTimeoutMs": {
+      "label": "Default Timeout (ms)",
+      "placeholder": "8000"
+    },
+    "searchTimeoutMs": {
+      "label": "Search Timeout (ms)",
+      "placeholder": "15000"
+    },
     "tenantID": {
       "label": "Tenant ID (legacy)",
       "placeholder": "uuid...",

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@mem9/mem9",
-  "version": "0.3.7",
+  "version": "0.4.0-rc.0",
   "description": "OpenClaw shared memory plugin — cloud-persistent memory with hybrid vector + keyword search via mnemo-server",
   "type": "module",
   "license": "Apache-2.0",
   "author": "mem9-ai",
   "repository": {
     "type": "git",
-    "url": "https://github.com/mem9-ai/mem9.git",
+    "url": "git+https://github.com/mem9-ai/mem9.git",
     "directory": "openclaw-plugin"
   },
   "homepage": "https://github.com/mem9-ai/mem9/tree/main/openclaw-plugin#readme",
@@ -34,6 +34,7 @@
     "access": "public"
   },
   "scripts": {
+    "test": "node --experimental-strip-types --test ./server-backend.test.ts",
     "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.ts";
+
+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

@@ -14,25 +14,60 @@ type ProvisionMem9sResponse = {
   id: string;
 };
 
+export const DEFAULT_TIMEOUT_MS = 8_000;
+export const DEFAULT_SEARCH_TIMEOUT_MS = 15_000;
+
+export interface BackendTimeouts {
+  defaultTimeoutMs?: number;
+  searchTimeoutMs?: number;
+}
+
+interface ServerBackendOptions {
+  timeouts?: BackendTimeouts;
+  provisionQueryParams?: Record<string, string>;
+}
+
+interface RequestOptions {
+  timeoutMs?: number;
+}
+
 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,
+    options: ServerBackendOptions = {},
   ) {
     this.baseUrl = apiUrl.replace(/\/+$/, "");
     this.apiKey = apiKey;
     this.agentName = agentName;
+    this.provisionQueryParams = options.provisionQueryParams ?? {};
+    this.timeouts = {
+      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(8_000),
+      signal: AbortSignal.timeout(this.timeouts.defaultTimeoutMs),
     });
 
     if (!resp.ok) {
@@ -75,7 +110,12 @@ export class ServerBackend implements MemoryBackend {
       total: number;
       limit: number;
       offset: number;
-    }>("GET", `${this.memoryPath("/memories")}${qs ? "?" + qs : ""}`);
+    }>(
+      "GET",
+      `${this.memoryPath("/memories")}${qs ? "?" + qs : ""}`,
+      undefined,
+      { timeoutMs: this.timeouts.searchTimeoutMs },
+    );
     return {
       data: raw.memories ?? [],
       total: raw.total,
@@ -116,7 +156,8 @@ export class ServerBackend implements MemoryBackend {
   private async requestRaw(
     method: string,
     path: string,
-    body?: unknown
+    body?: unknown,
+    options?: RequestOptions,
   ): Promise<Response> {
     const url = this.baseUrl + path;
     const headers: Record<string, string> = {
@@ -128,16 +169,17 @@ export class ServerBackend implements MemoryBackend {
       method,
       headers,
       body: body != null ? JSON.stringify(body) : undefined,
-      signal: AbortSignal.timeout(8_000),
+      signal: AbortSignal.timeout(options?.timeoutMs ?? this.timeouts.defaultTimeoutMs),
     });
   }
 
   private async request<T>(
     method: string,
     path: string,
-    body?: unknown
+    body?: unknown,
+    options?: RequestOptions,
   ): Promise<T> {
-    const resp = await this.requestRaw(method, path, body);
+    const resp = await this.requestRaw(method, path, body, options);
 
     if (resp.status === 204) {
       return undefined as T;

package/types.ts

@@ -2,7 +2,10 @@ export interface PluginConfig {
   // Server mode (apiUrl present → server)
   apiUrl?: string;
   apiKey?: string;
+  provisionQueryParams?: Record<string, string>;
   tenantID?: string;
+  defaultTimeoutMs?: number;
+  searchTimeoutMs?: number;
 
   tenantName?: string;
 
@@ -25,6 +28,7 @@ export interface Memory {
   created_at: string;
   updated_at: string;
   score?: number;
+  confidence?: number;
 
   // Smart memory pipeline (server mode)
   memory_type?: string;