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

basic_memory/mcp/project_context.py

@@ -0,0 +1,141 @@
+"""Project context utilities for Basic Memory MCP server.
+
+Provides project lookup utilities for MCP tools.
+Handles project validation and context management in one place.
+"""
+
+import os
+from typing import Optional, List
+from httpx import AsyncClient
+from httpx._types import (
+    HeaderTypes,
+)
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.config import ConfigManager
+from basic_memory.mcp.tools.utils import call_get
+from basic_memory.schemas.project_info import ProjectItem, ProjectList
+from basic_memory.utils import generate_permalink
+
+
+async def resolve_project_parameter(project: Optional[str] = None) -> Optional[str]:
+    """Resolve project parameter using three-tier hierarchy.
+
+    if config.cloud_mode:
+        project is required
+    else:
+        Resolution order:
+        1. Single Project Mode  (--project cli arg, or BASIC_MEMORY_MCP_PROJECT env var) - highest priority
+        2. Explicit project parameter - medium priority
+        3. Default project if default_project_mode=true - lowest priority
+
+    Args:
+        project: Optional explicit project parameter
+
+    Returns:
+        Resolved project name or None if no resolution possible
+    """
+
+    config = ConfigManager().config
+    # if cloud_mode, project is required
+    if config.cloud_mode:
+        if project:
+            logger.debug(f"project: {project}, cloud_mode: {config.cloud_mode}")
+            return project
+        else:
+            raise ValueError("No project specified. Project is required for cloud mode.")
+
+    # Priority 1: CLI constraint overrides everything (--project arg sets env var)
+    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+    if constrained_project:
+        logger.debug(f"Using CLI constrained project: {constrained_project}")
+        return constrained_project
+
+    # Priority 2: Explicit project parameter
+    if project:
+        logger.debug(f"Using explicit project parameter: {project}")
+        return project
+
+    # Priority 3: Default project mode
+    if config.default_project_mode:
+        logger.debug(f"Using default project from config: {config.default_project}")
+        return config.default_project
+
+    # No resolution possible
+    return None
+
+
+async def get_project_names(client: AsyncClient, headers: HeaderTypes | None = None) -> List[str]:
+    response = await call_get(client, "/projects/projects", headers=headers)
+    project_list = ProjectList.model_validate(response.json())
+    return [project.name for project in project_list.projects]
+
+
+async def get_active_project(
+    client: AsyncClient,
+    project: Optional[str] = None,
+    context: Optional[Context] = None,
+    headers: HeaderTypes | None = None,
+) -> ProjectItem:
+    """Get and validate project, setting it in context if available.
+
+    Args:
+        client: HTTP client for API calls
+        project: Optional project name (resolved using hierarchy)
+        context: Optional FastMCP context to cache the result
+
+    Returns:
+        The validated project item
+
+    Raises:
+        ValueError: If no project can be resolved
+        HTTPError: If project doesn't exist or is inaccessible
+    """
+    resolved_project = await resolve_project_parameter(project)
+    if not resolved_project:
+        project_names = await get_project_names(client, headers)
+        raise ValueError(
+            "No project specified. "
+            "Either set 'default_project_mode=true' in config, or use 'project' argument.\n"
+            f"Available projects: {project_names}"
+        )
+
+    project = resolved_project
+
+    # Check if already cached in context
+    if context:
+        cached_project = context.get_state("active_project")
+        if cached_project and cached_project.name == project:
+            logger.debug(f"Using cached project from context: {project}")
+            return cached_project
+
+    # Validate project exists by calling API
+    logger.debug(f"Validating project: {project}")
+    permalink = generate_permalink(project)
+    response = await call_get(client, f"/{permalink}/project/item", headers=headers)
+    active_project = ProjectItem.model_validate(response.json())
+
+    # Cache in context if available
+    if context:
+        context.set_state("active_project", active_project)
+        logger.debug(f"Cached project in context: {project}")
+
+    logger.debug(f"Validated project: {active_project.name}")
+    return active_project
+
+
+def add_project_metadata(result: str, project_name: str) -> str:
+    """Add project context as metadata footer for assistant session tracking.
+
+    Provides clear project context to help the assistant remember which
+    project is being used throughout the conversation session.
+
+    Args:
+        result: The tool result string
+        project_name: The project name that was used
+
+    Returns:
+        Result with project session tracking metadata
+    """
+    return f"{result}\n\n[Session: Using project '{project_name}']"

basic_memory/mcp/prompts/ai_assistant_guide.py

@@ -1,5 +1,6 @@
 from pathlib import Path
 
+from basic_memory.config import ConfigManager
 from basic_memory.mcp.server import mcp
 from loguru import logger
 
@@ -12,14 +13,58 @@ from loguru import logger
 def ai_assistant_guide() -> str:
     """Return a concise guide on Basic Memory tools and how to use them.
 
-    Args:
-        focus: Optional area to focus on ("writing", "context", "search", etc.)
+    Dynamically adapts instructions based on configuration:
+    - Default project mode: Simplified instructions with automatic project
+    - Regular mode: Project discovery and selection guidance
+    - CLI constraint mode: Single project constraint information
 
     Returns:
         A focused guide on Basic Memory usage.
     """
     logger.info("Loading AI assistant guide resource")
