basic-memory 0.17.1__py3-none-any.whl

basic_memory/markdown/schemas.py

@@ -0,0 +1,70 @@
+"""Schema models for entity markdown files."""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class Observation(BaseModel):
+    """An observation about an entity."""
+
+    category: Optional[str] = "Note"
+    content: str
+    tags: Optional[List[str]] = None
+    context: Optional[str] = None
+
+    def __str__(self) -> str:
+        obs_string = f"- [{self.category}] {self.content}"
+        if self.context:
+            obs_string += f" ({self.context})"
+        return obs_string
+
+
+class Relation(BaseModel):
+    """A relation between entities."""
+
+    type: str
+    target: str
+    context: Optional[str] = None
+
+    def __str__(self) -> str:
+        rel_string = f"- {self.type} [[{self.target}]]"
+        if self.context:
+            rel_string += f" ({self.context})"
+        return rel_string
+
+
+class EntityFrontmatter(BaseModel):
+    """Required frontmatter fields for an entity."""
+
+    metadata: dict = {}
+
+    @property
+    def tags(self) -> List[str]:
+        return self.metadata.get("tags") if self.metadata else None  # pyright: ignore
+
+    @property
+    def title(self) -> str:
+        return self.metadata.get("title") if self.metadata else None  # pyright: ignore
+
+    @property
+    def type(self) -> str:
+        return self.metadata.get("type", "note") if self.metadata else "note"  # pyright: ignore
+
+    @property
+    def permalink(self) -> str:
+        return self.metadata.get("permalink") if self.metadata else None  # pyright: ignore
+
+
+class EntityMarkdown(BaseModel):
+    """Complete entity combining frontmatter, content, and metadata."""
+
+    frontmatter: EntityFrontmatter
+    content: Optional[str] = None
+    observations: List[Observation] = []
+    relations: List[Relation] = []
+
+    # created, updated will have values after a read
+    created: Optional[datetime] = None
+    modified: Optional[datetime] = None

basic_memory/markdown/utils.py

@@ -0,0 +1,117 @@
+"""Utilities for converting between markdown and entity models."""
+
+from pathlib import Path
+from typing import Any, Optional
+
+
+from frontmatter import Post
+
+from basic_memory.file_utils import has_frontmatter, remove_frontmatter, parse_frontmatter
+from basic_memory.markdown import EntityMarkdown
+from basic_memory.models import Entity
+from basic_memory.models import Observation as ObservationModel
+
+
+def entity_model_from_markdown(
+    file_path: Path,
+    markdown: EntityMarkdown,
+    entity: Optional[Entity] = None,
+    project_id: Optional[int] = None,
+) -> Entity:
+    """
+    Convert markdown entity to model. Does not include relations.
+
+    Args:
+        file_path: Path to the markdown file
+        markdown: Parsed markdown entity
+        entity: Optional existing entity to update
+        project_id: Project ID for new observations (uses entity.project_id if not provided)
+
+    Returns:
+        Entity model populated from markdown
+
+    Raises:
+        ValueError: If required datetime fields are missing from markdown
+    """
+
+    if not markdown.created or not markdown.modified:  # pragma: no cover
+        raise ValueError("Both created and modified dates are required in markdown")
+
+    # Create or update entity
+    model = entity or Entity()
+
+    # Update basic fields
+    model.title = markdown.frontmatter.title
+    model.entity_type = markdown.frontmatter.type
+    # Only update permalink if it exists in frontmatter, otherwise preserve existing
+    if markdown.frontmatter.permalink is not None:
+        model.permalink = markdown.frontmatter.permalink
+    model.file_path = file_path.as_posix()
+    model.content_type = "text/markdown"
+    model.created_at = markdown.created
+    model.updated_at = markdown.modified
+
+    # Handle metadata - ensure all values are strings and filter None
+    metadata = markdown.frontmatter.metadata or {}
+    model.entity_metadata = {k: str(v) for k, v in metadata.items() if v is not None}
+
+    # Get project_id from entity if not provided
+    obs_project_id = project_id or (model.project_id if hasattr(model, "project_id") else None)
+
+    # Convert observations
+    model.observations = [
+        ObservationModel(
+            project_id=obs_project_id,
+            content=obs.content,
+            category=obs.category,
+            context=obs.context,
+            tags=obs.tags,
+        )
+        for obs in markdown.observations
+    ]
+
+    return model
+
+
+async def schema_to_markdown(schema: Any) -> Post:
+    """
+    Convert schema to markdown Post object.
+
+    Args:
+        schema: Schema to convert (must have title, entity_type, and permalink attributes)
+
+    Returns:
+        Post object with frontmatter metadata
+    """
+    # Extract content and metadata
+    content = schema.content or ""
+    entity_metadata = dict(schema.entity_metadata or {})
+
+    # if the content contains frontmatter, remove it and merge
+    if has_frontmatter(content):
+        content_frontmatter = parse_frontmatter(content)
+        content = remove_frontmatter(content)
+
+        # Merge content frontmatter with entity metadata
+        # (entity_metadata takes precedence for conflicts)
+        content_frontmatter.update(entity_metadata)
+        entity_metadata = content_frontmatter
+
+    # Remove special fields for ordered frontmatter
+    for field in ["type", "title", "permalink"]:
+        entity_metadata.pop(field, None)
+
+    # Create Post with fields ordered by insert order
+    post = Post(
+        content,
+        title=schema.title,
+        type=schema.entity_type,
+    )
+    # set the permalink if passed in
+    if schema.permalink:
+        post.metadata["permalink"] = schema.permalink
+
+    if entity_metadata:
+        post.metadata.update(entity_metadata)
+
+    return post

