feat: add stable external_id (UUID) to Project and Entity models

src/basic_memory/alembic/versions/6830751f5fb6_merge_multiple_heads.py

@@ -0,0 +1,26 @@
+"""Merge multiple heads
+
+Revision ID: 6830751f5fb6
+Revises: a2b3c4d5e6f7, g9a0b3c4d5e6
+Create Date: 2025-12-29 12:46:46.476268
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '6830751f5fb6'
+down_revision: Union[str, Sequence[str], None] = ('a2b3c4d5e6f7', 'g9a0b3c4d5e6')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

src/basic_memory/alembic/versions/g9a0b3c4d5e6_add_external_id_to_project_and_entity.py

@@ -0,0 +1,173 @@
+"""Add external_id UUID column to project and entity tables
+
+Revision ID: g9a0b3c4d5e6
+Revises: f8a9b2c3d4e5
+Create Date: 2025-12-29 10:00:00.000000
+
+"""
+
+import uuid
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy import text
+
+
+def column_exists(connection, table: str, column: str) -> bool:
+    """Check if a column exists in a table (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text(
+                "SELECT 1 FROM information_schema.columns "
+                "WHERE table_name = :table AND column_name = :column"
+            ),
+            {"table": table, "column": column},
+        )
+        return result.fetchone() is not None
+    else:
+        # SQLite
+        result = connection.execute(text(f"PRAGMA table_info({table})"))
+        columns = [row[1] for row in result]
+        return column in columns
+
+
+def index_exists(connection, index_name: str) -> bool:
+    """Check if an index exists (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text("SELECT 1 FROM pg_indexes WHERE indexname = :index_name"),
+            {"index_name": index_name},
+        )
+        return result.fetchone() is not None
+    else:
+        # SQLite
+        result = connection.execute(
+            text("SELECT 1 FROM sqlite_master WHERE type='index' AND name = :index_name"),
+            {"index_name": index_name},
+        )
+        return result.fetchone() is not None
+
+
+# revision identifiers, used by Alembic.
+revision: str = "g9a0b3c4d5e6"
+down_revision: Union[str, None] = "f8a9b2c3d4e5"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add external_id UUID column to project and entity tables.
+
+    This migration:
+    1. Adds external_id column to project table
+    2. Adds external_id column to entity table
+    3. Generates UUIDs for existing rows
+    4. Creates unique indexes on both columns
+    """
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    # -------------------------------------------------------------------------
+    # Add external_id to project table
+    # -------------------------------------------------------------------------
+
+    if not column_exists(connection, "project", "external_id"):
+        # Step 1: Add external_id column as nullable first
+        op.add_column("project", sa.Column("external_id", sa.String(), nullable=True))
+
+        # Step 2: Generate UUIDs for existing rows
+        if dialect == "postgresql":
+            # Postgres has gen_random_uuid() function
+            op.execute("""
+                UPDATE project
+                SET external_id = gen_random_uuid()::text
+                WHERE external_id IS NULL
+            """)
+        else:
+            # SQLite: need to generate UUIDs in Python
+            result = connection.execute(text("SELECT id FROM project WHERE external_id IS NULL"))
+            for row in result:
+                new_uuid = str(uuid.uuid4())
+                connection.execute(
+                    text("UPDATE project SET external_id = :uuid WHERE id = :id"),
+                    {"uuid": new_uuid, "id": row[0]},
+                )
+
+        # Step 3: Make external_id NOT NULL
+        if dialect == "postgresql":
+            op.alter_column("project", "external_id", nullable=False)
+        else:
+            # SQLite requires batch operations for ALTER COLUMN
+            with op.batch_alter_table("project") as batch_op:
+                batch_op.alter_column("external_id", nullable=False)
+
+    # Step 4: Create unique index on project.external_id (idempotent)
+    if not index_exists(connection, "ix_project_external_id"):
+        op.create_index("ix_project_external_id", "project", ["external_id"], unique=True)
+
+    # -------------------------------------------------------------------------
+    # Add external_id to entity table
+    # -------------------------------------------------------------------------
+
+    if not column_exists(connection, "entity", "external_id"):
+        # Step 1: Add external_id column as nullable first
+        op.add_column("entity", sa.Column("external_id", sa.String(), nullable=True))
+
+        # Step 2: Generate UUIDs for existing rows
+        if dialect == "postgresql":
+            # Postgres has gen_random_uuid() function
+            op.execute("""
+                UPDATE entity
+                SET external_id = gen_random_uuid()::text
+                WHERE external_id IS NULL
+            """)
+        else:
+            # SQLite: need to generate UUIDs in Python
+            result = connection.execute(text("SELECT id FROM entity WHERE external_id IS NULL"))
+            for row in result:
+                new_uuid = str(uuid.uuid4())
+                connection.execute(
+                    text("UPDATE entity SET external_id = :uuid WHERE id = :id"),
+                    {"uuid": new_uuid, "id": row[0]},
+                )
+
+        # Step 3: Make external_id NOT NULL
+        if dialect == "postgresql":
+            op.alter_column("entity", "external_id", nullable=False)
+        else:
+            # SQLite requires batch operations for ALTER COLUMN
+            with op.batch_alter_table("entity") as batch_op:
+                batch_op.alter_column("external_id", nullable=False)
+
+    # Step 4: Create unique index on entity.external_id (idempotent)
+    if not index_exists(connection, "ix_entity_external_id"):
+        op.create_index("ix_entity_external_id", "entity", ["external_id"], unique=True)
+
+
+def downgrade() -> None:
+    """Remove external_id columns from project and entity tables."""
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    # Drop from entity table
+    if index_exists(connection, "ix_entity_external_id"):
+        op.drop_index("ix_entity_external_id", table_name="entity")
+
+    if column_exists(connection, "entity", "external_id"):
+        if dialect == "postgresql":
+            op.drop_column("entity", "external_id")
+        else:
+            with op.batch_alter_table("entity") as batch_op:
+                batch_op.drop_column("external_id")
+
+    # Drop from project table
+    if index_exists(connection, "ix_project_external_id"):
+        op.drop_index("ix_project_external_id", table_name="project")
+
+    if column_exists(connection, "project", "external_id"):
+        if dialect == "postgresql":
+            op.drop_column("project", "external_id")
+        else:
+            with op.batch_alter_table("project") as batch_op:
+                batch_op.drop_column("external_id")

