memory-lancedb-pro 1.0.0

package/openclaw.plugin.json

@@ -0,0 +1,385 @@
+{
+  "id": "memory-lancedb-pro",
+  "name": "Memory (LanceDB Pro)",
+  "description": "Enhanced LanceDB-backed long-term memory with hybrid retrieval, multi-scope isolation, and management CLI",
+  "version": "2026.2.16",
+  "kind": "memory",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "embedding": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "provider": {
+            "type": "string",
+            "const": "openai-compatible"
+          },
+          "apiKey": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "baseURL": {
+            "type": "string"
+          },
+          "dimensions": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "taskQuery": {
+            "type": "string",
+            "description": "Embedding task for queries (provider-specific, e.g. Jina: retrieval.query)"
+          },
+          "taskPassage": {
+            "type": "string",
+            "description": "Embedding task for passages/documents (provider-specific, e.g. Jina: retrieval.passage)"
+          },
+          "normalized": {
+            "type": "boolean",
+            "description": "Request normalized embeddings when supported by the provider (e.g. Jina v5)"
+          }
+        },
+        "required": [
+          "apiKey"
+        ]
+      },
+      "dbPath": {
+        "type": "string"
+      },
+      "enableManagementTools": {
+        "type": "boolean",
+        "default": false,
+        "description": "Enable memory_list and memory_stats management tools"
+      },
+      "autoCapture": {
+        "type": "boolean"
+      },
+      "autoRecall": {
+        "type": "boolean"
+      },
+      "captureAssistant": {
+        "type": "boolean"
+      },
+      "retrieval": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": [
+              "hybrid",
+              "vector"
+            ],
+            "default": "hybrid"
+          },
+          "vectorWeight": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "default": 0.7
+          },
+          "bm25Weight": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "default": 0.3
+          },
+          "minScore": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "default": 0.3
+          },
+          "rerank": {
+            "type": "string",
+            "enum": [
+              "cross-encoder",
+              "lightweight",
+              "none"
+            ],
+            "default": "cross-encoder"
+          },
+          "rerankApiKey": {
+            "type": "string",
+            "description": "API key for reranker service (enables cross-encoder reranking)"
+          },
+          "rerankModel": {
+            "type": "string",
+            "default": "jina-reranker-v2-base-multilingual",
+            "description": "Reranker model name"
+          },
+          "rerankEndpoint": {
+            "type": "string",
+            "default": "https://api.jina.ai/v1/rerank",
+            "description": "Reranker API endpoint URL. Compatible with Jina, SiliconFlow, Pinecone, or any service with a similar interface."
+          },
+          "rerankProvider": {
+            "type": "string",
+            "enum": ["jina", "siliconflow", "pinecone"],
+            "default": "jina",
+            "description": "Reranker provider format. Determines request/response shape and auth header."
+          },
+          "candidatePoolSize": {
+            "type": "integer",
+            "minimum": 10,
+            "maximum": 100,
+            "default": 20
+          },
+          "recencyHalfLifeDays": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 365,
+            "default": 14,
+            "description": "Half-life in days for recency boost. Newer memories get higher scores. Set 0 to disable."
+          },
+          "recencyWeight": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 0.5,
+            "default": 0.1,
+            "description": "Maximum recency boost factor added to score"
+          },
+          "filterNoise": {
+            "type": "boolean",
+            "default": true,
+            "description": "Filter out noise memories (agent denials, meta-questions, boilerplate)"
+          },
+          "lengthNormAnchor": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 5000,
+            "default": 500,
+            "description": "Length normalization anchor in chars. Entries longer than this get score penalized. Set 0 to disable."
+          },
+          "hardMinScore": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "default": 0.35,
+            "description": "Hard cutoff after all scoring stages. Results below this score are discarded."
+          },
+          "timeDecayHalfLifeDays": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 365,
+            "default": 60,
+            "description": "Time decay half-life in days. Old entries lose score gradually. Floor at 0.5x. Set 0 to disable."
+          }
+        }
+      },
+      "sessionMemory": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "Store session summaries to LanceDB on /new command (replaces built-in session-memory hook)"
+          },
+          "messageCount": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 15,
+            "description": "Number of recent messages to include in session summary"
+          }
+        }
+      },
+      "scopes": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "default": {
+            "type": "string",
+            "default": "global"
+          },
+          "definitions": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "description": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "agentAccess": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "required": [
+      "embedding"
+    ]
+  },
+  "uiHints": {
+    "embedding.apiKey": {
+      "label": "API Key",
+      "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)"
+    },
+    "embedding.model": {
+      "label": "Embedding Model",
+      "placeholder": "text-embedding-3-small",
+      "help": "Embedding model name (e.g. text-embedding-3-small, gemini-embedding-001, nomic-embed-text)"
+    },
+    "embedding.baseURL": {
+      "label": "Base URL",
+      "placeholder": "https://api.openai.com/v1",
+      "help": "Custom base URL for OpenAI-compatible embedding endpoints (e.g. https://generativelanguage.googleapis.com/v1beta/openai/ for Gemini, http://localhost:11434/v1 for Ollama)",
+      "advanced": true
+    },
+    "embedding.dimensions": {
+      "label": "Vector Dimensions",
+      "placeholder": "auto-detected from model",
+      "help": "Override vector dimensions for custom models not in the built-in lookup table",
+      "advanced": true
+    },
+    "dbPath": {
+      "label": "Database Path",
+      "placeholder": "~/.openclaw/memory/lancedb-pro",
+      "help": "Directory path for the LanceDB database files",
+      "advanced": true
+    },
+    "autoCapture": {
+      "label": "Auto-Capture",
+      "help": "Automatically capture important information from conversations"
+    },
+    "autoRecall": {
+      "label": "Auto-Recall",
+      "help": "Automatically inject relevant memories into context"
+    },
+    "captureAssistant": {
+      "label": "Capture Assistant Messages",
+      "help": "Also auto-capture assistant messages (default false to reduce memory pollution)",
+      "advanced": true
+    },
+    "retrieval.mode": {
+      "label": "Retrieval Mode",
+      "help": "Use hybrid search (vector + BM25) or vector-only for backward compatibility",
+      "advanced": true
+    },
+    "retrieval.vectorWeight": {
+      "label": "Vector Search Weight",
+      "help": "Weight for vector similarity in hybrid search (0-1)",
+      "advanced": true
+    },
+    "retrieval.bm25Weight": {
+      "label": "BM25 Search Weight",
+      "help": "Weight for BM25 keyword search in hybrid search (0-1)",
+      "advanced": true
+    },
+    "retrieval.minScore": {
+      "label": "Minimum Score Threshold",
+      "help": "Drop results below this relevance score (0-1)",
+      "advanced": true
+    },
+    "retrieval.rerank": {
+      "label": "Reranking Mode",
+      "help": "Re-score fused results for better quality (cross-encoder uses configured reranker API)",
+      "advanced": true
+    },
+    "retrieval.rerankApiKey": {
+      "label": "Reranker API Key",
+      "sensitive": true,
+      "placeholder": "jina_... / sk-... / pcsk_...",
+      "help": "Reranker API key for cross-encoder reranking",
+      "advanced": true
+    },
+    "retrieval.rerankModel": {
+      "label": "Reranker Model",
+      "placeholder": "jina-reranker-v2-base-multilingual",
+      "help": "Reranker model name (e.g. jina-reranker-v2-base-multilingual, BAAI/bge-reranker-v2-m3)",
+      "advanced": true
+    },
+    "retrieval.rerankEndpoint": {
+      "label": "Reranker Endpoint",
+      "placeholder": "https://api.jina.ai/v1/rerank",
+      "help": "Custom reranker API endpoint URL",
+      "advanced": true
+    },
+    "retrieval.rerankProvider": {
+      "label": "Reranker Provider",
+      "help": "Provider format: jina (default), siliconflow, or pinecone",
+      "advanced": true
+    },
+    "retrieval.candidatePoolSize": {
+      "label": "Candidate Pool Size",
+      "help": "Number of candidates to fetch before fusion and reranking",
+      "advanced": true
+    },
+    "sessionMemory.enabled": {
+      "label": "Session Memory",
+      "help": "Store session summaries to LanceDB when /new is triggered (replaces built-in session-memory hook)"
+    },
+    "sessionMemory.messageCount": {
+      "label": "Session Message Count",
+      "help": "Number of recent messages to include in session summaries",
+      "advanced": true
+    },
+    "scopes.default": {
+      "label": "Default Scope",
+      "help": "Default memory scope for new memories",
+      "advanced": true
+    },
+    "scopes.definitions": {
+      "label": "Scope Definitions",
+      "help": "Define custom memory scopes with descriptions",
+      "advanced": true
+    },
+    "scopes.agentAccess": {
+      "label": "Agent Access Control",
+      "help": "Define which scopes each agent can access",
+      "advanced": true
+    },
+    "enableManagementTools": {
+      "label": "Management Tools",
+      "help": "Enable memory_list and memory_stats tools for debugging and auditing",
+      "advanced": true
+    },
+    "retrieval.lengthNormAnchor": {
+      "label": "Length Normalization Anchor",
+      "help": "Entries longer than this (chars) get score penalized to prevent long entries dominating. 0 = disabled.",
+      "advanced": true
+    },
+    "retrieval.hardMinScore": {
+      "label": "Hard Minimum Score",
+      "help": "Discard results below this score after all scoring stages. Higher = fewer but more relevant results.",
+      "advanced": true
+    },
+    "retrieval.timeDecayHalfLifeDays": {
+      "label": "Time Decay Half-Life",
+      "help": "Old entries lose score over this many days. Floor at 0.5x. 0 = disabled.",
+      "advanced": true
+    },
+    "embedding.taskQuery": {
+      "label": "Query Task",
+      "placeholder": "retrieval.query",
+      "help": "Optional task selector for query embeddings (Jina: retrieval.query). If unset, no task field is sent.",
+      "advanced": true
+    },
+    "embedding.taskPassage": {
+      "label": "Passage Task",
+      "placeholder": "retrieval.passage",
+      "help": "Optional task selector for passage/document embeddings (Jina: retrieval.passage). If unset, no task field is sent.",
+      "advanced": true
+    },
+    "embedding.normalized": {
+      "label": "Normalized Embeddings",
+      "help": "Request normalized embeddings when the provider supports it (Jina v5). If unset, the field is not sent.",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "memory-lancedb-pro",
+  "version": "1.0.0",
+  "description": "OpenClaw enhanced LanceDB memory plugin with hybrid retrieval (Vector + BM25), cross-encoder rerank, multi-scope isolation, and management CLI",
+  "type": "module",
+  "main": "index.ts",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "lancedb",
+    "vector-search",
+    "bm25",
+    "hybrid-retrieval",
+    "rerank",
+    "ai-memory",
+    "long-term-memory"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/win4r/memory-lancedb-pro"
+  },
+  "author": "win4r",
+  "license": "MIT",
+  "dependencies": {
+    "@lancedb/lancedb": "^0.26.2",
+    "@sinclair/typebox": "0.34.48",
+    "openai": "^6.21.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/skills/lesson/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: lesson
+description: Store a lesson learned from the current conversation. Triggered by /lesson command. Use when Master signals that the recent conversation contains a pitfall, fix, or key insight that should be persisted to long-term memory.
+---
+
+# Lesson Extraction & Storage
+
+When triggered, extract and store lessons from the **recent conversation context**.
+
+## Steps
+
+1. **Scan recent context** — identify the pitfall, bug fix, or key insight just discussed
+2. **Store technical layer** (category: fact, importance ≥ 0.8):
+   ```
+   Pitfall: [symptom]. Cause: [root cause]. Fix: [solution]. Prevention: [how to avoid].
+   ```
+3. **Store principle layer** (category: decision, importance ≥ 0.85):
+   ```
+   Decision principle ([tag]): [behavioral rule]. Trigger: [when]. Action: [what to do].
+   ```
+4. **Verify** — `memory_recall` with anchor keywords to confirm both entries retrievable
+5. **Report** — tell Master what was stored (brief summary)
+
+## Rules
+
+- Keep entries short and atomic (< 500 chars each)
+- If the lesson also affects a checklist or SKILL.md, update those files too
+- If no clear lesson is found in recent context, ask Master what to store

package/src/adaptive-retrieval.ts

@@ -0,0 +1,60 @@
+/**
+ * Adaptive Retrieval
+ * Determines whether a query needs memory retrieval at all.
+ * Skips retrieval for greetings, commands, simple instructions, and system messages.
+ * Saves embedding API calls and reduces noise injection.
+ */
+
+// Queries that are clearly NOT memory-retrieval candidates
+const SKIP_PATTERNS = [
+  // Greetings & pleasantries
+  /^(hi|hello|hey|good\s*(morning|afternoon|evening|night)|greetings|yo|sup|howdy|what'?s up)\b/i,
+  // System/bot commands
+  /^\//,  // slash commands
+  /^(run|build|test|ls|cd|git|npm|pip|docker|curl|cat|grep|find|make|sudo)\b/i,
+  // Simple affirmations/negations
+  /^(yes|no|yep|nope|ok|okay|sure|fine|thanks|thank you|thx|ty|got it|understood|cool|nice|great|good|perfect|awesome|👍|👎|✅|❌)\s*[.!]?$/i,
+  // Continuation prompts
+  /^(go ahead|continue|proceed|do it|start|begin|next|实施|开始|继续|好的|可以|行)\s*[.!]?$/i,
+  // Pure emoji
+  /^[\p{Emoji}\s]+$/u,
+  // Heartbeat/system
+  /^HEARTBEAT/i,
+  /^\[System/i,
+];
+
+// Queries that SHOULD trigger retrieval even if short
+const FORCE_RETRIEVE_PATTERNS = [
+  /\b(remember|recall|forgot|memory|memories)\b/i,
+  /\b(last time|before|previously|earlier|yesterday|ago)\b/i,
+  /\b(my (name|email|phone|address|birthday|preference))\b/i,
+  /\b(what did (i|we)|did i (tell|say|mention))\b/i,
+  /(你记得|之前|上次|以前|还记得|提到过|说过)/i,
+];
+
+/**
+ * Determine if a query should skip memory retrieval.
+ * Returns true if retrieval should be skipped.
+ */
+export function shouldSkipRetrieval(query: string): boolean {
+  const trimmed = query.trim();
+
+  // Force retrieve if query has memory-related intent (checked FIRST,
+  // before length check, so short CJK queries like "你记得吗" aren't skipped)
+  if (FORCE_RETRIEVE_PATTERNS.some(p => p.test(trimmed))) return false;
+
+  // Too short to be meaningful
+  if (trimmed.length < 5) return true;
+
+  // Skip if matches any skip pattern
+  if (SKIP_PATTERNS.some(p => p.test(trimmed))) return true;
+
+  // Skip very short non-question messages (likely commands or affirmations)
+  // CJK characters carry more meaning per character, so use a lower threshold
+  const hasCJK = /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/.test(trimmed);
+  const minLength = hasCJK ? 6 : 15;
+  if (trimmed.length < minLength && !trimmed.includes('?') && !trimmed.includes('？')) return true;
+
+  // Default: do retrieve
+  return false;
+}