basic_memory/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP server for basic-memory."""

basic_memory/mcp/async_client.py

@@ -0,0 +1,139 @@
+from contextlib import asynccontextmanager, AbstractAsyncContextManager
+from typing import AsyncIterator, Callable, Optional
+
+from httpx import ASGITransport, AsyncClient, Timeout
+from loguru import logger
+
+from basic_memory.api.app import app as fastapi_app
+from basic_memory.config import ConfigManager
+
+
+# Optional factory override for dependency injection
+_client_factory: Optional[Callable[[], AbstractAsyncContextManager[AsyncClient]]] = None
+
+
+def set_client_factory(factory: Callable[[], AbstractAsyncContextManager[AsyncClient]]) -> None:
+    """Override the default client factory (for cloud app, testing, etc).
+
+    Args:
+        factory: An async context manager that yields an AsyncClient
+
+    Example:
+        @asynccontextmanager
+        async def custom_client_factory():
+            async with AsyncClient(...) as client:
+                yield client
+
+        set_client_factory(custom_client_factory)
+    """
+    global _client_factory
+    _client_factory = factory
+
+
+@asynccontextmanager
+async def get_client() -> AsyncIterator[AsyncClient]:
+    """Get an AsyncClient as a context manager.
+
+    This function provides proper resource management for HTTP clients,
+    ensuring connections are closed after use. It supports three modes:
+
+    1. **Factory injection** (cloud app, tests):
+       If a custom factory is set via set_client_factory(), use that.
+
+    2. **CLI cloud mode**:
+       When cloud_mode_enabled is True, create HTTP client with auth
+       token from CLIAuth for requests to cloud proxy endpoint.
+
+    3. **Local mode** (default):
+       Use ASGI transport for in-process requests to local FastAPI app.
+
+    Usage:
+        async with get_client() as client:
+            response = await client.get("/path")
+
+    Yields:
+        AsyncClient: Configured HTTP client for the current mode
+
+    Raises:
+        RuntimeError: If cloud mode is enabled but user is not authenticated
+    """
+    if _client_factory:
+        # Use injected factory (cloud app, tests)
+        async with _client_factory() as client:
+            yield client
+    else:
+        # Default: create based on config
+        config = ConfigManager().config
+        timeout = Timeout(
+            connect=10.0,  # 10 seconds for connection
+            read=30.0,  # 30 seconds for reading response
+            write=30.0,  # 30 seconds for writing request
+            pool=30.0,  # 30 seconds for connection pool
+        )
+
+        if config.cloud_mode_enabled:
+            # CLI cloud mode: inject auth when creating client
+            from basic_memory.cli.auth import CLIAuth
+
+            auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
+            token = await auth.get_valid_token()
+
+            if not token:
+                raise RuntimeError(
+                    "Cloud mode enabled but not authenticated. "
+                    "Run 'basic-memory cloud login' first."
+                )
+
+            # Auth header set ONCE at client creation
+            proxy_base_url = f"{config.cloud_host}/proxy"
+            logger.info(f"Creating HTTP client for cloud proxy at: {proxy_base_url}")
+            async with AsyncClient(
+                base_url=proxy_base_url,
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=timeout,
+            ) as client:
+                yield client
+        else:
+            # Local mode: ASGI transport for in-process calls
+            # Note: ASGI transport does NOT trigger FastAPI lifespan, so no special handling needed
+            logger.info("Creating ASGI client for local Basic Memory API")
+            async with AsyncClient(
+                transport=ASGITransport(app=fastapi_app), base_url="http://test", timeout=timeout
+            ) as client:
+                yield client
+
+
+def create_client() -> AsyncClient:
+    """Create an HTTP client based on configuration.
+
+    DEPRECATED: Use get_client() context manager instead for proper resource management.
+
+    This function is kept for backward compatibility but will be removed in a future version.
+    The returned client should be closed manually by calling await client.aclose().
+
+    Returns:
+        AsyncClient configured for either local ASGI or remote proxy
+    """
+    config_manager = ConfigManager()
+    config = config_manager.config
+
+    # Configure timeout for longer operations like write_note
+    # Default httpx timeout is 5 seconds which is too short for file operations
+    timeout = Timeout(
+        connect=10.0,  # 10 seconds for connection
+        read=30.0,  # 30 seconds for reading response
+        write=30.0,  # 30 seconds for writing request
+        pool=30.0,  # 30 seconds for connection pool
+    )
+
+    if config.cloud_mode_enabled:
+        # Use HTTP transport to proxy endpoint
+        proxy_base_url = f"{config.cloud_host}/proxy"
+        logger.info(f"Creating HTTP client for proxy at: {proxy_base_url}")
+        return AsyncClient(base_url=proxy_base_url, timeout=timeout)
+    else:
+        # Default: use ASGI transport for local API (development mode)
+        logger.info("Creating ASGI client for local Basic Memory API")
+        return AsyncClient(
+            transport=ASGITransport(app=fastapi_app), base_url="http://test", timeout=timeout
+        )

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