memory-lancedb-pro 1.0.22 → 1.0.24

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,81 @@
+name: 🐛 Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the sections below.
+
+  - type: input
+    id: version
+    attributes:
+      label: Plugin Version
+      description: "Run `openclaw memory-pro version` to check"
+      placeholder: "e.g. 1.0.22"
+    validations:
+      required: true
+
+  - type: input
+    id: openclaw-version
+    attributes:
+      label: OpenClaw Version
+      description: "Run `openclaw --version` to check"
+      placeholder: "e.g. 2026.3.1"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of what happened
+      placeholder: "When I run `openclaw memory-pro search ...`, it throws..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal steps to reproduce the issue
+      placeholder: |
+        1. Set config ...
+        2. Run command ...
+        3. See error ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error Logs / Screenshots
+      description: Paste relevant error output or screenshots
+      render: shell
+
+  - type: dropdown
+    id: embedding
+    attributes:
+      label: Embedding Provider
+      options:
+        - OpenAI
+        - Jina
+        - Gemini
+        - Ollama
+        - Other
+    validations:
+      required: false
+
+  - type: input
+    id: os
+    attributes:
+      label: OS / Platform
+      placeholder: "e.g. Ubuntu 24.04, macOS 15, Windows 11"

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: ❓ Question / Help
+    url: https://discord.com/invite/clawd
+    about: For questions and support, join the OpenClaw Discord community

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,57 @@
+name: ✨ Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a feature! Please describe your idea below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: What problem does this solve? Why do you need it?
+      placeholder: "I often need to ... but currently there's no way to ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How would you like this to work?
+      placeholder: "It would be great if `openclaw memory-pro` could ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any workarounds or alternative approaches you've tried?
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Area
+      description: Which part of the plugin does this affect?
+      options:
+        - Retrieval / Search
+        - Storage / Database
+        - Embedding
+        - CLI Commands
+        - Configuration
+        - Auto-capture / Auto-recall
+        - Scopes / Access Control
+        - Migration
+        - Documentation
+        - Other
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Screenshots, examples, or links that help explain the feature

package/README.md