src/basic_memory/api/routers/project_router.py

@@ -51,6 +51,7 @@ async def get_project(
 
     return ProjectItem(
         id=found_project.id,
+        external_id=found_project.external_id,
         name=found_project.name,
         path=normalize_project_path(found_project.path),
         is_default=found_project.is_default or False,
@@ -89,6 +90,7 @@ async def update_project(
 
         old_project_info = ProjectItem(
             id=old_project.id,
+            external_id=old_project.external_id,
             name=old_project.name,
             path=old_project.path,
             is_default=old_project.is_default or False,
@@ -111,6 +113,7 @@ async def update_project(
             old_project=old_project_info,
             new_project=ProjectItem(
                 id=updated_project.id,
+                external_id=updated_project.external_id,
                 name=updated_project.name,
                 path=updated_project.path,
                 is_default=updated_project.is_default or False,
@@ -203,6 +206,7 @@ async def list_projects(
     project_items = [
         ProjectItem(
             id=project.id,
+            external_id=project.external_id,
             name=project.name,
             path=normalize_project_path(project.path),
             is_default=project.is_default or False,
@@ -250,6 +254,7 @@ async def add_project(
                 default=existing_project.is_default or False,
                 new_project=ProjectItem(
                     id=existing_project.id,
+                    external_id=existing_project.external_id,
                     name=existing_project.name,
                     path=existing_project.path,
                     is_default=existing_project.is_default or False,
@@ -279,6 +284,7 @@ async def add_project(
             default=project_data.set_default,
             new_project=ProjectItem(
                 id=new_project.id,
+                external_id=new_project.external_id,
                 name=new_project.name,
                 path=new_project.path,
                 is_default=new_project.is_default or False,
@@ -334,6 +340,7 @@ async def remove_project(
             default=False,
             old_project=ProjectItem(
                 id=old_project.id,
+                external_id=old_project.external_id,
                 name=old_project.name,
                 path=old_project.path,
                 is_default=old_project.is_default or False,
@@ -382,12 +389,14 @@ async def set_default_project(
             default=True,
             old_project=ProjectItem(
                 id=default_project.id,
+                external_id=default_project.external_id,
                 name=default_name,
                 path=default_project.path,
                 is_default=False,
             ),
             new_project=ProjectItem(
                 id=new_default_project.id,
+                external_id=new_default_project.external_id,
                 name=name,
                 path=new_default_project.path,
                 is_default=True,
@@ -417,6 +426,7 @@ async def get_default_project(
 
     return ProjectItem(
         id=default_project.id,
+        external_id=default_project.external_id,
         name=default_project.name,
         path=default_project.path,
         is_default=True,

src/basic_memory/api/v2/routers/directory_router.py

@@ -1,34 +1,34 @@
 """V2 Directory Router - ID-based directory tree operations.
 
 This router provides directory structure browsing for projects using
-integer project IDs instead of name-based identifiers.
+external_id UUIDs instead of name-based identifiers.
 
 Key improvements:
-- Direct project lookup via integer primary keys
+- Direct project lookup via external_id UUIDs
 - Consistent with other v2 endpoints
 - Better performance through indexed queries
 """
 
 from typing import List, Optional
 
-from fastapi import APIRouter, Query
+from fastapi import APIRouter, Query, Path
 
-from basic_memory.deps import DirectoryServiceV2Dep, ProjectIdPathDep
+from basic_memory.deps import DirectoryServiceV2ExternalDep
 from basic_memory.schemas.directory import DirectoryNode
 
 router = APIRouter(prefix="/directory", tags=["directory-v2"])
 
 
 @router.get("/tree", response_model=DirectoryNode, response_model_exclude_none=True)
 async def get_directory_tree(
-    directory_service: DirectoryServiceV2Dep,
-    project_id: ProjectIdPathDep,
+    directory_service: DirectoryServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
 ):
     """Get hierarchical directory structure from the knowledge base.
 
     Args:
         directory_service: Service for directory operations
-        project_id: Numeric project ID
+        project_id: Project external UUID
 
     Returns:
         DirectoryNode representing the root of the hierarchical tree structure
@@ -42,8 +42,8 @@ async def get_directory_tree(
 
 @router.get("/structure", response_model=DirectoryNode, response_model_exclude_none=True)
 async def get_directory_structure(
-    directory_service: DirectoryServiceV2Dep,
-    project_id: ProjectIdPathDep,
+    directory_service: DirectoryServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
 ):
     """Get folder structure for navigation (no files).
 
@@ -52,7 +52,7 @@ async def get_directory_structure(
 
     Args:
         directory_service: Service for directory operations
-        project_id: Numeric project ID
+        project_id: Project external UUID
 
     Returns:
         DirectoryNode tree containing only folders (type="directory")
@@ -63,8 +63,8 @@ async def get_directory_structure(
 
 @router.get("/list", response_model=List[DirectoryNode], response_model_exclude_none=True)
 async def list_directory(
-    directory_service: DirectoryServiceV2Dep,
-    project_id: ProjectIdPathDep,
+    directory_service: DirectoryServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
     dir_name: str = Query("/", description="Directory path to list"),
     depth: int = Query(1, ge=1, le=10, description="Recursion depth (1-10)"),
     file_name_glob: Optional[str] = Query(
@@ -75,7 +75,7 @@ async def list_directory(
 
     Args:
         directory_service: Service for directory operations
-        project_id: Numeric project ID
+        project_id: Project external UUID
         dir_name: Directory path to list (default: root "/")
         depth: Recursion depth (1-10, default: 1 for immediate children only)
         file_name_glob: Optional glob pattern for filtering file names (e.g., "*.md", "*meeting*")