Remove outdated troubleshooting documentation for database, diagnostics, reference, and worker operations in claude-mem plugin.
This commit is contained in:
Alex Newman
@@ -1,89 +0,0 @@
|
||||
---
|
||||
name: troubleshoot
|
||||
description: Diagnose and fix claude-mem installation issues. Checks worker status, database integrity, service health, dependencies, and provides automated fixes for common problems.
|
||||
---
|
||||
|
||||
# Claude-Mem Troubleshooting Skill
|
||||
|
||||
Diagnose and resolve installation and operational issues with the claude-mem plugin.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Invoke this skill when:**
|
||||
- Memory not persisting after `/clear`
|
||||
- Viewer UI empty or not loading
|
||||
- Worker service not running
|
||||
- Database missing or corrupted
|
||||
- Port conflicts
|
||||
- Missing dependencies
|
||||
- "Nothing is remembered" complaints
|
||||
- Search results empty when they shouldn't be
|
||||
|
||||
**Do NOT invoke** for feature requests or usage questions (use regular documentation for that).
|
||||
|
||||
## Quick Decision Guide
|
||||
|
||||
Once the skill is loaded, choose the appropriate operation:
|
||||
|
||||
**What's the problem?**
|
||||
|
||||
- "Nothing is being remembered" → [operations/common-issues.md](operations/common-issues.md#nothing-remembered)
|
||||
- "Viewer is empty" → [operations/common-issues.md](operations/common-issues.md#viewer-empty)
|
||||
- "Worker won't start" → [operations/common-issues.md](operations/common-issues.md#worker-not-starting)
|
||||
- "Want to run full diagnostics" → [operations/diagnostics.md](operations/diagnostics.md)
|
||||
- "Need automated fix" → [operations/automated-fixes.md](operations/automated-fixes.md)
|
||||
|
||||
## Available Operations
|
||||
|
||||
Choose the appropriate operation file for detailed instructions:
|
||||
|
||||
### Diagnostic Workflows
|
||||
1. **[Full System Diagnostics](operations/diagnostics.md)** - Comprehensive step-by-step diagnostic workflow
|
||||
2. **[Worker Diagnostics](operations/worker.md)** - Bun worker-specific troubleshooting
|
||||
3. **[Database Diagnostics](operations/database.md)** - Database integrity and data checks
|
||||
|
||||
### Issue Resolution
|
||||
4. **[Common Issues](operations/common-issues.md)** - Quick fixes for frequently encountered problems
|
||||
5. **[Automated Fixes](operations/automated-fixes.md)** - One-command fix sequences
|
||||
|
||||
### Reference
|
||||
6. **[Quick Commands](operations/reference.md)** - Essential commands for troubleshooting
|
||||
|
||||
## Quick Start
|
||||
|
||||
**Fast automated fix (try this first):**
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/ && \
|
||||
npm run worker:stop; \
|
||||
npm install && \
|
||||
npm run worker:start && \
|
||||
sleep 3 && \
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
```
|
||||
|
||||
Expected output: `{"status":"ok"}`
|
||||
|
||||
If that doesn't work, proceed to detailed diagnostics.
|
||||
|
||||
## Response Format
|
||||
|
||||
When troubleshooting:
|
||||
1. **Identify the symptom** - What's the user reporting?
|
||||
2. **Choose operation file** - Use the decision guide above
|
||||
3. **Follow steps systematically** - Don't skip diagnostic steps
|
||||
4. **Report findings** - Tell user what you found and what was fixed
|
||||
5. **Verify resolution** - Confirm the issue is resolved
|
||||
|
||||
## Technical Notes
|
||||
|
||||
- **Worker port:** Default 37777 (configurable via `CLAUDE_MEM_WORKER_PORT`)
|
||||
- **Database location:** `~/.claude-mem/claude-mem.db`
|
||||
- **Plugin location:** `~/.claude/plugins/marketplaces/thedotmack/`
|
||||
- **Worker PID file:** `~/.claude-mem/worker.pid`
|
||||
|
||||
## Error Reporting
|
||||
|
||||
If troubleshooting doesn't resolve the issue, collect diagnostic data and direct user to:
|
||||
https://github.com/thedotmack/claude-mem/issues
|
||||
|
||||
See [operations/diagnostics.md](operations/diagnostics.md#reporting-issues) for details on what to collect.
|
||||
@@ -1,206 +0,0 @@
|
||||
# Automated Fix Sequences
|
||||
|
||||
One-command fix sequences for common claude-mem issues.
|
||||
|
||||
## Quick Fix: Complete Reset and Restart
|
||||
|
||||
**Use when:** General issues, worker not responding, after updates
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/ && \
|
||||
npm run worker:stop; \
|
||||
npm install && \
|
||||
npm run worker:start && \
|
||||
sleep 3 && \
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
```
|
||||
|
||||
**Expected output:** `{"status":"ok"}`
|
||||
|
||||
**What it does:**
|
||||
1. Stops the worker (if running)
|
||||
2. Ensures dependencies are installed
|
||||
3. Starts worker
|
||||
4. Waits for startup
|
||||
5. Verifies health
|
||||
|
||||
## Fix: Worker Not Running
|
||||
|
||||
**Use when:** Worker status shows it's not running
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/ && \
|
||||
npm run worker:start && \
|
||||
sleep 2 && \
|
||||
npm run worker:status
|
||||
```
|
||||
|
||||
**Expected output:** Worker running with PID and health OK
|
||||
|
||||
## Fix: Dependencies Missing
|
||||
|
||||
**Use when:** Worker won't start due to missing packages
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/ && \
|
||||
npm install && \
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
## Fix: Stale PID File
|
||||
|
||||
**Use when:** Worker reports running but health check fails
|
||||
|
||||
```bash
|
||||
rm -f ~/.claude-mem/worker.pid && \
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/ && \
|
||||
npm run worker:start && \
|
||||
sleep 2 && \
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
```
|
||||
|
||||
**Expected output:** `{"status":"ok"}`
|
||||
|
||||
## Fix: Port Conflict
|
||||
|
||||
**Use when:** Error shows port already in use
|
||||
|
||||
```bash
|
||||
# Change to port 37778
|
||||
mkdir -p ~/.claude-mem && \
|
||||
echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json && \
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/ && \
|
||||
npm run worker:restart && \
|
||||
sleep 2 && \
|
||||
curl -s http://127.0.0.1:37778/health
|
||||
```
|
||||
|
||||
**Expected output:** `{"status":"ok"}`
|
||||
|
||||
## Fix: Database Issues
|
||||
|
||||
**Use when:** Database appears corrupted or out of sync
|
||||
|
||||
```bash
|
||||
# Backup and test integrity
|
||||
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup && \
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;" && \
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/ && \
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
**If integrity check fails, recreate database:**
|
||||
```bash
|
||||
# WARNING: This deletes all memory data
|
||||
mv ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.old && \
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/ && \
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
## Fix: Clean Reinstall
|
||||
|
||||
**Use when:** All else fails, nuclear option
|
||||
|
||||
```bash
|
||||
# Backup data first
|
||||
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup 2>/dev/null
|
||||
|
||||
# Stop worker
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:stop
|
||||
|
||||
# Clean PID file
|
||||
rm -f ~/.claude-mem/worker.pid
|
||||
|
||||
# Reinstall dependencies
|
||||
rm -rf node_modules && \
|
||||
npm install
|
||||
|
||||
# Start worker
|
||||
npm run worker:start && \
|
||||
sleep 3 && \
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
```
|
||||
|
||||
## Fix: Clear Old Logs
|
||||
|
||||
**Use when:** Want to start with fresh logs
|
||||
|
||||
```bash
|
||||
# Archive old logs
|
||||
tar -czf ~/.claude-mem/logs-archive-$(date +%Y-%m-%d).tar.gz ~/.claude-mem/logs/*.log 2>/dev/null
|
||||
|
||||
# Remove logs older than 7 days
|
||||
find ~/.claude-mem/logs/ -name "worker-*.log" -mtime +7 -delete
|
||||
|
||||
# Restart worker for fresh log
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
**Note:** Logs auto-rotate daily, manual cleanup rarely needed.
|
||||
|
||||
## Verification Commands
|
||||
|
||||
**After running any fix, verify with these:**
|
||||
|
||||
```bash
|
||||
# Check worker status
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:status
|
||||
|
||||
# Check health
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
|
||||
# Check database
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
|
||||
|
||||
# Check viewer
|
||||
curl -s http://127.0.0.1:37777/api/stats
|
||||
|
||||
# Check logs for errors
|
||||
grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -20
|
||||
```
|
||||
|
||||
**All checks should pass:**
|
||||
- Worker status: Shows PID and "Health: OK"
|
||||
- Health endpoint: `{"status":"ok"}`
|
||||
- Database: Shows count (may be 0 if new)
|
||||
- Stats: Returns JSON with counts
|
||||
- Logs: No recent errors
|
||||
|
||||
## One-Line Complete Diagnostic
|
||||
|
||||
**Quick health check:**
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/ && npm run worker:status && curl -s http://127.0.0.1:37777/health && echo " ✓ All systems OK"
|
||||
```
|
||||
|
||||
## Troubleshooting the Fixes
|
||||
|
||||
**If automated fix fails:**
|
||||
1. Run the diagnostic script from [diagnostics.md](diagnostics.md)
|
||||
2. Check specific error in worker logs:
|
||||
```bash
|
||||
tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
```
|
||||
3. Try manual worker start to see detailed error:
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
bun plugin/scripts/worker-service.js
|
||||
```
|
||||
4. Use the bug report tool:
|
||||
```bash
|
||||
npm run bug-report
|
||||
```
|
||||
|
||||
## Common Error Patterns and Fixes
|
||||
|
||||
| Error Pattern | Likely Cause | Quick Fix |
|
||||
|---------------|--------------|-----------|
|
||||
| `EADDRINUSE` | Port conflict | Change port in settings.json |
|
||||
| `SQLITE_ERROR` | Database corruption | Run integrity check, recreate if needed |
|
||||
| `ENOENT` | Missing files | Run `npm install` |
|
||||
| `Module not found` | Dependency issue | Clean reinstall |
|
||||
| Connection refused | Worker not running | `npm run worker:start` |
|
||||
| Stale PID | Old PID file | Remove `~/.claude-mem/worker.pid` |
|
||||
@@ -1,237 +0,0 @@
|
||||
# Common Issue Resolutions
|
||||
|
||||
Quick fixes for frequently encountered claude-mem problems.
|
||||
|
||||
## Issue: Nothing is Remembered After `/clear` {#nothing-remembered}
|
||||
|
||||
**Symptoms:**
|
||||
- Data doesn't persist across sessions
|
||||
- Context is empty after `/clear`
|
||||
- Search returns no results for past work
|
||||
|
||||
**Root cause:** Sessions are marked complete but data should persist. This suggests:
|
||||
- Worker not processing observations
|
||||
- Database not being written to
|
||||
- Context hook not reading from database
|
||||
|
||||
**Fix:**
|
||||
1. Verify worker is running:
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:status
|
||||
```
|
||||
|
||||
2. Check database has recent observations:
|
||||
```bash
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations WHERE created_at > datetime('now', '-1 day');"
|
||||
```
|
||||
|
||||
3. Restart worker and start new session:
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
4. Create a test observation: `/skill version-bump` then cancel
|
||||
|
||||
5. Check if observation appears in viewer:
|
||||
```bash
|
||||
open http://127.0.0.1:37777
|
||||
# Or manually check database:
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM observations ORDER BY created_at DESC LIMIT 1;"
|
||||
```
|
||||
|
||||
## Issue: Viewer Empty After Every Claude Restart {#viewer-empty}
|
||||
|
||||
**Symptoms:**
|
||||
- Viewer shows no data at http://127.0.0.1:37777
|
||||
- Stats endpoint returns all zeros
|
||||
- Database appears empty in UI
|
||||
|
||||
**Root cause:**
|
||||
- Database being recreated on startup (shouldn't happen)
|
||||
- Worker reading from wrong database location
|
||||
- Database permissions issue
|
||||
|
||||
**Fix:**
|
||||
1. Check database file exists and has data:
|
||||
```bash
|
||||
ls -lh ~/.claude-mem/claude-mem.db
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
|
||||
```
|
||||
|
||||
2. Check file permissions:
|
||||
```bash
|
||||
ls -la ~/.claude-mem/claude-mem.db
|
||||
# Should be readable/writable by your user
|
||||
```
|
||||
|
||||
3. Verify worker is using correct database path in logs:
|
||||
```bash
|
||||
grep "Database" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
```
|
||||
|
||||
4. Test viewer connection manually:
|
||||
```bash
|
||||
curl -s http://127.0.0.1:37777/api/stats
|
||||
# Should show non-zero counts if data exists
|
||||
```
|
||||
|
||||
## Issue: Old Memory in Claude {#old-memory}
|
||||
|
||||
**Symptoms:**
|
||||
- Context contains outdated observations
|
||||
- Irrelevant past work appearing in sessions
|
||||
- Context feels stale
|
||||
|
||||
**Root cause:** Context hook injecting stale observations
|
||||
|
||||
**Fix:**
|
||||
1. Check the observation count setting:
|
||||
```bash
|
||||
grep CLAUDE_MEM_CONTEXT_OBSERVATIONS ~/.claude-mem/settings.json
|
||||
```
|
||||
|
||||
2. Default is 50 observations - you can adjust this:
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"CLAUDE_MEM_CONTEXT_OBSERVATIONS": "25"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Check database for actual observation dates:
|
||||
```bash
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT created_at, project, title FROM observations ORDER BY created_at DESC LIMIT 10;"
|
||||
```
|
||||
|
||||
4. Consider filtering by project if working on multiple codebases
|
||||
|
||||
## Issue: Worker Not Starting {#worker-not-starting}
|
||||
|
||||
**Symptoms:**
|
||||
- Worker status shows not running or error
|
||||
- Health check fails
|
||||
- Viewer not accessible
|
||||
|
||||
**Root cause:**
|
||||
- Port already in use
|
||||
- Bun not installed
|
||||
- Missing dependencies
|
||||
|
||||
**Fix:**
|
||||
1. Try manual worker start to see error:
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
bun plugin/scripts/worker-service.js
|
||||
# Should start server on port 37777 or show error
|
||||
```
|
||||
|
||||
2. If port in use, change it:
|
||||
```bash
|
||||
mkdir -p ~/.claude-mem
|
||||
echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
|
||||
```
|
||||
|
||||
3. If dependencies missing:
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm install
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
## Issue: Search Results Empty
|
||||
|
||||
**Symptoms:**
|
||||
- Search skill returns no results
|
||||
- API endpoints return empty arrays
|
||||
- Know there's data but can't find it
|
||||
|
||||
**Root cause:**
|
||||
- FTS5 tables not synchronized
|
||||
- Wrong project filter
|
||||
- Database not being queried correctly
|
||||
|
||||
**Fix:**
|
||||
1. Check if observations exist in database:
|
||||
```bash
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
|
||||
```
|
||||
|
||||
2. Check FTS5 table sync:
|
||||
```bash
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations_fts;"
|
||||
# Should match observation count
|
||||
```
|
||||
|
||||
3. Try search via API directly:
|
||||
```bash
|
||||
curl "http://127.0.0.1:37777/api/search/observations?q=test&format=index"
|
||||
```
|
||||
|
||||
4. If FTS5 out of sync, restart worker (triggers reindex):
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
## Issue: Port Conflicts
|
||||
|
||||
**Symptoms:**
|
||||
- Worker won't start
|
||||
- Error: "EADDRINUSE: address already in use"
|
||||
- Health check fails
|
||||
|
||||
**Fix:**
|
||||
1. Check what's using port 37777:
|
||||
```bash
|
||||
lsof -i :37777
|
||||
```
|
||||
|
||||
2. Either kill the conflicting process or change claude-mem port:
|
||||
```bash
|
||||
mkdir -p ~/.claude-mem
|
||||
echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
## Issue: Database Corrupted
|
||||
|
||||
**Symptoms:**
|
||||
- SQLite errors in logs
|
||||
- Worker crashes on startup
|
||||
- Queries fail
|
||||
|
||||
**Fix:**
|
||||
1. Backup the database:
|
||||
```bash
|
||||
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
|
||||
```
|
||||
|
||||
2. Try to repair:
|
||||
```bash
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
|
||||
```
|
||||
|
||||
3. If repair fails, recreate (loses data):
|
||||
```bash
|
||||
rm ~/.claude-mem/claude-mem.db
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:restart
|
||||
# Worker will create new database
|
||||
```
|
||||
|
||||
## Prevention Tips
|
||||
|
||||
**Keep claude-mem healthy:**
|
||||
- Regularly check viewer UI to see if observations are being captured
|
||||
- Monitor database size (shouldn't grow unbounded)
|
||||
- Update plugin when new versions are released
|
||||
- Keep Claude Code updated
|
||||
|
||||
**Performance tuning:**
|
||||
- Adjust `CLAUDE_MEM_CONTEXT_OBSERVATIONS` if context is too large/small
|
||||
- Use `/clear` to mark sessions complete and start fresh
|
||||
- Use search skill to query specific memories instead of loading everything
|
||||
@@ -1,409 +0,0 @@
|
||||
# Database Diagnostics
|
||||
|
||||
SQLite database troubleshooting for claude-mem.
|
||||
|
||||
## Database Overview
|
||||
|
||||
Claude-mem uses SQLite3 for persistent storage:
|
||||
- **Location:** `~/.claude-mem/claude-mem.db`
|
||||
- **Library:** bun:sqlite (native Bun SQLite, synchronous)
|
||||
- **Features:** FTS5 full-text search, triggers, indexes
|
||||
- **Tables:** observations, sessions, user_prompts, observations_fts, sessions_fts, prompts_fts
|
||||
|
||||
## Basic Database Checks
|
||||
|
||||
### Check Database Exists
|
||||
|
||||
```bash
|
||||
# Check file exists
|
||||
ls -lh ~/.claude-mem/claude-mem.db
|
||||
|
||||
# Check file size
|
||||
du -h ~/.claude-mem/claude-mem.db
|
||||
|
||||
# Check permissions
|
||||
ls -la ~/.claude-mem/claude-mem.db
|
||||
```
|
||||
|
||||
**Expected:**
|
||||
- File exists
|
||||
- Size: 100KB - 10MB+ (depends on usage)
|
||||
- Permissions: Readable/writable by your user
|
||||
|
||||
### Check Database Integrity
|
||||
|
||||
```bash
|
||||
# Run integrity check
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
|
||||
```
|
||||
|
||||
**Expected output:** `ok`
|
||||
|
||||
**If errors appear:**
|
||||
- Database corrupted
|
||||
- Backup immediately: `cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup`
|
||||
- Consider recreating (data loss)
|
||||
|
||||
## Data Inspection
|
||||
|
||||
### Count Records
|
||||
|
||||
```bash
|
||||
# Observation count
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
|
||||
|
||||
# Session count
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM sessions;"
|
||||
|
||||
# User prompt count
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM user_prompts;"
|
||||
|
||||
# FTS5 table counts (should match main tables)
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations_fts;"
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM sessions_fts;"
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM prompts_fts;"
|
||||
```
|
||||
|
||||
### View Recent Records
|
||||
|
||||
```bash
|
||||
# Recent observations
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT
|
||||
created_at,
|
||||
type,
|
||||
title,
|
||||
project
|
||||
FROM observations
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 10;
|
||||
"
|
||||
|
||||
# Recent sessions
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT
|
||||
created_at,
|
||||
request,
|
||||
project
|
||||
FROM sessions
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 5;
|
||||
"
|
||||
|
||||
# Recent user prompts
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT
|
||||
created_at,
|
||||
prompt
|
||||
FROM user_prompts
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 10;
|
||||
"
|
||||
```
|
||||
|
||||
### Check Projects
|
||||
|
||||
```bash
|
||||
# List all projects
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT DISTINCT project
|
||||
FROM observations
|
||||
ORDER BY project;
|
||||
"
|
||||
|
||||
# Count observations per project
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT
|
||||
project,
|
||||
COUNT(*) as count
|
||||
FROM observations
|
||||
GROUP BY project
|
||||
ORDER BY count DESC;
|
||||
"
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
|
||||
### View Table Structure
|
||||
|
||||
```bash
|
||||
# List all tables
|
||||
sqlite3 ~/.claude-mem/claude-mem.db ".tables"
|
||||
|
||||
# Show observations table schema
|
||||
sqlite3 ~/.claude-mem/claude-mem.db ".schema observations"
|
||||
|
||||
# Show all schemas
|
||||
sqlite3 ~/.claude-mem/claude-mem.db ".schema"
|
||||
```
|
||||
|
||||
### Expected Tables
|
||||
|
||||
- `observations` - Main observation records
|
||||
- `observations_fts` - FTS5 virtual table for full-text search
|
||||
- `sessions` - Session summary records
|
||||
- `sessions_fts` - FTS5 virtual table for session search
|
||||
- `user_prompts` - User prompt records
|
||||
- `prompts_fts` - FTS5 virtual table for prompt search
|
||||
|
||||
## FTS5 Synchronization
|
||||
|
||||
The FTS5 tables should stay synchronized with main tables via triggers.
|
||||
|
||||
### Check FTS5 Sync
|
||||
|
||||
```bash
|
||||
# Compare counts
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT
|
||||
(SELECT COUNT(*) FROM observations) as observations,
|
||||
(SELECT COUNT(*) FROM observations_fts) as observations_fts,
|
||||
(SELECT COUNT(*) FROM sessions) as sessions,
|
||||
(SELECT COUNT(*) FROM sessions_fts) as sessions_fts,
|
||||
(SELECT COUNT(*) FROM user_prompts) as prompts,
|
||||
(SELECT COUNT(*) FROM prompts_fts) as prompts_fts;
|
||||
"
|
||||
```
|
||||
|
||||
**Expected:** All pairs should match (observations = observations_fts, etc.)
|
||||
|
||||
### Fix FTS5 Desync
|
||||
|
||||
If FTS5 counts don't match, triggers may have failed. Restart worker to rebuild:
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
The worker will rebuild FTS5 indexes on startup if they're out of sync.
|
||||
|
||||
## Common Database Issues
|
||||
|
||||
### Issue: Database Doesn't Exist
|
||||
|
||||
**Cause:** First run, or database was deleted
|
||||
|
||||
**Fix:** Database will be created automatically on first observation. No action needed.
|
||||
|
||||
### Issue: Database is Empty (0 Records)
|
||||
|
||||
**Cause:**
|
||||
- New installation (normal)
|
||||
- Data was deleted
|
||||
- Worker not processing observations
|
||||
|
||||
**Fix:**
|
||||
1. Create test observation (use any skill and cancel)
|
||||
2. Check worker logs for errors:
|
||||
```bash
|
||||
tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
```
|
||||
3. Verify observation appears in database
|
||||
|
||||
### Issue: Database Permission Denied
|
||||
|
||||
**Cause:** File permissions wrong, database owned by different user
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check ownership
|
||||
ls -la ~/.claude-mem/claude-mem.db
|
||||
|
||||
# Fix permissions (if needed)
|
||||
chmod 644 ~/.claude-mem/claude-mem.db
|
||||
chown $USER ~/.claude-mem/claude-mem.db
|
||||
```
|
||||
|
||||
### Issue: Database Locked
|
||||
|
||||
**Cause:**
|
||||
- Multiple processes accessing database
|
||||
- Crash left lock file
|
||||
- Long-running transaction
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
# Check for lock file
|
||||
ls -la ~/.claude-mem/claude-mem.db-wal
|
||||
ls -la ~/.claude-mem/claude-mem.db-shm
|
||||
|
||||
# Remove lock files (only if worker is stopped!)
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:stop
|
||||
rm ~/.claude-mem/claude-mem.db-wal ~/.claude-mem/claude-mem.db-shm
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
### Issue: Database Growing Too Large
|
||||
|
||||
**Cause:** Too many observations accumulated
|
||||
|
||||
**Check size:**
|
||||
```bash
|
||||
du -h ~/.claude-mem/claude-mem.db
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
|
||||
```
|
||||
|
||||
**Options:**
|
||||
1. Delete old observations (manual cleanup):
|
||||
```bash
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
DELETE FROM observations
|
||||
WHERE created_at < datetime('now', '-90 days');
|
||||
"
|
||||
```
|
||||
|
||||
2. Vacuum to reclaim space:
|
||||
```bash
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
|
||||
```
|
||||
|
||||
3. Archive and start fresh:
|
||||
```bash
|
||||
mv ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.archive
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
## Database Recovery
|
||||
|
||||
### Backup Database
|
||||
|
||||
**Before any destructive operations:**
|
||||
```bash
|
||||
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
|
||||
```
|
||||
|
||||
### Restore from Backup
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:stop
|
||||
cp ~/.claude-mem/claude-mem.db.backup ~/.claude-mem/claude-mem.db
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
### Export Data
|
||||
|
||||
Export to JSON for safekeeping:
|
||||
|
||||
```bash
|
||||
# Export observations
|
||||
sqlite3 ~/.claude-mem/claude-mem.db -json "SELECT * FROM observations;" > observations.json
|
||||
|
||||
# Export sessions
|
||||
sqlite3 ~/.claude-mem/claude-mem.db -json "SELECT * FROM sessions;" > sessions.json
|
||||
|
||||
# Export prompts
|
||||
sqlite3 ~/.claude-mem/claude-mem.db -json "SELECT * FROM user_prompts;" > prompts.json
|
||||
```
|
||||
|
||||
### Recreate Database
|
||||
|
||||
**WARNING: Data loss. Backup first!**
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
|
||||
# Stop worker
|
||||
npm run worker:stop
|
||||
|
||||
# Backup current database
|
||||
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.old
|
||||
|
||||
# Delete database
|
||||
rm ~/.claude-mem/claude-mem.db
|
||||
|
||||
# Start worker (creates new database)
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
## Database Statistics
|
||||
|
||||
### Storage Analysis
|
||||
|
||||
```bash
|
||||
# Database file size
|
||||
du -h ~/.claude-mem/claude-mem.db
|
||||
|
||||
# Record counts by type
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT
|
||||
type,
|
||||
COUNT(*) as count
|
||||
FROM observations
|
||||
GROUP BY type
|
||||
ORDER BY count DESC;
|
||||
"
|
||||
|
||||
# Observations per month
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT
|
||||
strftime('%Y-%m', created_at) as month,
|
||||
COUNT(*) as count
|
||||
FROM observations
|
||||
GROUP BY month
|
||||
ORDER BY month DESC;
|
||||
"
|
||||
|
||||
# Average observation size (characters)
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT
|
||||
AVG(LENGTH(content)) as avg_content_length,
|
||||
MAX(LENGTH(content)) as max_content_length
|
||||
FROM observations;
|
||||
"
|
||||
```
|
||||
|
||||
## Advanced Queries
|
||||
|
||||
### Find Specific Observations
|
||||
|
||||
```bash
|
||||
# Search by keyword (FTS5)
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT title, created_at
|
||||
FROM observations_fts
|
||||
WHERE observations_fts MATCH 'authentication'
|
||||
ORDER BY created_at DESC;
|
||||
"
|
||||
|
||||
# Find by type
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT title, created_at
|
||||
FROM observations
|
||||
WHERE type = 'bugfix'
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 10;
|
||||
"
|
||||
|
||||
# Find by file path
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
SELECT title, created_at
|
||||
FROM observations
|
||||
WHERE file_path LIKE '%auth%'
|
||||
ORDER BY created_at DESC;
|
||||
"
|
||||
```
|
||||
|
||||
## Database Maintenance
|
||||
|
||||
### Regular Maintenance Tasks
|
||||
|
||||
```bash
|
||||
# Analyze for query optimization
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "ANALYZE;"
|
||||
|
||||
# Rebuild FTS5 indexes
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "
|
||||
INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
|
||||
INSERT INTO sessions_fts(sessions_fts) VALUES('rebuild');
|
||||
INSERT INTO prompts_fts(prompts_fts) VALUES('rebuild');
|
||||
"
|
||||
|
||||
# Vacuum to reclaim space
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"
|
||||
```
|
||||
|
||||
**Run monthly to keep database healthy.**
|
||||
@@ -1,309 +0,0 @@
|
||||
# Full System Diagnostics
|
||||
|
||||
Comprehensive step-by-step diagnostic workflow for claude-mem issues.
|
||||
|
||||
## Diagnostic Workflow
|
||||
|
||||
Run these checks systematically to identify the root cause:
|
||||
|
||||
### 1. Check Worker Status
|
||||
|
||||
First, verify if the worker service is running:
|
||||
|
||||
```bash
|
||||
# Check worker status using npm script
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:status
|
||||
|
||||
# Or check health endpoint directly
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
```
|
||||
|
||||
**Expected output from npm run worker:status:**
|
||||
```
|
||||
✓ Worker is running (PID: 12345)
|
||||
Port: 37777
|
||||
Uptime: 45m
|
||||
Health: OK
|
||||
```
|
||||
|
||||
**Expected output from health endpoint:** `{"status":"ok"}`
|
||||
|
||||
**If worker not running:**
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
**If health endpoint fails but worker reports running:**
|
||||
Check for stale PID file:
|
||||
```bash
|
||||
cat ~/.claude-mem/worker.pid
|
||||
ps -p $(cat ~/.claude-mem/worker.pid 2>/dev/null | grep -o '"pid":[0-9]*' | grep -o '[0-9]*') 2>/dev/null || echo "Stale PID - worker not actually running"
|
||||
rm ~/.claude-mem/worker.pid
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
### 2. Check Worker Service Health
|
||||
|
||||
Test if the worker service responds to HTTP requests:
|
||||
|
||||
```bash
|
||||
# Default port is 37777
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
|
||||
# Check custom port from settings
|
||||
PORT=$(cat ~/.claude-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_WORKER_PORT | grep -o '[0-9]\+' || echo "37777")
|
||||
curl -s http://127.0.0.1:$PORT/health
|
||||
```
|
||||
|
||||
**Expected output:** `{"status":"ok"}`
|
||||
|
||||
**If connection refused:**
|
||||
- Worker not running → Go back to step 1
|
||||
- Port conflict → Check what's using the port:
|
||||
```bash
|
||||
lsof -i :37777 || netstat -tlnp | grep 37777
|
||||
```
|
||||
|
||||
### 3. Check Database
|
||||
|
||||
Verify the database exists and contains data:
|
||||
|
||||
```bash
|
||||
# Check if database file exists
|
||||
ls -lh ~/.claude-mem/claude-mem.db
|
||||
|
||||
# Check database size (should be > 0 bytes)
|
||||
du -h ~/.claude-mem/claude-mem.db
|
||||
|
||||
# Query database for observation count (requires sqlite3)
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) as observation_count FROM observations;" 2>&1
|
||||
|
||||
# Query for session count
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) as session_count FROM sessions;" 2>&1
|
||||
|
||||
# Check recent observations
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT created_at, type, title FROM observations ORDER BY created_at DESC LIMIT 5;" 2>&1
|
||||
```
|
||||
|
||||
**Expected:**
|
||||
- Database file exists (typically 100KB - 10MB+)
|
||||
- Contains observations and sessions
|
||||
- Recent observations visible
|
||||
|
||||
**If database missing or empty:**
|
||||
- New installation - this is normal, database will populate as you work
|
||||
- After `/clear` - sessions are marked complete but not deleted, data should persist
|
||||
- Corrupted database - backup and recreate:
|
||||
```bash
|
||||
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup
|
||||
# Worker will recreate on next observation
|
||||
```
|
||||
|
||||
### 4. Check Dependencies Installation
|
||||
|
||||
Verify all required npm packages are installed:
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
|
||||
# Check for critical packages
|
||||
ls node_modules/@anthropic-ai/claude-agent-sdk 2>&1 | head -1
|
||||
ls node_modules/express 2>&1 | head -1
|
||||
|
||||
# Check if Bun is available
|
||||
bun --version 2>&1
|
||||
```
|
||||
|
||||
**Expected:** All critical packages present, Bun installed
|
||||
|
||||
**If dependencies missing:**
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm install
|
||||
```
|
||||
|
||||
### 5. Check Worker Logs
|
||||
|
||||
Review recent worker logs for errors:
|
||||
|
||||
```bash
|
||||
# View logs using npm script
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:logs
|
||||
|
||||
# View today's log file directly
|
||||
cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Last 50 lines
|
||||
tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Check for specific errors
|
||||
grep -iE "error|exception|failed" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -20
|
||||
```
|
||||
|
||||
**Common error patterns to look for:**
|
||||
- `SQLITE_ERROR` - Database issues
|
||||
- `EADDRINUSE` - Port conflict
|
||||
- `ENOENT` - Missing files
|
||||
- `Module not found` - Dependency issues
|
||||
|
||||
### 6. Test Viewer UI
|
||||
|
||||
Check if the web viewer is accessible:
|
||||
|
||||
```bash
|
||||
# Test viewer endpoint
|
||||
curl -s http://127.0.0.1:37777/ | head -20
|
||||
|
||||
# Test stats endpoint
|
||||
curl -s http://127.0.0.1:37777/api/stats
|
||||
```
|
||||
|
||||
**Expected:**
|
||||
- `/` returns HTML page with React viewer
|
||||
- `/api/stats` returns JSON with database counts
|
||||
|
||||
### 7. Check Port Configuration
|
||||
|
||||
Verify port settings and availability:
|
||||
|
||||
```bash
|
||||
# Check if custom port is configured
|
||||
cat ~/.claude-mem/settings.json 2>/dev/null
|
||||
cat ~/.claude/settings.json 2>/dev/null
|
||||
|
||||
# Check what's listening on default port
|
||||
lsof -i :37777 2>&1 || netstat -tlnp 2>&1 | grep 37777
|
||||
|
||||
# Test connectivity
|
||||
nc -zv 127.0.0.1 37777 2>&1
|
||||
```
|
||||
|
||||
## Full System Diagnosis Script
|
||||
|
||||
Run this comprehensive diagnostic script to collect all information:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
echo "=== Claude-Mem Troubleshooting Report ==="
|
||||
echo ""
|
||||
echo "1. Environment"
|
||||
echo " OS: $(uname -s)"
|
||||
echo " Node version: $(node --version 2>/dev/null || echo 'N/A')"
|
||||
echo " Bun version: $(bun --version 2>/dev/null || echo 'N/A')"
|
||||
echo ""
|
||||
echo "2. Plugin Installation"
|
||||
echo " Plugin directory exists: $([ -d ~/.claude/plugins/marketplaces/thedotmack ] && echo 'YES' || echo 'NO')"
|
||||
echo " Package version: $(grep '"version"' ~/.claude/plugins/marketplaces/thedotmack/package.json 2>/dev/null | head -1)"
|
||||
echo ""
|
||||
echo "3. Database"
|
||||
echo " Database exists: $([ -f ~/.claude-mem/claude-mem.db ] && echo 'YES' || echo 'NO')"
|
||||
echo " Database size: $(du -h ~/.claude-mem/claude-mem.db 2>/dev/null | cut -f1)"
|
||||
echo " Observation count: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM observations;' 2>/dev/null || echo 'N/A')"
|
||||
echo " Session count: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM sessions;' 2>/dev/null || echo 'N/A')"
|
||||
echo ""
|
||||
echo "4. Worker Service"
|
||||
echo " Worker PID file: $([ -f ~/.claude-mem/worker.pid ] && echo 'EXISTS' || echo 'MISSING')"
|
||||
if [ -f ~/.claude-mem/worker.pid ]; then
|
||||
WORKER_PID=$(cat ~/.claude-mem/worker.pid 2>/dev/null | grep -o '"pid":[0-9]*' | grep -o '[0-9]*')
|
||||
echo " Worker PID: $WORKER_PID"
|
||||
echo " Process running: $(ps -p $WORKER_PID >/dev/null 2>&1 && echo 'YES' || echo 'NO (stale PID)')"
|
||||
fi
|
||||
echo " Health check: $(curl -s http://127.0.0.1:37777/health 2>/dev/null || echo 'FAILED')"
|
||||
echo ""
|
||||
echo "5. Configuration"
|
||||
echo " Port setting: $(cat ~/.claude-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_WORKER_PORT || echo 'default (37777)')"
|
||||
echo " Observation count: $(cat ~/.claude-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_CONTEXT_OBSERVATIONS || echo 'default (50)')"
|
||||
echo " Model: $(cat ~/.claude-mem/settings.json 2>/dev/null | grep CLAUDE_MEM_MODEL || echo 'default (claude-sonnet-4-5)')"
|
||||
echo ""
|
||||
echo "6. Recent Activity"
|
||||
echo " Latest observation: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT created_at FROM observations ORDER BY created_at DESC LIMIT 1;' 2>/dev/null || echo 'N/A')"
|
||||
echo " Latest session: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT created_at FROM sessions ORDER BY created_at DESC LIMIT 1;' 2>/dev/null || echo 'N/A')"
|
||||
echo ""
|
||||
echo "7. Logs"
|
||||
echo " Today's log file: $([ -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log ] && echo 'EXISTS' || echo 'MISSING')"
|
||||
echo " Log file size: $(du -h ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log 2>/dev/null | cut -f1 || echo 'N/A')"
|
||||
echo " Recent errors: $(grep -c -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log 2>/dev/null || echo '0')"
|
||||
echo ""
|
||||
echo "=== End Report ==="
|
||||
```
|
||||
|
||||
Save this as `/tmp/claude-mem-diagnostics.sh` and run:
|
||||
```bash
|
||||
bash /tmp/claude-mem-diagnostics.sh
|
||||
```
|
||||
|
||||
## Quick Diagnostic One-Liners
|
||||
|
||||
```bash
|
||||
# Full status check
|
||||
npm run worker:status && curl -s http://127.0.0.1:37777/health && echo " - All systems OK"
|
||||
|
||||
# Database stats
|
||||
echo "DB: $(du -h ~/.claude-mem/claude-mem.db | cut -f1) | Obs: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM observations;' 2>/dev/null) | Sessions: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM sessions;' 2>/dev/null)"
|
||||
|
||||
# Recent errors
|
||||
grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log 2>/dev/null | tail -5 || echo "No recent errors"
|
||||
|
||||
# Port check
|
||||
lsof -i :37777 || echo "Port 37777 is free"
|
||||
|
||||
# Worker process check
|
||||
ps aux | grep -E "bun.*worker-service" | grep -v grep || echo "Worker not running"
|
||||
```
|
||||
|
||||
## Automated Fix Sequence
|
||||
|
||||
If diagnostics show issues, run this automated fix sequence:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
echo "Running automated fix sequence..."
|
||||
|
||||
# 1. Stop worker if running
|
||||
echo "1. Stopping worker..."
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:stop
|
||||
|
||||
# 2. Clean stale PID if exists
|
||||
echo "2. Cleaning stale PID file..."
|
||||
rm -f ~/.claude-mem/worker.pid
|
||||
|
||||
# 3. Reinstall dependencies
|
||||
echo "3. Reinstalling dependencies..."
|
||||
npm install
|
||||
|
||||
# 4. Start worker
|
||||
echo "4. Starting worker..."
|
||||
npm run worker:start
|
||||
|
||||
# 5. Wait for startup
|
||||
echo "5. Waiting for worker to start..."
|
||||
sleep 3
|
||||
|
||||
# 6. Verify health
|
||||
echo "6. Verifying health..."
|
||||
curl -s http://127.0.0.1:37777/health || echo "Worker health check FAILED"
|
||||
|
||||
echo "Fix sequence complete!"
|
||||
```
|
||||
|
||||
## Reporting Issues
|
||||
|
||||
If troubleshooting doesn't resolve the issue, run the built-in bug report tool:
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run bug-report
|
||||
```
|
||||
|
||||
This will collect:
|
||||
1. Full diagnostic report
|
||||
2. Worker logs
|
||||
3. System information
|
||||
4. Configuration details
|
||||
5. Database stats
|
||||
|
||||
Post the generated report to: https://github.com/thedotmack/claude-mem/issues
|
||||
@@ -1,207 +0,0 @@
|
||||
# Quick Commands Reference
|
||||
|
||||
Essential commands for troubleshooting claude-mem.
|
||||
|
||||
## Worker Management
|
||||
|
||||
```bash
|
||||
# Check worker status
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:status
|
||||
|
||||
# Start worker
|
||||
npm run worker:start
|
||||
|
||||
# Restart worker
|
||||
npm run worker:restart
|
||||
|
||||
# Stop worker
|
||||
npm run worker:stop
|
||||
|
||||
# View logs
|
||||
npm run worker:logs
|
||||
|
||||
# View today's log file
|
||||
cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Last 50 lines
|
||||
tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Follow logs in real-time
|
||||
tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
```bash
|
||||
# Check worker health (default port)
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
|
||||
# Check viewer stats
|
||||
curl -s http://127.0.0.1:37777/api/stats
|
||||
|
||||
# Open viewer in browser
|
||||
open http://127.0.0.1:37777
|
||||
|
||||
# Test custom port
|
||||
PORT=37778
|
||||
curl -s http://127.0.0.1:$PORT/health
|
||||
```
|
||||
|
||||
## Database Queries
|
||||
|
||||
```bash
|
||||
# Observation count
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM observations;"
|
||||
|
||||
# Session count
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM sessions;"
|
||||
|
||||
# Recent observations
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT created_at, type, title FROM observations ORDER BY created_at DESC LIMIT 10;"
|
||||
|
||||
# Recent sessions
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT created_at, request FROM sessions ORDER BY created_at DESC LIMIT 5;"
|
||||
|
||||
# Database size
|
||||
du -h ~/.claude-mem/claude-mem.db
|
||||
|
||||
# Database integrity check
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
|
||||
|
||||
# Projects in database
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "SELECT DISTINCT project FROM observations ORDER BY project;"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
```bash
|
||||
# View current settings
|
||||
cat ~/.claude-mem/settings.json
|
||||
cat ~/.claude/settings.json
|
||||
|
||||
# Change worker port
|
||||
echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
|
||||
|
||||
# Change context observation count
|
||||
# Edit ~/.claude-mem/settings.json and add:
|
||||
{
|
||||
"CLAUDE_MEM_CONTEXT_OBSERVATIONS": "25"
|
||||
}
|
||||
|
||||
# Change AI model
|
||||
{
|
||||
"CLAUDE_MEM_MODEL": "claude-sonnet-4-5"
|
||||
}
|
||||
```
|
||||
|
||||
## Plugin Management
|
||||
|
||||
```bash
|
||||
# Navigate to plugin directory
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
|
||||
# Check plugin version
|
||||
grep '"version"' package.json
|
||||
|
||||
# Reinstall dependencies
|
||||
npm install
|
||||
|
||||
# View package.json
|
||||
cat package.json
|
||||
```
|
||||
|
||||
## Port Diagnostics
|
||||
|
||||
```bash
|
||||
# Check what's using port 37777
|
||||
lsof -i :37777
|
||||
netstat -tlnp | grep 37777
|
||||
|
||||
# Test port connectivity
|
||||
nc -zv 127.0.0.1 37777
|
||||
curl -v http://127.0.0.1:37777/health
|
||||
```
|
||||
|
||||
## Log Analysis
|
||||
|
||||
```bash
|
||||
# Search logs for errors
|
||||
grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Search for specific keyword
|
||||
grep "keyword" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Search across all log files
|
||||
grep -i "error" ~/.claude-mem/logs/worker-*.log
|
||||
|
||||
# Last 100 error lines
|
||||
grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -100
|
||||
|
||||
# Follow logs in real-time
|
||||
tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
```
|
||||
|
||||
## File Locations
|
||||
|
||||
```bash
|
||||
# Plugin directory
|
||||
~/.claude/plugins/marketplaces/thedotmack/
|
||||
|
||||
# Database
|
||||
~/.claude-mem/claude-mem.db
|
||||
|
||||
# Settings
|
||||
~/.claude-mem/settings.json
|
||||
~/.claude/settings.json
|
||||
|
||||
# Chroma vector database
|
||||
~/.claude-mem/chroma/
|
||||
|
||||
# Worker logs (daily rotation)
|
||||
~/.claude-mem/logs/worker-*.log
|
||||
|
||||
# Worker PID file
|
||||
~/.claude-mem/worker.pid
|
||||
```
|
||||
|
||||
## System Information
|
||||
|
||||
```bash
|
||||
# OS version
|
||||
uname -a
|
||||
|
||||
# Node version
|
||||
node --version
|
||||
|
||||
# NPM version
|
||||
npm --version
|
||||
|
||||
# Bun version
|
||||
bun --version
|
||||
|
||||
# SQLite version
|
||||
sqlite3 --version
|
||||
|
||||
# Check disk space
|
||||
df -h ~/.claude-mem/
|
||||
```
|
||||
|
||||
## One-Line Diagnostics
|
||||
|
||||
```bash
|
||||
# Full worker status check
|
||||
npm run worker:status && curl -s http://127.0.0.1:37777/health
|
||||
|
||||
# Quick health check
|
||||
curl -s http://127.0.0.1:37777/health && echo " - Worker is healthy"
|
||||
|
||||
# Database stats
|
||||
echo "Observations: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM observations;')" && echo "Sessions: $(sqlite3 ~/.claude-mem/claude-mem.db 'SELECT COUNT(*) FROM sessions;')"
|
||||
|
||||
# Recent errors
|
||||
grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -10
|
||||
|
||||
# Port check
|
||||
lsof -i :37777 || echo "Port 37777 is free"
|
||||
```
|
||||
@@ -1,362 +0,0 @@
|
||||
# Worker Service Diagnostics
|
||||
|
||||
Bun worker-specific troubleshooting for claude-mem.
|
||||
|
||||
## Worker Overview
|
||||
|
||||
The claude-mem worker is a persistent background service managed by Bun. It:
|
||||
- Runs Express.js server on port 37777 (default)
|
||||
- Processes observations asynchronously
|
||||
- Serves the viewer UI
|
||||
- Provides search API endpoints
|
||||
|
||||
## Check Worker Status
|
||||
|
||||
### Basic Status Check
|
||||
|
||||
```bash
|
||||
# Check worker status using npm script
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:status
|
||||
|
||||
# Or check health endpoint directly
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
```
|
||||
|
||||
**Expected npm run worker:status output:**
|
||||
```
|
||||
✓ Worker is running (PID: 12345)
|
||||
Port: 37777
|
||||
Uptime: 45m
|
||||
Health: OK
|
||||
```
|
||||
|
||||
**Expected health endpoint output:**
|
||||
```json
|
||||
{"status":"ok"}
|
||||
```
|
||||
|
||||
**Status indicators:**
|
||||
- `Worker is running` - Worker running correctly
|
||||
- `Worker is not running` - Worker stopped or crashed
|
||||
- Connection refused - Worker not running
|
||||
- Timeout - Worker hung (restart needed)
|
||||
|
||||
### Detailed Worker Info
|
||||
|
||||
```bash
|
||||
# View PID file
|
||||
cat ~/.claude-mem/worker.pid
|
||||
|
||||
# Check process details
|
||||
ps aux | grep "bun.*worker-service"
|
||||
```
|
||||
|
||||
## Worker Health Endpoint
|
||||
|
||||
The worker exposes a health endpoint at `/health`:
|
||||
|
||||
```bash
|
||||
# Check health (default port)
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
|
||||
# With custom port
|
||||
PORT=$(grep CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json | grep -o '[0-9]\+' || echo "37777")
|
||||
curl -s http://127.0.0.1:$PORT/health
|
||||
```
|
||||
|
||||
**Expected response:** `{"status":"ok"}`
|
||||
|
||||
**Error responses:**
|
||||
- Connection refused - Worker not running
|
||||
- Timeout - Worker hung (restart needed)
|
||||
- Empty response - Worker crashed mid-request
|
||||
|
||||
## Worker Logs
|
||||
|
||||
### View Recent Logs
|
||||
|
||||
```bash
|
||||
# View logs using npm script
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:logs
|
||||
|
||||
# View today's log file directly
|
||||
cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Last 50 lines of today's log
|
||||
tail -50 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Follow logs in real-time
|
||||
tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
```
|
||||
|
||||
### Search Logs for Errors
|
||||
|
||||
```bash
|
||||
# Find errors in today's log
|
||||
grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Find exceptions
|
||||
grep -i "exception" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Find failed requests
|
||||
grep -i "failed" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# All error patterns
|
||||
grep -iE "error|exception|failed|crash" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# Search across all log files
|
||||
grep -iE "error|exception|failed|crash" ~/.claude-mem/logs/worker-*.log
|
||||
```
|
||||
|
||||
### Common Log Patterns
|
||||
|
||||
**Good startup:**
|
||||
```
|
||||
Worker service started on port 37777
|
||||
Database initialized
|
||||
Express server listening
|
||||
```
|
||||
|
||||
**Database errors:**
|
||||
```
|
||||
Error: SQLITE_ERROR
|
||||
Error initializing database
|
||||
Database locked
|
||||
```
|
||||
|
||||
**Port conflicts:**
|
||||
```
|
||||
Error: listen EADDRINUSE
|
||||
Port 37777 already in use
|
||||
```
|
||||
|
||||
**Crashes:**
|
||||
```
|
||||
Worker process exited with code 1
|
||||
Worker restarting...
|
||||
```
|
||||
|
||||
## Starting the Worker
|
||||
|
||||
### Basic Start
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
### Force Restart
|
||||
|
||||
```bash
|
||||
# Restart worker (stops and starts)
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:restart
|
||||
|
||||
# Or manually stop and start
|
||||
npm run worker:stop
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
## Stopping the Worker
|
||||
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm run worker:stop
|
||||
```
|
||||
|
||||
## Worker Not Starting
|
||||
|
||||
### Diagnostic Steps
|
||||
|
||||
1. **Try manual start to see error:**
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
bun plugin/scripts/worker-service.js
|
||||
```
|
||||
This runs the worker directly, showing full error output.
|
||||
|
||||
2. **Check Bun installation:**
|
||||
```bash
|
||||
which bun
|
||||
bun --version
|
||||
```
|
||||
If Bun not found, run: `npm install` (auto-installs Bun)
|
||||
|
||||
3. **Check dependencies:**
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
ls node_modules/@anthropic-ai/claude-agent-sdk
|
||||
ls node_modules/express
|
||||
```
|
||||
|
||||
4. **Check port availability:**
|
||||
```bash
|
||||
lsof -i :37777
|
||||
```
|
||||
If port in use, either kill that process or change claude-mem port.
|
||||
|
||||
5. **Check PID file:**
|
||||
```bash
|
||||
cat ~/.claude-mem/worker.pid
|
||||
```
|
||||
If worker PID exists but process is dead, remove stale PID:
|
||||
```bash
|
||||
rm ~/.claude-mem/worker.pid
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
### Common Fixes
|
||||
|
||||
**Dependencies missing:**
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
npm install
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
**Port conflict:**
|
||||
```bash
|
||||
echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
**Stale PID file:**
|
||||
```bash
|
||||
rm ~/.claude-mem/worker.pid
|
||||
npm run worker:start
|
||||
```
|
||||
|
||||
## Worker Crashing Repeatedly
|
||||
|
||||
If worker keeps restarting (check logs for repeated startup messages):
|
||||
|
||||
### Find the Cause
|
||||
|
||||
1. **Check error logs:**
|
||||
```bash
|
||||
grep -i "error" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log | tail -100
|
||||
```
|
||||
|
||||
2. **Look for crash pattern:**
|
||||
```bash
|
||||
grep -A 5 "exited with code" ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
```
|
||||
|
||||
3. **Run worker in foreground to see crashes:**
|
||||
```bash
|
||||
cd ~/.claude/plugins/marketplaces/thedotmack/
|
||||
bun plugin/scripts/worker-service.js
|
||||
```
|
||||
|
||||
### Common Crash Causes
|
||||
|
||||
**Database corruption:**
|
||||
```bash
|
||||
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"
|
||||
```
|
||||
If fails, backup and recreate database.
|
||||
|
||||
**Out of memory:**
|
||||
Check if database is too large or memory leak. Restart:
|
||||
```bash
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
**Port conflict race condition:**
|
||||
Another process grabbing port intermittently. Change port:
|
||||
```bash
|
||||
echo '{"CLAUDE_MEM_WORKER_PORT":"37778"}' > ~/.claude-mem/settings.json
|
||||
npm run worker:restart
|
||||
```
|
||||
|
||||
## Worker Management Commands
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
npm run worker:status
|
||||
|
||||
# Start worker
|
||||
npm run worker:start
|
||||
|
||||
# Stop worker
|
||||
npm run worker:stop
|
||||
|
||||
# Restart worker
|
||||
npm run worker:restart
|
||||
|
||||
# View logs
|
||||
npm run worker:logs
|
||||
|
||||
# Check health endpoint
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
|
||||
# View PID
|
||||
cat ~/.claude-mem/worker.pid
|
||||
|
||||
# View today's log file
|
||||
cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# List all log files
|
||||
ls -lh ~/.claude-mem/logs/worker-*.log
|
||||
```
|
||||
|
||||
## Log File Management
|
||||
|
||||
Worker logs are stored in `~/.claude-mem/logs/` with daily rotation:
|
||||
|
||||
```bash
|
||||
# View today's log
|
||||
cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
||||
|
||||
# View yesterday's log
|
||||
cat ~/.claude-mem/logs/worker-$(date -d "yesterday" +%Y-%m-%d).log # Linux
|
||||
cat ~/.claude-mem/logs/worker-$(date -v-1d +%Y-%m-%d).log # macOS
|
||||
|
||||
# List all logs
|
||||
ls -lh ~/.claude-mem/logs/
|
||||
|
||||
# Clean old logs (older than 7 days)
|
||||
find ~/.claude-mem/logs/ -name "worker-*.log" -mtime +7 -delete
|
||||
|
||||
# Archive logs
|
||||
tar -czf ~/claude-mem-logs-backup-$(date +%Y-%m-%d).tar.gz ~/.claude-mem/logs/
|
||||
```
|
||||
|
||||
**Note:** Logs auto-rotate daily. No manual flush required.
|
||||
|
||||
## Testing Worker Endpoints
|
||||
|
||||
Once worker is running, test all endpoints:
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl -s http://127.0.0.1:37777/health
|
||||
|
||||
# Viewer HTML
|
||||
curl -s http://127.0.0.1:37777/ | head -20
|
||||
|
||||
# Stats API
|
||||
curl -s http://127.0.0.1:37777/api/stats
|
||||
|
||||
# Search API
|
||||
curl -s "http://127.0.0.1:37777/api/search?query=test&limit=5"
|
||||
|
||||
# Recent context
|
||||
curl -s "http://127.0.0.1:37777/api/context/recent?limit=3"
|
||||
```
|
||||
|
||||
All should return appropriate responses (HTML for viewer, JSON for APIs).
|
||||
|
||||
## Troubleshooting Quick Reference
|
||||
|
||||
| Problem | Command | Expected Result |
|
||||
|---------|---------|----------------|
|
||||
| Check if running | `npm run worker:status` | Shows PID and uptime |
|
||||
| Worker not running | `npm run worker:start` | Worker starts successfully |
|
||||
| Worker crashed | `npm run worker:restart` | Worker restarts |
|
||||
| View recent errors | `grep -i error ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log \| tail -20` | Shows recent errors |
|
||||
| Port in use | `lsof -i :37777` | Shows process using port |
|
||||
| Stale PID | `rm ~/.claude-mem/worker.pid && npm run worker:start` | Removes stale PID and starts |
|
||||
| Dependencies missing | `npm install && npm run worker:start` | Installs deps and starts |
|
||||
Reference in New Issue
Block a user