basic-memory 0.14.3__py3-none-any.whl → 0.15.0__py3-none-any.whl

basic_memory/mcp/tools/read_note.py

@@ -4,12 +4,13 @@ from textwrap import dedent
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project
 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
 from basic_memory.utils import validate_project_path
 
@@ -18,43 +19,83 @@ from basic_memory.utils import validate_project_path
     description="Read a markdown note by title or permalink.",
 )
 async def read_note(
-    identifier: str, page: int = 1, page_size: int = 10, project: Optional[str] = None
+    identifier: str,
+    project: Optional[str] = None,
+    page: int = 1,
+    page_size: int = 10,
+    context: Context | None = None,
 ) -> str:
-    """Read a markdown note from the knowledge base.
+    """Return the raw markdown for a note, or guidance text if no match is found.
 
-    This tool finds and retrieves a note by its title, permalink, or content search,
+    Finds and retrieves a note by its title, permalink, or content search,
     returning the raw markdown content including observations, relations, and metadata.
-    It will try multiple lookup strategies to find the most relevant note.
+
+    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.
+
+    This tool will try multiple lookup strategies to find the most relevant note:
+    1. Direct permalink lookup
+    2. Title search fallback
+    3. Text search as last resort
 
     Args:
+        project: Project name to read from. Optional - server will resolve using the
+                hierarchy above. If unknown, use list_memory_projects() to discover
+                available projects.
         identifier: The title or permalink of the note to read
                    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.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         The full markdown content of the note if found, or helpful guidance if not found.
+        Content includes frontmatter, observations, relations, and all markdown formatting.
 
     Examples:
         # Read by permalink
-        read_note("specs/search-spec")
+        read_note("my-research", "specs/search-spec")
 
         # Read by title
-        read_note("Search Specification")
+        read_note("work-project", "Search Specification")
 
         # Read with memory URL
-        read_note("memory://specs/search-spec")
+        read_note("my-research", "memory://specs/search-spec")
 
         # Read with pagination
-        read_note("Project Updates", page=2, page_size=5)
+        read_note("work-project", "Project Updates", page=2, page_size=5)
+
+        # Read recent meeting notes
+        read_note("team-docs", "Weekly Standup")
 
-        # Read from specific project
-        read_note("Meeting Notes", project="work-project")
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If identifier attempts path traversal
+
+    Note:
+        If the exact note isn't found, this tool provides helpful suggestions
+        including related notes, search commands, and note creation templates.
     """
 
-    # Get the active project first to check project-specific sync status
-    active_project = get_active_project(project)
+    # Get and validate the project
+    active_project = await get_active_project(client, project, context)
+
+    # Validate identifier to prevent path traversal attacks
+    # We need to check both the raw identifier and the processed path
+    processed_path = memory_url_path(identifier)
+    project_path = active_project.home
+
+    if not validate_project_path(identifier, project_path) or not validate_project_path(
+        processed_path, project_path
+    ):
+        logger.warning(
+            "Attempted path traversal attack blocked",
+            identifier=identifier,
+            processed_path=processed_path,
+            project=active_project.name,
+        )
+        return f"# Error\n\nIdentifier '{identifier}' is not allowed - paths must stay within project boundaries"
 
     # Check migration status and wait briefly if needed
     from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
@@ -68,19 +109,8 @@ async def read_note(
 
     # Get the file via REST API - first try direct permalink lookup
     entity_path = memory_url_path(identifier)
-
-    # Validate path to prevent path traversal attacks
-    project_path = active_project.home
-    if not validate_project_path(entity_path, project_path):
-        logger.warning(
-            "Attempted path traversal attack blocked",
-            identifier=identifier,
-            entity_path=entity_path,
-            project=active_project.name,
-        )
-        return f"# Error\n\nPath '{identifier}' is not allowed - paths must stay within project boundaries"
     path = f"{project_url}/resource/{entity_path}"
-    logger.info(f"Attempting to read note from URL: {path}")
+    logger.info(f"Attempting to read note from Project: {active_project.name} URL: {path}")
 
     try:
         # Try direct lookup first
@@ -96,9 +126,12 @@ async def read_note(
 
     # Fallback 1: Try title search via API
     logger.info(f"Search title for: {identifier}")
-    title_results = await search_notes.fn(query=identifier, search_type="title", project=project)
+    title_results = await search_notes.fn(
+        query=identifier, search_type="title", project=project, context=context
+    )
 
-    if title_results and title_results.results:
+    # Handle both SearchResponse object and error strings
+    if title_results and hasattr(title_results, "results") and title_results.results:
         result = title_results.results[0]  # Get the first/best match
         if result.permalink:
             try:
@@ -116,58 +149,64 @@ async def read_note(
                     f"Failed to fetch content for found title match {result.permalink}: {e}"
                 )
     else:
-        logger.info(f"No results in title search for: {identifier}")
+        logger.info(
+            f"No results in title search for: {identifier} in project {active_project.name}"
+        )
 
     # Fallback 2: Text search as a last resort
     logger.info(f"Title search failed, trying text search for: {identifier}")
-    text_results = await search_notes.fn(query=identifier, search_type="text", project=project)
+    text_results = await search_notes.fn(
+        query=identifier, search_type="text", project=project, context=context
+    )
 
     # We didn't find a direct match, construct a helpful error message
-    if not text_results or not text_results.results:
+    # Handle both SearchResponse object and error strings
+    if not text_results or not hasattr(text_results, "results") or not text_results.results:
         # No results at all
-        return format_not_found_message(identifier)
+        return format_not_found_message(active_project.name, identifier)
     else:
         # We found some related results
-        return format_related_results(identifier, text_results.results[:5])
+        return format_related_results(active_project.name, identifier, text_results.results[:5])
 
 
-def format_not_found_message(identifier: str) -> str:
+def format_not_found_message(project: str | None, identifier: str) -> str:
     """Format a helpful message when no note was found."""
     return dedent(f"""
