feat(mcp): Phase 2 - Cloud-Only Fallback Mode

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -75,6 +75,7 @@ body:
       description: Which client are you using?
       options:
         - Claude Code CLI
+        - Claude Desktop (Cowork)
         - Cursor
         - VS Code
         - Other

.gitignore

@@ -17,20 +17,41 @@ yarn-debug.log*
 yarn-error.log*
 
 # OS files
+# macOS
 .DS_Store
 .DS_Store?
 ._*
+.AppleDouble
+.LSOverride
 .Spotlight-V100
 .Trashes
-ehthumbs.db
+# Windows
 Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+Desktop.ini
+# Linux
+*~
+.directory
+.fuse_hidden*
+.nfs*
 
-# IDE
+# IDE & Editors
+# VS Code
 .vscode/
+# JetBrains (IntelliJ, WebStorm, etc.)
 .idea/
+# Sublime Text
+*.sublime-project
+*.sublime-workspace
+# Vim
 *.swp
 *.swo
+# Emacs
 *~
+\#*\#
+.#*
 
 # Build outputs
 # Note: dist/ contains compiled TypeScript for npm package
@@ -51,13 +72,30 @@ chroma_db/
 *.db
 *.sqlite
 
+# Test databases
+*.test.db
+*.test.sqlite
+*.spec.db
+test.db*
+
 # Data directory (development databases and files)
 data/
 !data/.gitkeep
 
+# Benchmark outputs
+benchmarks/
+benchmark-results/
+benchmarks/results/
+*.benchmark
+
 # Test coverage
 coverage/
 .nyc_output/
+*.lcov
+*.coverage
+htmlcov/
+.coverage
+.coverage.*
 
 # Temporary files
 tmp/

README.md

@@ -92,11 +92,30 @@ npm install && npm run build
 ### Claude Code Integration
 
 MeMesh works seamlessly with:
-- ✅ **Claude Code CLI** (terminal)
-- ✅ **Claude Code VS Code Extension**
-- ✅ **Cursor** (via MCP)
+- ✅ **Claude Code CLI** (terminal) - **Full functionality**
+- ✅ **Claude Code VS Code Extension** - **Full functionality**
+- ✅ **Cursor** (via MCP) - **Full functionality**
+- ⚠️  **Claude Desktop (Cowork)** - **Partial support** (see below)
 - ✅ **Other MCP-compatible editors**
 
+#### Claude Desktop Cowork Compatibility
+
+**Current Status**: Cloud-only mode with limited functionality
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| MCP Server | ✅ Works | Starts successfully in cloud-only mode |
+| Basic Commands | ✅ Works | buddy-help, list-skills, etc. |
+| Memory Tools | ❌ Disabled | recall-memory, create-entities, buddy-do, buddy-remember |
+| Cloud Sync | ✅ Works | When MEMESH_API_KEY is configured |
+| Local Knowledge Graph | ❌ Unavailable | better-sqlite3 cannot compile in Cowork sandbox |
+
+**Why Limited**: Cowork sandbox has read-only filesystem and blocks native module compilation (better-sqlite3, onnxruntime-node, sqlite-vec).
+
+**Future**: Full support planned through cloud-first memory architecture. See [docs/COWORK_SUPPORT.md](docs/COWORK_SUPPORT.md) for details.
+
+**Recommendation**: Use **CLI version** for full functionality until cloud-first memory is implemented.
+
 ### Known Limitations
 
 - Windows native terminal may have display issues (use WSL2)

docs/COWORK_SUPPORT.md

