basic-memory 0.7.0__py3-none-any.whl → 0.17.4__py3-none-any.whl

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"]

basic_memory/mcp/prompts/utils.py

@@ -0,0 +1,162 @@
+"""Utility functions for formatting prompt responses.
+
+These utilities help format data from various tools into consistent,
+user-friendly markdown summaries.
+"""
+
+from dataclasses import dataclass
+from textwrap import dedent
+from typing import List
+
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import (
+    normalize_memory_url,
+    EntitySummary,
+    RelationSummary,
+    ObservationSummary,
+)
+
+
+@dataclass
+class PromptContextItem:
+    primary_results: List[EntitySummary]
+    related_results: List[EntitySummary | RelationSummary | ObservationSummary]
+
+
+@dataclass
+class PromptContext:
+    timeframe: TimeFrame
+    topic: str
+    results: List[PromptContextItem]
+
+
+def format_prompt_context(context: PromptContext) -> str:
+    """Format continuation context into a helpful summary.
+    Returns:
+        Formatted continuation summary
+    """
+    if not context.results:  # pragma: no cover
+        return dedent(f"""
+            # Continuing conversation on: {context.topic}
+
+            This is a memory retrieval session. 
+            The supplied query did not return any information specifically on this topic.
+            
+            ## Opportunity to Capture New Knowledge!
+            
+            This is an excellent chance to start documenting this topic:
+            
+            ```python
+            await write_note(
+                title="{context.topic}",
+                content=f'''
+                # {context.topic}
+                
+                ## Overview
+                [Summary of what we know about {context.topic}]
+                
+                ## Key Points
+                [Main aspects or components of {context.topic}]
+                
+                ## Observations
+                - [category] [First important observation about {context.topic}]
+                - [category] [Second observation about {context.topic}]
+                
+                ## Relations
+                - relates_to [[Related Topic]]
+                - part_of [[Broader Context]]
+                '''
+            )
+            ```
+            
+            ## Other Options
+            
+            Please use the available basic-memory tools to gather relevant context before responding.
+            You can also:
+            - Try a different search term
+            - Check recent activity with `recent_activity(timeframe="1w")`
+            """)
+
+    # Start building our summary with header - add knowledge capture emphasis
+    summary = dedent(f"""
+        # Continuing conversation on: {context.topic}
+
+        This is a memory retrieval session. 
+        
+        Please use the available basic-memory tools to gather relevant context before responding. 
+        Start by executing one of the suggested commands below to retrieve content.
+
+        Here's what I found from previous conversations:
+        
+        > **Knowledge Capture Recommendation:** As you continue this conversation, actively look for opportunities to record new information, decisions, or insights that emerge. Use `write_note()` to document important context.
+        """)
+
+    # Track what we've added to avoid duplicates
+    added_permalinks = set()
+    sections = []
+
+    # Process each context
+    for context in context.results:  # pyright: ignore
+        for primary in context.primary_results:  # pyright: ignore
+            if primary.permalink not in added_permalinks:
+                primary_permalink = primary.permalink
+
+                added_permalinks.add(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}
+                    """)
+
+                # Add creation date
+                section += f"- **Created**: {primary.created_at.strftime('%Y-%m-%d %H:%M')}\n"
+
+                # Add content snippet
+                if hasattr(primary, "content") and primary.content:  # pyright: ignore
+                    content = primary.content or ""  # pyright: ignore  # pragma: no cover
+                    if content:  # pragma: no cover
+                        section += f"\n**Excerpt**:\n{content}\n"  # pragma: no cover
+
+                section += dedent(f"""
+
+                    You can read this document with: `{read_command}`
+                    """)
+                sections.append(section)
+
+        if context.related_results:  # pyright: ignore
+            section += dedent(  # pyright: ignore
+                """   
+                ## Related Context
+                """
+            )
+
+            for related in context.related_results:  # pyright: ignore
+                section_content = dedent(f"""
+                    - type: **{related.type}**
+                    - title: {related.title}
+                    """)
+                if related.permalink:  # pragma: no cover
+                    section_content += (
+                        f'You can view this document with: `read_note("{related.permalink}")`'
+                    )
+                else:  # pragma: no cover
+                    section_content += (
+                        f'You can view this file with: `read_file("{related.file_path}")`'
+                    )
+
+                section += section_content
+                sections.append(section)
+
+    # Add all sections
+    summary += "\n".join(sections)
+    return summary

basic_memory/mcp/resources/ai_assistant_guide.md

@@ -0,0 +1,283 @@
+# AI Assistant Guide for Basic Memory
+
+Quick reference for using Basic Memory tools effectively through MCP.
+
+**For comprehensive coverage**: See the [Extended AI Assistant Guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) with detailed examples, advanced patterns, and self-contained sections.
+
+## Overview
+
+Basic Memory creates a semantic knowledge graph from markdown files. Focus on building rich connections between notes.
+
+- **Local-First**: Plain text files on user's computer
+- **Persistent**: Knowledge survives across sessions
+- **Semantic**: Observations and relations create a knowledge graph
+
+**Your role**: You're helping humans build enduring knowledge they'll own forever. The semantic graph (observations, relations, context) helps you provide better assistance by understanding connections and maintaining continuity. Think: lasting insights worth keeping, not disposable chat logs.
+
+## Project Management 
+
+All tools require explicit project specification.
+
+**Three-tier resolution:**
+1. CLI constraint: `--project name` (highest priority)
+2. Explicit parameter: `project="name"` in tool calls
+3. Default mode: `default_project_mode=true` in config (fallback)
+
+### Quick Setup Check
+
+```python
+# Discover projects
+projects = await list_memory_projects()
+
+# Check if default_project_mode enabled
+# If yes: project parameter optional
+# If no: project parameter required
+```
+
+### Default Project Mode
+
+When `default_project_mode=true`:
+```python
+# These are equivalent:
+await write_note("Note", "Content", "folder")
+await write_note("Note", "Content", "folder", project="main")
+```
+
+When `default_project_mode=false` (default):
+```python
+# Project required:
+await write_note("Note", "Content", "folder", project="main")  # ✓
+await write_note("Note", "Content", "folder")  # ✗ Error
+```
+
+## Core Tools
+
+### Writing Knowledge
+
+```python
+await write_note(
+    title="Topic",
+    content="# Topic\n## Observations\n- [category] fact\n## Relations\n- relates_to [[Other]]",
+    folder="notes",
+    project="main"  # Required unless default_project_mode=true
+)
+```
+
+### Reading Knowledge
+
+```python
+# By identifier
+content = await read_note("Topic", project="main")
+
+# By memory:// URL
+content = await read_note("memory://folder/topic", project="main")
+```
+
+### Searching
+
+```python
+results = await search_notes(
+    query="authentication",
+    project="main",
+    page_size=10
+)
+```
+
+### Building Context
+
+```python
+context = await build_context(
+    url="memory://specs/auth",
+    project="main",
+    depth=2,
+    timeframe="1 week"
+)
+```
+
+## Knowledge Graph Essentials
+
+### Observations
+
+Categorized facts with optional tags:
+```markdown
+- [decision] Use JWT for authentication #security
+- [technique] Hash passwords with bcrypt #best-practice
+- [requirement] Support OAuth 2.0 providers
+```
+
+### Relations
+
+Directional links between entities:
+```markdown
+- implements [[Authentication Spec]]
+- requires [[User Database]]
+- extends [[Base Security Model]]
+```
+
+**Common relation types:** `relates_to`, `implements`, `requires`, `extends`, `part_of`, `contrasts_with`
+
+### Forward References
+
+Reference entities that don't exist yet:
+```python
+# Create note with forward reference
+await write_note(
+    title="Login Flow",
+    content="## Relations\n- requires [[OAuth Provider]]",  # Doesn't exist yet
+    folder="auth",
+    project="main"
+)
+
+# Later, create referenced entity
+await write_note(
+    title="OAuth Provider",
+    content="# OAuth Provider\n...",
+    folder="auth",
+    project="main"
+)
+# → Relation automatically resolved
+```
+
+## Best Practices
+
+### 1. Project Management
+
+**Single-project users:**
+- Enable `default_project_mode=true`
+- Simpler tool calls
+
+**Multi-project users:**
+- Keep `default_project_mode=false`
+- Always specify project explicitly
+
+**Discovery:**
+```python
+# Start with discovery
+projects = await list_memory_projects()
+
+# Cross-project activity (no project param = all projects)
+activity = await recent_activity()
+
+# Or specific project
+activity = await recent_activity(project="main")
+```
+
+### 2. Building Rich Graphs
+
+**Always include:**
+- 3-5 observations per note
+- 2-3 relations per note
+- Meaningful categories and relation types
+
+**Search before creating:**
+```python
+# Find existing entities to reference
+results = await search_notes(query="authentication", project="main")
+# Use exact titles in [[WikiLinks]]
+```
+
+### 3. Writing Effective Notes
+
+**Structure:**
+```markdown
+# Title
+
+## Context
+Background information
+
+## Observations
+- [category] Fact with #tags
+- [category] Another fact
+
+## Relations
+- relation_type [[Exact Entity Title]]
+```
+
+**Categories:** `[idea]`, `[decision]`, `[fact]`, `[technique]`, `[requirement]`
+
+### 4. Error Handling
+
+**Missing project:**
+```python
+try:
+    await search_notes(query="test")  # Missing project parameter - will error
+except:
+    # Show available projects
+    projects = await list_memory_projects()
+    # Then retry with project
+    results = await search_notes(query="test", project=projects[0].name)
+```
+
+**Forward references:**
+```python
+# Check response for unresolved relations
+response = await write_note(
+    title="New Topic",
+    content="## Relations\n- relates_to [[Future Topic]]",
+    folder="notes",
+    project="main"
+)
+# Forward refs will resolve when target created
+```
+
+### 5. Recording Context
+
+**Ask permission:**
+> "Would you like me to save our discussion about [topic] to Basic Memory?"
+
+**Confirm when done:**
+> "I've saved our discussion to Basic Memory."
+
+**What to record:**
+- Decisions and rationales
+- Important discoveries
+- Action items and plans
+- Connected topics
+
+## Common Patterns
+
+### Capture Decision
+
+```python
+await write_note(
+    title="DB Choice",
+    content="""# DB Choice\n## Decision\nUse PostgreSQL\n## Observations\n- [requirement] ACID compliance #reliability\n- [decision] PostgreSQL over MySQL\n## Relations\n- implements [[Data Architecture]]""",
+    folder="decisions",
+    project="main"
+)
+```
+
+### Link Topics & Build Context
+
+```python
+# Link bidirectionally
+await write_note(title="API Auth", content="## Relations\n- part_of [[API Design]]", folder="api", project="main")
+await edit_note(identifier="API Design", operation="append", content="\n- includes [[API Auth]]", project="main")
+
+# Search and build context
+results = await search_notes(query="authentication", project="main")
+context = await build_context(url=f"memory://{results[0].permalink}", project="main", depth=2)
+```
+
+## Tool Quick Reference
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `write_note` | Create/update | title, content, folder, project |
+| `read_note` | Read content | identifier, project |
+| `edit_note` | Modify existing | identifier, operation, content, project |
+| `search_notes` | Find notes | query, project |
+| `build_context` | Graph traversal | url, depth, project |
+| `recent_activity` | Recent changes | timeframe, project |
+| `list_memory_projects` | Show projects | (none) |
+
+## memory:// URL Format
+
+- `memory://title` - By title
+- `memory://folder/title` - By folder + title
+- `memory://permalink` - By permalink
+- `memory://folder/*` - All in folder
+
+For full documentation: https://docs.basicmemory.com
+
+Built with ♥️ by Basic Machines

