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 index 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 authentication and connection 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

Indexing Issues

Changes Not Indexing

Problem: File changes not appearing in knowledge base.

Solutions:

1. Check index 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. Rebuild the index (or reset if issues persist):

   basic-memory reindex
   # heavier: drop and rebuild the database
   basic-memory reset --reindex
   

   Plain basic-memory reset only deletes the index — pass --reindex to rebuild it from your files. May take time for large knowledge bases.

Duplicate Notes on macOS

Problem: The same file appears twice — duplicate search results, -1-suffixed permalinks, or edit_note failing on an affected note. Typically triggered by cross-platform sync tools that rewrite Unicode filename forms (#1275) or by case-only renames on case-insensitive APFS (#1281).

Solution: Collapse the duplicates with a full rebuild, and avoid case-only or normalization-only renames. These rename edge cases remain open in v0.23.2:

basic-memory reindex --full -p <project>

Ordinary write_note and note-move destinations are different: v0.23.2 reuses a uniquely matching existing folder regardless of case, preventing a new schemas/ folder beside Schemas/. It does not repair existing duplicates or perform case-only folder renames. See Known issues in v0.23 for details.

Cloud Sync Issues

Problem: Push or pull not working — setup errors, conflicts, or "no local sync path configured".

The Cloud Sync Guide's troubleshooting section owns the fixes: re-running setup, previewing transfers with --dry-run, resolving conflicts with --on-conflict, and configuring sync paths.

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. Rebuild the search index:

   basic-memory reindex
   

Entity Not Found

Problem: Note doesn't exist at specified path.

Solutions:

1. Search for the note — ask your AI assistant:

   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 knowledge base statistics:

   basic-memory project info main
   

2. Archive old content - Move inactive notes to archive folder
3. Coalesce rapid file saves - Increase the index delay when an editor writes the same file repeatedly in a short burst:

   bm config set index_delay 2000
   

4. Tune concurrent accepted writes carefully - For workloads that submit many local writes at once, increase materialization workers from the default of 4:

   bm config set materialization_workers 8
   

   
   This affects local write materialization, not general indexing concurrency.

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: Unsupported Python version error.

Solution: Install Python 3.12 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 cloud sync-setup research ~/Documents/research
bm cloud pull --name research

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. Clean up SQLite WAL/shared-memory files — after closing all clients, the supported path is:

   basic-memory reset --reindex
   

   
   (It removes memory.db-shm/memory.db-wal itself — deleting the -wal file by hand can silently discard recently indexed changes.)

Corrupted Database

Problem: Database errors or inconsistent state.

Solution: Reset and re-index:

basic-memory reset --reindex

Getting Help

Check Logs

# View the log file (Windows uses per-process basic-memory-<pid>.log names)
cat ~/.basic-memory/basic-memory.log

# For cloud connection diagnostics
bm cloud status

Command Help

# View all commands
basic-memory --help

# Get help for specific commands
basic-memory status --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