basic-memory 0.7.0__py3-none-any.whl → 0.16.1__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/__init__.py

@@ -0,0 +1,19 @@
+"""Basic Memory MCP prompts.
+
+Prompts are a special type of tool that returns a string response
+formatted for a user to read, typically invoking one or more tools
+and transforming their results into user-friendly text.
+"""
+
+# Import individual prompt modules to register them with the MCP server
+from basic_memory.mcp.prompts import continue_conversation
+from basic_memory.mcp.prompts import recent_activity
+from basic_memory.mcp.prompts import search
+from basic_memory.mcp.prompts import ai_assistant_guide
+
+__all__ = [
+    "ai_assistant_guide",
+    "continue_conversation",
+    "recent_activity",
+    "search",
+]

basic_memory/mcp/prompts/ai_assistant_guide.py

@@ -0,0 +1,70 @@
+from pathlib import Path
+
+from basic_memory.config import ConfigManager
+from basic_memory.mcp.server import mcp
+from loguru import logger
+
+
+@mcp.resource(
+    uri="memory://ai_assistant_guide",
+    name="ai assistant guide",
+    description="Give an AI assistant guidance on how to use Basic Memory tools effectively",
+)
+def ai_assistant_guide() -> str:
+    """Return a concise guide on Basic Memory tools and how to use them.
+
+    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")
+
+    # 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

@@ -0,0 +1,62 @@
+"""Session continuation prompts for Basic Memory MCP server.
+
+These prompts help users continue conversations and work across sessions,
+providing context from previous interactions to maintain continuity.
+"""
+
+from typing import Annotated, Optional
+
+from loguru import logger
+from pydantic import Field
+
+from basic_memory.config import get_project_config
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.utils import call_post
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.prompt import ContinueConversationRequest
+
+
+@mcp.prompt(
+    name="continue_conversation",
+    description="Continue a previous conversation",
+)
+async def continue_conversation(
+    topic: Annotated[Optional[str], Field(description="Topic or keyword to search for")] = None,
+    timeframe: Annotated[
+        Optional[TimeFrame],
+        Field(description="How far back to look for activity (e.g. '1d', '1 week')"),
+    ] = None,
+) -> str:
+    """Continue a previous conversation or work session.
+
+    This prompt helps you pick up where you left off by finding recent context
+    about a specific topic or showing general recent activity.
+
+    Args:
+        topic: Topic or keyword to search for (optional)
+        timeframe: How far back to look for activity
+
+    Returns:
+        Context from previous sessions on this topic
+    """
+    logger.info(f"Continuing session, topic: {topic}, timeframe: {timeframe}")
+
+    async with get_client() as client:
+        # Create request model
+        request = ContinueConversationRequest(  # pyright: ignore [reportCallIssue]
+            topic=topic, timeframe=timeframe
+        )
+
+        project_url = get_project_config().project_url
+
+        # Call the prompt API endpoint
+        response = await call_post(
+            client,
+            f"{project_url}/prompt/continue-conversation",
+            json=request.model_dump(exclude_none=True),
+        )
+
+        # Extract the rendered prompt from the response
+        result = response.json()
+        return result["prompt"]

basic_memory/mcp/prompts/recent_activity.py

@@ -0,0 +1,188 @@
+"""Recent activity prompts for Basic Memory MCP server.
+
+These prompts help users see what has changed in their knowledge base recently.
+"""
+
+from typing import Annotated, Optional
+
+from loguru import logger
+from pydantic import Field
+
+from basic_memory.mcp.prompts.utils import format_prompt_context, PromptContext, PromptContextItem
+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="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 a specific project or across all projects.
+
+    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}, project: {project}")
+
+    recent = await recent_activity.fn(
+        project=project, timeframe=timeframe, type=[SearchItemType.ENTITY]
+    )
+
+    # Extract primary results from the hierarchical structure
+    primary_results = []
+    related_results = []
+
+    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=topic,
+            timeframe=timeframe,
+            results=[
+                PromptContextItem(
+                    primary_results=primary_results,
+                    related_results=related_results[:10],  # Limit total related results
+                )
+            ],
+        )
+    )
+
+    # Add mode-specific suggestions
+    first_title = "Recent Topic"
+    if primary_results and len(primary_results) > 0:
+        first_title = primary_results[0].title
+
+    if project:
+        # Project-specific suggestions
+        capture_suggestions = f"""
+    ## Opportunity to Capture Activity Summary
+
+    Consider creating a summary note of recent activity in {project}:
+
+    ```python
+    await write_note(
+        "{project}",
+        title="Activity Summary {timeframe}",
+        content='''
+        # Activity Summary for {project} ({timeframe})
+
+        ## Overview
+        [Summary of key changes and developments in this project over this period]
+
+        ## Key Updates
+        [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]]
+        ''',
+        folder="summaries"
+    )
+    ```
+
+    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

@@ -0,0 +1,57 @@
+"""Search prompts for Basic Memory MCP server.
+
+These prompts help users search and explore their knowledge base.
+"""
+
+from typing import Annotated, Optional
+
+from loguru import logger
+from pydantic import Field
+
+from basic_memory.config import get_project_config
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.utils import call_post
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.prompt import SearchPromptRequest
+
+
+@mcp.prompt(
+    name="search_knowledge_base",
+    description="Search across all content in basic-memory",
+)
+async def search_prompt(
+    query: str,
+    timeframe: Annotated[
+        Optional[TimeFrame],
+        Field(description="How far back to search (e.g. '1d', '1 week')"),
+    ] = None,
+) -> str:
+    """Search across all content in basic-memory.
+
+    This prompt helps search for content in the knowledge base and
+    provides helpful context about the results.
+
+    Args:
+        query: The search text to look for
+        timeframe: Optional timeframe to limit results (e.g. '1d', '1 week')
+
+    Returns:
+        Formatted search results with context
+    """
+    logger.info(f"Searching knowledge base, query: {query}, timeframe: {timeframe}")
+
+    async with get_client() as client:
+        # Create request model
+        request = SearchPromptRequest(query=query, timeframe=timeframe)
+
+        project_url = get_project_config().project_url
+
+        # Call the prompt API endpoint
+        response = await call_post(
+            client, f"{project_url}/prompt/search", json=request.model_dump(exclude_none=True)
+        )
+
+        # Extract the rendered prompt from the response
+        result = response.json()
+        return result["prompt"]