basic_memory/mcp/resources/project_info.py

@@ -0,0 +1,71 @@
+"""Project info tool for Basic Memory MCP server."""
+
+from typing import Optional
+
+from loguru import logger
+from fastmcp import Context
+
+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",
+    description="Get information and statistics about the current Basic Memory project.",
+)
+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
+    Basic Memory project, including:
+
+    - Project configuration
+    - Entity, observation, and relation counts
+    - Graph metrics (most connected entities, isolated entities)
+    - Recent activity and growth over time
+    - System status (database, watch service, version)
+
+    Use this tool to:
+    - Verify your Basic Memory installation is working correctly
+    - Get insights into your knowledge base structure
+    - 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/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}")
+
+        # Check system status
+        print(f"Basic Memory version: {info.system.version}")
+    """
+    logger.info("Getting 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())

basic_memory/mcp/server.py

@@ -1,15 +1,67 @@
-"""Enhanced FastMCP server instance for Basic Memory."""
+"""
+Basic Memory FastMCP server.
+"""
 
-from mcp.server.fastmcp import FastMCP
+from contextlib import asynccontextmanager
 
-from basic_memory.utils import setup_logging
+from fastmcp import FastMCP
+from loguru import logger
 
-# mcp console logging
-# configure_logging(level='INFO')
+from basic_memory import db
+from basic_memory.mcp.container import McpContainer, set_container
+from basic_memory.services.initialization import initialize_app
+from basic_memory.telemetry import show_notice_if_needed, track_app_started
 
 
-# start our out file logging
-setup_logging(log_file=".basic-memory/basic-memory.log")
+@asynccontextmanager
+async def lifespan(app: FastMCP):
+    """Lifecycle manager for the MCP server.
 
