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

basic_memory/api/routers/__init__.py

@@ -1,8 +1,11 @@
 """API routers."""
 
 from . import knowledge_router as knowledge
+from . import management_router as management
 from . import memory_router as memory
+from . import project_router as project
 from . import resource_router as resource
 from . import search_router as search
+from . import prompt_router as prompt
 
-__all__ = ["knowledge", "memory", "resource", "search"]
+__all__ = ["knowledge", "management", "memory", "project", "resource", "search", "prompt"]

basic_memory/api/routers/directory_router.py

@@ -0,0 +1,84 @@
+"""Router for directory tree operations."""
+
+from typing import List, Optional
+
+from fastapi import APIRouter, Query
+
+from basic_memory.deps import DirectoryServiceDep, ProjectIdDep
+from basic_memory.schemas.directory import DirectoryNode
+
+router = APIRouter(prefix="/directory", tags=["directory"])
+
+
+@router.get("/tree", response_model=DirectoryNode, response_model_exclude_none=True)
+async def get_directory_tree(
+    directory_service: DirectoryServiceDep,
+    project_id: ProjectIdDep,
+):
+    """Get hierarchical directory structure from the knowledge base.
+
+    Args:
+        directory_service: Service for directory operations
+        project_id: ID of the current project
+
+    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: DirectoryServiceDep,
+    project_id: ProjectIdDep,
+):
+    """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: ID of the current project
+
+    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: DirectoryServiceDep,
+    project_id: ProjectIdDep,
+    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: ID of the current project
+        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

basic_memory/api/routers/importer_router.py

@@ -0,0 +1,152 @@
+"""Import router for Basic Memory API."""
+
+import json
+import logging
+
+from fastapi import APIRouter, Form, HTTPException, UploadFile, status
+
+from basic_memory.deps import (
+    ChatGPTImporterDep,
+    ClaudeConversationsImporterDep,
+    ClaudeProjectsImporterDep,
+    MemoryJsonImporterDep,
+)
+from basic_memory.importers import Importer
+from basic_memory.schemas.importer import (
+    ChatImportResult,
+    EntityImportResult,
+    ProjectImportResult,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/import", tags=["import"])
+
+
+@router.post("/chatgpt", response_model=ChatImportResult)
+async def import_chatgpt(
+    importer: ChatGPTImporterDep,
+    file: UploadFile,
+    folder: str = Form("conversations"),
+) -> ChatImportResult:
+    """Import conversations from ChatGPT JSON export.
+
+    Args:
+        file: The ChatGPT conversations.json file.
+        folder: The folder to place the files in.
+        markdown_processor: MarkdownProcessor instance.
+
+    Returns:
+        ChatImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    return await import_file(importer, file, folder)
+
+
+@router.post("/claude/conversations", response_model=ChatImportResult)
+async def import_claude_conversations(
+    importer: ClaudeConversationsImporterDep,
+    file: UploadFile,
+    folder: str = Form("conversations"),
+) -> ChatImportResult:
+    """Import conversations from Claude conversations.json export.
+
+    Args:
+        file: The Claude conversations.json file.
+        folder: The folder to place the files in.
+        markdown_processor: MarkdownProcessor instance.
+
+    Returns:
+        ChatImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    return await import_file(importer, file, folder)
+
+
+@router.post("/claude/projects", response_model=ProjectImportResult)
+async def import_claude_projects(
+    importer: ClaudeProjectsImporterDep,
+    file: UploadFile,
+    folder: str = Form("projects"),
+) -> ProjectImportResult:
+    """Import projects from Claude projects.json export.
+
+    Args:
+        file: The Claude projects.json file.
+        base_folder: The base folder to place the files in.
+        markdown_processor: MarkdownProcessor instance.
+
+    Returns:
+        ProjectImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    return await import_file(importer, file, folder)
+
+
+@router.post("/memory-json", response_model=EntityImportResult)
+async def import_memory_json(
+    importer: MemoryJsonImporterDep,
+    file: UploadFile,
+    folder: str = Form("conversations"),
+) -> EntityImportResult:
+    """Import entities and relations from a memory.json file.
+
+    Args:
+        file: The memory.json file.
+        destination_folder: Optional destination folder within the project.
+        markdown_processor: MarkdownProcessor instance.
+
+    Returns:
+        EntityImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    try:
+        file_data = []
+        file_bytes = await file.read()
+        file_str = file_bytes.decode("utf-8")
+        for line in file_str.splitlines():
+            json_data = json.loads(line)
+            file_data.append(json_data)
+
+        result = await importer.import_data(file_data, folder)
+        if not result.success:  # pragma: no cover
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=result.error_message or "Import failed",
+            )
+    except Exception as e:
+        logger.exception("Import failed")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Import failed: {str(e)}",
+        )
+    return result
+
+
+async def import_file(importer: Importer, file: UploadFile, destination_folder: str):
+    try:
+        # Process file
+        json_data = json.load(file.file)
+        result = await importer.import_data(json_data, destination_folder)
+        if not result.success:  # pragma: no cover
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=result.error_message or "Import failed",
+            )
+
+        return result
+
+    except Exception as e:
+        logger.exception("Import failed")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Import failed: {str(e)}",
+        )

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
 