+
+    # Load base guide content
     guide_doc = Path(__file__).parent.parent / "resources" / "ai_assistant_guide.md"
     content = guide_doc.read_text(encoding="utf-8")
-    logger.info(f"Loaded AI assistant guide ({len(content)} chars)")
-    return content
+
+    # Check configuration for mode-specific instructions
+    config = ConfigManager().config
+
+    # Add mode-specific header
+    mode_info = ""
+    if config.default_project_mode:
+        mode_info = f"""
+# 🎯 Default Project Mode Active
+
+**Current Configuration**: All operations automatically use project '{config.default_project}'
+
+**Simplified Usage**: You don't need to specify the project parameter in tool calls.
+- `write_note(title="Note", content="...", folder="docs")` ✅
+- Project parameter is optional and will default to '{config.default_project}'
+- To use a different project, explicitly specify: `project="other-project"`
+
+────────────────────────────────────────
+
+"""
+    else:
+        mode_info = """
+# 🔧 Multi-Project Mode Active
+
+**Current Configuration**: Project parameter required for all operations
+
+**Project Discovery Required**: Use these tools to select a project:
+- `list_memory_projects()` - See all available projects
+- `recent_activity()` - Get project activity and recommendations
+- Remember the user's project choice throughout the conversation
+
+────────────────────────────────────────
+
+"""
+
+    # Prepend mode info to the guide
+    enhanced_content = mode_info + content
+
+    logger.info(
+        f"Loaded AI assistant guide ({len(enhanced_content)} chars) with mode: {'default_project' if config.default_project_mode else 'multi_project'}"
+    )
+    return enhanced_content

basic_memory/mcp/prompts/continue_conversation.py

