tryweb · tryweb · Apr 3, 2026 · Apr 2, 2026 · Apr 3, 2026
diff --git a/README.md b/README.md
@@ -3,14 +3,21 @@
 **LanceDB-backed long-term memory provider for OpenCode**
 
 [![npm version](https://img.shields.io/npm/v/lancedb-opencode-pro)](https://www.npmjs.com/package/lancedb-opencode-pro)
-[![OpenCode](https://img.shields.io/badge/OpenCode-1.2.27+-blue)](https://opencode.ai)
+[![OpenCode](https://img.shields.io/badge/OpenCode-1.2.27--1.3.7-blue)](https://opencode.ai) ⚠️ [1.3.8+ known issue](docs/OPENCODE_COMPATIBILITY.md)
 
 Welcome to **lancedb-opencode-pro**! This plugin empowers OpenCode with a durable, long-term memory system powered by LanceDB.
 
 To help you find what you need quickly, please select the guide that best fits your needs:
 
 ## 🗺️ Choose Your Path
 
+### ⚠️ Experiencing Issues?
+*You see "Memory store unavailable" error or plugin not loading on OpenCode v1.3.8+*
+👉 **[Read the Compatibility Guide (10 min)](docs/OPENCODE_COMPATIBILITY.md)** 
+- Known OpenCode v1.3.8+ NAPI bug (Issue #20623)
+- Diagnosis checklist and solutions
+- Downgrade instructions & alternatives
+
 ### 🚀 First-Time Users
 *You are new to this project and want to get it running quickly.*
 👉 **[Read the Quick Start Guide (15 min)](docs/QUICK_START.md)**

diff --git a/docs/OPENCODE_COMPATIBILITY.md b/docs/OPENCODE_COMPATIBILITY.md
@@ -0,0 +1,298 @@
+# OpenCode Compatibility & Troubleshooting Guide
+
+**Last Updated**: April 3, 2026  
+**Status**: Active  
+**Scope**: OpenCode version compatibility, plugin loading, NAPI native addon issues
+
+---
+
+## 🔴 Critical Issue: OpenCode v1.3.8+ Native NAPI Addon Bug
+
+### Overview
+
+If you see this error when using memory tools:
+```
+Memory store unavailable (ollama embedding may be offline). Will retry automatically.
+```
+
+And embedding is confirmed working but memory tools persistently fail, **you likely have a native NAPI addon loading issue with OpenCode v1.3.8+**.
+
+---
+
+## 📋 Affected Versions & Status
+
+| OpenCode Version | Status | LanceDB Native Support | Notes |
+|------------------|--------|----------------------|-------|
+| **v1.3.7 and earlier** | ✅ **Stable** | ✅ **Working** | Recommended |
+| **v1.3.8 - v1.3.13** | ❌ **Broken** | ❌ **Broken** | Known bug (Issue #20623) |
+| **v1.4.0+** | ⏳ **Unknown** | ⏳ **TBD** | Monitor releases |
+
+### Root Cause (Issue #20623)
+
+**Title**: `[Bug]: Plugins with native NAPI dependencies return empty module ({}) since v1.3.8 plugin loader refactor`
+
+**Root cause**: Plugin loader refactor in v1.3.8 (PR #20112) breaks external NAPI addon resolution.
+
+```
+v1.3.8+ Plugin Loader:
+  resolvePackagePath() + pathToFileURL()
+  → @lancedb/lancedb resolves to empty object {}
+  → import("@lancedb/lancedb") returns {}
+  → store.init() fails silently in catch block
+  → state.initialized stays false
+  → All memory tools return "unavailable" error
+```
+
+**Affected plugins** (all native NAPI users):
+- ✅ `lancedb-opencode-pro` (this plugin)
+- ✅ Any plugin using: `sharp`, `better-sqlite3`, `@libsql/client`, etc.
+
+---
+
+## 🔧 Solutions
+
+### Solution 1: Downgrade to OpenCode v1.3.7 (RECOMMENDED - Fastest)
+
+**Status**: ✅ Proven to work
+
+**Steps**:
+```bash
+# Check current version
+opencode --version
+# Output should be: 1.3.7 or earlier
+
+# If you have v1.3.8+, downgrade
+opencode upgrade 1.3.7
+
+# Verify
+opencode --version
+# Restart OpenCode
+```
+
+**Pros**:
+- Immediate fix, no code changes needed
+- lancedb-opencode-pro works perfectly
+
+**Cons**:
+- You cannot use OpenCode 1.3.8+ features
+- Will be prompted to upgrade again
+
+**Timeframe**: Immediate (5 minutes)
+
+---
+
+### Solution 2: Improve Error Messaging (INTERIM - Helps Debugging)
+
+**Status**: 🔄 Proposed patch for lancedb-opencode-pro
+
+Add clear error handling to `src/store.ts` to help users diagnose the issue:
+
+**File**: `/home/devuser/workspace/lancedb-opencode-pro/src/store.ts`
+
+**Current code** (line 93):
+```typescript
+async init(vectorDim: number): Promise<void> {
+  await mkdir(this.dbPath, { recursive: true });
+  await mkdir(dirname(this.dbPath), { recursive: true });
+  this.lancedb = await import("@lancedb/lancedb");
+  this.connection = (await this.lancedb.connect(this.dbPath));
+  // ... rest of init
+}
+```
+
+**Proposed change**:
+```typescript
+async init(vectorDim: number): Promise<void> {
+  await mkdir(this.dbPath, { recursive: true });
+  await mkdir(dirname(this.dbPath), { recursive: true });
+
+  try {
+    this.lancedb = await import("@lancedb/lancedb");
+    if (!this.lancedb || typeof this.lancedb.connect !== "function") {
+      throw new Error(
+        "LanceDB module loaded but is invalid/empty. " +
+        "This is a known issue in OpenCode v1.3.8+. " +
+        "Please downgrade to v1.3.7 or wait for OpenCode fix."
+      );
+    }
+    this.connection = (await this.lancedb.connect(this.dbPath));
+  } catch (error) {
+    const errorMsg = (error as Error).message;
+    throw new Error(
+      `[lancedb-opencode-pro] Failed to initialize memory store. ` +
+      `Error: ${errorMsg} ` +
+      `(For OpenCode v1.3.8+, this is Issue #20623. Downgrade to v1.3.7)`
+    );
+  }
+  // ... rest of init
+}
+```
+
+**Pros**:
+- Clear error messages guide users to solution
+- Easy to implement
+- No functional changes
+
+**Cons**:
+- Doesn't fix the actual issue
+- Still needs downgrade or OpenCode fix
+
+**Timeframe**: Short-term (1-2 PRs)
+
+---
+
+### Solution 3: Long-Term - Migrate to Pure JS Backend (COMPLEX)
+
+**Status**: 🔄 Requires significant refactoring
+
+If you need to support OpenCode 1.3.8+ permanently, consider:
+
+**Option A**: Use LanceDB HTTP API (remote database)
+```typescript
+// Instead of local @lancedb/lancedb native binding
+// Use HTTP client to connect to remote LanceDB server
+this.lancedb = await fetch("http://lancedb-server:8000/api/...");
+```
+
+**Option B**: Use alternative pure-JS vector database
+- `usearch` (pure JS, no native bindings)
+- `milvus-sdk-node` (with pure JS mode)
+- `chroma` (HTTP API)
+
+**Pros**:
+- Works with OpenCode 1.3.8+
+- Potentially more scalable
+- No native dependency issues
+
+**Cons**:
+- Major refactoring (50+ files)
+- Adds network dependency (latency)
+- Requires separate database server
+- Loses local-first architecture advantage
+
+**Timeframe**: Long-term (3-6 months, major effort)
+
+---
+
+## 🐛 Diagnosis Checklist
+
+Use this to confirm if you have the v1.3.8+ NAPI bug:
+
+**Step 1: Check OpenCode version**
+```bash
+opencode --version
+# If output is v1.3.8 - v1.3.13, you have the issue
+```
+
+**Step 2: Verify Ollama is working**
+```bash
+curl http://ollama:11434/api/tags
+curl http://ollama:11434/api/embeddings -d '{"model":"nomic-embed-text","prompt":"test"}'
+# Both should return valid JSON
+```
+
+**Step 3: Check plugin installation**
+```bash
+ls ~/.cache/opencode/node_modules/lancedb-opencode-pro/dist/
+# Should list: index.js, store.js, embedder.js, etc.
+```
+
+**Step 4: Try memory_stats**
+```
+# In OpenCode chat, use: memory_stats
+# If you see "Memory store unavailable" despite Ollama working → Issue #20623
+```
+
+**Step 5: Check for NAPI loading error** (advanced)
+```bash
+cd ~/.cache/opencode
+bun -e "
+import { MemoryStore } from './node_modules/lancedb-opencode-pro/dist/store.js';
+import { createEmbedder } from './node_modules/lancedb-opencode-pro/dist/embedder.js';
+
+const e = createEmbedder({provider:'ollama',model:'nomic-embed-text',baseUrl:'http://ollama:11434',timeoutMs:6000});
+const s = new MemoryStore(process.env.HOME + '/.opencode/memory/lancedb');
+await s.init(await e.dim());
+console.log('SUCCESS: Store initialized');
+" 2>&1
+# If this succeeds but OpenCode fails → Confirmed Issue #20623
+```
+
+---
+
+## 📞 Support & Escalation
+
+### If Downgrade Works
+- ✅ You're good! Stay on v1.3.7
+- Monitor [OpenCode Issue #20623](https://github.com/anomalyco/opencode/issues/20623)
+- When OpenCode releases fix, upgrade to new version
+
+### If Downgrade Doesn't Work
+- ❌ Different issue (not v1.3.8+ NAPI bug)
+- Check [QUICK_START.md](QUICK_START.md) prerequisites
+- Verify Ollama is accessible from OpenCode host
+- Check logs: `~/.local/share/opencode/log/`
+
+### Report Issues
+1. **This plugin**: https://github.com/tryweb/lancedb-opencode-pro/issues
+2. **OpenCode native addon support**: https://github.com/anomalyco/opencode/issues/20623
+
+Include:
+- OpenCode version (`opencode --version`)
+- Plugin version (`npm list lancedb-opencode-pro` or check `package.json`)
+- Steps to reproduce
+- Ollama verification output
+
+---
+
+## 🔍 Related Issues
+
+| Issue | Component | Status | Impact |
+|-------|-----------|--------|--------|
+| [#20623](https://github.com/anomalyco/opencode/issues/20623) | OpenCode plugin loader | Open | 🔴 Blocks all NAPI plugins |
+| [#20112](https://github.com/anomalyco/opencode/pull/20112) | Plugin loader refactor | Merged | 🔴 Introduced bug |
+| [#20139](https://github.com/anomalyco/opencode/issues/20139) | npm plugin loading | Open | 🟡 Related |
+| [#20149](https://github.com/anomalyco/opencode/issues/20149) | Package main entries | Open | 🟡 Related |
+
+---
+
+## 📊 Troubleshooting Decision Tree
+
+```
+┌─ OpenCode v1.3.8+?
+│  ├─ YES → Issue #20623 (this page)
+│  │  ├─ Try downgrade to v1.3.7 → Works? ✅ Done
+│  │  └─ Doesn't work? → Different issue
+│  └─ NO (v1.3.7 or earlier) → Skip this section
+│
+└─ Ollama accessible?
+   ├─ curl http://ollama:11434/api/tags → Returns JSON? ✅
+   ├─ NO → Fix Ollama access first
+   └─ YES → Check prerequisites in QUICK_START.md
+```
+
+---
+
+## 📚 Related Documentation
+
+- **[QUICK_START.md](QUICK_START.md)** — Prerequisites & setup (check version requirement)
+- **[DEVELOPMENT_WORKFLOW.md](DEVELOPMENT_WORKFLOW.md)** — For developers working on fixes
+- **[ADVANCED_CONFIG.md](ADVANCED_CONFIG.md)** — Configuration validation
+
+---
+
+## 🎯 Summary
+
+| Aspect | Status | Action |
+|--------|--------|--------|
+| **Current state** | ❌ OpenCode v1.3.8+ broke NAPI addons | Check your OpenCode version |
+| **This plugin** | ✅ Code is correct, works on v1.3.7 | No code changes needed |
+| **Fix timeline** | ⏳ OpenCode team aware but no ETA | Monitor Issue #20623 |
+| **Workaround** | ✅ Downgrade to v1.3.7 | Recommended now |
+| **Long-term** | 🔄 Wait for OpenCode fix or refactor | 1-3 months |
+
+---
+
+**Last Verified**: April 3, 2026  
+**Tested On**: OpenCode v1.3.13, lancedb-opencode-pro v0.6.0  
+**Status**: Active Issue
diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md
@@ -8,7 +8,7 @@ Complete the following steps to start using the long-term memory feature within
 
 ## Prerequisites
 
-- [ ] OpenCode 1.2.27+ installed
+- [ ] OpenCode **1.2.27 - 1.3.7** installed *(⚠️ 1.3.8+ has known NAPI bug, see [OPENCODE_COMPATIBILITY.md](OPENCODE_COMPATIBILITY.md))*
 - [ ] Ollama installed and accessible
 - [ ] Embedding model downloaded (`nomic-embed-text`)
 
@@ -142,6 +142,8 @@ If you see `.lance` files, it means the memory has been successfully persisted.
 
 ## Troubleshooting
 
+> **⚠️ Critical Issue**: If you see "Memory store unavailable" error on OpenCode v1.3.8 or later, see [OPENCODE_COMPATIBILITY.md](OPENCODE_COMPATIBILITY.md). This is a known platform bug.
+
 ### Issue 1: Plugin Not Loaded
 
 **Symptom**: OpenCode does not recognize `memory_*` tools