@@ -10,6 +17,11 @@ from basic_memory.deps import (
     get_search_service,
     SearchServiceDep,
     LinkResolverDep,
+    ProjectPathDep,
+    FileServiceDep,
+    ProjectConfigDep,
+    AppConfigDep,
+    SyncServiceDep,
 )
 from basic_memory.schemas import (
     EntityListResponse,
@@ -17,10 +29,35 @@ from basic_memory.schemas import (
     DeleteEntitiesResponse,
     DeleteEntitiesRequest,
 )
+from basic_memory.schemas.request import EditEntityRequest, MoveEntityRequest
 from basic_memory.schemas.base import Permalink, Entity
-from basic_memory.services.exceptions import EntityNotFoundError
 
-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:
+    """Background task to resolve relations for a specific entity.
+
+    This runs asynchronously after the API response is sent, preventing
+    long delays when creating entities with many relations.
+    """
+    try:
+        # Only resolve relations for the newly created entity
+        await sync_service.resolve_relations(entity_id=entity_id)
+        logger.debug(
+            f"Background: Resolved relations for entity {entity_permalink} (id={entity_id})"
+        )
+    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}"
+        )
+
 
 ## Create endpoints
 
@@ -33,7 +70,9 @@ async def create_entity(
     search_service: SearchServiceDep,
 ) -> EntityResponse:
     """Create an entity."""
-    logger.info(f"request: create_entity with data={data}")
+    logger.info(
+        "API request", endpoint="create_entity", entity_type=data.entity_type, title=data.title
+    )
 
     entity = await entity_service.create_entity(data)
 