@@ -0,0 +1,213 @@
+# Claude Desktop Cowork Support
+
+## Current Status: Partial Support (Cloud-Only Mode)
+
+MeMesh plugin can run in **Claude Desktop Cowork** environments, but with limited functionality due to native module restrictions in the Cowork sandbox.
+
+### ✅ What Works
+
+- **MCP Server Startup**: Server initializes successfully in cloud-only mode
+- **Basic Commands**: Non-memory tools (buddy-help, list-skills, etc.) work normally
+- **Cloud Sync**: When `MEMESH_API_KEY` is configured, cloud sync functionality is available
+
+### ⚠️ Current Limitations
+
+- **Memory Tools Disabled**: Local memory operations (recall-memory, create-entities, buddy-do, buddy-remember) are currently disabled
+- **No Local Knowledge Graph**: better-sqlite3 cannot compile in Cowork sandbox (read-only filesystem + blocked node-gyp)
+- **No Embeddings/Vector Search**: onnxruntime-node and sqlite-vec also unavailable (native modules)
+
+### 📋 System Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│ CLI Environment (Recommended)                       │
+├─────────────────────────────────────────────────────┤
+│ ✅ Local SQLite (better-sqlite3)                    │
+│ ✅ Full Knowledge Graph                             │
+│ ✅ All memory tools                                 │
+│ ✅ Embeddings & vector search                       │
+│ ✅ Optional cloud sync                              │
+└─────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────┐
+│ Claude Desktop Cowork (Limited)                     │
+├─────────────────────────────────────────────────────┤
+│ ⚠️  Cloud-only mode (no local SQLite)               │
+│ ❌ Memory tools disabled                            │
+│ ✅ Basic commands work                              │
+│ ✅ Cloud sync available (if MEMESH_API_KEY set)     │
+└─────────────────────────────────────────────────────┘
+```
+
+## Why These Limitations Exist
+
+### Cowork Sandbox Constraints
+
+Claude Desktop Cowork runs plugins in a restricted sandbox environment:
+
+1. **Read-only Plugin Filesystem**: Cannot write to `.claude-plugin/memesh/` directory
+2. **Blocked node-gyp Compilation**: HTTP 403 when downloading Node.js headers from nodejs.org
+3. **No Prebuilt Binaries**: Native modules (better-sqlite3, onnxruntime-node, sqlite-vec) don't ship ARM64 Linux binaries
+4. **Ephemeral Storage**: `~/.memesh/` directory is session-scoped, wiped on restart
+
+### Result
+
+Native modules fail to load, causing:
+- better-sqlite3 → No local SQLite → Knowledge Graph unavailable
+- onnxruntime-node → No embeddings → Semantic search unavailable
+- sqlite-vec → No vector index → KNN search unavailable
+
+## Installation in Cowork
+
+### Method 1: Cloud-Only Mode (Recommended)
+
+If you have a MeMesh Cloud account:
+
+1. **Set API Key**:
+   ```bash
+   export MEMESH_API_KEY="your-api-key"
+   ```
+
+2. **Install Plugin**:
+   - Open Claude Desktop
+   - Go to Settings → Plugins
+   - Search for "MeMesh"
+   - Click Install
+
+3. **Verify Installation**:
+   - Start a new Cowork session
+   - Type `/help` to see available commands
+   - Note: Memory tools will show "not available in cloud-only mode" errors
+
+### Method 2: CLI Alternative (Full Features)
+
+For full functionality, use the CLI version instead:
+
+```bash
+# Install globally
+npm install -g @pcircle/memesh
+
+# Or use via npx
+npx @pcircle/memesh --help
+
+# Configure in Claude Code
+# Add to ~/.claude/mcp_settings.json:
+{
+  "mcpServers": {
+    "memesh": {
+      "command": "npx",
+      "args": ["-y", "@pcircle/memesh"]
+    }
+  }
+}
+```
+
+## Expected Behavior
+
+### When Memory Tools are Called in Cowork
+
+```
+User: buddy-remember "authentication approach"
+
+❌ Tool 'buddy-remember' is not available in cloud-only mode.
+
+This MCP server is running without local SQLite storage (better-sqlite3 unavailable).
+
+To use local memory tools:
+1. Install better-sqlite3: npm install better-sqlite3
+2. Restart the MCP server
+
+OR use cloud sync tools instead:
+- memesh-cloud-sync: Sync with cloud storage (requires MEMESH_API_KEY)
+```
+
+### When Basic Commands are Called
+
+```
+User: buddy-help
+
+✅ Works normally - displays help information
+```
+
+## Future Roadmap
+
+### 🔮 Planned: Cloud-First Memory Architecture
+
+We're planning full Claude Desktop support through a cloud-first architecture:
+
+**Goal**: Access Knowledge Graph via MeMesh Cloud API instead of local SQLite
+
+**Implementation**:
+1. Cloud API endpoints for KG operations (create, recall, search)
+2. Memory tools proxy to cloud in cloud-only mode
+3. Shared KG accessible from any client
+4. No local persistence needed (cloud as source of truth)
+
+**Timeline**: Long-term (no ETA yet)
+
+**Related Issues**: [#73](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/73), [#76](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/76), [#77](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/77)
+
+## Troubleshooting
+
+### MCP Server Doesn't Start
+
+**Symptom**: No memesh tools appear in Claude Desktop
+
+**Cause**: Server failed to initialize (check logs)
+
+**Solution**:
+1. Check MCP server logs in Claude Desktop
+2. Verify MEMESH_API_KEY is set if using cloud sync
+3. Ensure plugin is enabled in Settings → Plugins
+
+### Memory Tools Return Errors
+
+**Symptom**: "not available in cloud-only mode" errors
+
+**Expected Behavior**: This is normal in Cowork until cloud-first memory is implemented
+
+**Workaround**: Use CLI version for full memory functionality
+
+### Database Not Persisted Between Sessions
+
+**Symptom**: Local memories disappear after restarting Cowork
+
+**Cause**: `~/.memesh/` directory is ephemeral in Cowork
+
+**Solution**:
+- Current: This is expected behavior (no workaround)
+- Future: Cloud-first memory will solve this naturally
+
+## Recommendations
+
+### For Development Work
+
+**Use CLI Version** for full functionality:
+- Local Knowledge Graph
+- All memory tools
+- Embeddings & vector search
+- Optional cloud sync for backup
+
+### For Quick Tasks in Cowork
+
+**Use Cloud-Only Mode** if you just need:
+- Basic commands (buddy-help, list-skills)
+- Cloud sync functionality
+- Don't need memory tools
+
+### For Production Use
+
+**CLI is Recommended** until cloud-first memory is implemented.
+
+## Getting Help
+
+- **Bug Reports**: [Create an issue](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?template=bug_report.yml)
+- **Feature Requests**: [Request a feature](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new?template=feature_request.yml)
+- **Questions**: [Start a discussion](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
+
+When reporting Cowork-specific issues, select **"Claude Desktop (Cowork)"** in the Client dropdown.
+
+---
+
+**Last Updated**: 2026-02-16
+**Status**: Partial support (cloud-only mode functional, memory tools disabled)