basic-memory 0.14.4__py3-none-any.whl → 0.15.1__py3-none-any.whl

basic_memory/mcp/resources/project_info.py

@@ -1,19 +1,24 @@
 """Project info tool for Basic Memory MCP server."""
 
+from typing import Optional
+
 from loguru import logger
+from fastmcp import Context
 
-from basic_memory.mcp.project_session import get_active_project
-from basic_memory.mcp.async_client import client
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas import ProjectInfoResponse
 
 
 @mcp.resource(
-    uri="memory://project_info",
+    uri="memory://{project}/info",
     description="Get information and statistics about the current Basic Memory project.",
 )
-async def project_info() -> ProjectInfoResponse:
+async def project_info(
+    project: Optional[str] = None, context: Context | None = None
+) -> ProjectInfoResponse:
     """Get comprehensive information about the current Basic Memory project.
 
     This tool provides detailed statistics and status information about your
@@ -31,13 +36,22 @@ async def project_info() -> ProjectInfoResponse:
     - Monitor growth and activity over time
     - Identify potential issues like unresolved relations
 
+    Args:
+        project: Optional project name. If not provided, uses default_project
+                (if default_project_mode=true) or CLI constraint. If unknown,
+                use list_memory_projects() to discover available projects.
+        context: Optional FastMCP context for performance caching.
+
     Returns:
         Detailed project information and statistics
 
     Examples:
-        # Get information about the current project
+        # Get information about the current/default project
         info = await project_info()
 
+        # Get information about a specific project
+        info = await project_info(project="my-project")
+
         # Check entity counts
         print(f"Total entities: {info.statistics.total_entities}")
 
@@ -45,11 +59,13 @@ async def project_info() -> ProjectInfoResponse:
         print(f"Basic Memory version: {info.system.version}")
     """
     logger.info("Getting project info")
-    project_config = get_active_project()
-    project_url = project_config.project_url
 
-    # Call the API endpoint
-    response = await call_get(client, f"{project_url}/project/info")
+    async with get_client() as client:
+        project_config = await get_active_project(client, project, context)
+        project_url = project_config.permalink
+
+        # Call the API endpoint
+        response = await call_get(client, f"{project_url}/project/info")
 
-    # Convert response to ProjectInfoResponse
-    return ProjectInfoResponse.model_validate(response.json())
+        # Convert response to ProjectInfoResponse
+        return ProjectInfoResponse.model_validate(response.json())

basic_memory/mcp/server.py

@@ -2,45 +2,8 @@
 Basic Memory FastMCP server.
 """
 
-import asyncio
-from contextlib import asynccontextmanager
-from dataclasses import dataclass
-from typing import AsyncIterator, Optional, Any
-
 from fastmcp import FastMCP
 
-from basic_memory.config import ConfigManager
-from basic_memory.services.initialization import initialize_app
-
-
-@dataclass
-class AppContext:
-    watch_task: Optional[asyncio.Task]
-    migration_manager: Optional[Any] = None
-
-
-@asynccontextmanager
-async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:  # pragma: no cover
-    """ """
-    # defer import so tests can monkeypatch
-    from basic_memory.mcp.project_session import session
-
-    app_config = ConfigManager().config
-    # Initialize on startup (now returns migration_manager)
-    migration_manager = await initialize_app(app_config)
-
-    # Initialize project session with default project
-    session.initialize(app_config.default_project)
-
-    try:
-        yield AppContext(watch_task=None, migration_manager=migration_manager)
-    finally:
-        # Cleanup on shutdown - migration tasks will be cancelled automatically
-        pass
-
-
-# Create the shared server instance with custom Stytch auth
 mcp = FastMCP(
     name="Basic Memory",
-    lifespan=app_lifespan,
 )

basic_memory/mcp/tools/__init__.py

@@ -21,13 +21,13 @@ from basic_memory.mcp.tools.move_note import move_note
 from basic_memory.mcp.tools.sync_status import sync_status
 from basic_memory.mcp.tools.project_management import (
     list_memory_projects,
-    switch_project,
-    get_current_project,
-    set_default_project,
     create_memory_project,
     delete_project,
 )
 
+# ChatGPT-compatible tools
+from basic_memory.mcp.tools.chatgpt_tools import search, fetch
+
 __all__ = [
     "build_context",
     "canvas",
@@ -35,16 +35,15 @@ __all__ = [
     "delete_note",
     "delete_project",
     "edit_note",
-    "get_current_project",
+    "fetch",
     "list_directory",
     "list_memory_projects",
     "move_note",
     "read_content",
     "read_note",
     "recent_activity",
+    "search",
     "search_notes",
-    "set_default_project",
-    "switch_project",
     "sync_status",
     "view_note",
     "write_note",

basic_memory/mcp/tools/build_context.py

@@ -3,11 +3,12 @@
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
-from basic_memory.mcp.async_client import client
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.project_context import get_active_project
 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,
@@ -17,18 +18,19 @@ from basic_memory.schemas.memory import (
 
 type StringOrInt = str | int
 
+
 @mcp.tool(
     description="""Build context from a memory:// URI to continue conversations naturally.
