fix: Complete v2 API project ID implementation

- Add `id` field to ProjectItem schema as required field
- Update all ProjectItem instantiations to include project ID
- Change v2 API route from /v2/{project} to /v2/{project_id}
- Create ProjectIdPathDep dependency for validating integer project IDs
- Add V2-specific dependencies (repositories, services) that use ProjectIdPathDep
- Update all v2 knowledge router endpoints to use V2 dependencies
- Fix forward reference issues in deps.py with string annotations
- Update test mocks to include project ID in responses
- Fix update_project endpoint to return 400 (not 404) for backward compatibility

This completes the Phase 1 implementation by ensuring v2 API uses
stable integer project IDs instead of string project names/paths.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jope-bm

.gitignore

@@ -52,4 +52,5 @@ ENV/
 
 # claude action
 claude-output
-**/.claude/settings.local.json
+**/.claude/settings.local.json
+.mcp.json

src/basic_memory/api/app.py

@@ -92,7 +92,7 @@ async def lifespan(app: FastAPI):  # pragma: no cover
 app.include_router(importer_router.router, prefix="/{project}")
 
 # Include v2 routers (current)
-app.include_router(v2_knowledge, prefix="/v2/{project}")
+app.include_router(v2_knowledge, prefix="/v2/{project_id}")
 
 # Project resource router works across projects
 app.include_router(project.project_resource_router)

src/basic_memory/api/routers/project_router.py

