memory-lancedb-pro 1.0.23 → 1.0.25

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 |
@@ -733,12 +778,14 @@ Top contributors (from GitHub’s contributors list, sorted by commit contributi
 <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)

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.
+```
+
+---
+
 ## 依赖
 
 | 包 | 用途 |
@@ -607,12 +652,14 @@ LanceDB 表 `memories`：
 <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 次提交）

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,25 @@ function parsePluginConfig(value: unknown): PluginConfig {
     throw new Error("embedding config is required");
   }
 
-  const apiKey = typeof embedding.apiKey === "string"
-    ? embedding.apiKey
-    : process.env.OPENAI_API_KEY || "";
+  // Accept single key (string) or array of keys for round-robin rotation
+  let apiKey: string | string[];
+  if (typeof embedding.apiKey === "string") {
+    apiKey = embedding.apiKey;
+  } else if (Array.isArray(embedding.apiKey) && embedding.apiKey.length > 0) {
+    // Validate every element is a non-empty string
+    const invalid = embedding.apiKey.findIndex((k: unknown) => typeof k !== "string" || (k as string).trim().length === 0);
+    if (invalid !== -1) {
+      throw new Error(`embedding.apiKey[${invalid}] is invalid: expected non-empty string`);
+    }
+    apiKey = embedding.apiKey as string[];
+  } else if (embedding.apiKey !== undefined) {
+    // apiKey is present but wrong type — throw, don't silently fall back
+    throw new Error("embedding.apiKey must be a string or non-empty array of strings");
+  } else {
+    apiKey = 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.24",
   "kind": "memory",
   "configSchema": {
     "type": "object",
@@ -17,7 +17,21 @@
             "const": "openai-compatible"
           },
           "apiKey": {
-            "type": "string"
+            "oneOf": [
+              {
+                "type": "string",
+                "minLength": 1
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 1
+              }
+            ],
+            "description": "Single API key or array of keys for round-robin rotation"
           },
           "model": {
             "type": "string"
@@ -243,10 +257,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.23",
+  "version": "1.0.25",
   "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,96 @@ 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 / overload error. */
+  private isRateLimitError(error: unknown): boolean {
+    if (!error || typeof error !== "object") return false;
+
+    const err = error as Record<string, any>;
+
+    // HTTP status: 429 (rate limit) or 503 (service overload)
+    if (err.status === 429 || err.status === 503) return true;
+
+    // OpenAI SDK structured error code
+    if (err.code === "rate_limit_exceeded" || err.code === "insufficient_quota") return true;
+
+    // Nested error object (some providers)
+    const nested = err.error;
+    if (nested && typeof nested === "object") {
+      if (nested.type === "rate_limit_exceeded" || nested.type === "insufficient_quota") return true;
+      if (nested.code === "rate_limit_exceeded" || nested.code === "insufficient_quota") return true;
+    }
+
+    // Fallback: message text matching
+    const msg = error instanceof Error ? error.message : String(error);
+    return /rate.limit|quota|too many requests|insufficient.*credit|429|503.*overload/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) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (this.isRateLimitError(error) && attempt < maxAttempts - 1) {
+          console.log(
+            `[memory-lancedb-pro] Attempt ${attempt + 1}/${maxAttempts} hit rate limit, rotating to next key...`
+          );
+          continue;
+        }
+
+        // Non-rate-limit error → don't retry, let caller handle (e.g. chunking)
+        if (!this.isRateLimitError(error)) {
+          throw error;
+        }
+      }
+    }
+
+    // All keys exhausted with rate-limit errors
+    throw new Error(
+      `All ${maxAttempts} API keys exhausted (rate limited). Last error: ${lastError?.message || "unknown"}`,
+      { cause: lastError }
+    );
+  }
+
+  /** Number of API keys in the rotation pool. */
+  get keyCount(): number {
+    return this.clients.length;
+  }
+
   // --------------------------------------------------------------------------
   // Backward-compatible API
   // --------------------------------------------------------------------------
@@ -271,7 +358,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 +448,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 +566,10 @@ export class Embedder {
   }
 
   get cacheStats() {
-    return this._cache.stats;
+    return {
+      ...this._cache.stats,
+      keyCount: this.clients.length,
+    };
   }
 }