@@ -710,6 +710,51 @@ On LanceDB 0.26+ (via Apache Arrow), some numeric columns may be returned as `Bi
 
 upgrade to **memory-lancedb-pro >= 1.0.14**. This plugin now coerces these values using `Number(...)` before doing arithmetic (for example, when computing scores or sorting by timestamp).
 
+## Iron Rules for AI Agents (铁律)
+
+> **For OpenClaw users**: copy the code block below into your `AGENTS.md` so your agent enforces these rules automatically.
+
+```markdown
+## Rule 1 — 双层记忆存储（铁律）
+
+Every pitfall/lesson learned → IMMEDIATELY store TWO memories to LanceDB before moving on:
+
+- **Technical layer**: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid]
+  (category: fact, importance ≥ 0.8)
+- **Principle layer**: Decision principle ([tag]): [behavioral rule]. Trigger: [when it applies]. Action: [what to do]
+  (category: decision, importance ≥ 0.85)
+- After each store, immediately `memory_recall` with anchor keywords to verify retrieval.
+  If not found, rewrite and re-store.
+- Missing either layer = incomplete.
+  Do NOT proceed to next topic until both are stored and verified.
+- Also update relevant SKILL.md files to prevent recurrence.
+
+## Rule 2 — LanceDB 卫生
+
+Entries must be short and atomic (< 500 chars). Never store raw conversation summaries, large blobs, or duplicates.
+Prefer structured format with keywords for retrieval.
+
+## Rule 3 — Recall before retry
+
+On ANY tool failure, repeated error, or unexpected behavior, ALWAYS `memory_recall` with relevant keywords
+(error message, tool name, symptom) BEFORE retrying. LanceDB likely already has the fix.
+Blind retries waste time and repeat known mistakes.
+
+## Rule 4 — 编辑前确认目标代码库
+
+When working on memory plugins, confirm you are editing the intended package
+(e.g., `memory-lancedb-pro` vs built-in `memory-lancedb`) before making changes;
+use `memory_recall` + filesystem search to avoid patching the wrong repo.
+
+## Rule 5 — 插件代码变更必须清 jiti 缓存（MANDATORY）
+
+After modifying ANY `.ts` file under `plugins/`, MUST run `rm -rf /tmp/jiti/` BEFORE `openclaw gateway restart`.
+jiti caches compiled TS; restart alone loads STALE code. This has caused silent bugs multiple times.
+Config-only changes do NOT need cache clearing.
+```
+
+---
+
 ## Dependencies
 
 | Package | Purpose |
@@ -720,16 +765,6 @@ upgrade to **memory-lancedb-pro >= 1.0.14**. This plugin now coerces these value
 
 ---
 
-## ⭐ Star History
-
-<a href="https://star-history.com/#win4r/memory-lancedb-pro&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&theme=dark&transparent=true" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&transparent=true" />
-    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&transparent=true" />
-  </picture>
-</a>
-
 ## Contributors
 
 Top contributors (from GitHub’s contributors list, sorted by commit contributions; bots excluded):
@@ -742,11 +777,15 @@ Top contributors (from GitHub’s contributors list, sorted by commit contributi
 <a href="https://github.com/Minidoracat"><img src="https://avatars.githubusercontent.com/u/11269639?v=4" width="48" height="48" alt="@Minidoracat" /></a>
 <a href="https://github.com/furedericca-lab"><img src="https://avatars.githubusercontent.com/u/263020793?v=4" width="48" height="48" alt="@furedericca-lab" /></a>
 <a href="https://github.com/joe2643"><img src="https://avatars.githubusercontent.com/u/19421931?v=4" width="48" height="48" alt="@joe2643" /></a>
+<a href="https://github.com/AliceLJY"><img src="https://avatars.githubusercontent.com/u/136287420?v=4" width="48" height="48" alt="@AliceLJY" /></a>
+<a href="https://github.com/chenjiyong"><img src="https://avatars.githubusercontent.com/u/8199522?v=4" width="48" height="48" alt="@chenjiyong" /></a>
 </p>
 
 - [@win4r](https://github.com/win4r) (3 commits)
 - [@kctony](https://github.com/kctony) (2 commits)
 - [@Akatsuki-Ryu](https://github.com/Akatsuki-Ryu) (1 commit)
+- [@AliceLJY](https://github.com/AliceLJY) (1 commit)
+- [@chenjiyong](https://github.com/chenjiyong) (1 commit)
 - [@JasonSuz](https://github.com/JasonSuz) (1 commit)
 - [@Minidoracat](https://github.com/Minidoracat) (1 commit)
 - [@furedericca-lab](https://github.com/furedericca-lab) (1 commit)
@@ -754,6 +793,16 @@ Top contributors (from GitHub’s contributors list, sorted by commit contributi
 
 Full list: https://github.com/win4r/memory-lancedb-pro/graphs/contributors
 
+## ⭐ Star History
+
+<a href="https://star-history.com/#win4r/memory-lancedb-pro&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&theme=dark&transparent=true" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&transparent=true" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&transparent=true" />
+  </picture>
+</a>
+
 ## License
 
 MIT

package/README_CN.md

@@ -584,6 +584,51 @@ LanceDB 表 `memories`：
 
 请升级到 **memory-lancedb-pro >= 1.0.14**。插件已对这些字段统一做 `Number(...)` 转换后再参与运算（例如：计算分数、按时间排序）。
 
+## AI Agent 铁律（Iron Rules）
+
+> **OpenClaw 用户**：将下方代码块复制到你的 `AGENTS.md` 中，让 Agent 自动遵守这些规则。
+
+```markdown
+## Rule 1 — 双层记忆存储（铁律）
+
+Every pitfall/lesson learned → IMMEDIATELY store TWO memories to LanceDB before moving on:
+
+- **Technical layer**: Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid]
+  (category: fact, importance ≥ 0.8)
+- **Principle layer**: Decision principle ([tag]): [behavioral rule]. Trigger: [when it applies]. Action: [what to do]
+  (category: decision, importance ≥ 0.85)
+- After each store, immediately `memory_recall` with anchor keywords to verify retrieval.
+  If not found, rewrite and re-store.
+- Missing either layer = incomplete.
+  Do NOT proceed to next topic until both are stored and verified.
+- Also update relevant SKILL.md files to prevent recurrence.
+
+## Rule 2 — LanceDB 卫生
+
+Entries must be short and atomic (< 500 chars). Never store raw conversation summaries, large blobs, or duplicates.
+Prefer structured format with keywords for retrieval.
+
+## Rule 3 — Recall before retry
+
+On ANY tool failure, repeated error, or unexpected behavior, ALWAYS `memory_recall` with relevant keywords
+(error message, tool name, symptom) BEFORE retrying. LanceDB likely already has the fix.
+Blind retries waste time and repeat known mistakes.
+
+## Rule 4 — 编辑前确认目标代码库
+
+When working on memory plugins, confirm you are editing the intended package
+(e.g., `memory-lancedb-pro` vs built-in `memory-lancedb`) before making changes;
+use `memory_recall` + filesystem search to avoid patching the wrong repo.
+
+## Rule 5 — 插件代码变更必须清 jiti 缓存（MANDATORY）
+
+After modifying ANY `.ts` file under `plugins/`, MUST run `rm -rf /tmp/jiti/` BEFORE `openclaw gateway restart`.
+jiti caches compiled TS; restart alone loads STALE code. This has caused silent bugs multiple times.
+Config-only changes do NOT need cache clearing.
+```
+
+---
+
 ## 依赖
 
 | 包 | 用途 |
@@ -594,16 +639,6 @@ LanceDB 表 `memories`：
 
 ---
 
-## ⭐ Star 趋势
-
-<a href="https://star-history.com/#win4r/memory-lancedb-pro&Date">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&theme=dark&transparent=true" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&transparent=true" />
-    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&transparent=true" />
-  </picture>
-</a>
-
 ## 主要贡献者
 
 按 GitHub Contributors 列表自动生成（按 commit 贡献数排序，已排除 bot）：
@@ -616,11 +651,15 @@ LanceDB 表 `memories`：
 <a href="https://github.com/Minidoracat"><img src="https://avatars.githubusercontent.com/u/11269639?v=4" width="48" height="48" alt="@Minidoracat" /></a>
 <a href="https://github.com/furedericca-lab"><img src="https://avatars.githubusercontent.com/u/263020793?v=4" width="48" height="48" alt="@furedericca-lab" /></a>
 <a href="https://github.com/joe2643"><img src="https://avatars.githubusercontent.com/u/19421931?v=4" width="48" height="48" alt="@joe2643" /></a>
+<a href="https://github.com/AliceLJY"><img src="https://avatars.githubusercontent.com/u/136287420?v=4" width="48" height="48" alt="@AliceLJY" /></a>
+<a href="https://github.com/chenjiyong"><img src="https://avatars.githubusercontent.com/u/8199522?v=4" width="48" height="48" alt="@chenjiyong" /></a>
 </p>
 
 - [@win4r](https://github.com/win4r)（3 次提交）
 - [@kctony](https://github.com/kctony)（2 次提交）
 - [@Akatsuki-Ryu](https://github.com/Akatsuki-Ryu)（1 次提交）
+- [@AliceLJY](https://github.com/AliceLJY)（1 次提交）
+- [@chenjiyong](https://github.com/chenjiyong)（1 次提交）
 - [@JasonSuz](https://github.com/JasonSuz)（1 次提交）
 - [@Minidoracat](https://github.com/Minidoracat)（1 次提交）
 - [@furedericca-lab](https://github.com/furedericca-lab)（1 次提交）
@@ -628,6 +667,16 @@ LanceDB 表 `memories`：
 
 完整列表：https://github.com/win4r/memory-lancedb-pro/graphs/contributors
 
+## ⭐ Star 趋势
+
+<a href="https://star-history.com/#win4r/memory-lancedb-pro&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&theme=dark&transparent=true" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&transparent=true" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=win4r/memory-lancedb-pro&type=Date&transparent=true" />
+  </picture>
+</a>
+
 ## License
 
 MIT

package/index.ts

@@ -336,7 +336,7 @@ const memoryLanceDBProPlugin = {
     const store = new MemoryStore({ dbPath: resolvedDbPath, vectorDim });
     const embedder = createEmbedder({
       provider: "openai-compatible",
-      apiKey: resolveEnvVars(config.embedding.apiKey),
+      apiKey: config.embedding.apiKey,
       model: config.embedding.model || "text-embedding-3-small",
       baseURL: config.embedding.baseURL,
       dimensions: config.embedding.dimensions,
@@ -742,11 +742,14 @@ function parsePluginConfig(value: unknown): PluginConfig {
     throw new Error("embedding config is required");
   }
 
-  const apiKey = typeof embedding.apiKey === "string"
+  // Accept single key (string) or array of keys for round-robin rotation
+  const apiKey: string | string[] = typeof embedding.apiKey === "string"
     ? embedding.apiKey
-    : process.env.OPENAI_API_KEY || "";
+    : Array.isArray(embedding.apiKey) && embedding.apiKey.length > 0 && embedding.apiKey.every((k: unknown) => typeof k === "string")
+      ? (embedding.apiKey as string[])
+      : process.env.OPENAI_API_KEY || "";
 
-  if (!apiKey) {
+  if (!apiKey || (Array.isArray(apiKey) && apiKey.length === 0)) {
     throw new Error("embedding.apiKey is required (set directly or via OPENAI_API_KEY env var)");
   }
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "memory-lancedb-pro",
   "name": "Memory (LanceDB Pro)",
   "description": "Enhanced LanceDB-backed long-term memory with hybrid retrieval, multi-scope isolation, long-context chunking, and management CLI",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "kind": "memory",
   "configSchema": {
     "type": "object",
@@ -17,7 +17,11 @@
             "const": "openai-compatible"
           },
           "apiKey": {
-            "type": "string"
+            "oneOf": [
+              { "type": "string" },
+              { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+            ],
+            "description": "Single API key or array of keys for round-robin rotation"
           },
           "model": {
             "type": "string"
@@ -243,10 +247,10 @@
   },
   "uiHints": {
     "embedding.apiKey": {
-      "label": "API Key",
+      "label": "API Key(s)",
       "sensitive": true,
-      "placeholder": "sk-proj-... or ${GEMINI_API_KEY} or 'ollama'",
-      "help": "API key for the embedding provider (or use ${OPENAI_API_KEY}; use a dummy value for keyless local endpoints)"
+      "placeholder": "sk-proj-... or [\"key1\", \"key2\"] for rotation",
+      "help": "Single API key or array of keys for round-robin rotation with automatic failover on rate limits (or use ${OPENAI_API_KEY}; use a dummy value for keyless local endpoints)"
     },
     "embedding.model": {
       "label": "Embedding Model",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-lancedb-pro",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "OpenClaw enhanced LanceDB memory plugin with hybrid retrieval (Vector + BM25), cross-encoder rerank, multi-scope isolation, long-context chunking, and management CLI",
   "type": "module",
   "main": "index.ts",

package/src/embedder.ts

@@ -85,7 +85,8 @@ class EmbeddingCache {
 
 export interface EmbeddingConfig {
   provider: "openai-compatible";
-  apiKey: string;
+  /** Single API key or array of keys for round-robin rotation with failover. */
+  apiKey: string | string[];
   model: string;
   baseURL?: string;
   dimensions?: number;
@@ -151,7 +152,11 @@ export function getVectorDimensions(model: string, overrideDims?: number): numbe
 // ============================================================================
 
 export class Embedder {
-  private client: OpenAI;
+  /** Pool of OpenAI clients — one per API key for round-robin rotation. */
+  private clients: OpenAI[];
+  /** Round-robin index for client rotation. */
+  private _clientIndex: number = 0;
+
   public readonly dimensions: number;
   private readonly _cache: EmbeddingCache;
 
@@ -166,8 +171,9 @@ export class Embedder {
   private readonly _autoChunk: boolean;
 
   constructor(config: EmbeddingConfig & { chunking?: boolean }) {
-    // Resolve environment variables in API key
-    const resolvedApiKey = resolveEnvVars(config.apiKey);
+    // Normalize apiKey to array and resolve environment variables
+    const apiKeys = Array.isArray(config.apiKey) ? config.apiKey : [config.apiKey];
+    const resolvedKeys = apiKeys.map(k => resolveEnvVars(k));
 
     this._model = config.model;
     this._taskQuery = config.taskQuery;
@@ -177,15 +183,74 @@ export class Embedder {
     // Enable auto-chunking by default for better handling of long documents
     this._autoChunk = config.chunking !== false;
 
-    this.client = new OpenAI({
-      apiKey: resolvedApiKey,
+    // Create a client pool — one OpenAI client per key
+    this.clients = resolvedKeys.map(key => new OpenAI({
+      apiKey: key,
       ...(config.baseURL ? { baseURL: config.baseURL } : {}),
-    });
+    }));
+
+    if (this.clients.length > 1) {
+      console.log(`[memory-lancedb-pro] Initialized ${this.clients.length} API keys for round-robin rotation`);
+    }
 
     this.dimensions = getVectorDimensions(config.model, config.dimensions);
     this._cache = new EmbeddingCache(256, 30); // 256 entries, 30 min TTL
   }
 
+  // --------------------------------------------------------------------------
+  // Multi-key rotation helpers
+  // --------------------------------------------------------------------------
+
+  /** Return the next client in round-robin order. */
+  private nextClient(): OpenAI {
+    const client = this.clients[this._clientIndex % this.clients.length];
+    this._clientIndex = (this._clientIndex + 1) % this.clients.length;
+    return client;
+  }
+
+  /** Check whether an error is a rate-limit / quota-exceeded error. */
+  private isRateLimitError(error: unknown): boolean {
+    // OpenAI SDK typed error
+    if (error && typeof error === "object" && "status" in error && (error as any).status === 429) {
+      return true;
+    }
+    const msg = error instanceof Error ? error.message : String(error);
+    return /rate.limit|quota|too many requests|insufficient.*credit|429/i.test(msg);
+  }
+
+  /**
+   * Call embeddings.create with automatic key rotation on rate-limit errors.
+   * Tries each key in the pool at most once before giving up.
+   */
+  private async embedWithRetry(payload: any): Promise<any> {
+    const maxAttempts = this.clients.length;
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const client = this.nextClient();
+      try {
+        return await client.embeddings.create(payload);
+      } catch (error) {
+        if (this.isRateLimitError(error) && attempt < maxAttempts - 1) {
+          console.log(
+            `[memory-lancedb-pro] API key ${attempt + 1}/${maxAttempts} hit rate limit, rotating to next key...`
+          );
+          lastError = error instanceof Error ? error : new Error(String(error));
+          continue;
+        }
+        // Non-rate-limit error or last attempt — let caller handle
+        throw error;
+      }
+    }
+
+    throw lastError || new Error("All API keys exhausted (rate limited)");
+  }
+
+  /** Number of API keys in the rotation pool. */
+  get keyCount(): number {
+    return this.clients.length;
+  }
+
   // --------------------------------------------------------------------------
   // Backward-compatible API
   // --------------------------------------------------------------------------
@@ -271,7 +336,7 @@ export class Embedder {
     if (cached) return cached;
 
     try {
-      const response = await this.client.embeddings.create(this.buildPayload(text, task) as any);
+      const response = await this.embedWithRetry(this.buildPayload(text, task));
       const embedding = response.data[0]?.embedding as number[] | undefined;
       if (!embedding) {
         throw new Error("No embedding returned from provider");
@@ -361,8 +426,8 @@ export class Embedder {
     }
 
     try {
-      const response = await this.client.embeddings.create(
-        this.buildPayload(validTexts, task) as any
+      const response = await this.embedWithRetry(
+        this.buildPayload(validTexts, task)
       );
 
       // Create result array with proper length
@@ -479,7 +544,10 @@ export class Embedder {
   }
 
   get cacheStats() {
-    return this._cache.stats;
+    return {
+      ...this._cache.stats,
+      keyCount: this.clients.length,
+    };
   }
 }
 

package/src/tools.ts

@@ -26,6 +26,12 @@ interface ToolContext {
   agentId?: string;
 }
 
+function resolveAgentId(runtimeAgentId: unknown, fallback?: string): string | undefined {
+  if (typeof runtimeAgentId === "string" && runtimeAgentId.trim().length > 0) return runtimeAgentId;
+  if (typeof fallback === "string" && fallback.trim().length > 0) return fallback;
+  return undefined;
+}
+
 // ============================================================================
 // Utility Functions
 // ============================================================================
@@ -58,8 +64,10 @@ function sanitizeMemoryForSerialization(results: RetrievalResult[]) {
 
 export function registerMemoryRecallTool(api: OpenClawPluginApi, context: ToolContext) {
   api.registerTool(
-    {
-      name: "memory_recall",
+    (toolCtx) => {
+      const agentId = resolveAgentId((toolCtx as any)?.agentId, context.agentId) ?? "main";
+      return {
+        name: "memory_recall",
       label: "Memory Recall",
       description: "Search through long-term memories using hybrid retrieval (vector + keyword search). Use when you need context about user preferences, past decisions, or previously discussed topics.",
       parameters: Type.Object({
@@ -80,9 +88,9 @@ export function registerMemoryRecallTool(api: OpenClawPluginApi, context: ToolCo
           const safeLimit = clampInt(limit, 1, 20);
 
           // Determine accessible scopes
-          let scopeFilter = context.scopeManager.getAccessibleScopes(context.agentId);
+          let scopeFilter = context.scopeManager.getAccessibleScopes(agentId);
           if (scope) {
-            if (context.scopeManager.isAccessible(scope, context.agentId)) {
+            if (context.scopeManager.isAccessible(scope, agentId)) {
               scopeFilter = [scope];
             } else {
               return {
@@ -134,6 +142,7 @@ export function registerMemoryRecallTool(api: OpenClawPluginApi, context: ToolCo
           };
         }
       },
+    };
     },
     { name: "memory_recall" }
   );
@@ -141,8 +150,10 @@ export function registerMemoryRecallTool(api: OpenClawPluginApi, context: ToolCo
 
 export function registerMemoryStoreTool(api: OpenClawPluginApi, context: ToolContext) {
   api.registerTool(
-    {
-      name: "memory_store",
+    (toolCtx) => {
+      const agentId = resolveAgentId((toolCtx as any)?.agentId, context.agentId) ?? "main";
+      return {
+        name: "memory_store",
       label: "Memory Store",
       description: "Save important information in long-term memory. Use for preferences, facts, decisions, and other notable information.",
       parameters: Type.Object({
@@ -166,10 +177,10 @@ export function registerMemoryStoreTool(api: OpenClawPluginApi, context: ToolCon
 
         try {
           // Determine target scope
-          let targetScope = scope || context.scopeManager.getDefaultScope(context.agentId);
+          let targetScope = scope || context.scopeManager.getDefaultScope(agentId);
 
           // Validate scope access
-          if (!context.scopeManager.isAccessible(targetScope, context.agentId)) {
+          if (!context.scopeManager.isAccessible(targetScope, agentId)) {
             return {
               content: [{ type: "text", text: `Access denied to scope: ${targetScope}` }],
               details: { error: "scope_access_denied", requestedScope: targetScope },
@@ -233,6 +244,7 @@ export function registerMemoryStoreTool(api: OpenClawPluginApi, context: ToolCon
           };
         }
       },
+    };
     },
     { name: "memory_store" }
   );
@@ -240,8 +252,10 @@ export function registerMemoryStoreTool(api: OpenClawPluginApi, context: ToolCon
 
 export function registerMemoryForgetTool(api: OpenClawPluginApi, context: ToolContext) {
   api.registerTool(
-    {
-      name: "memory_forget",
+    (toolCtx) => {
+      const agentId = resolveAgentId((toolCtx as any)?.agentId, context.agentId) ?? "main";
+      return {
+        name: "memory_forget",
       label: "Memory Forget",
       description: "Delete specific memories. Supports both search-based and direct ID-based deletion.",
       parameters: Type.Object({
@@ -258,9 +272,9 @@ export function registerMemoryForgetTool(api: OpenClawPluginApi, context: ToolCo
 
         try {
           // Determine accessible scopes
-          let scopeFilter = context.scopeManager.getAccessibleScopes(context.agentId);
+          let scopeFilter = context.scopeManager.getAccessibleScopes(agentId);
           if (scope) {
-            if (context.scopeManager.isAccessible(scope, context.agentId)) {
+            if (context.scopeManager.isAccessible(scope, agentId)) {
               scopeFilter = [scope];
             } else {
               return {
@@ -338,6 +352,7 @@ export function registerMemoryForgetTool(api: OpenClawPluginApi, context: ToolCo
           };
         }
       },
+    };
     },
     { name: "memory_forget" }
   );
@@ -349,8 +364,10 @@ export function registerMemoryForgetTool(api: OpenClawPluginApi, context: ToolCo
 
 export function registerMemoryUpdateTool(api: OpenClawPluginApi, context: ToolContext) {
   api.registerTool(
-    {
-      name: "memory_update",
+    (toolCtx) => {
+      const agentId = resolveAgentId((toolCtx as any)?.agentId, context.agentId) ?? "main";
+      return {
+        name: "memory_update",
       label: "Memory Update",
       description: "Update an existing memory in-place. Preserves original timestamp. Use when correcting outdated info or adjusting importance/category without losing creation date.",
       parameters: Type.Object({
@@ -376,7 +393,7 @@ export function registerMemoryUpdateTool(api: OpenClawPluginApi, context: ToolCo
           }
 
           // Determine accessible scopes
-          const scopeFilter = context.scopeManager.getAccessibleScopes(context.agentId);
+          const scopeFilter = context.scopeManager.getAccessibleScopes(agentId);
 
           // Resolve memoryId: if it doesn't look like a UUID, try search
           let resolvedId = memoryId;
@@ -452,6 +469,7 @@ export function registerMemoryUpdateTool(api: OpenClawPluginApi, context: ToolCo
           };
         }
       },
+    };
     },
     { name: "memory_update" }
   );
@@ -463,8 +481,10 @@ export function registerMemoryUpdateTool(api: OpenClawPluginApi, context: ToolCo
 
 export function registerMemoryStatsTool(api: OpenClawPluginApi, context: ToolContext) {
   api.registerTool(
-    {
-      name: "memory_stats",
+    (toolCtx) => {
+      const agentId = resolveAgentId((toolCtx as any)?.agentId, context.agentId) ?? "main";
+      return {
+        name: "memory_stats",
       label: "Memory Statistics",
       description: "Get statistics about memory usage, scopes, and categories.",
       parameters: Type.Object({
@@ -475,9 +495,9 @@ export function registerMemoryStatsTool(api: OpenClawPluginApi, context: ToolCon
 
         try {
           // Determine accessible scopes
-          let scopeFilter = context.scopeManager.getAccessibleScopes(context.agentId);
+          let scopeFilter = context.scopeManager.getAccessibleScopes(agentId);
           if (scope) {
-            if (context.scopeManager.isAccessible(scope, context.agentId)) {
+            if (context.scopeManager.isAccessible(scope, agentId)) {
               scopeFilter = [scope];
             } else {
               return {
@@ -524,6 +544,7 @@ export function registerMemoryStatsTool(api: OpenClawPluginApi, context: ToolCon
           };
         }
       },
+    };
     },
     { name: "memory_stats" }
   );
@@ -531,8 +552,10 @@ export function registerMemoryStatsTool(api: OpenClawPluginApi, context: ToolCon
 
 export function registerMemoryListTool(api: OpenClawPluginApi, context: ToolContext) {
   api.registerTool(
-    {
-      name: "memory_list",
+    (toolCtx) => {
+      const agentId = resolveAgentId((toolCtx as any)?.agentId, context.agentId) ?? "main";
+      return {
+        name: "memory_list",
       label: "Memory List",
       description: "List recent memories with optional filtering by scope and category.",
       parameters: Type.Object({
@@ -559,9 +582,9 @@ export function registerMemoryListTool(api: OpenClawPluginApi, context: ToolCont
           const safeOffset = clampInt(offset, 0, 1000);
 
           // Determine accessible scopes
-          let scopeFilter = context.scopeManager.getAccessibleScopes(context.agentId);
+          let scopeFilter = context.scopeManager.getAccessibleScopes(agentId);
           if (scope) {
-            if (context.scopeManager.isAccessible(scope, context.agentId)) {
+            if (context.scopeManager.isAccessible(scope, agentId)) {
               scopeFilter = [scope];
             } else {
               return {
@@ -609,6 +632,7 @@ export function registerMemoryListTool(api: OpenClawPluginApi, context: ToolCont
           };
         }
       },
+    };
     },
     { name: "memory_list" }
   );