basic-memory 0.12.3__py3-none-any.whl → 0.13.0__py3-none-any.whl

basic_memory/mcp/tools/utils.py

@@ -5,6 +5,7 @@ to the Basic Memory API, with improved error handling and logging.
 """
 
 import typing
+from typing import Optional
 
 from httpx import Response, URL, AsyncClient, HTTPStatusError
 from httpx._client import UseClientDefault, USE_CLIENT_DEFAULT
@@ -23,7 +24,9 @@ from loguru import logger
 from mcp.server.fastmcp.exceptions import ToolError
 
 
-def get_error_message(status_code: int, url: URL | str, method: str) -> str:
+def get_error_message(
+    status_code: int, url: URL | str, method: str, msg: Optional[str] = None
+) -> str:
     """Get a friendly error message based on the HTTP status code.
 
     Args:
@@ -103,6 +106,7 @@ async def call_get(
         ToolError: If the request fails with an appropriate error message
     """
     logger.debug(f"Calling GET '{url}' params: '{params}'")
+    error_message = None
     try:
         response = await client.get(
             url,
@@ -120,7 +124,12 @@ async def call_get(
 
         # Handle different status codes differently
         status_code = response.status_code
-        error_message = get_error_message(status_code, url, "GET")
+        # get the message if available
+        response_data = response.json()
+        if isinstance(response_data, dict) and "detail" in response_data:
+            error_message = response_data["detail"]
+        else:
+            error_message = get_error_message(status_code, url, "PUT")
 
         # Log at appropriate level based on status code
         if 400 <= status_code < 500:
@@ -138,8 +147,6 @@ async def call_get(
         return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
 
     except HTTPStatusError as e:
-        status_code = e.response.status_code
-        error_message = get_error_message(status_code, url, "GET")
         raise ToolError(error_message) from e
 
 
@@ -183,6 +190,8 @@ async def call_put(
         ToolError: If the request fails with an appropriate error message
     """
     logger.debug(f"Calling PUT '{url}'")
+    error_message = None
+
     try:
         response = await client.put(
             url,
@@ -204,7 +213,13 @@ async def call_put(
 
         # Handle different status codes differently
         status_code = response.status_code
-        error_message = get_error_message(status_code, url, "PUT")
+
+        # get the message if available
+        response_data = response.json()
+        if isinstance(response_data, dict) and "detail" in response_data:
+            error_message = response_data["detail"]  # pragma: no cover
+        else:
+            error_message = get_error_message(status_code, url, "PUT")
 
         # Log at appropriate level based on status code
         if 400 <= status_code < 500:
@@ -221,9 +236,110 @@ async def call_put(
         response.raise_for_status()  # Will always raise since we're in the error case
         return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
 
+    except HTTPStatusError as e:
+        raise ToolError(error_message) from e
+
+
+async def call_patch(
+    client: AsyncClient,
+    url: URL | str,
+    *,
+    content: RequestContent | None = None,
+    data: RequestData | None = None,
+    files: RequestFiles | None = None,
+    json: typing.Any | None = None,
+    params: QueryParamTypes | None = None,
+    headers: HeaderTypes | None = None,
+    cookies: CookieTypes | None = None,
+    auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,
+    timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    extensions: RequestExtensions | None = None,
+) -> Response:
+    """Make a PATCH request and handle errors appropriately.
+
+    Args:
+        client: The HTTPX AsyncClient to use
+        url: The URL to request
+        content: Request content
+        data: Form data
+        files: Files to upload
+        json: JSON data
+        params: Query parameters
+        headers: HTTP headers
+        cookies: HTTP cookies
+        auth: Authentication
+        follow_redirects: Whether to follow redirects
+        timeout: Request timeout
+        extensions: HTTPX extensions
+
+    Returns:
+        The HTTP response
+
+    Raises:
+        ToolError: If the request fails with an appropriate error message
+    """
+    logger.debug(f"Calling PATCH '{url}'")
+    try:
+        response = await client.patch(
+            url,
+            content=content,
+            data=data,
+            files=files,
+            json=json,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            auth=auth,
+            follow_redirects=follow_redirects,
+            timeout=timeout,
+            extensions=extensions,
+        )
+
+        if response.is_success:
+            return response
+
+        # Handle different status codes differently
+        status_code = response.status_code
+
+        # Try to extract specific error message from response body
+        try:
+            response_data = response.json()
+            if isinstance(response_data, dict) and "detail" in response_data:
+                error_message = response_data["detail"]
+            else:
+                error_message = get_error_message(status_code, url, "PATCH")  # pragma: no cover
+        except Exception:  # pragma: no cover
+            error_message = get_error_message(status_code, url, "PATCH")  # pragma: no cover
+
+        # Log at appropriate level based on status code
+        if 400 <= status_code < 500:
+            # Client errors: log as info except for 429 (Too Many Requests)
+            if status_code == 429:  # pragma: no cover
+                logger.warning(f"Rate limit exceeded: PATCH {url}: {error_message}")
+            else:
+                logger.info(f"Client error: PATCH {url}: {error_message}")
+        else:  # pragma: no cover
+            # Server errors: log as error
+            logger.error(f"Server error: PATCH {url}: {error_message}")  # pragma: no cover
+
+        # Raise a tool error with the friendly message
+        response.raise_for_status()  # Will always raise since we're in the error case
+        return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
+
     except HTTPStatusError as e:
         status_code = e.response.status_code
-        error_message = get_error_message(status_code, url, "PUT")
+
+        # Try to extract specific error message from response body
+        try:
+            response_data = e.response.json()
+            if isinstance(response_data, dict) and "detail" in response_data:
+                error_message = response_data["detail"]
+            else:
+                error_message = get_error_message(status_code, url, "PATCH")  # pragma: no cover
+        except Exception:  # pragma: no cover
+            error_message = get_error_message(status_code, url, "PATCH")  # pragma: no cover
+
         raise ToolError(error_message) from e
 
 
@@ -267,6 +383,7 @@ async def call_post(
         ToolError: If the request fails with an appropriate error message
     """
     logger.debug(f"Calling POST '{url}'")
+    error_message = None
     try:
         response = await client.post(
             url=url,
@@ -282,13 +399,19 @@ async def call_post(
             timeout=timeout,
             extensions=extensions,
         )
+        logger.debug(f"response: {response.json()}")
 
         if response.is_success:
             return response
 
         # Handle different status codes differently
         status_code = response.status_code
-        error_message = get_error_message(status_code, url, "POST")
+        # get the message if available
+        response_data = response.json()
+        if isinstance(response_data, dict) and "detail" in response_data:
+            error_message = response_data["detail"]
+        else:
+            error_message = get_error_message(status_code, url, "POST")
 
         # Log at appropriate level based on status code
         if 400 <= status_code < 500:
@@ -306,8 +429,6 @@ async def call_post(
         return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
 
     except HTTPStatusError as e:
-        status_code = e.response.status_code
-        error_message = get_error_message(status_code, url, "POST")
         raise ToolError(error_message) from e
 
 
@@ -343,6 +464,7 @@ async def call_delete(
         ToolError: If the request fails with an appropriate error message
     """
     logger.debug(f"Calling DELETE '{url}'")
+    error_message = None
     try:
         response = await client.delete(
             url=url,
@@ -360,7 +482,12 @@ async def call_delete(
 
         # Handle different status codes differently
         status_code = response.status_code
-        error_message = get_error_message(status_code, url, "DELETE")
+        # get the message if available
+        response_data = response.json()
+        if isinstance(response_data, dict) and "detail" in response_data:
+            error_message = response_data["detail"]  # pragma: no cover
+        else:
+            error_message = get_error_message(status_code, url, "DELETE")
 
         # Log at appropriate level based on status code
         if 400 <= status_code < 500:
@@ -378,6 +505,51 @@ async def call_delete(
         return response  # This line will never execute, but it satisfies the type checker  # pragma: no cover
 
     except HTTPStatusError as e:
-        status_code = e.response.status_code
-        error_message = get_error_message(status_code, url, "DELETE")
         raise ToolError(error_message) from e
+
+
+def check_migration_status() -> Optional[str]:
+    """Check if sync/migration is in progress and return status message if so.
+
+    Returns:
+        Status message if sync is in progress, None if system is ready
+    """
+    try:
+        from basic_memory.services.sync_status_service import sync_status_tracker
+
+        if not sync_status_tracker.is_ready:
+            return sync_status_tracker.get_summary()
+        return None
+    except Exception:
+        # If there's any error checking sync status, assume ready
+        return None
+
+
+async def wait_for_migration_or_return_status(timeout: float = 5.0) -> Optional[str]:
+    """Wait briefly for sync/migration to complete, or return status message.
+
+    Args:
+        timeout: Maximum time to wait for sync completion
+
+    Returns:
+        Status message if sync is still in progress, None if ready
+    """
+    try:
+        from basic_memory.services.sync_status_service import sync_status_tracker
+        import asyncio
+
+        if sync_status_tracker.is_ready:
+            return None
+
+        # Wait briefly for sync to complete
+        start_time = asyncio.get_event_loop().time()
+        while (asyncio.get_event_loop().time() - start_time) < timeout:
+            if sync_status_tracker.is_ready:
+                return None
+            await asyncio.sleep(0.1)  # Check every 100ms
+
+        # Still not ready after timeout
+        return sync_status_tracker.get_summary()
+    except Exception:  # pragma: no cover
+        # If there's any error, assume ready
+        return None

basic_memory/mcp/tools/view_note.py

@@ -0,0 +1,66 @@
+"""View note tool for Basic Memory MCP server."""
+
+from textwrap import dedent
+from typing import Optional
+
+from loguru import logger
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.read_note import read_note
+
+
+@mcp.tool(
+    description="View a note as a formatted artifact for better readability.",
+)
+async def view_note(
+    identifier: str, page: int = 1, page_size: int = 10, project: Optional[str] = None
+) -> str:
+    """View a markdown note as a formatted artifact.
+
+    This tool reads a note using the same logic as read_note but displays the content
+    as a markdown artifact for better viewing experience in Claude Desktop.
+
+    After calling this tool, create an artifact using the returned content to display
+    the note in a readable format. The tool returns the note content that should be
+    used to create a markdown artifact.
+
+    Args:
+        identifier: The title or permalink of the note to view
+        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.
+
+    Returns:
+        The note content as a markdown artifact with a confirmation message.
+    """
+
+    logger.info(f"Viewing note: {identifier}")
+
+    # Call the existing read_note logic
+    content = await read_note.fn(identifier, page, page_size, project)
+
+    # Check if this is an error message (note not found)
+    if "# Note Not Found:" in content:
+        return content  # Return error message directly instead of creating artifact
+
+    # Extract title from content if possible
+    title = identifier
+    lines = content.split("\n")
+    for line in lines:
+        if line.startswith("title:"):
+            # Extract title from frontmatter
+            title = line.split("title:", 1)[1].strip().strip('"').strip("'")
+            break
+        elif line.startswith("# "):
+            # Extract title from first heading
+            title = line[2:].strip()
+            break
+
+    # Return the artifact XML as part of the response
+    artifact = f'<artifact identifier="note-{hash(identifier) & 0x7FFFFFFF}" type="text/markdown" title="{title}">\n{content}\n</artifact>'
+
+    return dedent(f"""
+            <instructions>
+            Create an artifact using the returned artifact content to display the note in a readable format.
+            </instructions>
+            {artifact}\n\n✅ Note displayed as artifact: **{title}**""")

basic_memory/mcp/tools/write_note.py

@@ -1,12 +1,13 @@
 """Write note tool for Basic Memory MCP server."""
 
-from typing import List, Union
+from typing import List, Union, Optional
 
 from loguru import logger
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put
+from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas import EntityResponse
 from basic_memory.schemas.base import Entity
 from basic_memory.utils import parse_tags
@@ -26,6 +27,7 @@ async def write_note(
     content: str,
     folder: str,
     tags=None,  # Remove type hint completely to avoid schema issues
+    project: Optional[str] = None,
 ) -> str:
     """Write a markdown note to the knowledge base.
 
@@ -52,9 +54,11 @@ async def write_note(
     Args:
         title: The title of the note
         content: Markdown content for the note, can include observations and relations
-        folder: the folder where the file should be saved
+        folder: Folder path relative to project root where the file should be saved.
+                Use forward slashes (/) as separators. Examples: "notes", "projects/2025", "research/ml"
         tags: Tags to categorize the note. Can be a list of strings, a comma-separated string, or None.
               Note: If passing from external MCP clients, use a string format (e.g. "tag1,tag2,tag3")
+        project: Optional project name to write to. If not provided, uses current active project.
 
     Returns:
         A markdown formatted summary of the semantic content, including:
@@ -64,12 +68,19 @@ async def write_note(
         - Relation counts (resolved/unresolved)
         - Tags if present
     """
-    logger.info("MCP tool call", tool="write_note", folder=folder, title=title, tags=tags)
+    logger.info(f"MCP tool call tool=write_note folder={folder}, title={title}, tags={tags}")
+
+    # Check migration status and wait briefly if needed
+    from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
+
+    migration_status = await wait_for_migration_or_return_status(timeout=5.0)
+    if migration_status:  # pragma: no cover
+        return f"# System Status\n\n{migration_status}\n\nPlease wait for migration to complete before creating notes."
 
     # Process tags using the helper function
     tag_list = parse_tags(tags)
     # Create the entity request
-    metadata = {"tags": [f"#{tag}" for tag in tag_list]} if tag_list else None
+    metadata = {"tags": tag_list} if tag_list else None
     entity = Entity(
         title=title,
         folder=folder,
@@ -78,10 +89,12 @@ async def write_note(
         content=content,
         entity_metadata=metadata,
     )
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
 
     # Create or update via knowledge API
-    logger.debug("Creating entity via API", permalink=entity.permalink)
-    url = f"/knowledge/entities/{entity.permalink}"
+    logger.debug(f"Creating entity via API permalink={entity.permalink}")
+    url = f"{project_url}/knowledge/entities/{entity.permalink}"
     response = await call_put(client, url, json=entity.model_dump())
     result = EntityResponse.model_validate(response.json())
 
@@ -115,22 +128,16 @@ async def write_note(
         summary.append(f"- Resolved: {resolved}")
         if unresolved:
             summary.append(f"- Unresolved: {unresolved}")
-            summary.append("\nUnresolved relations will be retried on next sync.")
+            summary.append("\nNote: Unresolved relations point to entities that don't exist yet.")
+            summary.append(
+                "They will be automatically resolved when target entities are created or during sync operations."
+            )
 
     if tag_list:
         summary.append(f"\n## Tags\n- {', '.join(tag_list)}")
 
     # Log the response with structured data
     logger.info(
-        "MCP tool response",
-        tool="write_note",
-        action=action,
-        permalink=result.permalink,
-        observations_count=len(result.observations),
-        relations_count=len(result.relations),
-        resolved_relations=resolved,
-        unresolved_relations=unresolved,
-        status_code=response.status_code,
+        f"MCP tool response: tool=write_note action={action} permalink={result.permalink} observations_count={len(result.observations)} relations_count={len(result.relations)} resolved_relations={resolved} unresolved_relations={unresolved} status_code={response.status_code}"
     )
-
     return "\n".join(summary)

basic_memory/models/__init__.py

@@ -3,12 +3,13 @@
 import basic_memory
 from basic_memory.models.base import Base
 from basic_memory.models.knowledge import Entity, Observation, Relation
-
-SCHEMA_VERSION = basic_memory.__version__ + "-" + "003"
+from basic_memory.models.project import Project
 
 __all__ = [
     "Base",
     "Entity",
     "Observation",
     "Relation",
+    "Project",
+    "basic_memory",
 ]

basic_memory/models/knowledge.py

@@ -17,7 +17,6 @@ from sqlalchemy import (
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from basic_memory.models.base import Base
-
 from basic_memory.utils import generate_permalink
 
 
@@ -29,6 +28,7 @@ class Entity(Base):
     - Maps to a file on disk
     - Maintains a checksum for change detection
     - Tracks both source file and semantic properties
+    - Belongs to a specific project
     """
 
     __tablename__ = "entity"
@@ -38,13 +38,21 @@ class Entity(Base):
         Index("ix_entity_title", "title"),
         Index("ix_entity_created_at", "created_at"),  # For timeline queries
         Index("ix_entity_updated_at", "updated_at"),  # For timeline queries
-        # Unique index only for markdown files with non-null permalinks
+        Index("ix_entity_project_id", "project_id"),  # For project filtering
+        # Project-specific uniqueness constraints
         Index(
-            "uix_entity_permalink",
+            "uix_entity_permalink_project",
             "permalink",
+            "project_id",
             unique=True,
             sqlite_where=text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
         ),
+        Index(
+            "uix_entity_file_path_project",
+            "file_path",
+            "project_id",
+            unique=True,
+        ),
     )
 
     # Core identity
@@ -54,10 +62,13 @@ class Entity(Base):
     entity_metadata: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True)
     content_type: Mapped[str] = mapped_column(String)
 
+    # Project reference
+    project_id: Mapped[int] = mapped_column(Integer, ForeignKey("project.id"), nullable=False)
+
     # Normalized path for URIs - required for markdown files only
     permalink: Mapped[Optional[str]] = mapped_column(String, nullable=True, index=True)
     # Actual filesystem relative path
-    file_path: Mapped[str] = mapped_column(String, unique=True, index=True)
+    file_path: Mapped[str] = mapped_column(String, index=True)
     # checksum of file
     checksum: Mapped[Optional[str]] = mapped_column(String, nullable=True)
 
@@ -66,6 +77,7 @@ class Entity(Base):
     updated_at: Mapped[datetime] = mapped_column(DateTime)
 
     # Relationships
+    project = relationship("Project", back_populates="entities")
     observations = relationship(
         "Observation", back_populates="entity", cascade="all, delete-orphan"
     )

basic_memory/models/project.py

@@ -0,0 +1,78 @@
+"""Project model for Basic Memory."""
+
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import (
+    Integer,
+    String,
+    Text,
+    Boolean,
+    DateTime,
+    Index,
+    event,
+)
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from basic_memory.models.base import Base
+from basic_memory.utils import generate_permalink
+
+
+class Project(Base):
+    """Project model for Basic Memory.
+
+    A project represents a collection of knowledge entities that are grouped together.
+    Projects are stored in the app-level database and provide context for all knowledge
+    operations.
+    """
+
+    __tablename__ = "project"
+    __table_args__ = (
+        # Regular indexes
+        Index("ix_project_name", "name", unique=True),
+        Index("ix_project_permalink", "permalink", unique=True),
+        Index("ix_project_path", "path"),
+        Index("ix_project_created_at", "created_at"),
+        Index("ix_project_updated_at", "updated_at"),
+    )
+
+    # Core identity
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String, unique=True)
+    description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+
+    # URL-friendly identifier generated from name
+    permalink: Mapped[str] = mapped_column(String, unique=True)
+
+    # Filesystem path to project directory
+    path: Mapped[str] = mapped_column(String)
+
+    # Status flags
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    is_default: Mapped[Optional[bool]] = mapped_column(Boolean, default=None, nullable=True)
+
+    # Timestamps
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, default=datetime.utcnow, onupdate=datetime.utcnow
+    )
+
+    # Define relationships to entities, observations, and relations
+    # These relationships will be established once we add project_id to those models
+    entities = relationship("Entity", back_populates="project", cascade="all, delete-orphan")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"Project(id={self.id}, name='{self.name}', permalink='{self.permalink}', path='{self.path}')"
+
+
+@event.listens_for(Project, "before_insert")
+@event.listens_for(Project, "before_update")
+def set_project_permalink(mapper, connection, project):
+    """Generate URL-friendly permalink for the project if needed.
+
+    This event listener ensures the permalink is always derived from the name,
+    even if the name changes.
+    """
+    # If the name changed or permalink is empty, regenerate permalink
+    if not project.permalink or project.permalink != generate_permalink(project.name):
+        project.permalink = generate_permalink(project.name)

basic_memory/models/search.py

@@ -13,21 +13,24 @@ CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
     permalink,             -- Stable identifier (now indexed for path search)
     file_path UNINDEXED,   -- Physical location
     type UNINDEXED,        -- entity/relation/observation
-    
-    -- Relation fields 
+
+    -- Project context
+    project_id UNINDEXED,  -- Project identifier
+
+    -- Relation fields
     from_id UNINDEXED,     -- Source entity
     to_id UNINDEXED,       -- Target entity
     relation_type UNINDEXED, -- Type of relation
-    
+
     -- Observation fields
     entity_id UNINDEXED,   -- Parent entity
     category UNINDEXED,    -- Observation category
-    
+
     -- Common fields
     metadata UNINDEXED,    -- JSON metadata
     created_at UNINDEXED,  -- Creation timestamp
     updated_at UNINDEXED,  -- Last update
-    
+
     -- Configuration
     tokenize='unicode61 tokenchars 0x2F',  -- Hex code for /
     prefix='1,2,3,4'                    -- Support longer prefixes for paths

basic_memory/repository/__init__.py

@@ -1,9 +1,11 @@
 from .entity_repository import EntityRepository
 from .observation_repository import ObservationRepository
+from .project_repository import ProjectRepository
 from .relation_repository import RelationRepository
 
 __all__ = [
     "EntityRepository",
     "ObservationRepository",
+    "ProjectRepository",
     "RelationRepository",
 ]

basic_memory/repository/entity_repository.py

@@ -18,9 +18,14 @@ class EntityRepository(Repository[Entity]):
     to strings before passing to repository methods.
     """
 
-    def __init__(self, session_maker: async_sessionmaker[AsyncSession]):
-        """Initialize with session maker."""
-        super().__init__(session_maker, Entity)
+    def __init__(self, session_maker: async_sessionmaker[AsyncSession], project_id: int):
+        """Initialize with session maker and project_id filter.
+
+        Args:
+            session_maker: SQLAlchemy session maker
+            project_id: Project ID to filter all operations by
+        """
+        super().__init__(session_maker, Entity, project_id=project_id)
 
     async def get_by_permalink(self, permalink: str) -> Optional[Entity]:
         """Get entity by permalink.