@memvid/sdk 2.0.140 → 2.0.142

package/README.md

@@ -1,8 +1,8 @@
 # @memvid/sdk
 
-Single-file AI memory system for Node.js. Store documents, search with BM25 ranking, and run retrieval-augmented generation (RAG) queries from a portable `.mv2` file.
+A single-file AI memory system for Node.js. Store documents, search with BM25 + vector ranking, and run RAG queries from a portable `.mv2` file.
 
-Built on Rust via N-API for native performance. No database setup, no network dependencies, no configuration files.
+Built on Rust via N-API. No database setup, no external services required.
 
 ## Install
 
@@ -10,392 +10,337 @@ Built on Rust via N-API for native performance. No database setup, no network de
 npm install @memvid/sdk
 ```
 
-## Quick start
+The package automatically installs the correct binary for your platform (macOS, Linux, or Windows).
 
-```typescript
-import { use, create } from "@memvid/sdk";
+## Quick Start
 
-// Create a new memory file
-const mv = await use("basic", "notes.mv2", { mode: "auto" });
+```javascript
+import { create } from "@memvid/sdk";
+
+// Create a memory file
+const mv = await create("notes.mv2");
 
-// Store a document
+// Store some documents
 await mv.put({
-  title: "Project kickoff",
+  title: "Project Update",
   label: "meeting",
-  text: "Discussed timeline, assigned tasks to team members.",
-  metadata: { date: "2024-01-15" },
+  text: "Discussed Q4 roadmap. Alice will handle the frontend refactor.",
+  metadata: { date: "2024-01-15", attendees: ["Alice", "Bob"] }
+});
+
+await mv.put({
+  title: "Technical Decision",
+  label: "architecture",
+  text: "Decided to use PostgreSQL for the main database. Redis for caching.",
 });
 
 // Search by keyword
-const results = await mv.find("timeline");
+const results = await mv.find("database");
 console.log(results.hits);
 
-// Ask a question (retrieves relevant context)
-const answer = await mv.ask("What was discussed in the kickoff?");
-console.log(answer.context);
+// Ask a question
+const answer = await mv.ask("What database are we using?", {
+  model: "openai:gpt-4o-mini"
+});
+console.log(answer.text);
 
-// Commit and close
+// Close the file
 await mv.seal();
 ```
 
 ## Core API
 
-### Opening a memory
+### Opening and Creating
+
+```javascript
+import { create, use } from "@memvid/sdk";
+
+// Create a new memory file
+const mv = await create("notes.mv2");
+
+// Open an existing file
+const mv = await use("basic", "notes.mv2", { mode: "open" });
 
-```typescript
-const mv = await use(kind, path, options?)
+// Create or open (auto mode)
+const mv = await use("basic", "notes.mv2", { mode: "auto" });
+
+// Open read-only
+const mv = await use("basic", "notes.mv2", { readOnly: true });
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `kind` | `string` | Adapter type: `"basic"`, `"langchain"`, `"llamaindex"`, `"openai"`, `"crewai"`, `"vercel-ai"`, `"autogen"` |
-| `path` | `string` | Path to `.mv2` file |
-| `options.mode` | `string` | `"open"` (default), `"create"`, or `"auto"` |
-| `options.enableLex` | `boolean` | Enable lexical index (default: `true`) |
-| `options.enableVec` | `boolean` | Enable vector index (default: `true`) |
-| `options.readOnly` | `boolean` | Open in read-only mode (default: `false`) |
-| `options.lockTimeoutMs` | `number` | Lock acquisition timeout (ms) |
-| `options.force` | `"stale_only"` | Force-open when a stale lock exists |
-| `options.forceWritable` | `boolean` | Force writable open (dangerous) |
-| `options.memvidApiKey` | `string` | Memvid API key for capacity beyond free tier (`mv2_*`) |
-
-### Storing documents
-
-```typescript
+### Storing Documents
+
+```javascript
+// Store text content
 await mv.put({
-  title: "Document title",
-  label: "category",
-  text: "Document content...",
-  metadata: { key: "value" },
-  uri: "mv2://custom/path",
-  tags: ["tag1", "tag2"],
+  title: "Meeting Notes",
+  label: "meeting",
+  text: "Discussed the new API design.",
+  metadata: { date: "2024-01-15", priority: "high" },
+  tags: ["api", "design", "q1"]
 });