-# Create the shared server instance
-mcp = FastMCP("Basic Memory")
+    Handles:
+    - Database initialization and migrations
+    - Telemetry notice and tracking
+    - File sync via SyncCoordinator (if enabled and not in cloud mode)
+    - Proper cleanup on shutdown
+    """
+    # --- Composition Root ---
+    # Create container and read config (single point of config access)
+    container = McpContainer.create()
+    set_container(container)
+
+    logger.info(f"Starting Basic Memory MCP server (mode={container.mode.name})")
+
+    # Show telemetry notice (first run only) and track startup
+    show_notice_if_needed()
+    track_app_started("mcp")
+
+    # Track if we created the engine (vs test fixtures providing it)
+    # This prevents disposing an engine provided by test fixtures when
+    # multiple Client connections are made in the same test
+    engine_was_none = db._engine is None
+
+    # Initialize app (runs migrations, reconciles projects)
+    await initialize_app(container.config)
+
+    # Create and start sync coordinator (lifecycle centralized in coordinator)
+    sync_coordinator = container.create_sync_coordinator()
+    await sync_coordinator.start()
+
+    try:
+        yield
+    finally:
+        # Shutdown - coordinator handles clean task cancellation
+        logger.info("Shutting down Basic Memory MCP server")
+        await sync_coordinator.stop()
+
+        # Only shutdown DB if we created it (not if test fixture provided it)
+        if engine_was_none:
+            await db.shutdown_db()
+            logger.info("Database connections closed")
+        else:  # pragma: no cover
+            logger.debug("Skipping DB shutdown - engine provided externally")
+
+
+mcp = FastMCP(
+    name="Basic Memory",
+    lifespan=lifespan,
+)