-    
+
     Use this to follow up on previous discussions or explore related topics.
-    
+
     Memory URL Format:
-    - Use paths like "folder/note" or "memory://folder/note" 
+    - Use paths like "folder/note" or "memory://folder/note"
     - Pattern matching: "folder/*" matches all notes in folder
     - Valid characters: letters, numbers, hyphens, underscores, forward slashes
     - Avoid: double slashes (//), angle brackets (<>), quotes, pipes (|)
     - Examples: "specs/search", "projects/basic-memory", "notes/*"
-    
+
     Timeframes support natural language like:
     - "2 days ago", "last week", "today", "3 months ago"
     - Or standard formats like "7d", "24h"
@@ -36,27 +38,34 @@ type StringOrInt = str | int
 )
 async def build_context(
     url: MemoryUrl,
+    project: Optional[str] = None,
     depth: Optional[StringOrInt] = 1,
     timeframe: Optional[TimeFrame] = "7d",
     page: int = 1,
     page_size: int = 10,
     max_related: int = 10,
-    project: Optional[str] = None,
+    context: Context | None = None,
 ) -> GraphContext:
-    """Get context needed to continue a discussion.
+    """Get context needed to continue a discussion within a specific project.
 
     This tool enables natural continuation of discussions by loading relevant context
     from memory:// URIs. It uses pattern matching to find relevant content and builds
     a rich context graph of related information.
 
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
     Args:
+        project: Project name to build context from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         url: memory:// URI pointing to discussion content (e.g. memory://specs/search)
         depth: How many relation hops to traverse (1-3 recommended for performance)
         timeframe: How far back to look. Supports natural language like "2 days ago", "last week"
         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 build context from. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         GraphContext containing:
