Claude Code Research

Basic Memory Sync Issues Resolution Guide

2 min read

Basic Memory Sync Issues Resolution Guide

Current Sync Error

The Basic Memory sync is failing with a database constraint error:

(sqlite3.IntegrityError) UNIQUE constraint failed: entity.file_path, entity.project_id
[SQL: UPDATE entity SET file_path=? WHERE entity.id = ?]
[parameters: ('quartz/i18n/locales/ro-RO.ts', 220)]

Root Cause

This error occurs when Basic Memory tries to update an entity with a file path that already exists for the same project. This can happen when:

  1. Files are moved or renamed outside of Basic Memory
  2. The database has stale entries from previous file locations
  3. Multiple files with the same path were indexed at different times

For broader patterns on building resilient systems that handle failures gracefully, see Error Recovery & Resilience Patterns.

Resolution Steps

  1. Stop the Basic Memory MCP server
  2. Clear any cache or temporary files
  3. Restart the server to trigger a fresh sync

Option 2: Create New Project

If restarting doesn’t resolve the issue:

  1. Create a new Basic Memory project for the repository
  2. This will start with a clean database
  3. All files will be freshly indexed
# Using Basic Memory MCP
create_memory_project("claude-research-v2", "/Users/johnlindquist/dev/claude-research")
switch_project("claude-research-v2")

Option 3: Manual Database Cleanup

For advanced users only:

  1. Locate the Basic Memory database
  2. Remove duplicate entries for the affected file paths
  3. Restart the sync process

Prevention

To prevent future sync issues:

  1. Use Basic Memory for file operations - When moving or renaming files, use Basic Memory’s move_note function
  2. Regular sync checks - Periodically check sync status
  3. Avoid external file moves - Don’t move files outside of Basic Memory while it’s running
  4. Single project instance - Ensure only one Basic Memory project points to the same directory

Current Workaround

Despite the sync error, Basic Memory is still functional for most operations:

  • File reading and writing work normally
  • Search functionality is available for previously indexed content
  • New files can be created and will be indexed

The sync error primarily affects:

  • Automatic indexing of externally created files
  • Updates to file paths in the database
  • Complete project synchronization

Next Steps

  1. Monitor the Basic Memory GitHub repository for updates
  2. Consider filing an issue if the problem persists
  3. Use the workaround methods documented above
  4. Continue using Basic Memory with awareness of the limitation

basic-memory troubleshooting sync-issues database claude-code

Graph View

Backlinks