memory-lancedb-pro 1.0.21 → 1.0.22

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog
 
 
+## 1.0.22
+
+**Storage Path Validation & Better Error Messages**
+
+- **Fix**: Validate `dbPath` at startup — resolve symlinks, auto-create missing directories, check write permissions (#26, #27)
+- **Fix**: Write/connection failures now include `errno`, resolved path, and actionable fix suggestions instead of generic errors (#28)
+- **New**: Exported `validateStoragePath()` utility for external tooling and diagnostics
+
+Breaking changes: None. Backward compatible.
+
+---
+
 ## 1.0.21
 
 **Long Context Chunking**

package/README.md

@@ -720,6 +720,40 @@ 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):
+
+<p>
+<a href="https://github.com/win4r"><img src="https://avatars.githubusercontent.com/u/42172631?v=4" width="48" height="48" alt="@win4r" /></a>
+<a href="https://github.com/kctony"><img src="https://avatars.githubusercontent.com/u/1731141?v=4" width="48" height="48" alt="@kctony" /></a>
+<a href="https://github.com/Akatsuki-Ryu"><img src="https://avatars.githubusercontent.com/u/8062209?v=4" width="48" height="48" alt="@Akatsuki-Ryu" /></a>
+<a href="https://github.com/JasonSuz"><img src="https://avatars.githubusercontent.com/u/612256?v=4" width="48" height="48" alt="@JasonSuz" /></a>
+<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>
+</p>
+
+- [@win4r](https://github.com/win4r) (3 commits)
+- [@kctony](https://github.com/kctony) (2 commits)
+- [@Akatsuki-Ryu](https://github.com/Akatsuki-Ryu) (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)
+- [@joe2643](https://github.com/joe2643) (1 commit)
+
+Full list: https://github.com/win4r/memory-lancedb-pro/graphs/contributors
+
 ## License
 
 MIT

package/README_CN.md

@@ -594,6 +594,40 @@ 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）：
+
+<p>
+<a href="https://github.com/win4r"><img src="https://avatars.githubusercontent.com/u/42172631?v=4" width="48" height="48" alt="@win4r" /></a>
+<a href="https://github.com/kctony"><img src="https://avatars.githubusercontent.com/u/1731141?v=4" width="48" height="48" alt="@kctony" /></a>
+<a href="https://github.com/Akatsuki-Ryu"><img src="https://avatars.githubusercontent.com/u/8062209?v=4" width="48" height="48" alt="@Akatsuki-Ryu" /></a>
+<a href="https://github.com/JasonSuz"><img src="https://avatars.githubusercontent.com/u/612256?v=4" width="48" height="48" alt="@JasonSuz" /></a>
+<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>
+</p>
+
+- [@win4r](https://github.com/win4r)（3 次提交）
+- [@kctony](https://github.com/kctony)（2 次提交）
+- [@Akatsuki-Ryu](https://github.com/Akatsuki-Ryu)（1 次提交）
+- [@JasonSuz](https://github.com/JasonSuz)（1 次提交）
+- [@Minidoracat](https://github.com/Minidoracat)（1 次提交）
+- [@furedericca-lab](https://github.com/furedericca-lab)（1 次提交）
+- [@joe2643](https://github.com/joe2643)（1 次提交）
+
+完整列表：https://github.com/win4r/memory-lancedb-pro/graphs/contributors
+
 ## License
 
 MIT

package/index.ts

@@ -10,7 +10,7 @@ import { readFile, readdir, writeFile, mkdir } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 
 // Import core components
-import { MemoryStore } from "./src/store.js";
+import { MemoryStore, validateStoragePath } from "./src/store.js";
 import { createEmbedder, getVectorDimensions } from "./src/embedder.js";
 import { createRetriever, DEFAULT_RETRIEVAL_CONFIG } from "./src/retriever.js";
 import { createScopeManager } from "./src/scopes.js";
@@ -315,6 +315,18 @@ const memoryLanceDBProPlugin = {
     const config = parsePluginConfig(api.pluginConfig);
 
     const resolvedDbPath = api.resolvePath(config.dbPath || getDefaultDbPath());
+
+    // Pre-flight: validate storage path (symlink resolution, mkdir, write check).
+    // Runs synchronously and logs warnings; does NOT block gateway startup.
+    try {
+      validateStoragePath(resolvedDbPath);
+    } catch (err) {
+      api.logger.warn(
+        `memory-lancedb-pro: storage path issue — ${String(err)}\n` +
+        `  The plugin will still attempt to start, but writes may fail.`
+      );
+    }
+
     const vectorDim = getVectorDimensions(
       config.embedding.model || "text-embedding-3-small",
       config.embedding.dimensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-lancedb-pro",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "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/store.ts

@@ -4,6 +4,8 @@
 
 import type * as LanceDB from "@lancedb/lancedb";
 import { randomUUID } from "node:crypto";
+import { existsSync, accessSync, constants, mkdirSync, realpathSync, lstatSync } from "node:fs";
+import { dirname } from "node:path";
 
 // ============================================================================
 // Types
@@ -60,6 +62,72 @@ function escapeSqlLiteral(value: string): string {
   return value.replace(/'/g, "''");
 }
 
+// ============================================================================
+// Storage Path Validation
+// ============================================================================
+
+/**
+ * Validate and prepare the storage directory before LanceDB connection.
+ * Resolves symlinks, creates missing directories, and checks write permissions.
+ * Returns the resolved absolute path on success, or throws a descriptive error.
+ */
+export function validateStoragePath(dbPath: string): string {
+  let resolvedPath = dbPath;
+
+  // Resolve symlinks (including dangling symlinks)
+  try {
+    const stats = lstatSync(dbPath);
+    if (stats.isSymbolicLink()) {
+      try {
+        resolvedPath = realpathSync(dbPath);
+      } catch (err: any) {
+        throw new Error(
+          `dbPath "${dbPath}" is a symlink whose target does not exist.\n` +
+          `  Fix: Create the target directory, or update the symlink to point to a valid path.\n` +
+          `  Details: ${err.code || ""} ${err.message}`
+        );
+      }
+    }
+  } catch (err: any) {
+    // Missing path is OK (it will be created below)
+    if (err?.code === "ENOENT") {
+      // no-op
+    } else if (typeof err?.message === "string" && err.message.includes("symlink whose target does not exist")) {
+      throw err;
+    } else {
+      // Other lstat failures — continue with original path
+    }
+  }
+
+  // Create directory if it doesn't exist
+  if (!existsSync(resolvedPath)) {
+    try {
+      mkdirSync(resolvedPath, { recursive: true });
+    } catch (err: any) {
+      throw new Error(
+        `Failed to create dbPath directory "${resolvedPath}".\n` +
+        `  Fix: Ensure the parent directory "${dirname(resolvedPath)}" exists and is writable,\n` +
+        `       or create it manually: mkdir -p "${resolvedPath}"\n` +
+        `  Details: ${err.code || ""} ${err.message}`
+      );
+    }
+  }
+
+  // Check write permissions
+  try {
+    accessSync(resolvedPath, constants.W_OK);
+  } catch (err: any) {
+    throw new Error(
+      `dbPath directory "${resolvedPath}" is not writable.\n` +
+      `  Fix: Check permissions with: ls -la "${dirname(resolvedPath)}"\n` +
+      `       Or grant write access: chmod u+w "${resolvedPath}"\n` +
+      `  Details: ${err.code || ""} ${err.message}`
+    );
+  }
+
+  return resolvedPath;
+}
+
 // ============================================================================
 // Memory Store
 // ============================================================================
@@ -95,7 +163,19 @@ export class MemoryStore {
 
   private async doInitialize(): Promise<void> {
     const lancedb = await loadLanceDB();
-    const db = await lancedb.connect(this.config.dbPath);
+
+    let db: LanceDB.Connection;
+    try {
+      db = await lancedb.connect(this.config.dbPath);
+    } catch (err: any) {
+      const code = err.code || "";
+      const message = err.message || String(err);
+      throw new Error(
+        `Failed to open LanceDB at "${this.config.dbPath}": ${code} ${message}\n` +
+        `  Fix: Verify the path exists and is writable. Check parent directory permissions.`
+      );
+    }
+
     let table: LanceDB.Table;
 
     // Idempotent table init: try openTable first, create only if missing,
@@ -196,7 +276,15 @@ export class MemoryStore {
       metadata: entry.metadata || "{}",
     };
 
-    await this.table!.add([fullEntry]);
+    try {
+      await this.table!.add([fullEntry]);
+    } catch (err: any) {
+      const code = err.code || "";
+      const message = err.message || String(err);
+      throw new Error(
+        `Failed to store memory in "${this.config.dbPath}": ${code} ${message}`
+      );
+    }
     return fullEntry;
   }