@@ -50,6 +50,7 @@ async def get_project(
         )  # pragma: no cover
 
     return ProjectItem(
+        id=found_project.id,
         name=found_project.name,
         path=normalize_project_path(found_project.path),
         is_default=found_project.is_default or False,
@@ -80,9 +81,15 @@ async def update_project(
             raise HTTPException(status_code=400, detail="Path must be absolute")
 
         # Get original project info for the response
+        old_project = await project_service.get_project(name)
+        if not old_project:
+            raise HTTPException(status_code=400, detail=f"Project '{name}' not found in configuration")
+
         old_project_info = ProjectItem(
-            name=name,
-            path=project_service.projects.get(name, ""),
+            id=old_project.id,
+            name=old_project.name,
+            path=old_project.path,
+            is_default=old_project.is_default or False,
         )
 
         if path:
@@ -91,14 +98,21 @@ async def update_project(
             await project_service.update_project(name, is_active=is_active)
 
         # Get updated project info
-        updated_path = path if path else project_service.projects.get(name, "")
+        updated_project = await project_service.get_project(name)
+        if not updated_project:
+            raise HTTPException(status_code=404, detail=f"Project '{name}' not found after update")
 
         return ProjectStatusResponse(
             message=f"Project '{name}' updated successfully",
             status="success",
             default=(name == project_service.default_project),
             old_project=old_project_info,
-            new_project=ProjectItem(name=name, path=updated_path),
+            new_project=ProjectItem(
+                id=updated_project.id,
+                name=updated_project.name,
+                path=updated_project.path,
+                is_default=updated_project.is_default or False,
+            ),
         )
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
@@ -186,6 +200,7 @@ async def list_projects(
 
     project_items = [
         ProjectItem(
+            id=project.id,
             name=project.name,
             path=normalize_project_path(project.path),
             is_default=project.is_default or False,
@@ -232,6 +247,7 @@ async def add_project(
                 status="success",
                 default=existing_project.is_default or False,
                 new_project=ProjectItem(
+                    id=existing_project.id,
                     name=existing_project.name,
                     path=existing_project.path,
                     is_default=existing_project.is_default or False,
@@ -250,12 +266,20 @@ async def add_project(
             project_data.name, project_data.path, set_default=project_data.set_default
         )
 
+        # Fetch the newly created project to get its ID
+        new_project = await project_service.get_project(project_data.name)
+        if not new_project:
+            raise HTTPException(status_code=500, detail="Failed to retrieve newly created project")
+
         return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
             message=f"Project '{project_data.name}' added successfully",
             status="success",
             default=project_data.set_default,
             new_project=ProjectItem(
-                name=project_data.name, path=project_data.path, is_default=project_data.set_default
+                id=new_project.id,
+                name=new_project.name,
+                path=new_project.path,
+                is_default=new_project.is_default or False,
             ),
         )
     except ValueError as e:  # pragma: no cover
@@ -306,7 +330,12 @@ async def remove_project(
             message=f"Project '{name}' removed successfully",
             status="success",
             default=False,
-            old_project=ProjectItem(name=old_project.name, path=old_project.path),
+            old_project=ProjectItem(
+                id=old_project.id,
+                name=old_project.name,
+                path=old_project.path,
+                is_default=old_project.is_default or False,
+            ),
             new_project=None,
         )
     except ValueError as e:  # pragma: no cover
@@ -349,8 +378,14 @@ async def set_default_project(
             message=f"Project '{name}' set as default successfully",
             status="success",
             default=True,
-            old_project=ProjectItem(name=default_name, path=default_project.path),
+            old_project=ProjectItem(
+                id=default_project.id,
+                name=default_name,
+                path=default_project.path,
+                is_default=False,
+            ),
             new_project=ProjectItem(
+                id=new_default_project.id,
                 name=name,
                 path=new_default_project.path,
                 is_default=True,
@@ -378,7 +413,12 @@ async def get_default_project(
             status_code=404, detail=f"Default Project: '{default_name}' does not exist"
         )
 
-    return ProjectItem(name=default_project.name, path=default_project.path, is_default=True)
+    return ProjectItem(
+        id=default_project.id,
+        name=default_project.name,
+        path=default_project.path,
+        is_default=True,
+    )
 
 
 # Synchronize projects between config and database

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

@@ -14,13 +14,14 @@
 from loguru import logger
 
 from basic_memory.deps import (
-    EntityServiceDep,
-    SearchServiceDep,
-    LinkResolverDep,
-    ProjectConfigDep,
+    EntityServiceV2Dep,
+    SearchServiceV2Dep,
+    LinkResolverV2Dep,
+    ProjectConfigV2Dep,
     AppConfigDep,
-    SyncServiceDep,
-    EntityRepositoryDep,
+    SyncServiceV2Dep,
+    EntityRepositoryV2Dep,
+    ProjectIdPathDep,
 )
 from basic_memory.schemas import EntityResponse, DeleteEntitiesResponse
 from basic_memory.schemas.base import Entity
@@ -58,8 +59,9 @@ async def resolve_relations_background(sync_service, entity_id: int, entity_perm
 
 @router.post("/resolve", response_model=EntityResolveResponse)
 async def resolve_identifier(
+    project_id: ProjectIdPathDep,
     data: EntityResolveRequest,
-    link_resolver: LinkResolverDep,
+    link_resolver: LinkResolverV2Dep,
 ) -> EntityResolveResponse:
     """Resolve a string identifier (permalink, title, or path) to an entity ID.
 
@@ -128,8 +130,9 @@ async def resolve_identifier(
 
 @router.get("/entities/{entity_id}", response_model=EntityResponseV2)
 async def get_entity_by_id(
+    project_id: ProjectIdPathDep,
     entity_id: int,
-    entity_repository: EntityRepositoryDep,
+    entity_repository: EntityRepositoryV2Dep,
 ) -> EntityResponseV2:
     """Get an entity by its numeric ID.
 
@@ -162,10 +165,11 @@ async def get_entity_by_id(
 
 @router.post("/entities", response_model=EntityResponse)
 async def create_entity(
+    project_id: ProjectIdPathDep,
     data: Entity,
     background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    search_service: SearchServiceDep,
+    entity_service: EntityServiceV2Dep,
+    search_service: SearchServiceV2Dep,
 ) -> EntityResponse:
     """Create a new entity.
 
@@ -199,14 +203,15 @@ async def create_entity(
 
 @router.put("/entities/{entity_id}", response_model=EntityResponse)
 async def update_entity_by_id(
+    project_id: ProjectIdPathDep,
     entity_id: int,
     data: Entity,
     response: Response,
     background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    search_service: SearchServiceDep,
-    sync_service: SyncServiceDep,
-    entity_repository: EntityRepositoryDep,
+    entity_service: EntityServiceV2Dep,
+    search_service: SearchServiceV2Dep,
+    sync_service: SyncServiceV2Dep,
+    entity_repository: EntityRepositoryV2Dep,
 ) -> EntityResponse:
     """Update an entity by ID.
 
@@ -248,12 +253,13 @@ async def update_entity_by_id(
 
 @router.patch("/entities/{entity_id}", response_model=EntityResponse)
 async def edit_entity_by_id(
+    project_id: ProjectIdPathDep,
     entity_id: int,
     data: EditEntityRequest,
     background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    search_service: SearchServiceDep,
-    entity_repository: EntityRepositoryDep,
+    entity_service: EntityServiceV2Dep,
+    search_service: SearchServiceV2Dep,
+    entity_repository: EntityRepositoryV2Dep,
 ) -> EntityResponse:
     """Edit an existing entity by ID using operations like append, prepend, etc.
 
@@ -267,7 +273,9 @@ async def edit_entity_by_id(
     Raises:
         HTTPException: 404 if entity not found, 400 if edit fails
     """
-    logger.info(f"API v2 request: edit_entity_by_id entity_id={entity_id}, operation='{data.operation}'")
+    logger.info(
+        f"API v2 request: edit_entity_by_id entity_id={entity_id}, operation='{data.operation}'"
+    )
 
     # Verify entity exists
     entity = await entity_repository.get_by_id(entity_id)
@@ -307,10 +315,11 @@ async def edit_entity_by_id(
 
 @router.delete("/entities/{entity_id}", response_model=DeleteEntitiesResponse)
 async def delete_entity_by_id(
+    project_id: ProjectIdPathDep,
     entity_id: int,
     background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    entity_repository: EntityRepositoryDep,
+    entity_service: EntityServiceV2Dep,
+    entity_repository: EntityRepositoryV2Dep,
     search_service=Depends(lambda: None),  # Optional for now
 ) -> DeleteEntitiesResponse:
     """Delete an entity by ID.
@@ -347,12 +356,13 @@ async def delete_entity_by_id(
 
 @router.post("/move", response_model=EntityResponse)
 async def move_entity(
+    project_id: ProjectIdPathDep,
     data: MoveEntityRequest,
     background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    project_config: ProjectConfigDep,
+    entity_service: EntityServiceV2Dep,
+    project_config: ProjectConfigV2Dep,
     app_config: AppConfigDep,
-    search_service: SearchServiceDep,
+    search_service: SearchServiceV2Dep,
 ) -> EntityResponse:
     """Move an entity to a new file location.