-```
 
-### Automatic embeddings (optional)
-
-To enable semantic search without supplying pre-computed vectors, set `enableEmbedding: true` on `put()`:
+// Store a file (PDF, DOCX, TXT, etc.)
+await mv.put({
+  title: "Q4 Report",
+  label: "reports",
+  file: "./documents/q4-report.pdf"
+});
 
-```typescript
+// Store with both text and file
 await mv.put({
-  title: "Document title",
-  label: "category",
-  text: "Document content...",
-  enableEmbedding: true,
-  // Optional (defaults to "bge-small")
-  embeddingModel: "bge-small", // or "openai-small"
+  title: "Contract Summary",
+  label: "legal",
+  text: "Key terms: 2-year agreement, auto-renewal clause.",
+  file: "./contracts/agreement.pdf"
 });
 ```
 
-Notes:
-- Local embedding models use `fastembed` and cache weights under `MEMVID_MODELS_DIR` (first run may download).
-- OpenAI embedding models require `OPENAI_API_KEY` (and optionally `OPENAI_BASE_URL`).
-- If embeddings cannot be generated, the SDK throws `MV015` (it will not silently ingest without embeddings).
-
-### Batch ingestion
+### Batch Ingestion
 
-For bulk imports, `putMany` processes documents in parallel:
+For large imports, `putMany` is significantly faster:
 
-```typescript
-const docs = [
-  { title: "Doc 1", text: "First document content..." },
-  { title: "Doc 2", text: "Second document content..." },
+```javascript
+const documents = [
+  { title: "Doc 1", label: "notes", text: "First document content..." },
+  { title: "Doc 2", label: "notes", text: "Second document content..." },
   // ... thousands more
 ];
 
-const frameIds = await mv.putMany(docs, { compressionLevel: 3 });
-console.log(`Ingested ${frameIds.length} documents`);
+const frameIds = await mv.putMany(documents);
+console.log(`Added ${frameIds.length} documents`);
 ```
 
-To auto-generate embeddings during batch ingest, enable embeddings in the options (requests that already include `embedding` are left unchanged):
-
-```typescript
-await mv.putMany(docs, {
-  enableEmbedding: true,
-  embeddingModel: "bge-small", // or "openai-small"
-});
-```
-
-If you provide **pre-computed embeddings**, also attach the embedding identity so the CLI/SDKs can auto-detect the correct query embedding model later:
+### Searching
 
-```typescript
-import { OpenAIEmbeddings } from "@memvid/sdk";
+```javascript
+// Lexical search (BM25 ranking)
+const results = await mv.find("machine learning", { k: 10 });
 
-const embedder = new OpenAIEmbeddings({ model: "text-embedding-3-small" });
-const vectors = await embedder.embedDocuments(docs.map((d) => d.text));
-
-await mv.putMany(
-  docs.map((doc, i) => ({
-    ...doc,
-    embedding: vectors[i],
-    embeddingIdentity: {
-      provider: "openai",
-      model: embedder.modelName,
-      dimension: embedder.dimension,
-    },
-  }))
-);
+for (const hit of results.hits) {
+  console.log(`${hit.title}: ${hit.snippet}`);
+}
 ```
 
-### External embedding providers (bring your own)
+Search options:
 
-For developer-friendly “use any embedding model/API” workflows, pass an `embedder`:
+| Option | Type | Description |
+|--------|------|-------------|
+| `k` | number | Number of results (default: 10) |
+| `snippetChars` | number | Snippet length (default: 240) |
+| `mode` | string | `"lex"`, `"sem"`, or `"auto"` |
+| `scope` | string | Filter by URI prefix |
 
-```typescript
-import { OpenAIEmbeddings } from "@memvid/sdk";
+### Semantic Search
 
-const embedder = new OpenAIEmbeddings({ model: "text-embedding-3-small" });
+Semantic search requires embeddings. You can generate them during ingestion:
 
-// Ingest: computes embeddings for requests that omit `embedding` and stores embedding identity metadata.
-await mv.putMany(docs, { embedder });
+```javascript
+// Using local embeddings (bge-small, nomic, etc.)
+await mv.put({
+  title: "Document",
+  text: "Content here...",
+  enableEmbedding: true,
+  embeddingModel: "bge-small"
+});
 
-// Query: computes query embeddings when `queryEmbedding` is omitted.
-const results = await mv.find("timeline", { mode: "sem", embedder });
-const context = await mv.ask("What happened?", { mode: "sem", contextOnly: true, embedder });
+// Using OpenAI embeddings
+await mv.put({
+  title: "Document",
+  text: "Content here...",
+  enableEmbedding: true,
+  embeddingModel: "openai-small"  // requires OPENAI_API_KEY
+});
 ```
 
-Built-in external providers (API keys via env vars):
-- `OpenAIEmbeddings` (`OPENAI_API_KEY`)
-- `CohereEmbeddings` (`COHERE_API_KEY`)
-- `VoyageEmbeddings` (`VOYAGE_API_KEY`)
-- `NvidiaEmbeddings` (`NVIDIA_API_KEY`, default base URL `https://integrate.api.nvidia.com`)
-
-Notes:
-- If `embedder` is set, `putMany({ enableEmbedding: true })` is ignored (embeddings are computed in JS).
-- `put()` does not accept pre-computed vectors; use `putMany([singleDoc], { embedder })` for external embeddings.
+Then search semantically:
 
-### Searching
-
-```typescript
-const results = await mv.find(query, options?)
+```javascript
+const results = await mv.find("neural networks", { mode: "sem" });
 ```
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `mode` | `"lex" \| "sem" \| "auto"` | Search mode (default: `"lex"`). `"sem"` uses vector search. `"auto"` reranks lexical hits when embeddings are available. |
-| `queryEmbedding` | `number[]` | Pre-computed query embedding (offline-safe). If omitted, the SDK tries to auto-detect the embedding model from the `.mv2` and embed the query. |
-| `queryEmbeddingModel` | `string` | Override the query embedding model (e.g. `"openai-small"`, `"bge-small"`). |
-| `k` | `number` | Number of results (default: `10`) |
-| `snippetChars` | `number` | Snippet length (default: `240`) |
-| `scope` | `string` | Filter by URI prefix |
-| `adaptive` | `boolean` | Enable adaptive retrieval (semantic-only) |
-| `minRelevancy` | `number` | Minimum relevancy ratio vs top score (default: `0.5`, adaptive-only) |
-| `maxK` | `number` | Max candidates to consider (default: `100`, adaptive-only) |
-| `adaptiveStrategy` | `"relative" \| "absolute" \| "cliff" \| "elbow" \| "combined"` | Adaptive cutoff strategy (default: `"relative"`, adaptive-only) |
-
-### Vector search (pre-computed query embedding)
-
-Use `vecSearch()` when you already have a query embedding vector (offline-safe):
-
-```typescript
-const queryEmbedding = [/* ... floats ... */];
-const results = await mv.vecSearch("my query", queryEmbedding, { k: 10 });
-console.log(results.hits);
-```
+**Windows users:** Local embedding models (bge-small, nomic, etc.) are not available on Windows due to ONNX runtime limitations. Use OpenAI embeddings instead by setting `OPENAI_API_KEY`.
 
-### Retrieval-augmented generation
+### Question Answering (RAG)
 
-```typescript
-const response = await mv.ask(question, options?)
-```
+```javascript
+// Basic RAG query
+const answer = await mv.ask("What did we decide about the database?");
+console.log(answer.text);
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `k` | `number` | Documents to retrieve (default: `6`) |
-| `mode` | `string` | `"lex"`, `"sem"`, or `"auto"`/`"hybrid"` |
-| `queryEmbedding` | `number[]` | Pre-computed query embedding for semantic/hybrid ask (offline-safe). If omitted, the SDK tries to auto-detect the embedding model from the `.mv2` and embed the query. |
-| `queryEmbeddingModel` | `string` | Override the query embedding model (e.g. `"openai-small"`, `"bge-small"`). |
-| `adaptive` | `boolean` | Enable adaptive retrieval (semantic/hybrid only) |
-| `minRelevancy` | `number` | Minimum relevancy ratio vs top score (default: `0.5`, adaptive-only) |
-| `maxK` | `number` | Max candidates to consider (default: `100`, adaptive-only) |
-| `adaptiveStrategy` | `"relative" \| "absolute" \| "cliff" \| "elbow" \| "combined"` | Adaptive cutoff strategy (default: `"relative"`, adaptive-only) |
-
-### Best practices: Adaptive retrieval
-
-For best search quality, enable adaptive retrieval with the `combined` strategy. This dynamically adjusts result counts based on relevance scores rather than returning a fixed `k`:
-
-```typescript
-// Recommended for find()
-const results = await mv.find("your query", {
-  mode: "sem", // or "auto"
-  adaptive: true,
-  adaptiveStrategy: "combined",
+// With specific model
+const answer = await mv.ask("Summarize the meeting notes", {
+  model: "openai:gpt-4o-mini",
+  k: 6  // number of documents to retrieve
 });
 
-// Recommended for ask()
-const answer = await mv.ask("your question", {
-  mode: "auto",
-  adaptive: true,
-  adaptiveStrategy: "combined",
-});
+// Get context only (no LLM synthesis)
+const context = await mv.ask("What was discussed?", { contextOnly: true });
+console.log(context.context);  // Retrieved document snippets
 ```
 
-The `combined` strategy uses both relative thresholds and score cliff detection to filter out low-relevance results, providing higher quality context for RAG applications.
+### Timeline and Stats
 
-### LLM synthesis options
+```javascript
+// Get recent entries
+const entries = await mv.timeline({ limit: 20 });
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `model` | `string` | LLM for synthesis (e.g., `"openai:gpt-4o-mini"`, `"nvidia:meta/llama3-8b-instruct"`) |
-| `modelApiKey` | `string` | API key for the LLM provider |
-| `contextOnly` | `boolean` | Skip synthesis, return context only |
-| `returnSources` | `boolean` | Include source metadata in response |
-
-### Timeline queries
-
-```typescript
-const entries = await mv.timeline({
-  limit: 50,
-  since: 1704067200,  // Unix timestamp
-  reverse: true,
-});
+// Get statistics
+const stats = await mv.stats();
+console.log(`Documents: ${stats.frame_count}`);
+console.log(`Size: ${stats.size_bytes} bytes`);
 ```
 
-### Statistics
+### Closing
 
-```typescript
-const stats = await mv.stats();
-// { frame_count, size_bytes, has_lex_index, has_vec_index, ... }
+Always close the memory when done:
+
+```javascript
+await mv.seal();
 ```
 
-### File operations
+## External Embeddings
 
-```typescript
-// Commit pending changes
-await mv.seal();
+For more control over embeddings, use external providers:
+
+```javascript
+import { create, OpenAIEmbeddings, getEmbedder } from "@memvid/sdk";
 
-// Verify file integrity
-import { verifyMemvid } from "@memvid/sdk";
-const report = await verifyMemvid("notes.mv2", { deep: true });
+// Create memory file
+const mv = await create("knowledge.mv2");
 
-// Repair indexes
-import { doctorMemvid } from "@memvid/sdk";
-await doctorMemvid("notes.mv2", { rebuildLexIndex: true, dryRun: true });
+// Initialize embedding provider
+const embedder = new OpenAIEmbeddings({ model: "text-embedding-3-small" });
+
+// Prepare documents
+const documents = [
+  { title: "ML Basics", label: "ai", text: "Machine learning enables systems to learn from data." },
+  { title: "Deep Learning", label: "ai", text: "Deep learning uses neural networks with multiple layers." },
+];
 
-// Verify the single-file guarantee (no sidecar files like -wal/-shm)
-import { verifySingleFile } from "@memvid/sdk";
-await verifySingleFile("notes.mv2");
+// Ingest with external embeddings
+await mv.putMany(documents, { embedder });
 
-// Lock visibility helpers
-import { lockWho, lockNudge } from "@memvid/sdk";
-console.log(await lockWho("notes.mv2")); // { locked: false } or { locked: true, owner: ... }
-await lockNudge("notes.mv2"); // sends SIGUSR1 to active writer (Unix)
+// Search using external embeddings
+const results = await mv.find("neural networks", { mode: "sem", k: 3, embedder });
+
+for (const hit of results.hits) {
+  console.log(`${hit.title}: ${hit.score.toFixed(3)}`);
+}
 ```
 
-## Framework adapters
+Built-in providers:
+- `OpenAIEmbeddings` (requires `OPENAI_API_KEY`)
+- `CohereEmbeddings` (requires `COHERE_API_KEY`)
+- `VoyageEmbeddings` (requires `VOYAGE_API_KEY`)
+- `NvidiaEmbeddings` (requires `NVIDIA_API_KEY`)
+- `GeminiEmbeddings` (requires `GOOGLE_API_KEY` or `GEMINI_API_KEY`)
+- `MistralEmbeddings` (requires `MISTRAL_API_KEY`)
 
-Adapters expose framework-native tools when the corresponding dependency is installed.
+Use the factory function for quick setup:
+
+```javascript
+import { getEmbedder } from "@memvid/sdk";
+
+// Create any supported provider
+const embedder = getEmbedder("openai");  // or "cohere", "voyage", "nvidia", "gemini", "mistral"
+```
+
+## Framework Integrations
 
 ### LangChain
 
-```typescript
+```javascript
 import { use } from "@memvid/sdk";
 
 const mv = await use("langchain", "notes.mv2");
-const tools = mv.tools; // StructuredTool instances for put/find/ask
+const tools = mv.tools;  // StructuredTool instances for agents
 ```
 
 ### LlamaIndex
 
-```typescript
+```javascript
 const mv = await use("llamaindex", "notes.mv2");
-const queryEngine = mv.asQueryEngine();
+const engine = mv.asQueryEngine();
+const response = await engine.query("What is the timeline?");
 ```
 
-### OpenAI function calling
+### OpenAI Function Calling
 
-```typescript
+```javascript
 const mv = await use("openai", "notes.mv2");
-const functions = mv.functions; // JSON schemas for tool_calls
+const functions = mv.functions;  // JSON schemas for tool_calls
 ```
 
 ### Vercel AI SDK
 
-```typescript
+```javascript
 const mv = await use("vercel-ai", "notes.mv2");
 ```
 
-## Table extraction
-
-Extract structured tables from PDFs:
+## Error Handling
 
-```typescript
-const result = await mv.putPdfTables("report.pdf", true);
-console.log(`Extracted ${result.tables_count} tables`);
+Errors include a code for programmatic handling:
 
-const tables = await mv.listTables();
-const data = await mv.getTable(tables[0].table_id, "json");
-```
-
-## Error handling
-
-Errors include a code prefix for programmatic handling:
-
-| Code | Description |
-|------|-------------|
-| `MV001` | Storage capacity exceeded |
-| `MV002` | Invalid ticket signature |
-| `MV003` | Ticket replay detected |
-| `MV004` | Lexical index not enabled |
-| `MV005` | Time index missing |
-| `MV006` | Verification failed |
-| `MV007` | File locked by another process |
-| `MV008` | Memvid API key required |
-| `MV009` | Memory already bound |
-| `MV010` | Frame not found |
-| `MV011` | Vector index not enabled |
-| `MV012` | Corrupt file detected |
-| `MV013` | I/O error (e.g., file not found) |
-| `MV014` | Vector dimension mismatch |
-| `MV015` | Embedding runtime unavailable/failed |
-| `MV999` | Unknown/internal error |
-
-```typescript
+```javascript
 import { MemvidError } from "@memvid/sdk";
 
 try {
-  await mv.put({ ... });
+  await mv.put({ title: "Doc", text: "Content" });
 } catch (err) {
   if (err instanceof MemvidError) {
-    if (err.code === "MV001") {
-      console.error("Out of storage capacity");
-    } else {
-      console.error(`Error ${err.code}: ${err.message}`);
+    switch (err.code) {
+      case "MV001": console.error("Storage capacity exceeded"); break;
+      case "MV007": console.error("File is locked"); break;
+      case "MV015": console.error("Embedding failed"); break;
+      default: console.error(`Error ${err.code}: ${err.message}`);
     }
   }
 }
 ```
 
-## Environment variables
+Common error codes:
 
-| Variable | Description |
-|----------|-------------|
-| `MEMVID_API_KEY` | API key for capacity beyond free tier |
-| `MEMVID_API_URL` | Control plane URL (for enterprise deployments) |
-| `MEMVID_MODELS_DIR` | Path to embedding model cache |
-| `MEMVID_OFFLINE` | Set to `1` to disable network-backed embeddings and avoid model downloads |
-| `OPENAI_API_KEY` | API key for OpenAI embeddings / LLMs (when used) |
-| `OPENAI_BASE_URL` | Override OpenAI API base URL (defaults to `https://api.openai.com`) |
+| Code | Description |
+|------|-------------|
+| MV001 | Storage capacity exceeded |
+| MV007 | File locked by another process |
+| MV010 | Frame not found |
+| MV013 | File not found |
+| MV015 | Embedding failed |
 
-## Building from source
+## Environment Variables
 
-```bash
-# Install dependencies
-pnpm install
+| Variable | Description |
+|----------|-------------|
+| `OPENAI_API_KEY` | For OpenAI embeddings and LLM synthesis |
+| `OPENAI_BASE_URL` | Custom OpenAI-compatible endpoint |
+| `NVIDIA_API_KEY` | For NVIDIA NIM embeddings |
+| `MEMVID_MODELS_DIR` | Local embedding model cache directory |
+| `MEMVID_API_KEY` | For capacity beyond the free tier |
+| `MEMVID_OFFLINE` | Set to `1` to disable network features |
+
+## Platform Support
+
+| Platform | Architecture | Local Embeddings |
+|----------|--------------|------------------|
+| macOS | ARM64 (Apple Silicon) | Yes |
+| macOS | x64 (Intel) | Yes |
+| Linux | x64 (glibc) | Yes |
+| Windows | x64 | No (use OpenAI) |
 
-# Build TypeScript
-pnpm run build
+## Requirements
 
-# Build native module (requires Rust toolchain)
-cargo build --release
-cp target/release/libmemvid_node.dylib index.node  # macOS
-```
+- Node.js 18 or later
+- For local embeddings: macOS or Linux (Windows requires OpenAI)
 
-## Requirements
+## More Information
 
-- Node.js 18+
-- macOS (Apple Silicon or Intel), Linux (x64), or Windows (x64)
+- Documentation: https://docs.memvid.com
+- GitHub: https://github.com/memvid/memvid
+- Discord: https://discord.gg/2mynS7fcK7
+- Website: https://memvid.com
 
 ## License
 
-Apache-2.0. See [LICENSE](./LICENSE).
+Apache-2.0

package/dist/index.js

@@ -488,16 +488,26 @@ function loadNativeAddon() {
     }
     // Production mode: load from platform-specific package
     if (platformInfo) {
+        // Split scoped package name: "@memvid/sdk-win32-x64-msvc" -> ["@memvid", "sdk-win32-x64-msvc"]
+        const pkgParts = platformInfo.pkg.split("/");
+        const scope = pkgParts[0]; // "@memvid"
+        const pkgName = pkgParts[1]; // "sdk-win32-x64-msvc"
         // Try to find the platform package in various locations
         const possiblePaths = [
-            // Standard npm install location
-            path.join(__dirname, "..", "node_modules", platformInfo.pkg, platformInfo.binary),
-            // Hoisted to parent node_modules
-            path.join(__dirname, "..", "..", platformInfo.pkg, platformInfo.binary),
+            // Sibling in same scope (most common for scoped packages)
+            // From @memvid/sdk/dist -> @memvid/sdk-win32-x64-msvc
+            path.join(__dirname, "..", "..", pkgName, platformInfo.binary),
+            // Standard npm install location (nested node_modules)
+            path.join(__dirname, "..", "node_modules", scope, pkgName, platformInfo.binary),
             // Hoisted to root node_modules
-            path.join(__dirname, "..", "..", "..", platformInfo.pkg, platformInfo.binary),
+            // From @memvid/sdk/dist -> ../../.. = node_modules, then @memvid/sdk-win32-x64-msvc
+            path.join(__dirname, "..", "..", "..", scope, pkgName, platformInfo.binary),
+            // Hoisted 4 levels up (deep yarn workspaces)
+            path.join(__dirname, "..", "..", "..", "..", scope, pkgName, platformInfo.binary),
             // pnpm structure
-            path.join(__dirname, "..", "..", ".pnpm", "node_modules", platformInfo.pkg, platformInfo.binary),
+            path.join(__dirname, "..", "..", ".pnpm", "node_modules", scope, pkgName, platformInfo.binary),
+            // Yarn PnP / berry
+            path.join(__dirname, "..", "..", ".yarn", "cache", `${scope.replace("@", "")}-${pkgName}`, platformInfo.binary),
         ];
         for (const binaryPath of possiblePaths) {
             try {
@@ -542,6 +552,17 @@ function loadNativeAddon() {
     }
     // No platform package found
     const supportedPlatforms = Object.keys(platformPackages).join(", ");
+    const platformPkg = platformInfo?.pkg;
+    if (platformPkg) {
+        // Platform is supported but binary not found
+        throw new Error(`Native binary not found for platform: ${key}\n` +
+            `The platform package ${platformPkg} may not have installed correctly.\n` +
+            `Try reinstalling:\n` +
+            `  npm install ${platformPkg}\n` +
+            `  # or: yarn add ${platformPkg}\n` +
+            `Then reinstall the main package:\n` +
+            `  npm install @memvid/sdk`);
+    }
     throw new Error(`Unsupported platform: ${key}\n` +
         `Supported platforms: ${supportedPlatforms}\n` +
         `Make sure you have installed @memvid/sdk correctly:\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memvid/sdk",
-  "version": "2.0.140",
+  "version": "2.0.142",
   "description": "Single-file AI memory system for Node.js. Store, search, and query documents with built-in RAG.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -41,10 +41,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@memvid/sdk-darwin-arm64": "2.0.140",
-    "@memvid/sdk-darwin-x64": "2.0.140",
-    "@memvid/sdk-linux-x64-gnu": "2.0.140",
-    "@memvid/sdk-win32-x64-msvc": "2.0.140"
+    "@memvid/sdk-darwin-arm64": "2.0.142",
+    "@memvid/sdk-darwin-x64": "2.0.142",
+    "@memvid/sdk-linux-x64-gnu": "2.0.142",
+    "@memvid/sdk-win32-x64-msvc": "2.0.142"
   },
   "peerDependencies": {
     "@langchain/core": ">=0.3.0",