basic-memory 0.12.3__py3-none-any.whl → 0.13.0b2__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,4 @@ 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

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.
 
@@ -55,6 +57,7 @@ async def write_note(
         folder: the folder where the file should be saved
         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 +67,12 @@ 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}")
 
     # 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 +81,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())
 
@@ -122,15 +127,6 @@ async def write_note(
 
     # 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,80 @@
+"""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, unique=True, 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.

basic_memory/repository/observation_repository.py

@@ -1,6 +1,6 @@
 """Repository for managing Observation objects."""
 
-from typing import Sequence
+from typing import Dict, List, Sequence
 
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import async_sessionmaker
@@ -12,8 +12,14 @@ from basic_memory.repository.repository import Repository
 class ObservationRepository(Repository[Observation]):
     """Repository for Observation model with memory-specific operations."""
 
-    def __init__(self, session_maker: async_sessionmaker):
-        super().__init__(session_maker, Observation)
+    def __init__(self, session_maker: async_sessionmaker, 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, Observation, project_id=project_id)
 
     async def find_by_entity(self, entity_id: int) -> Sequence[Observation]:
         """Find all observations for a specific entity."""
@@ -38,3 +44,29 @@ class ObservationRepository(Repository[Observation]):
         query = select(Observation.category).distinct()
         result = await self.execute_query(query, use_query_options=False)
         return result.scalars().all()
+
+    async def find_by_entities(self, entity_ids: List[int]) -> Dict[int, List[Observation]]:
+        """Find all observations for multiple entities in a single query.
+
+        Args:
+            entity_ids: List of entity IDs to fetch observations for
+
+        Returns:
+            Dictionary mapping entity_id to list of observations
+        """
+        if not entity_ids:  # pragma: no cover
+            return {}
+
+        # Query observations for all entities in the list
+        query = select(Observation).filter(Observation.entity_id.in_(entity_ids))
+        result = await self.execute_query(query)
+        observations = result.scalars().all()
+
+        # Group observations by entity_id
+        observations_by_entity = {}
+        for obs in observations:
+            if obs.entity_id not in observations_by_entity:
+                observations_by_entity[obs.entity_id] = []
+            observations_by_entity[obs.entity_id].append(obs)
+
+        return observations_by_entity

basic_memory/repository/project_info_repository.py

@@ -1,9 +1,10 @@
 from basic_memory.repository.repository import Repository
+from basic_memory.models.project import Project
 
 
 class ProjectInfoRepository(Repository):
     """Repository for statistics queries."""
 
     def __init__(self, session_maker):
-        # Initialize with a dummy model since we're just using the execute_query method
-        super().__init__(session_maker, None)  # type: ignore
+        # Initialize with Project model as a reference
+        super().__init__(session_maker, Project)