@@ -41,25 +80,38 @@ async def create_entity(
     await search_service.index_entity(entity, background_tasks=background_tasks)
     result = EntityResponse.model_validate(entity)
 
-    logger.info(f"response: create_entity with result={result}")
+    logger.info(
+        f"API response: endpoint='create_entity' title={result.title}, permalink={result.permalink}, status_code=201"
+    )
     return result
 
 
 @router.put("/entities/{permalink:path}", response_model=EntityResponse)
 async def create_or_update_entity(
+    project: ProjectPathDep,
     permalink: Permalink,
     data: Entity,
     response: Response,
     background_tasks: BackgroundTasks,
     entity_service: EntityServiceDep,
     search_service: SearchServiceDep,
+    file_service: FileServiceDep,
+    sync_service: SyncServiceDep,
 ) -> EntityResponse:
     """Create or update an entity. If entity exists, it will be updated, otherwise created."""
-    logger.info(f"request: create_or_update_entity with permalink={permalink}, data={data}")
+    logger.info(
+        f"API request: create_or_update_entity for {project=}, {permalink=}, {data.entity_type=}, {data.title=}"
+    )
 
     # Validate permalink matches
     if data.permalink != permalink:
-        raise HTTPException(status_code=400, detail="Entity permalink must match URL path")
+        logger.warning(
+            f"API validation error: creating/updating entity with permalink mismatch - url={permalink}, data={data.permalink}",
+        )
+        raise HTTPException(
+            status_code=400,
+            detail=f"Entity permalink {data.permalink} must match URL path: '{permalink}'",
+        )
 
     # Try create_or_update operation
     entity, created = await entity_service.create_or_update_entity(data)
@@ -67,36 +119,141 @@ async def create_or_update_entity(
 
     # reindex
     await search_service.index_entity(entity, background_tasks=background_tasks)
+
+    # Schedule relation resolution as a background task for new entities
+    # This prevents blocking the API response while resolving potentially many relations
+    if created:
+        background_tasks.add_task(
+            resolve_relations_background, sync_service, entity.id, entity.permalink or ""
+        )
+
     result = EntityResponse.model_validate(entity)
 
     logger.info(
-        f"response: create_or_update_entity with result={result}, status_code={response.status_code}"
+        f"API response: {result.title=}, {result.permalink=}, {created=}, status_code={response.status_code}"
     )
     return result
 
 
+@router.patch("/entities/{identifier:path}", response_model=EntityResponse)
+async def edit_entity(
+    identifier: str,
+    data: EditEntityRequest,
+    background_tasks: BackgroundTasks,
+    entity_service: EntityServiceDep,
+    search_service: SearchServiceDep,
+) -> EntityResponse:
+    """Edit an existing entity using various operations like append, prepend, find_replace, or replace_section.
+
+    This endpoint allows for targeted edits without requiring the full entity content.
+    """
+    logger.info(
+        f"API request: endpoint='edit_entity', identifier='{identifier}', operation='{data.operation}'"
+    )
+
+    try:
+        # Edit the entity using the service
+        entity = await entity_service.edit_entity(
+            identifier=identifier,
+            operation=data.operation,
+            content=data.content,
+            section=data.section,
+            find_text=data.find_text,
+            expected_replacements=data.expected_replacements,
+        )
+
+        # Reindex the updated entity
+        await search_service.index_entity(entity, background_tasks=background_tasks)
+
+        # Return the updated entity response
+        result = EntityResponse.model_validate(entity)
+
+        logger.info(
+            "API response",
+            endpoint="edit_entity",
+            identifier=identifier,
+            operation=data.operation,
+            permalink=result.permalink,
+            status_code=200,
+        )
+
+        return result
+
+    except Exception as e:
+        logger.error(f"Error editing entity: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/move")
+async def move_entity(
+    data: MoveEntityRequest,
+    background_tasks: BackgroundTasks,
+    entity_service: EntityServiceDep,
+    project_config: ProjectConfigDep,
+    app_config: AppConfigDep,
+    search_service: SearchServiceDep,
+) -> EntityResponse:
+    """Move an entity to a new file location with project consistency.
+
+    This endpoint moves a note to a different path while maintaining project
+    consistency and optionally updating permalinks based on configuration.
+    """
+    logger.info(
+        f"API request: endpoint='move_entity', identifier='{data.identifier}', destination='{data.destination_path}'"
+    )
+
+    try:
+        # Move the entity using the service
+        moved_entity = await entity_service.move_entity(
+            identifier=data.identifier,
+            destination_path=data.destination_path,
+            project_config=project_config,
+            app_config=app_config,
+        )
+
+        # Get the moved entity to reindex it
+        entity = await entity_service.link_resolver.resolve_link(data.destination_path)
+        if entity:
+            await search_service.index_entity(entity, background_tasks=background_tasks)
+
+        logger.info(
+            "API response",
+            endpoint="move_entity",
+            identifier=data.identifier,
+            destination=data.destination_path,
+            status_code=200,
+        )
+        result = EntityResponse.model_validate(moved_entity)
+        return result
+
+    except Exception as e:
+        logger.error(f"Error moving entity: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+
 ## Read endpoints
 
 
-@router.get("/entities/{permalink:path}", response_model=EntityResponse)
+@router.get("/entities/{identifier:path}", response_model=EntityResponse)
 async def get_entity(
     entity_service: EntityServiceDep,
-    permalink: str,
+    link_resolver: LinkResolverDep,
+    identifier: str,
 ) -> EntityResponse:
-    """Get a specific entity by ID.
+    """Get a specific entity by file path or permalink..
 
     Args:
-        permalink: Entity path ID
-        content: If True, include full file content
+        identifier: Entity file path or permalink
         :param entity_service: EntityService
+        :param link_resolver: LinkResolver
     """
-    logger.info(f"request: get_entity with permalink={permalink}")
-    try:
-        entity = await entity_service.get_by_permalink(permalink)
-        result = EntityResponse.model_validate(entity)
-        return result
-    except EntityNotFoundError:
-        raise HTTPException(status_code=404, detail=f"Entity with {permalink} not found")
+    logger.info(f"request: get_entity with identifier={identifier}")
+    entity = await link_resolver.resolve_link(identifier)
+    if not entity:
+        raise HTTPException(status_code=404, detail=f"Entity {identifier} not found")
+
+    result = EntityResponse.model_validate(entity)
+    return result
 
 
 @router.get("/entities", response_model=EntityListResponse)
@@ -133,10 +290,10 @@ async def delete_entity(
         return DeleteEntitiesResponse(deleted=False)
 
     # Delete the entity
-    deleted = await entity_service.delete_entity(entity.permalink)
+    deleted = await entity_service.delete_entity(entity.permalink or entity.id)
 
-    # Remove from search index
-    background_tasks.add_task(search_service.delete_by_permalink, entity.permalink)
+    # Remove from search index (entity, observations, and relations)
+    background_tasks.add_task(search_service.handle_delete, entity)
 
     result = DeleteEntitiesResponse(deleted=deleted)
     return result

basic_memory/api/routers/management_router.py

@@ -0,0 +1,80 @@
+"""Management router for basic-memory API."""
+
+import asyncio
+
+from fastapi import APIRouter, Request
+from loguru import logger
+from pydantic import BaseModel
+
+from basic_memory.config import ConfigManager
+from basic_memory.deps import SyncServiceDep, ProjectRepositoryDep
+
+router = APIRouter(prefix="/management", tags=["management"])
+
+
+class WatchStatusResponse(BaseModel):
+    """Response model for watch status."""
+
+    running: bool
+    """Whether the watch service is currently running."""
+
+
+@router.get("/watch/status", response_model=WatchStatusResponse)
+async def get_watch_status(request: Request) -> WatchStatusResponse:
+    """Get the current status of the watch service."""
+    return WatchStatusResponse(
+        running=request.app.state.watch_task is not None and not request.app.state.watch_task.done()
+    )
+
+
+@router.post("/watch/start", response_model=WatchStatusResponse)
+async def start_watch_service(
+    request: Request, project_repository: ProjectRepositoryDep, sync_service: SyncServiceDep
+) -> WatchStatusResponse:
+    """Start the watch service if it's not already running."""
+
+    # needed because of circular imports from sync -> app
+    from basic_memory.sync import WatchService
+    from basic_memory.sync.background_sync import create_background_sync_task
+
+    if request.app.state.watch_task is not None and not request.app.state.watch_task.done():
+        # Watch service is already running
+        return WatchStatusResponse(running=True)
+
+    app_config = ConfigManager().config
+
+    # Create and start a new watch service
+    logger.info("Starting watch service via management API")
+
+    # Get services needed for the watch task
+    watch_service = WatchService(
+        app_config=app_config,
+        project_repository=project_repository,
+    )
+
+    # Create and store the task
+    watch_task = create_background_sync_task(sync_service, watch_service)
+    request.app.state.watch_task = watch_task
+
+    return WatchStatusResponse(running=True)
+
+
+@router.post("/watch/stop", response_model=WatchStatusResponse)
+async def stop_watch_service(request: Request) -> WatchStatusResponse:  # pragma: no cover
+    """Stop the watch service if it's running."""
+    if request.app.state.watch_task is None or request.app.state.watch_task.done():
+        # Watch service is not running
+        return WatchStatusResponse(running=False)
+
+    # Cancel the running task
+    logger.info("Stopping watch service via management API")
+    request.app.state.watch_task.cancel()
+
+    # Wait for it to be properly cancelled
+    try:
+        await request.app.state.watch_task
+    except asyncio.CancelledError:
+        pass
+
+    request.app.state.watch_task = None
+    return WatchStatusResponse(running=False)