-        # Note Not Found: "{identifier}"
-        
-        I searched for "{identifier}" using multiple methods (direct lookup, title search, and text search) but couldn't find any matching notes. Here are some suggestions:
-        
+        # Note Not Found in {project}: "{identifier}"
+
+        I couldn't find any notes matching "{identifier}". Here are some suggestions:
+
         ## Check Identifier Type
         - If you provided a title, try using the exact permalink instead
         - If you provided a permalink, check for typos or try a broader search
-        
+
         ## Search Instead
         Try searching for related content:
         ```
-        search_notes(query="{identifier}")
+        search_notes(project="{project}", query="{identifier}")
         ```
-        
+
         ## Recent Activity
         Check recently modified notes:
         ```
         recent_activity(timeframe="7d")
         ```
-        
+
         ## Create New Note
         This might be a good opportunity to create a new note on this topic:
         ```
         write_note(
+            project="{project}",
             title="{identifier.capitalize()}",
             content='''
             # {identifier.capitalize()}
-            
+
             ## Overview
             [Your content here]
-            
+
             ## Observations
             - [category] [Observation about {identifier}]
-            
+
             ## Relations
             - relates_to [[Related Topic]]
             ''',
@@ -177,13 +216,13 @@ def format_not_found_message(identifier: str) -> str:
     """)
 
 
-def format_related_results(identifier: str, results) -> str:
+def format_related_results(project: str | None, identifier: str, results) -> str:
     """Format a helpful message with related results when an exact match wasn't found."""
     message = dedent(f"""
-        # Note Not Found: "{identifier}"
-        
-        I searched for "{identifier}" using direct lookup and title search but couldn't find an exact match. However, I found some related notes through text search:
-        
+        # Note Not Found in {project}: "{identifier}"
+
+        I couldn't find an exact match for "{identifier}", but I found some related notes:
+
         """)
 
     for i, result in enumerate(results):
@@ -191,28 +230,29 @@ def format_related_results(identifier: str, results) -> str:
             ## {i + 1}. {result.title}
             - **Type**: {result.type.value}
             - **Permalink**: {result.permalink}
-            
+
             You can read this note with:
             ```
-            read_note("{result.permalink}")
+            read_note(project="{project}", {result.permalink}")
             ```
-            
+
             """)
 
-    message += dedent("""
+    message += dedent(f"""
         ## Try More Specific Lookup
         For exact matches, try using the full permalink from one of the results above.
-        
+
         ## Search For More Results
         To see more related content:
         ```
-        search_notes(query="{identifier}")
+        search_notes(project="{project}", query="{identifier}")
         ```
-        
+
         ## Create New Note
         If none of these match what you're looking for, consider creating a new note:
         ```
         write_note(
+            project="{project}",
             title="[Your title]",
             content="[Your content]",
             folder="notes"