basic-memory 0.16.1__py3-none-any.whl → 0.17.4__py3-none-any.whl

basic_memory/api/routers/knowledge_router.py

@@ -1,4 +1,11 @@
-"""Router for knowledge graph operations."""
+"""Router for knowledge graph operations.
+
+⚠️ DEPRECATED: This v1 API is deprecated and will be removed on June 30, 2026.
+Please migrate to /v2/{project}/knowledge endpoints which use entity IDs instead
+of path-based identifiers for improved performance and stability.
+
+Migration guide: See docs/migration/v1-to-v2.md
+"""
 
 from typing import Annotated
 
@@ -25,7 +32,11 @@ from basic_memory.schemas import (
 from basic_memory.schemas.request import EditEntityRequest, MoveEntityRequest
 from basic_memory.schemas.base import Permalink, Entity
 
-router = APIRouter(prefix="/knowledge", tags=["knowledge"])
+router = APIRouter(
+    prefix="/knowledge",
+    tags=["knowledge"],
+    deprecated=True,  # Marks entire router as deprecated in OpenAPI docs
+)
 
 
 async def resolve_relations_background(sync_service, entity_id: int, entity_permalink: str) -> None:
@@ -40,9 +51,10 @@ async def resolve_relations_background(sync_service, entity_id: int, entity_perm
         logger.debug(
             f"Background: Resolved relations for entity {entity_permalink} (id={entity_id})"
         )
-    except Exception as e:
-        # Log but don't fail - this is a background task
-        logger.warning(
+    except Exception as e:  # pragma: no cover
+        # Log but don't fail - this is a background task.
+        # Avoid forcing synthetic failures just for coverage.
+        logger.warning(  # pragma: no cover
             f"Background: Failed to resolve relations for entity {entity_permalink}: {e}"
         )
 

basic_memory/api/routers/project_router.py

@@ -50,6 +50,8 @@ async def get_project(
         )  # pragma: no cover
 
     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,
@@ -80,9 +82,18 @@ 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,
+            external_id=old_project.external_id,
+            name=old_project.name,
+            path=old_project.path,
+            is_default=old_project.is_default or False,
         )
 
         if path:
@@ -91,17 +102,27 @@ 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(  # pragma: no cover
+                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,
+                external_id=updated_project.external_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))
+        raise HTTPException(status_code=400, detail=str(e))  # pragma: no cover
 
 
 # Sync project filesystem
@@ -165,10 +186,10 @@ async def project_sync_status(
     Returns:
         Scan report with details on files that need syncing
     """
-    logger.info(f"Scanning filesystem for project: {project_config.name}")
-    sync_report = await sync_service.scan(project_config.home)
+    logger.info(f"Scanning filesystem for project: {project_config.name}")  # pragma: no cover
+    sync_report = await sync_service.scan(project_config.home)  # pragma: no cover
 
-    return SyncReportResponse.from_sync_report(sync_report)
+    return SyncReportResponse.from_sync_report(sync_report)  # pragma: no cover
 
 
 # List all available projects
@@ -186,6 +207,8 @@ 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,
@@ -232,6 +255,8 @@ async def add_project(
                 status="success",
                 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,
@@ -250,12 +275,21 @@ 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",
+            message=f"Project '{new_project.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,
+                external_id=new_project.external_id,
+                name=new_project.name,
+                path=new_project.path,
+                is_default=new_project.is_default or False,
             ),
         )
     except ValueError as e:  # pragma: no cover
@@ -303,10 +337,16 @@ async def remove_project(
         await project_service.remove_project(name, delete_notes=delete_notes)
 
         return ProjectStatusResponse(
-            message=f"Project '{name}' removed successfully",
+            message=f"Project '{old_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,
+                external_id=old_project.external_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 +389,16 @@ 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,
+                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,
@@ -378,7 +426,13 @@ 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,
+        external_id=default_project.external_id,
+        name=default_project.name,
+        path=default_project.path,
+        is_default=True,
+    )
 
 
 # Synchronize projects between config and database

basic_memory/api/routers/resource_router.py

@@ -2,9 +2,9 @@
 
 import tempfile
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Union
 
-from fastapi import APIRouter, HTTPException, BackgroundTasks, Body
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Body, Response
 from fastapi.responses import FileResponse, JSONResponse
 from loguru import logger
 
@@ -25,6 +25,17 @@ from datetime import datetime
 router = APIRouter(prefix="/resource", tags=["resources"])
 
 
+def _mtime_to_datetime(entity: EntityModel) -> datetime:
+    """Convert entity mtime (file modification time) to datetime.
+
+    Returns the file's actual modification time, falling back to updated_at
+    if mtime is not available.
+    """
+    if entity.mtime:  # pragma: no cover
+        return datetime.fromtimestamp(entity.mtime).astimezone()  # pragma: no cover
+    return entity.updated_at
+
+
 def get_entity_ids(item: SearchIndexRow) -> set[int]:
     match item.type:
         case SearchItemType.ENTITY:
@@ -39,7 +50,7 @@ def get_entity_ids(item: SearchIndexRow) -> set[int]:
             raise ValueError(f"Unexpected type: {item.type}")
 
 
-@router.get("/{identifier:path}")
+@router.get("/{identifier:path}", response_model=None)
 async def get_resource_content(
     config: ProjectConfigDep,
     link_resolver: LinkResolverDep,
@@ -50,7 +61,7 @@ async def get_resource_content(
     identifier: str,
     page: int = 1,
     page_size: int = 10,
-) -> FileResponse:
+) -> Union[Response, FileResponse]:
     """Get resource content by identifier: name or permalink."""
     logger.debug(f"Getting content for: {identifier}")
 
@@ -81,13 +92,16 @@ async def get_resource_content(
     # return single response
     if len(results) == 1:
         entity = results[0]
-        file_path = Path(f"{config.home}/{entity.file_path}")
-        if not file_path.exists():
+        # Check file exists via file_service (for cloud compatibility)
+        if not await file_service.exists(entity.file_path):
             raise HTTPException(
                 status_code=404,
-                detail=f"File not found: {file_path}",
+                detail=f"File not found: {entity.file_path}",
             )
-        return FileResponse(path=file_path)
+        # Read content via file_service as bytes (works with both local and S3)
+        content = await file_service.read_file_bytes(entity.file_path)
+        content_type = file_service.content_type(entity.file_path)
+        return Response(content=content, media_type=content_type)
 
     # for multiple files, initialize a temporary file for writing the results
     with tempfile.NamedTemporaryFile(delete=False, mode="w", suffix=".md") as tmp_file:
@@ -97,7 +111,7 @@ async def get_resource_content(
             # Read content for each entity
             content = await file_service.read_entity_content(result)
             memory_url = normalize_memory_url(result.permalink)
-            modified_date = result.updated_at.isoformat()
+            modified_date = _mtime_to_datetime(result).isoformat()
             checksum = result.checksum[:8] if result.checksum else ""
 
             # Prepare the delimited content
@@ -155,11 +169,11 @@ async def write_resource(
         # FastAPI should validate this, but if a dict somehow gets through
         # (e.g., via JSON body parsing), we need to catch it here
         if isinstance(content, dict):
-            logger.error(
+            logger.error(  # pragma: no cover
                 f"Error writing resource {file_path}: "
                 f"content is a dict, expected string. Keys: {list(content.keys())}"
             )
-            raise HTTPException(
+            raise HTTPException(  # pragma: no cover
                 status_code=400,
                 detail="content must be a string, not a dict. "
                 "Ensure request body is sent as raw string content, not JSON object.",
@@ -171,21 +185,17 @@ async def write_resource(
         else:
             content_str = str(content)
 
-        # Get full file path
-        full_path = Path(f"{config.home}/{file_path}")
-
-        # Ensure parent directory exists
-        full_path.parent.mkdir(parents=True, exist_ok=True)
-
-        # Write content to file
-        checksum = await file_service.write_file(full_path, content_str)
+        # Cloud compatibility: do not assume a local filesystem path structure.
+        # Delegate directory creation + writes to the configured FileService (local or S3).
+        await file_service.ensure_directory(Path(file_path).parent)
+        checksum = await file_service.write_file(file_path, content_str)
 
         # Get file info
-        file_stats = file_service.file_stats(full_path)
+        file_metadata = await file_service.get_file_metadata(file_path)
 
         # Determine file details
         file_name = Path(file_path).name
-        content_type = file_service.content_type(full_path)
+        content_type = file_service.content_type(file_path)
 
         entity_type = "canvas" if file_path.endswith(".canvas") else "file"
 
@@ -202,7 +212,7 @@ async def write_resource(
                     "content_type": content_type,
                     "file_path": file_path,
                     "checksum": checksum,
-                    "updated_at": datetime.fromtimestamp(file_stats.st_mtime).astimezone(),
+                    "updated_at": file_metadata.modified_at,
                 },
             )
             status_code = 200
@@ -214,8 +224,8 @@ async def write_resource(
                 content_type=content_type,
                 file_path=file_path,
                 checksum=checksum,
-                created_at=datetime.fromtimestamp(file_stats.st_ctime).astimezone(),
-                updated_at=datetime.fromtimestamp(file_stats.st_mtime).astimezone(),
+                created_at=file_metadata.created_at,
+                updated_at=file_metadata.modified_at,
             )
             entity = await entity_repository.add(entity)
             status_code = 201
@@ -229,9 +239,9 @@ async def write_resource(
             content={
                 "file_path": file_path,
                 "checksum": checksum,
-                "size": file_stats.st_size,
-                "created_at": file_stats.st_ctime,
-                "modified_at": file_stats.st_mtime,
+                "size": file_metadata.size,
+                "created_at": file_metadata.created_at.timestamp(),
+                "modified_at": file_metadata.modified_at.timestamp(),
             },
         )
     except Exception as e:  # pragma: no cover

basic_memory/api/routers/utils.py

@@ -24,11 +24,30 @@ async def to_graph_context(
     page: Optional[int] = None,
     page_size: Optional[int] = None,
 ):
+    # First pass: collect all entity IDs needed for relations
+    entity_ids_needed: set[int] = set()
+    for context_item in context_result.results:
+        for item in (
+            [context_item.primary_result] + context_item.observations + context_item.related_results
+        ):
+            if item.type == SearchItemType.RELATION:
+                if item.from_id:  # pyright: ignore
+                    entity_ids_needed.add(item.from_id)  # pyright: ignore
+                if item.to_id:
+                    entity_ids_needed.add(item.to_id)
+
+    # Batch fetch all entities at once
+    entity_lookup: dict[int, str] = {}
+    if entity_ids_needed:
+        entities = await entity_repository.find_by_ids(list(entity_ids_needed))
+        entity_lookup = {e.id: e.title for e in entities}
+
     # Helper function to convert items to summaries
-    async def to_summary(item: SearchIndexRow | ContextResultRow):
+    def to_summary(item: SearchIndexRow | ContextResultRow):
         match item.type:
             case SearchItemType.ENTITY:
                 return EntitySummary(
+                    entity_id=item.id,
                     title=item.title,  # pyright: ignore
                     permalink=item.permalink,
                     content=item.content,
@@ -37,6 +56,8 @@ async def to_graph_context(
                 )
             case SearchItemType.OBSERVATION:
                 return ObservationSummary(
+                    observation_id=item.id,
+                    entity_id=item.entity_id,  # pyright: ignore
                     title=item.title,  # pyright: ignore
                     file_path=item.file_path,
                     category=item.category,  # pyright: ignore
@@ -45,15 +66,19 @@ async def to_graph_context(
                     created_at=item.created_at,
                 )
             case SearchItemType.RELATION:
-                from_entity = await entity_repository.find_by_id(item.from_id)  # pyright: ignore
-                to_entity = await entity_repository.find_by_id(item.to_id) if item.to_id else None
+                from_title = entity_lookup.get(item.from_id) if item.from_id else None  # pyright: ignore
+                to_title = entity_lookup.get(item.to_id) if item.to_id else None
                 return RelationSummary(
+                    relation_id=item.id,
+                    entity_id=item.entity_id,  # pyright: ignore
                     title=item.title,  # pyright: ignore
                     file_path=item.file_path,
                     permalink=item.permalink,  # pyright: ignore
                     relation_type=item.relation_type,  # pyright: ignore
-                    from_entity=from_entity.title if from_entity else None,
-                    to_entity=to_entity.title if to_entity else None,
+                    from_entity=from_title,
+                    from_entity_id=item.from_id,  # pyright: ignore
+                    to_entity=to_title,
+                    to_entity_id=item.to_id,
                     created_at=item.created_at,
                 )
             case _:  # pragma: no cover
@@ -63,23 +88,19 @@ async def to_graph_context(
     hierarchical_results = []
     for context_item in context_result.results:
         # Process primary result
-        primary_result = await to_summary(context_item.primary_result)
+        primary_result = to_summary(context_item.primary_result)
 
-        # Process observations
-        observations = []
-        for obs in context_item.observations:
-            observations.append(await to_summary(obs))
+        # Process observations (always ObservationSummary, validated by context_service)
+        observations = [to_summary(obs) for obs in context_item.observations]
 
         # Process related results
-        related = []
-        for rel in context_item.related_results:
-            related.append(await to_summary(rel))
+        related = [to_summary(rel) for rel in context_item.related_results]
 
         # Add to hierarchical results
         hierarchical_results.append(
             ContextResult(
                 primary_result=primary_result,
-                observations=observations,
+                observations=observations,  # pyright: ignore[reportArgumentType]
                 related_results=related,
             )
         )
@@ -111,6 +132,21 @@ async def to_search_results(entity_service: EntityService, results: List[SearchI
     search_results = []
     for r in results:
         entities = await entity_service.get_entities_by_id([r.entity_id, r.from_id, r.to_id])  # pyright: ignore
+
+        # Determine which IDs to set based on type
+        entity_id = None
+        observation_id = None
+        relation_id = None
+
+        if r.type == SearchItemType.ENTITY:
+            entity_id = r.id
+        elif r.type == SearchItemType.OBSERVATION:
+            observation_id = r.id
+            entity_id = r.entity_id  # Parent entity
+        elif r.type == SearchItemType.RELATION:
+            relation_id = r.id
+            entity_id = r.entity_id  # Parent entity
+
         search_results.append(
             SearchResult(
                 title=r.title,  # pyright: ignore
@@ -121,6 +157,9 @@ async def to_search_results(entity_service: EntityService, results: List[SearchI
                 content=r.content,
                 file_path=r.file_path,
                 metadata=r.metadata,
+                entity_id=entity_id,
+                observation_id=observation_id,
+                relation_id=relation_id,
                 category=r.category,
                 from_entity=entities[0].permalink if entities else None,
                 to_entity=entities[1].permalink if len(entities) > 1 else None,

basic_memory/api/v2/__init__.py

@@ -0,0 +1,35 @@
+"""API v2 module - ID-based entity references.
+
+Version 2 of the Basic Memory API uses integer entity IDs as the primary
+identifier for improved performance and stability.
+
+Key changes from v1:
+- Entity lookups use integer IDs instead of paths/permalinks
+- Direct database queries instead of cascading resolution
+- Stable references that don't change with file moves
+- Better caching support
+
+All v2 routers are registered with the /v2 prefix.
+"""
+
+from basic_memory.api.v2.routers import (
+    knowledge_router,
+    memory_router,
+    project_router,
+    resource_router,
+    search_router,
+    directory_router,
+    prompt_router,
+    importer_router,
+)
+
+__all__ = [
+    "knowledge_router",
+    "memory_router",
+    "project_router",
+    "resource_router",
+    "search_router",
+    "directory_router",
+    "prompt_router",
+    "importer_router",
+]

basic_memory/api/v2/routers/__init__.py

@@ -0,0 +1,21 @@
+"""V2 API routers."""
+
+from basic_memory.api.v2.routers.knowledge_router import router as knowledge_router
+from basic_memory.api.v2.routers.project_router import router as project_router
+from basic_memory.api.v2.routers.memory_router import router as memory_router
+from basic_memory.api.v2.routers.search_router import router as search_router
+from basic_memory.api.v2.routers.resource_router import router as resource_router
+from basic_memory.api.v2.routers.directory_router import router as directory_router
+from basic_memory.api.v2.routers.prompt_router import router as prompt_router
+from basic_memory.api.v2.routers.importer_router import router as importer_router
+
+__all__ = [
+    "knowledge_router",
+    "project_router",
+    "memory_router",
+    "search_router",
+    "resource_router",
+    "directory_router",
+    "prompt_router",
+    "importer_router",
+]

basic_memory/api/v2/routers/directory_router.py

@@ -0,0 +1,93 @@
+"""V2 Directory Router - ID-based directory tree operations.
+
+This router provides directory structure browsing for projects using
+external_id UUIDs instead of name-based identifiers.
+
+Key improvements:
+- 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, Path
+
+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: 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: Project external UUID
+
+    Returns:
+        DirectoryNode representing the root of the hierarchical tree structure
+    """
+    # Get a hierarchical directory tree for the specific project
+    tree = await directory_service.get_directory_tree()
+
+    # Return the hierarchical tree
+    return tree
+
+
+@router.get("/structure", response_model=DirectoryNode, response_model_exclude_none=True)
+async def get_directory_structure(
+    directory_service: DirectoryServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+):
+    """Get folder structure for navigation (no files).
+
+    Optimized endpoint for folder tree navigation. Returns only directory nodes
+    without file metadata. For full tree with files, use /directory/tree.
+
+    Args:
+        directory_service: Service for directory operations
+        project_id: Project external UUID
+
+    Returns:
+        DirectoryNode tree containing only folders (type="directory")
+    """
+    structure = await directory_service.get_directory_structure()
+    return structure
+
+
+@router.get("/list", response_model=List[DirectoryNode], response_model_exclude_none=True)
+async def list_directory(
+    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(
+        None, description="Glob pattern for filtering file names"
+    ),
+):
+    """List directory contents with filtering and depth control.
+
+    Args:
+        directory_service: Service for directory operations
+        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*")
+
+    Returns:
+        List of DirectoryNode objects matching the criteria
+    """
+    # Get directory listing with filtering
+    nodes = await directory_service.list_directory(
+        dir_name=dir_name,
+        depth=depth,
+        file_name_glob=file_name_glob,
+    )
+
+    return nodes