@@ -66,68 +75,70 @@ async def build_context(
 
     Examples:
         # Continue a specific discussion
-        build_context("memory://specs/search")
+        build_context("my-project", "memory://specs/search")
 
         # Get deeper context about a component
-        build_context("memory://components/memory-service", depth=2)
+        build_context("work-docs", "memory://components/memory-service", depth=2)
 
         # Look at recent changes to a specification
-        build_context("memory://specs/document-format", timeframe="today")
+        build_context("research", "memory://specs/document-format", timeframe="today")
 
         # Research the history of a feature
-        build_context("memory://features/knowledge-graph", timeframe="3 months ago")
+        build_context("dev-notes", "memory://features/knowledge-graph", timeframe="3 months ago")
 
-        # Build context from specific project
-        build_context("memory://specs/search", project="work-project")
+    Raises:
+        ToolError: If project doesn't exist or depth parameter is invalid
     """
-    logger.info(f"Building context from {url}")
-    
+    logger.info(f"Building context from {url} in project {project}")
+
     # Convert string depth to integer if needed
     if isinstance(depth, str):
         try:
             depth = int(depth)
         except ValueError:
             from mcp.server.fastmcp.exceptions import ToolError
+
             raise ToolError(f"Invalid depth parameter: '{depth}' is not a valid integer")
-    
+
     # URL is already validated and normalized by MemoryUrl type annotation
 
-    # Get the active project first to check project-specific sync status
-    active_project = get_active_project(project)
-
-    # Check migration status and wait briefly if needed
-    from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
-
-    migration_status = await wait_for_migration_or_return_status(
-        timeout=5.0, project_name=active_project.name
-    )
-    if migration_status:  # pragma: no cover
-        # Return a proper GraphContext with status message
-        from basic_memory.schemas.memory import MemoryMetadata
-        from datetime import datetime
-
-        return GraphContext(
-            results=[],
-            metadata=MemoryMetadata(
-                depth=depth or 1,
-                timeframe=timeframe,
-                generated_at=datetime.now().astimezone(),
-                primary_count=0,
-                related_count=0,
-                uri=migration_status,  # Include status in metadata
-            ),
+    async with get_client() as client:
+        # Get the active project using the new stateless approach
+        active_project = await get_active_project(client, project, context)
+
+        # Check migration status and wait briefly if needed
+        from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
+
+        migration_status = await wait_for_migration_or_return_status(
+            timeout=5.0, project_name=active_project.name
+        )
+        if migration_status:  # pragma: no cover
+            # Return a proper GraphContext with status message
+            from basic_memory.schemas.memory import MemoryMetadata
+            from datetime import datetime
+
+            return GraphContext(
+                results=[],
+                metadata=MemoryMetadata(
+                    depth=depth or 1,
+                    timeframe=timeframe,
+                    generated_at=datetime.now().astimezone(),
+                    primary_count=0,
+                    related_count=0,
+                    uri=migration_status,  # Include status in metadata
+                ),
+            )
+        project_url = active_project.project_url
+
+        response = await call_get(
+            client,
+            f"{project_url}/memory/{memory_url_path(url)}",
+            params={
+                "depth": depth,
+                "timeframe": timeframe,
+                "page": page,
+                "page_size": page_size,
+                "max_related": max_related,
+            },
         )
-    project_url = active_project.project_url
-
-    response = await call_get(
-        client,
-        f"{project_url}/memory/{memory_url_path(url)}",
-        params={
-            "depth": depth,
-            "timeframe": timeframe,
-            "page": page,
-            "page_size": page_size,
-            "max_related": max_related,
-        },
-    )
-    return GraphContext.model_validate(response.json())
+        return GraphContext.model_validate(response.json())

basic_memory/mcp/tools/canvas.py

@@ -7,11 +7,12 @@ import json
 from typing import Dict, List, Any, Optional
 
 from loguru import logger
+from fastmcp import Context
 
-from basic_memory.mcp.async_client import client
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put
-from basic_memory.mcp.project_session import get_active_project
 
 
 @mcp.tool(
@@ -23,21 +24,28 @@ async def canvas(
     title: str,
     folder: str,
     project: Optional[str] = None,
+    context: Context | None = None,
 ) -> str:
     """Create an Obsidian canvas file with the provided nodes and edges.
 
     This tool creates a .canvas file compatible with Obsidian's Canvas feature,
     allowing visualization of relationships between concepts or documents.
 
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
     For the full JSON Canvas 1.0 specification, see the 'spec://canvas' resource.
 
     Args:
+        project: Project name to create canvas in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         nodes: List of node objects following JSON Canvas 1.0 spec
         edges: List of edge objects following JSON Canvas 1.0 spec
         title: The title of the canvas (will be saved as title.canvas)
         folder: Folder path relative to project root where the canvas should be saved.
                 Use forward slashes (/) as separators. Examples: "diagrams", "projects/2025", "visual/maps"
-        project: Optional project name to create canvas in. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         A summary of the created canvas file
@@ -77,35 +85,39 @@ async def canvas(
     ```
 
     Examples:
-        # Create canvas in current project
-        canvas(nodes=[...], edges=[...], title="My Canvas", folder="diagrams")
+        # Create canvas in project
+        canvas("my-project", nodes=[...], edges=[...], title="My Canvas", folder="diagrams")
+
+        # Create canvas in work project
+        canvas("work-project", nodes=[...], edges=[...], title="Process Flow", folder="visual/maps")
 
-        # Create canvas in specific project
-        canvas(nodes=[...], edges=[...], title="My Canvas", folder="diagrams", project="work-project")
+    Raises:
+        ToolError: If project doesn't exist or folder path is invalid
     """
-    active_project = get_active_project(project)
-    project_url = active_project.project_url
+    async with get_client() as client:
+        active_project = await get_active_project(client, project, context)
+        project_url = active_project.project_url
 
-    # Ensure path has .canvas extension
-    file_title = title if title.endswith(".canvas") else f"{title}.canvas"
-    file_path = f"{folder}/{file_title}"
+        # Ensure path has .canvas extension
+        file_title = title if title.endswith(".canvas") else f"{title}.canvas"
+        file_path = f"{folder}/{file_title}"
 
-    # Create canvas data structure
-    canvas_data = {"nodes": nodes, "edges": edges}
+        # Create canvas data structure
+        canvas_data = {"nodes": nodes, "edges": edges}
 
-    # Convert to JSON
-    canvas_json = json.dumps(canvas_data, indent=2)
+        # Convert to JSON
+        canvas_json = json.dumps(canvas_data, indent=2)
 
-    # Write the file using the resource API
-    logger.info(f"Creating canvas file: {file_path}")
-    response = await call_put(client, f"{project_url}/resource/{file_path}", json=canvas_json)
+        # Write the file using the resource API
+        logger.info(f"Creating canvas file: {file_path} in project {project}")
+        response = await call_put(client, f"{project_url}/resource/{file_path}", json=canvas_json)
 
-    # Parse response
-    result = response.json()
-    logger.debug(result)
+        # Parse response
+        result = response.json()
+        logger.debug(result)
 
-    # Build summary
-    action = "Created" if response.status_code == 201 else "Updated"
-    summary = [f"# {action}: {file_path}", "\nThe canvas is ready to open in Obsidian."]
+        # Build summary
+        action = "Created" if response.status_code == 201 else "Updated"
+        summary = [f"# {action}: {file_path}", "\nThe canvas is ready to open in Obsidian."]
 
-    return "\n".join(summary)
+        return "\n".join(summary)

basic_memory/mcp/tools/chatgpt_tools.py

@@ -0,0 +1,187 @@
+"""ChatGPT-compatible MCP tools for Basic Memory.
+
+These adapters expose Basic Memory's search/fetch functionality using the exact
+tool names and response structure OpenAI's MCP clients expect: each call returns
+a list containing a single `{"type": "text", "text": "{...json...}"}` item.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.search import search_notes
+from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.schemas.search import SearchResponse
+from basic_memory.config import ConfigManager
+
+
+def _format_search_results_for_chatgpt(results: SearchResponse) -> List[Dict[str, Any]]:
+    """Format search results according to ChatGPT's expected schema.
+
+    Returns a list of result objects with id, title, and url fields.
+    """
+    formatted_results = []
+
+    for result in results.results:
+        formatted_result = {
+            "id": result.permalink or f"doc-{len(formatted_results)}",
+            "title": result.title if result.title and result.title.strip() else "Untitled",
+            "url": result.permalink or "",
+        }
+        formatted_results.append(formatted_result)
+
+    return formatted_results
+
+
+def _format_document_for_chatgpt(
+    content: str, identifier: str, title: Optional[str] = None
+) -> Dict[str, Any]:
+    """Format document content according to ChatGPT's expected schema.
+
+    Returns a document object with id, title, text, url, and metadata fields.
+    """
+    # Extract title from markdown content if not provided
+    if not title and isinstance(content, str):
+        lines = content.split("\n")
+        if lines and lines[0].startswith("# "):
+            title = lines[0][2:].strip()
+        else:
+            title = identifier.split("/")[-1].replace("-", " ").title()
+
+    # Ensure title is never None
+    if not title:
+        title = "Untitled Document"
+
+    # Handle error cases
+    if isinstance(content, str) and content.startswith("# Note Not Found"):
+        return {
+            "id": identifier,
+            "title": title or "Document Not Found",
+            "text": content,
+            "url": identifier,
+            "metadata": {"error": "Document not found"},
+        }
+
+    return {
+        "id": identifier,
+        "title": title or "Untitled Document",
+        "text": content,
+        "url": identifier,
+        "metadata": {"format": "markdown"},
+    }
+
+
+@mcp.tool(description="Search for content across the knowledge base")
+async def search(
+    query: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP search adapter returning a single text content item.
+
+    Args:
+        query: Search query (full-text syntax supported by `search_notes`)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body contains `results`, `total_count`, and echo of `query`.
+    """
+    logger.info(f"ChatGPT search request: query='{query}'")
+
+    try:
+        # ChatGPT tools don't expose project parameter, so use default project
+        config = ConfigManager().config
+        default_project = config.default_project
+
+        # Call underlying search_notes with sensible defaults for ChatGPT
+        results = await search_notes.fn(
+            query=query,
+            project=default_project,  # Use default project for ChatGPT
+            page=1,
+            page_size=10,  # Reasonable default for ChatGPT consumption
+            search_type="text",  # Default to full-text search
+            context=context,
+        )
+
+        # Handle string error responses from search_notes
+        if isinstance(results, str):
+            logger.warning(f"Search failed with error: {results[:100]}...")
+            search_results = {
+                "results": [],
+                "error": "Search failed",
+                "error_details": results[:500],  # Truncate long error messages
+            }
+        else:
+            # Format successful results for ChatGPT
+            formatted_results = _format_search_results_for_chatgpt(results)
+            search_results = {
+                "results": formatted_results,
+                "total_count": len(results.results),  # Use actual count from results
+                "query": query,
+            }
+            logger.info(f"Search completed: {len(formatted_results)} results returned")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(search_results, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT search failed for query '{query}': {e}")
+        error_results = {
+            "results": [],
+            "error": "Internal search error",
+            "error_message": str(e)[:200],
+        }
+        return [{"type": "text", "text": json.dumps(error_results, ensure_ascii=False)}]
+
+
+@mcp.tool(description="Fetch the full contents of a search result document")
+async def fetch(
+    id: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP fetch adapter returning a single text content item.
+
+    Args:
+        id: Document identifier (permalink, title, or memory URL)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body includes `id`, `title`, `text`, `url`, and metadata.
+    """
+    logger.info(f"ChatGPT fetch request: id='{id}'")
+
+    try:
+        # ChatGPT tools don't expose project parameter, so use default project
+        config = ConfigManager().config
+        default_project = config.default_project
+
+        # Call underlying read_note function
+        content = await read_note.fn(
+            identifier=id,
+            project=default_project,  # Use default project for ChatGPT
+            page=1,
+            page_size=10,  # Default pagination
+            context=context,
+        )
+
+        # Format the document for ChatGPT
+        document = _format_document_for_chatgpt(content, id)
+
+        logger.info(f"Fetch completed: id='{id}', content_length={len(document.get('text', ''))}")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(document, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT fetch failed for id '{id}': {e}")
+        error_document = {
+            "id": id,
+            "title": "Fetch Error",
+            "text": f"Failed to fetch document: {str(e)[:200]}",
+            "url": id,
+            "metadata": {"error": "Fetch failed"},
+        }
+        return [{"type": "text", "text": json.dumps(error_document, ensure_ascii=False)}]