Troubleshooting

This guide covers common issues and their solutions. For live help, visit our Discord server.

MCP Connection Issues

Claude Says "No Basic Memory Tools Available"

Problem: Claude Desktop can't find Basic Memory tools.

Solutions:

1. Check absolute paths - Use complete paths in Claude Desktop config:

   {
     "mcpServers": {
       "basic-memory": {
         "command": "/Users/yourusername/.local/bin/uvx",
         "args": ["basic-memory", "mcp"]
       }
     }
   }
   

   
   Find your path with: which uvx
2. Verify installation:

   basic-memory --version
   

3. Restart applications - Close and reopen both Terminal and Claude Desktop
4. Check sync status:

   basic-memory status
   

ENOENT Error

Problem: Claude Desktop cannot find the uv installation.

Solution:

1. Find the absolute path: which uvx
2. Update Claude Desktop config with the full path
3. Restart Claude Desktop

MCP Endpoint Connection Fails (Cloud)

Problem: Remote MCP connection not working.

Solutions:

1. Verify endpoint URL: https://cloud.basicmemory.com/mcp
2. Re-authenticate:

   bm cloud logout
   bm cloud login
   

3. Check subscription status:

   bm cloud status
   

4. Restart your MCP client (Claude Desktop, VS Code, etc.)

Cloud Issues

Cloud Mode Not Working

Problem: CLI commands not working in cloud mode.

Solution:

bm cloud logout
bm cloud login

Subscription Required Error

Problem: "Active subscription required" message.

Solution:

1. Visit basicmemory.com/subscribe
2. Complete subscription
3. Run bm cloud login again

Access is immediate when subscription becomes active.

Authentication Failed or Invalid Token

Problem: Token expired or invalid.

Solution:

bm cloud logout
bm cloud login

Sync Issues

Changes Not Syncing

Problem: File changes not appearing in knowledge base.

Solutions:

1. Check sync status:

   basic-memory status
   

2. Verify file permissions - Ensure Basic Memory can read/write to the project directory
3. Check .gitignore patterns - Files matching ignore patterns are skipped
4. Reset the database:

   basic-memory reset
   

   This re-indexes all files. May take time for large knowledge bases.

Sync In Progress

Problem: Operations failing with "sync in progress" message.

Solution: Wait for sync to complete, then retry. Check progress with:

basic-memory status

Cloud Sync Issues

Problem: Bisync not working.

Solutions:

1. Re-run setup:

   bm cloud setup
   

2. First bisync requires --resync:

   bm project bisync --name research --resync
   

3. Empty directory error - Add at least one file:

   echo "# Notes" > ~/Documents/research/README.md
   bm project bisync --name research --resync
   

4. Bisync state corruption - Reset state:

   bm project bisync-reset research
   bm project bisync --name research --resync
   

5. Too many deletes error - Review changes, then force:

   bm project bisync --name research --dry-run
   bm project bisync --name research --resync
   

Search and Content Issues

Claude Can't Find Knowledge

Problem: AI assistant not finding your notes.

Solutions:

1. Confirm files are in correct directory:

   basic-memory project list
   ls ~/basic-memory
   

2. Check frontmatter formatting - Ensure YAML is valid:

   ---
   title: My Note
   tags: [tag1, tag2]
   ---
   

3. Use memory:// URLs for direct access:

   memory://my-note-title
   

4. Trigger a re-sync:

   basic-memory sync
   

Entity Not Found

Problem: Note doesn't exist at specified path.

Solutions:

1. Search for the note:

   Find notes about [topic]
   

2. Check exact title/permalink - Titles are case-sensitive
3. List directory contents:

   List files in [folder]
   

Performance Issues

Slow Operations

Problem: Commands or syncing taking too long.

Solutions:

1. Check database size:

   basic-memory project info
   

2. Archive old content - Move inactive notes to archive folder
3. Adjust sync delay - Add to ~/.basic-memory/config.json:

   {
     "sync_delay": 2000
   }
   

4. Increase thread pool for large knowledge bases:

   {
     "sync_thread_pool_size": 8
   }
   

High Memory Usage

Problem: Basic Memory using too much memory.

Solutions:

1. Limit context depth in MCP calls (use depth=1 or depth=2)
2. Reduce search page size
3. Archive old content

Installation Issues

Python Version Error

Problem: "Python 3.13+ required" error.

Solution: Install Python 3.13 or higher:

# macOS with Homebrew
brew install python@3.13

# Or use pyenv
pyenv install 3.13.0
pyenv global 3.13.0

uv Not Found

Problem: uv command not found.

Solution: Install uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Then add to PATH (restart terminal or run)
source ~/.bashrc  # or ~/.zshrc

Permission Errors

Problem: Can't create files or access directories.

Solutions:

1. Check directory permissions:

   ls -la ~/basic-memory
   

2. Fix permissions:

   chmod -R u+rw ~/basic-memory
   

3. Ensure Claude Desktop can execute uvx

Project Issues

Project Not Found

Problem: Project doesn't exist in configuration.

Solutions:

1. List available projects:

   basic-memory project list
   

2. Add the project:

   basic-memory project add my-project ~/path/to/project
   

Project Not Configured for Sync (Cloud)

Problem: "Project has no local_sync_path configured"

Solution:

bm project sync-setup research ~/Documents/research
bm project bisync --name research --resync

Moving Notes Between Projects

Problem: Can't move notes from one project to another.

Current solution: Copy the file manually or create a new note in the destination project, then delete the original.

Configuration Issues

Config Changes Not Taking Effect

Problem: Updated config.json but nothing changed.

Solution: Restart your MCP client (Claude Desktop, VS Code, etc.) after changing configuration.

Invalid JSON in Config

Problem: Configuration file has syntax errors.

Solution: Validate your JSON:

cat ~/.basic-memory/config.json | python -m json.tool

Common issues:

• Missing commas between properties
• Trailing commas after last property
• Unquoted strings

Database Issues

Database Locked

Problem: "database is locked" error.

Solutions:

1. Close other applications accessing the database
2. Restart Basic Memory:

   # Find and kill processes
   pkill -f "basic-memory"
   

3. Remove lock files (if they exist):

   rm ~/.basic-memory/memory.db-shm
   rm ~/.basic-memory/memory.db-wal
   

Corrupted Database

Problem: Database errors or inconsistent state.

Solution: Reset and re-index:

basic-memory reset

Getting Help

Check Logs

# View log files
cat ~/.basic-memory/basic-memory-*.log

# Or for Cloud mode
cat ~/.basic-memory/basic-memory-cloud.json

Command Help

# View all commands
basic-memory --help

# Get help for specific commands
basic-memory sync --help
basic-memory project --help
bm cloud --help

Community Support

• Discord: discord.gg/tyvKNccgqN - #help channel
• GitHub Issues: github.com/basicmachines-co/basic-memory/issues

Next Steps