basic-memory 0.12.3__py3-none-any.whl → 0.13.0b2__py3-none-any.whl

basic_memory/mcp/tools/project_management.py

@@ -0,0 +1,300 @@
+"""Project management tools for Basic Memory MCP server.
+
+These tools allow users to switch between projects, list available projects,
+and manage project context during conversations.
+"""
+
+from fastmcp import Context
+from loguru import logger
+
+from basic_memory.config import get_project_config
+from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_session import session, add_project_metadata
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.utils import call_get, call_put, call_post, call_delete
+from basic_memory.schemas import ProjectInfoResponse
+from basic_memory.schemas.project_info import ProjectList, ProjectStatusResponse, ProjectInfoRequest
+
+
+@mcp.tool()
+async def list_projects(ctx: Context | None = None) -> str:
+    """List all available projects with their status.
+
+    Shows all Basic Memory projects that are available, indicating which one
+    is currently active and which is the default.
+
+    Returns:
+        Formatted list of projects with status indicators
+
+    Example:
+        list_projects()
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info("Listing all available projects")
+
+    # Get projects from API
+    response = await call_get(client, "/projects/projects")
+    project_list = ProjectList.model_validate(response.json())
+
+    current = session.get_current_project()
+
+    result = "Available projects:\n"
+
+    for project in project_list.projects:
+        indicators = []
+        if project.name == current:
+            indicators.append("current")
+        if project.is_default:
+            indicators.append("default")
+
+        if indicators:
+            result += f"• {project.name} ({', '.join(indicators)})\n"
+        else:
+            result += f"• {project.name}\n"
+
+    return add_project_metadata(result, current)
+
+
+@mcp.tool()
+async def switch_project(project_name: str, ctx: Context | None = None) -> str:
+    """Switch to a different project context.
+
+    Changes the active project context for all subsequent tool calls.
+    Shows a project summary after switching successfully.
+
+    Args:
+        project_name: Name of the project to switch to
+
+    Returns:
+        Confirmation message with project summary
+
+    Example:
+        switch_project("work-notes")
+        switch_project("personal-journal")
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info(f"Switching to project: {project_name}")
+
+    current_project = session.get_current_project()
+    try:
+        # Validate project exists by getting project list
+        response = await call_get(client, "/projects/projects")
+        project_list = ProjectList.model_validate(response.json())
+
+        # Check if project exists
+        project_exists = any(p.name == project_name for p in project_list.projects)
+        if not project_exists:
+            available_projects = [p.name for p in project_list.projects]
+            return f"Error: Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
+
+        # Switch to the project
+        session.set_current_project(project_name)
+        current_project = session.get_current_project()
+        project_config = get_project_config(current_project)
+
+        # Get project info to show summary
+        try:
+            response = await call_get(client, f"{project_config.project_url}/project/info")
+            project_info = ProjectInfoResponse.model_validate(response.json())
+
+            result = f"✓ Switched to {project_name} project\n\n"
+            result += "Project Summary:\n"
+            result += f"• {project_info.statistics.total_entities} entities\n"
+            result += f"• {project_info.statistics.total_observations} observations\n"
+            result += f"• {project_info.statistics.total_relations} relations\n"
+
+        except Exception as e:
+            # If we can't get project info, still confirm the switch
+            logger.warning(f"Could not get project info for {project_name}: {e}")
+            result = f"✓ Switched to {project_name} project\n\n"
+            result += "Project summary unavailable.\n"
+
+        return add_project_metadata(result, project_name)
+
+    except Exception as e:
+        logger.error(f"Error switching to project {project_name}: {e}")
+        # Revert to previous project on error
+        session.set_current_project(current_project)
+        raise e
+
+
+@mcp.tool()
+async def get_current_project(ctx: Context | None = None) -> str:
+    """Show the currently active project and basic stats.
+
+    Displays which project is currently active and provides basic information
+    about it.
+
+    Returns:
+        Current project name and basic statistics
+
+    Example:
+        get_current_project()
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info("Getting current project information")
+
+    current_project = session.get_current_project()
+    project_config = get_project_config(current_project)
+    result = f"Current project: {current_project}\n\n"
+
+    # get project stats
+    response = await call_get(client, f"{project_config.project_url}/project/info")
+    project_info = ProjectInfoResponse.model_validate(response.json())
+
+    result += f"• {project_info.statistics.total_entities} entities\n"
+    result += f"• {project_info.statistics.total_observations} observations\n"
+    result += f"• {project_info.statistics.total_relations} relations\n"
+
+    default_project = session.get_default_project()
+    if current_project != default_project:
+        result += f"• Default project: {default_project}\n"
+
+    return add_project_metadata(result, current_project)
+
+
+@mcp.tool()
+async def set_default_project(project_name: str, ctx: Context | None = None) -> str:
+    """Set default project in config. Requires restart to take effect.
+
+    Updates the configuration to use a different default project. This change
+    only takes effect after restarting the Basic Memory server.
+
+    Args:
+        project_name: Name of the project to set as default
+
+    Returns:
+        Confirmation message about config update
+
+    Example:
+        set_default_project("work-notes")
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info(f"Setting default project to: {project_name}")
+
+    # Call API to set default project
+    response = await call_put(client, f"/projects/{project_name}/default")
+    status_response = ProjectStatusResponse.model_validate(response.json())
+
+    result = f"✓ {status_response.message}\n\n"
+    result += "Restart Basic Memory for this change to take effect:\n"
+    result += "basic-memory mcp\n"
+
+    if status_response.old_project:
+        result += f"\nPrevious default: {status_response.old_project.name}\n"
+
+    return add_project_metadata(result, session.get_current_project())
+
+
+@mcp.tool()
+async def create_project(
+    project_name: str, project_path: str, set_default: bool = False, ctx: Context | None = None
+) -> str:
+    """Create a new Basic Memory project.
+
+    Creates a new project with the specified name and path. The project directory
+    will be created if it doesn't exist. Optionally sets the new project as default.
+
+    Args:
+        project_name: Name for the new project (must be unique)
+        project_path: File system path where the project will be stored
+        set_default: Whether to set this project as the default (optional, defaults to False)
+
+    Returns:
+        Confirmation message with project details
+
+    Example:
+        create_project("my-research", "~/Documents/research")
+        create_project("work-notes", "/home/user/work", set_default=True)
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info(f"Creating project: {project_name} at {project_path}")
+
+    # Create the project request
+    project_request = ProjectInfoRequest(
+        name=project_name, path=project_path, set_default=set_default
+    )
+
+    # Call API to create project
+    response = await call_post(client, "/projects/projects", json=project_request.model_dump())
+    status_response = ProjectStatusResponse.model_validate(response.json())
+
+    result = f"✓ {status_response.message}\n\n"
+
+    if status_response.new_project:
+        result += "Project Details:\n"
+        result += f"• Name: {status_response.new_project.name}\n"
+        result += f"• Path: {status_response.new_project.path}\n"
+
+        if set_default:
+            result += "• Set as default project\n"
+
+    result += "\nProject is now available for use.\n"
+
+    # If project was set as default, update session
+    if set_default:
+        session.set_current_project(project_name)
+
+    return add_project_metadata(result, session.get_current_project())
+
+
+@mcp.tool()
+async def delete_project(project_name: str, ctx: Context | None = None) -> str:
+    """Delete a Basic Memory project.
+
+    Removes a project from the configuration and database. This does NOT delete
+    the actual files on disk - only removes the project from Basic Memory's
+    configuration and database records.
+
+    Args:
+        project_name: Name of the project to delete
+
+    Returns:
+        Confirmation message about project deletion
+
+    Example:
+        delete_project("old-project")
+
+    Warning:
+        This action cannot be undone. The project will need to be re-added
+        to access its content through Basic Memory again.
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info(f"Deleting project: {project_name}")
+
+    current_project = session.get_current_project()
+
+    # Check if trying to delete current project
+    if project_name == current_project:
+        raise ValueError(
+            f"Cannot delete the currently active project '{project_name}'. Switch to a different project first."
+        )
+
+    # Get project info before deletion to validate it exists
+    response = await call_get(client, "/projects/projects")
+    project_list = ProjectList.model_validate(response.json())
+
+    # Check if project exists
+    project_exists = any(p.name == project_name for p in project_list.projects)
+    if not project_exists:
+        available_projects = [p.name for p in project_list.projects]
+        raise ValueError(
+            f"Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
+        )
+
+    # Call API to delete project
+    response = await call_delete(client, f"/projects/{project_name}")
+    status_response = ProjectStatusResponse.model_validate(response.json())
+
+    result = f"✓ {status_response.message}\n\n"
+
+    if status_response.old_project:
+        result += "Removed project details:\n"
+        result += f"• Name: {status_response.old_project.name}\n"
+        if hasattr(status_response.old_project, "path"):
+            result += f"• Path: {status_response.old_project.path}\n"
+
+    result += "Files remain on disk but project is no longer tracked by Basic Memory.\n"
+    result += "Re-add the project to access its content again.\n"
+
+    return add_project_metadata(result, session.get_current_project())

