Fix UNIQUE constraint failed: entity.permalink issue #139

Improved error handling in create_entity_from_markdown() to properly handle 
permalink conflicts when different files generate the same permalink.

Changes:
- Distinguish between file_path and permalink constraint failures
- For same file conflicts: update existing entity
- For different file conflicts: generate unique permalink with suffix
- Added comprehensive test case reproducing the exact issue scenario

This fixes the issue where write_note would fail when trying to create
notes with titles that generate the same permalink as existing notes.

Co-authored-by: Drew Cain <groksrc@users.noreply.github.com>

Author: claude[bot]

src/basic_memory/services/entity_service.py

@@ -302,14 +302,36 @@ async def create_entity_from_markdown(
         try:
             return await self.repository.add(model)
         except IntegrityError as e:
-            # Handle race condition where entity was created by another process
-            if "UNIQUE constraint failed: entity.file_path" in str(
-                e
-            ) or "UNIQUE constraint failed: entity.permalink" in str(e):
+            # Handle different types of UNIQUE constraint failures
+            if "UNIQUE constraint failed: entity.file_path" in str(e):
+                # File path conflict - update existing entity
                 logger.info(
-                    f"Entity already exists for file_path={file_path} (file_path or permalink conflict), updating instead of creating"
+                    f"Entity already exists for file_path={file_path}, updating instead of creating"
                 )
                 return await self.update_entity_and_observations(file_path, markdown)
+            elif "UNIQUE constraint failed: entity.permalink" in str(e):
+                # Permalink conflict - check if it's the same file or different file
+                existing_entity = await self.repository.get_by_permalink(model.permalink)
+                if existing_entity and existing_entity.file_path == str(file_path):
+                    # Same file - update existing entity
+                    logger.info(
+                        f"Entity already exists for file_path={file_path}, updating instead of creating"
+                    )
+                    return await self.update_entity_and_observations(file_path, markdown)
+                else:
+                    # Different file with same permalink - generate unique permalink
+                    logger.info(
+                        f"Permalink conflict for {model.permalink}, generating unique permalink"
+                    )
+                    # Generate unique permalink
+                    base_permalink = model.permalink
+                    suffix = 1
+                    while await self.repository.get_by_permalink(model.permalink):
+                        model.permalink = f"{base_permalink}-{suffix}"
+                        suffix += 1
+                    logger.debug(f"Using unique permalink: {model.permalink}")
+                    # Try to create with unique permalink
+                    return await self.repository.add(model)
             else:
                 # Re-raise if it's a different integrity error
                 raise

tests/mcp/test_tool_write_note.py

@@ -413,3 +413,66 @@ async def test_write_note_preserves_content_frontmatter(app):
         ).strip()
         in content
     )
+
+
+@pytest.mark.asyncio
+async def test_write_note_permalink_collision_fix_issue_139(app):
+    """Test fix for GitHub Issue #139: UNIQUE constraint failed: entity.permalink.
+    
+    This reproduces the exact scenario described in the issue:
+    1. Create a note with title "Note 1" 
+    2. Create another note with title "Note 2"
+    3. Try to create/replace first note again with same title "Note 1"
+    
+    Before the fix, step 3 would fail with UNIQUE constraint error.
+    After the fix, it should either update the existing note or create with unique permalink.
+    """
+    # Step 1: Create first note
+    result1 = await write_note.fn(
+        title="Note 1",
+        folder="test",
+        content="Original content for note 1"
+    )
+    assert "# Created note" in result1
+    assert "permalink: test/note-1" in result1
+    
+    # Step 2: Create second note with different title
+    result2 = await write_note.fn(
+        title="Note 2", 
+        folder="test",
+        content="Content for note 2"
+    )
+    assert "# Created note" in result2
+    assert "permalink: test/note-2" in result2
+    
+    # Step 3: Try to create/replace first note again
+    # This scenario would trigger the UNIQUE constraint failure before the fix
+    result3 = await write_note.fn(
+        title="Note 1",  # Same title as first note
+        folder="test",   # Same folder as first note
+        content="Replacement content for note 1"  # Different content
+    )
+    
+    # This should not raise a UNIQUE constraint failure error
+    # It should succeed and either:
+    # 1. Update the existing note (preferred behavior)
+    # 2. Create a new note with unique permalink (fallback behavior)
+    
+    assert result3 is not None
+    assert ("Updated note" in result3 or "Created note" in result3)
+    
+    # The result should contain either the original permalink or a unique one
+    assert ("permalink: test/note-1" in result3 or "permalink: test/note-1-1" in result3)
+    
+    # Verify we can read back the content
+    if "permalink: test/note-1" in result3:
+        # Updated existing note case
+        content = await read_note.fn("test/note-1")
+        assert "Replacement content for note 1" in content
+    else:
+        # Created new note with unique permalink case  
+        content = await read_note.fn("test/note-1-1")
+        assert "Replacement content for note 1" in content
+        # Original note should still exist
+        original_content = await read_note.fn("test/note-1")
+        assert "Original content for note 1" in original_content