docs: comprehensive v5.1.2 documentation update
This commit brings all documentation up to date with the current v5.1.2 codebase, addressing 12+ critical discrepancies and adding 2 major new documentation files. ## Files Modified (18 documentation files): ### Root Documentation: - README.md: Updated version badge (4.3.1 → 5.1.2), tool count (7 → 9), added viewer UI and theme toggle features, updated "What's New" section - CHANGELOG.md: Added 8 missing releases (v4.3.2 through v5.1.2) with comprehensive release notes - CLAUDE.md: Removed hardcoded personal paths, documented all 14 worker endpoints (was 8), added Chroma integration overview, updated v5.x releases ### Mintlify Documentation (docs/): - introduction.mdx: Updated search tool count to 9, added viewer UI and theme toggle to features - configuration.mdx: Added smart-install.js documentation, clarified data directory locations, added CLAUDE_CODE_PATH env var, explained observations vs sessions, updated hook configuration examples - development.mdx: Added comprehensive viewer UI development section (103 lines), updated build output filenames (search-server.mjs) - usage/search-tools.mdx: Added get_context_timeline and get_timeline_by_query documentation with examples, updated tool count to 9 - architecture/overview.mdx: Updated to 7 hook files, 9 search tools, added Chroma to tech stack, enhanced component details with viewer UI - architecture/hooks.mdx: Added smart-install.js and user-message-hook.js documentation, updated hook count to 7 - architecture/worker-service.mdx: Documented all 14 endpoints organized by category (Viewer & Health, Data Retrieval, Settings, Session Management) - architecture/mcp-search.mdx: Added timeline tools documentation, updated tool count to 9, fixed filename references (search-server.mjs) - architecture-evolution.mdx: Added complete v5.x release history (v5.0.0 through v5.1.2), updated title to "v3 to v5" - hooks-architecture.mdx: Updated to "Seven Hook Scripts", added smart-install and user-message-hook documentation - troubleshooting.mdx: Added v5.x specific issues section (viewer, theme toggle, SSE, Chroma, PM2 Windows fix) ### New Documentation Files: - docs/VIEWER.md: Complete 400+ line guide to web viewer UI including architecture, features, usage, development, API integration, performance considerations - docs/CHROMA.md: Complete 450+ line guide to vector database integration including hybrid search architecture, semantic search explanation, performance benchmarks, installation, configuration, troubleshooting ## Key Corrections Made: 1. ✅ Updated version badges and references: 4.3.1 → 5.1.2 2. ✅ Corrected search tool count: 7 → 9 (added get_context_timeline, get_timeline_by_query) 3. ✅ Fixed MCP server filename: search-server.js → search-server.mjs 4. ✅ Updated hook count: 5 → 7 (added smart-install.js, user-message-hook.js) 5. ✅ Documented all 14 worker endpoints (was 8, incorrectly claimed 6 were missing) 6. ✅ Removed hardcoded personal file paths 7. ✅ Added Chroma vector database documentation 8. ✅ Added viewer UI comprehensive documentation 9. ✅ Updated CHANGELOG with all missing v4.3.2-v5.1.2 releases 10. ✅ Clarified data directory locations (production vs development) 11. ✅ Added smart-install.js caching system documentation 12. ✅ Updated SessionStart hook configuration examples ## Documentation Statistics: - Total files modified: 18 - New files created: 2 - Lines added: ~2,000+ - Version mismatches fixed: 2 critical - Missing features documented: 5+ major - Missing tools documented: 2 MCP tools - Missing endpoints documented: 6 API endpoints ## Impact: Documentation now accurately reflects the current v5.1.2 codebase with: - Complete viewer UI documentation (v5.1.0) - Theme toggle feature (v5.1.2) - Hybrid search architecture with Chroma (v5.0.0) - Smart install caching (v5.0.3) - All 7 hook scripts documented - All 9 MCP search tools documented - All 14 worker service endpoints documented - Comprehensive troubleshooting for v5.x issues 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alex Newman
@@ -5,6 +5,177 @@ description: "Common issues and solutions for Claude-Mem"
|
||||
|
||||
# Troubleshooting Guide
|
||||
|
||||
## v5.x Specific Issues
|
||||
|
||||
### Viewer UI Not Loading
|
||||
|
||||
**Symptoms**: Cannot access http://localhost:37777, page doesn't load, or shows connection error.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check if worker is running on port 37777:
|
||||
```bash
|
||||
lsof -i :37777
|
||||
# or
|
||||
npm run worker:status
|
||||
```
|
||||
|
||||
2. Verify worker is healthy:
|
||||
```bash
|
||||
curl http://localhost:37777/health
|
||||
```
|
||||
|
||||
3. Check worker logs for errors:
|
||||
```bash
|
||||
npm run worker:logs
|
||||
```
|
||||
|
||||
4. Restart worker service:
|
||||
```bash
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
5. Check for port conflicts:
|
||||
```bash
|
||||
# If port 37777 is in use by another service
|
||||
export CLAUDE_MEM_WORKER_PORT=38000
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
### Theme Toggle Not Persisting
|
||||
|
||||
**Symptoms**: Theme preference (light/dark mode) resets after browser refresh.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check browser localStorage is enabled:
|
||||
```javascript
|
||||
// In browser console
|
||||
localStorage.getItem('claude-mem-settings')
|
||||
```
|
||||
|
||||
2. Verify settings endpoint is working:
|
||||
```bash
|
||||
curl http://localhost:37777/api/settings
|
||||
```
|
||||
|
||||
3. Clear localStorage and try again:
|
||||
```javascript
|
||||
// In browser console
|
||||
localStorage.removeItem('claude-mem-settings')
|
||||
```
|
||||
|
||||
4. Check for browser privacy mode (blocks localStorage)
|
||||
|
||||
### SSE Connection Issues
|
||||
|
||||
**Symptoms**: Viewer shows "Disconnected" status, updates not appearing in real-time.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check SSE endpoint is accessible:
|
||||
```bash
|
||||
curl -N http://localhost:37777/stream
|
||||
```
|
||||
|
||||
2. Check browser console for errors:
|
||||
- Open DevTools (F12)
|
||||
- Look for EventSource errors
|
||||
- Check Network tab for failed /stream requests
|
||||
|
||||
3. Verify worker is running:
|
||||
```bash
|
||||
npm run worker:status
|
||||
```
|
||||
|
||||
4. Check for network/proxy issues blocking SSE
|
||||
- Corporate firewalls may block SSE
|
||||
- Try disabling VPN temporarily
|
||||
|
||||
5. Restart worker and refresh browser:
|
||||
```bash
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
### Chroma/Python Dependency Issues (v5.0.0+)
|
||||
|
||||
**Symptoms**: Installation fails with chromadb or Python-related errors.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Verify Python 3.8+ is installed:
|
||||
```bash
|
||||
python --version
|
||||
# or
|
||||
python3 --version
|
||||
```
|
||||
|
||||
2. Install chromadb manually:
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack
|
||||
npm install chromadb
|
||||
```
|
||||
|
||||
3. Check chromadb health:
|
||||
```bash
|
||||
npm run chroma:health
|
||||
```
|
||||
|
||||
4. Windows-specific: Ensure Python is in PATH:
|
||||
```bash
|
||||
where python
|
||||
# Should show Python installation path
|
||||
```
|
||||
|
||||
5. If Chroma continues to fail, hybrid search will gracefully degrade to SQLite FTS5 only
|
||||
|
||||
### Smart Install Caching Issues (v5.0.3+)
|
||||
|
||||
**Symptoms**: Dependencies not updating after plugin update, stale version marker.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Clear install cache:
|
||||
```bash
|
||||
rm ~/.claude/plugins/marketplaces/thedotmack/.install-version
|
||||
```
|
||||
|
||||
2. Force reinstall:
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack
|
||||
npm install --force
|
||||
```
|
||||
|
||||
3. Check version marker:
|
||||
```bash
|
||||
cat ~/.claude/plugins/marketplaces/thedotmack/.install-version
|
||||
cat ~/.claude/plugins/marketplaces/thedotmack/package.json | grep version
|
||||
```
|
||||
|
||||
4. Restart Claude Code after manual install
|
||||
|
||||
### PM2 ENOENT Error on Windows (v5.1.1 Fix)
|
||||
|
||||
**Symptoms**: Worker fails to start with "ENOENT" error on Windows.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. This was fixed in v5.1.1 - update to latest version:
|
||||
```bash
|
||||
/plugin update claude-mem
|
||||
```
|
||||
|
||||
2. If still experiencing issues, verify PM2 path:
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack
|
||||
dir node_modules\.bin\pm2.cmd
|
||||
```
|
||||
|
||||
3. Manual PM2 install if needed:
|
||||
```bash
|
||||
npm install pm2@latest
|
||||
```
|
||||
|
||||
## Worker Service Issues
|
||||
|
||||
### Worker Service Not Starting
|
||||
|
||||
Reference in New Issue
Block a user