basic_memory/mcp/tools/read_content.py

@@ -5,17 +5,19 @@ supporting various file types including text, images, and other binary files.
 Files are read directly without any knowledge graph processing.
 """
 
+from typing import Optional
+import base64
+import io
+
 from loguru import logger
+from PIL import Image as PILImage
 
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.tools.utils import call_get
+from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.memory import memory_url_path
 
-import base64
-import io
-from PIL import Image as PILImage
-
 
 def calculate_target_params(content_length):
     """Calculate initial quality and size based on input file size"""
@@ -144,7 +146,7 @@ def optimize_image(img, content_length, max_output_bytes=350000):
 
 
 @mcp.tool(description="Read a file's raw content by path or permalink")
-async def read_content(path: str) -> dict:
+async def read_content(path: str, project: Optional[str] = None) -> dict:
     """Read a file's raw content by path or permalink.
 
     This tool provides direct access to file content in the knowledge base,
@@ -158,6 +160,7 @@ async def read_content(path: str) -> dict:
             - A regular file path (docs/example.md)
             - A memory URL (memory://docs/example)
             - A permalink (docs/example)
+        project: Optional project name to read from. If not provided, uses current active project.
 
     Returns:
         A dictionary with the file content and metadata:
@@ -175,11 +178,17 @@ async def read_content(path: str) -> dict:
 
         # Read using memory URL
         content = await read_file("memory://docs/architecture")
+
+        # Read from specific project
+        content = await read_content("docs/example.md", project="work-project")
     """
     logger.info("Reading file", path=path)
 
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
+
     url = memory_url_path(path)
-    response = await call_get(client, f"/resource/{url}")
+    response = await call_get(client, f"{project_url}/resource/{url}")
     content_type = response.headers.get("content-type", "application/octet-stream")
     content_length = int(response.headers.get("content-length", 0))
 

basic_memory/mcp/tools/read_note.py

@@ -1,6 +1,7 @@
 """Read note tool for Basic Memory MCP server."""
 
 from textwrap import dedent
+from typing import Optional
 
 from loguru import logger
 
@@ -8,13 +9,16 @@ from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.utils import call_get
+from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.memory import memory_url_path
 
 
 @mcp.tool(
     description="Read a markdown note by title or permalink.",
 )
-async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
+async def read_note(
+    identifier: str, page: int = 1, page_size: int = 10, project: Optional[str] = None
+) -> str:
     """Read a markdown note from the knowledge base.
 
     This tool finds and retrieves a note by its title, permalink, or content search,
@@ -26,6 +30,7 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
                    Can be a full memory:// URL, a permalink, a title, or search text
         page: Page number for paginated results (default: 1)
         page_size: Number of items per page (default: 10)
+        project: Optional project name to read from. If not provided, uses current active project.
 
     Returns:
         The full markdown content of the note if found, or helpful guidance if not found.
@@ -42,10 +47,17 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
 
         # Read with pagination
         read_note("Project Updates", page=2, page_size=5)
+
+        # Read from specific project
+        read_note("Meeting Notes", project="work-project")
     """
+
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
+
     # Get the file via REST API - first try direct permalink lookup
     entity_path = memory_url_path(identifier)
-    path = f"/resource/{entity_path}"
+    path = f"{project_url}/resource/{entity_path}"
     logger.info(f"Attempting to read note from URL: {path}")
 
     try:
@@ -62,14 +74,14 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
 
     # Fallback 1: Try title search via API
     logger.info(f"Search title for: {identifier}")
-    title_results = await search_notes(query=identifier, search_type="title")
+    title_results = await search_notes(query=identifier, search_type="title", project=project)
 
     if title_results and title_results.results:
         result = title_results.results[0]  # Get the first/best match
         if result.permalink:
             try:
                 # Try to fetch the content using the found permalink
-                path = f"/resource/{result.permalink}"
+                path = f"{project_url}/resource/{result.permalink}"
                 response = await call_get(
                     client, path, params={"page": page, "page_size": page_size}
                 )
@@ -86,7 +98,7 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
 
     # Fallback 2: Text search as a last resort
     logger.info(f"Title search failed, trying text search for: {identifier}")
-    text_results = await search_notes(query=identifier, search_type="text")
+    text_results = await search_notes(query=identifier, search_type="text", project=project)
 
     # We didn't find a direct match, construct a helpful error message
     if not text_results or not text_results.results:

basic_memory/mcp/tools/recent_activity.py

@@ -1,12 +1,13 @@
 """Recent activity tool for Basic Memory MCP server."""
 
-from typing import List, Union
+from typing import List, Union, Optional
 
 from loguru import logger
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
+from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.base import TimeFrame
 from basic_memory.schemas.memory import GraphContext
 from basic_memory.schemas.search import SearchItemType
@@ -31,6 +32,7 @@ async def recent_activity(
     page: int = 1,
     page_size: int = 10,
     max_related: int = 10,
+    project: Optional[str] = None,
 ) -> GraphContext:
     """Get recent activity across the knowledge base.
 
@@ -51,6 +53,7 @@ async def recent_activity(
         page: Page number of results to return (default: 1)
         page_size: Number of results to return per page (default: 10)
         max_related: Maximum number of related results to return (default: 10)
+        project: Optional project name to get activity from. If not provided, uses current active project.
 
     Returns:
         GraphContext containing:
@@ -74,6 +77,9 @@ async def recent_activity(
         # Look back further with more context
         recent_activity(type="entity", depth=2, timeframe="2 weeks ago")
 
+        # Get activity from specific project
+        recent_activity(type="entity", project="work-project")
+
     Notes:
         - Higher depth values (>3) may impact performance with large result sets
         - For focused queries, consider using build_context with a specific URI
@@ -114,9 +120,12 @@ async def recent_activity(
         # Add validated types to params
         params["type"] = [t.value for t in validated_types]  # pyright: ignore
 
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
+
     response = await call_get(
         client,
-        "/memory/recent",
+        f"{project_url}/memory/recent",
         params=params,
     )
     return GraphContext.model_validate(response.json())

basic_memory/mcp/tools/search.py

@@ -7,6 +7,7 @@ from loguru import logger
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_post
+from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.search import SearchItemType, SearchQuery, SearchResponse
 
 
@@ -21,6 +22,7 @@ async def search_notes(
     types: Optional[List[str]] = None,
     entity_types: Optional[List[str]] = None,
     after_date: Optional[str] = None,
+    project: Optional[str] = None,
 ) -> SearchResponse:
     """Search across all content in the knowledge base.
 
@@ -36,6 +38,7 @@ async def search_notes(
         types: Optional list of note types to search (e.g., ["note", "person"])
         entity_types: Optional list of entity types to filter by (e.g., ["entity", "observation"])
         after_date: Optional date filter for recent content (e.g., "1 week", "2d")
+        project: Optional project name to search in. If not provided, uses current active project.
 
     Returns:
         SearchResponse with results and pagination info
@@ -79,6 +82,9 @@ async def search_notes(
             query="docs/meeting-*",
             search_type="permalink"
         )
+
+        # Search in specific project
+        results = await search_notes("meeting notes", project="work-project")
     """
     # Create a SearchQuery object based on the parameters
     search_query = SearchQuery()
@@ -103,10 +109,13 @@ async def search_notes(
     if after_date:
         search_query.after_date = after_date
 
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
+
     logger.info(f"Searching for {search_query}")
     response = await call_post(
         client,
-        "/search/",
+        f"{project_url}/search/",
         json=search_query.model_dump(),
         params={"page": page, "page_size": page_size},
     )