@@ -18,7 +18,7 @@ from basic_memory.schemas.prompt import ContinueConversationRequest
 
 
 @mcp.prompt(
-    name="Continue Conversation",
+    name="continue_conversation",
     description="Continue a previous conversation",
 )
 async def continue_conversation(

basic_memory/mcp/prompts/recent_activity.py

@@ -3,7 +3,7 @@
 These prompts help users see what has changed in their knowledge base recently.
 """
 
-from typing import Annotated
+from typing import Annotated, Optional
 
 from loguru import logger
 from pydantic import Field
@@ -12,49 +12,83 @@ from basic_memory.mcp.prompts.utils import format_prompt_context, PromptContext,
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.recent_activity import recent_activity
 from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import GraphContext, ProjectActivitySummary
 from basic_memory.schemas.search import SearchItemType
 
 
 @mcp.prompt(
-    name="Share Recent Activity",
-    description="Get recent activity from across the knowledge base",
+    name="recent_activity",
+    description="Get recent activity from a specific project or across all projects",
 )
 async def recent_activity_prompt(
     timeframe: Annotated[
         TimeFrame,
         Field(description="How far back to look for activity (e.g. '1d', '1 week')"),
     ] = "7d",
+    project: Annotated[
+        Optional[str],
+        Field(
+            description="Specific project to get activity from (None for discovery across all projects)"
+        ),
+    ] = None,
 ) -> str:
-    """Get recent activity from across the knowledge base.
+    """Get recent activity from a specific project or across all projects.
 
-    This prompt helps you see what's changed recently in the knowledge base,
-    showing new or updated documents and related information.
+    This prompt helps you see what's changed recently in the knowledge base.
+    In discovery mode (project=None), it shows activity across all projects.
+    In project-specific mode, it shows detailed activity for one project.
 
     Args:
         timeframe: How far back to look for activity (e.g. '1d', '1 week')
+        project: Specific project to get activity from (None for discovery across all projects)
 
     Returns:
         Formatted summary of recent activity
     """
-    logger.info(f"Getting recent activity, timeframe: {timeframe}")
+    logger.info(f"Getting recent activity, timeframe: {timeframe}, project: {project}")
 
-    recent = await recent_activity.fn(timeframe=timeframe, type=[SearchItemType.ENTITY])
+    recent = await recent_activity.fn(
+        project=project, timeframe=timeframe, type=[SearchItemType.ENTITY]
+    )
 
     # Extract primary results from the hierarchical structure
     primary_results = []
     related_results = []
 
-    if recent.results:
-        # Take up to 5 primary results
-        for item in recent.results[:5]:
-            primary_results.append(item.primary_result)
-            # Add up to 2 related results per primary item
-            if item.related_results:
-                related_results.extend(item.related_results[:2])
+    if isinstance(recent, ProjectActivitySummary):
+        # Discovery mode - extract results from all projects
+        for _, project_activity in recent.projects.items():
+            if project_activity.activity.results:
+                # Take up to 2 primary results per project
+                for item in project_activity.activity.results[:2]:
+                    primary_results.append(item.primary_result)
+                    # Add up to 1 related result per primary item
+                    if item.related_results:
+                        related_results.extend(item.related_results[:1])
+
+        # Limit total results for readability
+        primary_results = primary_results[:8]
+        related_results = related_results[:6]
+
+    elif isinstance(recent, GraphContext):
+        # Project-specific mode - use existing logic
+        if recent.results:
+            # Take up to 5 primary results
+            for item in recent.results[:5]:
+                primary_results.append(item.primary_result)
+                # Add up to 2 related results per primary item
+                if item.related_results:
+                    related_results.extend(item.related_results[:2])
+
+    # Set topic based on mode
+    if project:
+        topic = f"Recent Activity in {project} ({timeframe})"
+    else:
+        topic = f"Recent Activity Across All Projects ({timeframe})"
 
     prompt_context = format_prompt_context(
         PromptContext(
-            topic=f"Recent Activity from ({timeframe})",
+            topic=topic,
             timeframe=timeframe,
             results=[
                 PromptContextItem(
@@ -65,40 +99,90 @@ async def recent_activity_prompt(
         )
     )
 
-    # Add suggestions for summarizing recent activity
+    # Add mode-specific suggestions
     first_title = "Recent Topic"
     if primary_results and len(primary_results) > 0:
         first_title = primary_results[0].title
 
-    capture_suggestions = f"""
+    if project:
+        # Project-specific suggestions
+        capture_suggestions = f"""
     ## Opportunity to Capture Activity Summary
-    
-    Consider creating a summary note of recent activity:
-    
+
+    Consider creating a summary note of recent activity in {project}:
+
     ```python
     await write_note(
+        "{project}",
         title="Activity Summary {timeframe}",
         content='''
-        # Activity Summary for {timeframe}
-        
+        # Activity Summary for {project} ({timeframe})
+
         ## Overview
-        [Summary of key changes and developments over this period]
-        
+        [Summary of key changes and developments in this project over this period]
+
         ## Key Updates
-        [List main updates and their significance]
-        
+        [List main updates and their significance within this project]
+
         ## Observations
         - [trend] [Observation about patterns in recent activity]
         - [insight] [Connection between different activities]
-        
+
         ## Relations
         - summarizes [[{first_title}]]
-        - relates_to [[Project Overview]]
-        '''
+        - relates_to [[{project} Overview]]
+        ''',
+        folder="summaries"
     )
     ```
-    
-    Summarizing periodic activity helps create high-level insights and connections between topics.
+
+    Summarizing periodic activity helps create high-level insights and connections within the project.
+    """
+    else:
+        # Discovery mode suggestions
+        project_count = len(recent.projects) if isinstance(recent, ProjectActivitySummary) else 0
+        most_active = (
+            getattr(recent.summary, "most_active_project", "Unknown")
+            if isinstance(recent, ProjectActivitySummary)
+            else "Unknown"
+        )
+
+        capture_suggestions = f"""
+    ## Cross-Project Activity Discovery
+
+    Found activity across {project_count} projects. Most active: **{most_active}**
+
+    Consider creating a cross-project summary:
+
+    ```python
+    await write_note(
+        "{most_active if most_active != "Unknown" else "main"}",
+        title="Cross-Project Activity Summary {timeframe}",
+        content='''
+        # Cross-Project Activity Summary ({timeframe})
+
+        ## Overview
+        Activity found across {project_count} projects, with {most_active} showing the most activity.
+
+        ## Key Developments
+        [Summarize important changes across all projects]
+
+        ## Project Insights
+        [Note patterns or connections between projects]
+
+        ## Observations
+        - [trend] [Cross-project patterns observed]
+        - [insight] [Connections between different project activities]
+
+        ## Relations
+        - summarizes [[{first_title}]]
+        - relates_to [[Project Portfolio Overview]]
+        ''',
+        folder="summaries"
+    )
+    ```
+
+    Cross-project summaries help identify broader trends and project interconnections.
     """
 
     return prompt_context + capture_suggestions

basic_memory/mcp/prompts/search.py

@@ -17,7 +17,7 @@ from basic_memory.schemas.prompt import SearchPromptRequest
 
 
 @mcp.prompt(
-    name="Search Knowledge Base",
+    name="search_knowledge_base",
     description="Search across all content in basic-memory",
 )
 async def search_prompt(

basic_memory/mcp/prompts/utils.py

@@ -103,10 +103,17 @@ def format_prompt_context(context: PromptContext) -> str:
 
                 added_permalinks.add(primary_permalink)
 
-                memory_url = normalize_memory_url(primary_permalink)
+                # Use permalink if available, otherwise use file_path
+                if primary_permalink:
+                    memory_url = normalize_memory_url(primary_permalink)
+                    read_command = f'read_note("{primary_permalink}")'
+                else:
+                    memory_url = f"file://{primary.file_path}"
+                    read_command = f'read_file("{primary.file_path}")'
+
                 section = dedent(f"""
                     --- {memory_url}
-                
+
                     ## {primary.title}
                     - **Type**: {primary.type}
                     """)
@@ -121,8 +128,8 @@ def format_prompt_context(context: PromptContext) -> str:
                         section += f"\n**Excerpt**:\n{content}\n"
 
                 section += dedent(f"""
-    
-                    You can read this document with: `read_note("{primary_permalink}")`
+
+                    You can read this document with: `{read_command}`
                     """)
                 sections.append(section)