basic-memory 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

basic_memory/mcp/tools/utils.py

@@ -1,3 +1,9 @@
+"""Utility functions for making HTTP requests in Basic Memory MCP tools.
+
+These functions provide a consistent interface for making HTTP requests
+to the Basic Memory API, with improved error handling and logging.
+"""
+
 import typing
 
 from httpx import Response, URL, AsyncClient, HTTPStatusError
@@ -17,6 +23,54 @@ from loguru import logger
 from mcp.server.fastmcp.exceptions import ToolError
 
 
+def get_error_message(status_code: int, url: URL | str, method: str) -> str:
+    """Get a friendly error message based on the HTTP status code.
+
+    Args:
+        status_code: The HTTP status code
+        url: The URL that was requested
+        method: The HTTP method used
+
+    Returns:
+        A user-friendly error message
+    """
+    # Extract path from URL for cleaner error messages
+    if isinstance(url, str):
+        path = url.split("/")[-1]
+    else:
+        path = str(url).split("/")[-1] if url else "resource"
+
+    # Client errors (400-499)
+    if status_code == 400:
+        return f"Invalid request: The request to '{path}' was malformed or invalid"
+    elif status_code == 401:  # pragma: no cover
+        return f"Authentication required: You need to authenticate to access '{path}'"
+    elif status_code == 403:  # pragma: no cover
+        return f"Access denied: You don't have permission to access '{path}'"
+    elif status_code == 404:
+        return f"Resource not found: '{path}' doesn't exist or has been moved"
+    elif status_code == 409:  # pragma: no cover
+        return f"Conflict: The request for '{path}' conflicts with the current state"
+    elif status_code == 429:  # pragma: no cover
+        return "Too many requests: Please slow down and try again later"
+    elif 400 <= status_code < 500:  # pragma: no cover
+        return f"Client error ({status_code}): The request for '{path}' could not be completed"
+
+    # Server errors (500-599)
+    elif status_code == 500:
+        return f"Internal server error: Something went wrong processing '{path}'"
+    elif status_code == 503:  # pragma: no cover
+        return (
+            f"Service unavailable: The server is currently unable to handle requests for '{path}'"
+        )
+    elif 500 <= status_code < 600:  # pragma: no cover
+        return f"Server error ({status_code}): The server encountered an error handling '{path}'"
+
+    # Fallback for any other status code
+    else:  # pragma: no cover
+        return f"HTTP error {status_code}: {method} request to '{path}' failed"
+
+
 async def call_get(
     client: AsyncClient,
     url: URL | str,
@@ -29,6 +83,25 @@ async def call_get(
     timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
     extensions: RequestExtensions | None = None,
 ) -> Response:
+    """Make a GET request and handle errors appropriately.
+
+    Args:
+        client: The HTTPX AsyncClient to use
+        url: The URL to request
+        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 GET '{url}' params: '{params}'")
     try:
         response = await client.get(
@@ -41,11 +114,33 @@ async def call_get(
             timeout=timeout,
             extensions=extensions,
         )
-        response.raise_for_status()
-        return response
+
+        if response.is_success:
+            return response
+
+        # Handle different status codes differently
+        status_code = response.status_code
+        error_message = get_error_message(status_code, url, "GET")
+
+        # 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: GET {url}: {error_message}")
+            else:
+                logger.info(f"Client error: GET {url}: {error_message}")
+        else:  # pragma: no cover
+            # Server errors: log as error
+            logger.error(f"Server error: GET {url}: {error_message}")
+
+        # 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:
-        logger.exception(f"Error calling GET {url}: {e}")
-        raise ToolError(f"Error calling tool: {e}.") from e
+        status_code = e.response.status_code
+        error_message = get_error_message(status_code, url, "GET")
+        raise ToolError(error_message) from e
 
 
 async def call_put(
@@ -64,6 +159,30 @@ async def call_put(
     timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
     extensions: RequestExtensions | None = None,
 ) -> Response:
+    """Make a PUT 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 PUT '{url}'")
     try:
         response = await client.put(
             url,
@@ -79,12 +198,33 @@ async def call_put(
             timeout=timeout,
             extensions=extensions,
         )
-        logger.debug(response)
-        response.raise_for_status()
-        return response
+
+        if response.is_success:
+            return response
+
+        # Handle different status codes differently
+        status_code = response.status_code
+        error_message = get_error_message(status_code, url, "PUT")
+
+        # 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: PUT {url}: {error_message}")
+            else:
+                logger.info(f"Client error: PUT {url}: {error_message}")
+        else:  # pragma: no cover
+            # Server errors: log as error
+            logger.error(f"Server error: PUT {url}: {error_message}")
+
+        # 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:
-        logger.error(f"Error calling PUT {url}: {e}")
-        raise ToolError(f"Error calling tool: {e}") from e
+        status_code = e.response.status_code
+        error_message = get_error_message(status_code, url, "PUT")
+        raise ToolError(error_message) from e
 
 
 async def call_post(
@@ -103,6 +243,30 @@ async def call_post(
     timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
     extensions: RequestExtensions | None = None,
 ) -> Response:
+    """Make a POST 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 POST '{url}'")
     try:
         response = await client.post(
             url=url,
@@ -118,11 +282,33 @@ async def call_post(
             timeout=timeout,
             extensions=extensions,
         )
-        response.raise_for_status()
-        return response
+
+        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")
+
+        # 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: POST {url}: {error_message}")
+            else:  # pragma: no cover
+                logger.info(f"Client error: POST {url}: {error_message}")
+        else:
+            # Server errors: log as error
+            logger.error(f"Server error: POST {url}: {error_message}")
+
+        # 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:
-        logger.error(f"Error calling POST {url}: {e}")
-        raise ToolError(f"Error calling tool: {e}") from e
+        status_code = e.response.status_code
+        error_message = get_error_message(status_code, url, "POST")
+        raise ToolError(error_message) from e
 
 
 async def call_delete(
@@ -137,6 +323,26 @@ async def call_delete(
     timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
     extensions: RequestExtensions | None = None,
 ) -> Response:
+    """Make a DELETE request and handle errors appropriately.
+
+    Args:
+        client: The HTTPX AsyncClient to use
+        url: The URL to request
+        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 DELETE '{url}'")
     try:
         response = await client.delete(
             url=url,
@@ -148,8 +354,30 @@ async def call_delete(
             timeout=timeout,
             extensions=extensions,
         )
-        response.raise_for_status()
-        return response
+
+        if response.is_success:
+            return response
+
+        # Handle different status codes differently
+        status_code = response.status_code
+        error_message = get_error_message(status_code, url, "DELETE")
+
+        # 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: DELETE {url}: {error_message}")
+            else:
+                logger.info(f"Client error: DELETE {url}: {error_message}")
+        else:  # pragma: no cover
+            # Server errors: log as error
+            logger.error(f"Server error: DELETE {url}: {error_message}")
+
+        # 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:
-        logger.error(f"Error calling DELETE {url}: {e}")
-        raise ToolError(f"Error calling tool: {e}") from 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

@@ -0,0 +1,124 @@
+"""Write note tool for Basic Memory MCP server."""
+
+from typing import Optional, List
+
+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.schemas import EntityResponse
+from basic_memory.schemas.base import Entity
+
+
+@mcp.tool(
+    description="Create or update a markdown note. Returns a markdown formatted summary of the semantic content.",
+)
+async def write_note(
+    title: str,
+    content: str,
+    folder: str,
+    tags: Optional[List[str]] = None,
+) -> str:
+    """Write a markdown note to the knowledge base.
+
+    The content can include semantic observations and relations using markdown syntax.
+    Relations can be specified either explicitly or through inline wiki-style links:
+
+    Observations format:
+        `- [category] Observation text #tag1 #tag2 (optional context)`
+
+        Examples:
+        `- [design] Files are the source of truth #architecture (All state comes from files)`
+        `- [tech] Using SQLite for storage #implementation`
+        `- [note] Need to add error handling #todo`
+
+    Relations format:
+        - Explicit: `- relation_type [[Entity]] (optional context)`
+        - Inline: Any `[[Entity]]` reference creates a relation
+
+        Examples:
+        `- depends_on [[Content Parser]] (Need for semantic extraction)`
+        `- implements [[Search Spec]] (Initial implementation)`
+        `- This feature extends [[Base Design]] and uses [[Core Utils]]`
+
+    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
+        tags: Optional list of tags to categorize the note
+
+    Returns:
+        A markdown formatted summary of the semantic content, including:
+        - Creation/update status
+        - File path and checksum
+        - Observation counts by category
+        - Relation counts (resolved/unresolved)
+        - Tags if present
+    """
+    logger.info("MCP tool call", tool="write_note", folder=folder, title=title, tags=tags)
+
+    # Create the entity request
+    metadata = {"tags": [f"#{tag}" for tag in tags]} if tags else None
+    entity = Entity(
+        title=title,
+        folder=folder,
+        entity_type="note",
+        content_type="text/markdown",
+        content=content,
+        entity_metadata=metadata,
+    )
+
+    # Create or update via knowledge API
+    logger.debug("Creating entity via API", permalink=entity.permalink)
+    url = f"/knowledge/entities/{entity.permalink}"
+    response = await call_put(client, url, json=entity.model_dump())
+    result = EntityResponse.model_validate(response.json())
+
+    # Format semantic summary based on status code
+    action = "Created" if response.status_code == 201 else "Updated"
+    summary = [
+        f"# {action} {result.file_path} ({result.checksum[:8] if result.checksum else 'unknown'})",
+        f"permalink: {result.permalink}",
+    ]
+
+    # Count observations by category
+    categories = {}
+    if result.observations:
+        for obs in result.observations:
+            categories[obs.category] = categories.get(obs.category, 0) + 1
+
+        summary.append("\n## Observations")
+        for category, count in sorted(categories.items()):
+            summary.append(f"- {category}: {count}")
+
+    # Count resolved/unresolved relations
+    unresolved = 0
+    resolved = 0
+    if result.relations:
+        unresolved = sum(1 for r in result.relations if not r.to_id)
+        resolved = len(result.relations) - unresolved
+
+        summary.append("\n## Relations")
+        summary.append(f"- Resolved: {resolved}")
+        if unresolved:
+            summary.append(f"- Unresolved: {unresolved}")
+            summary.append("\nUnresolved relations will be retried on next sync.")
+
+    if tags:
+        summary.append(f"\n## Tags\n- {', '.join(tags)}")
+
+    # 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,
+    )
+
+    return "\n".join(summary)

basic_memory/models/search.py

@@ -8,7 +8,8 @@ CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
     -- Core entity fields
     id UNINDEXED,          -- Row ID
     title,                 -- Title for searching
-    content,               -- Main searchable content
+    content_stems,         -- Main searchable content split into stems
+    content_snippet,       -- File content snippet for display
     permalink,             -- Stable identifier (now indexed for path search)
     file_path UNINDEXED,   -- Physical location
     type UNINDEXED,        -- entity/relation/observation

basic_memory/repository/entity_repository.py

@@ -31,14 +31,15 @@ class EntityRepository(Repository[Entity]):
         query = self.select().where(Entity.permalink == permalink).options(*self.get_load_options())
         return await self.find_one(query)
 
-    async def get_by_title(self, title: str) -> Optional[Entity]:
+    async def get_by_title(self, title: str) -> Sequence[Entity]:
         """Get entity by title.
 
         Args:
             title: Title of the entity to find
         """
         query = self.select().where(Entity.title == title).options(*self.get_load_options())
-        return await self.find_one(query)
+        result = await self.execute_query(query)
+        return list(result.scalars().all())
 
     async def get_by_file_path(self, file_path: Union[Path, str]) -> Optional[Entity]:
         """Get entity by file_path.

basic_memory/repository/project_info_repository.py

@@ -0,0 +1,9 @@
+from basic_memory.repository.repository import Repository
+
+
+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

basic_memory/repository/repository.py

@@ -29,10 +29,11 @@ class Repository[T: Base]:
 
     def __init__(self, session_maker: async_sessionmaker[AsyncSession], Model: Type[T]):
         self.session_maker = session_maker
-        self.Model = Model
-        self.mapper = inspect(self.Model).mapper
-        self.primary_key: Column[Any] = self.mapper.primary_key[0]
-        self.valid_columns = [column.key for column in self.mapper.columns]
+        if Model:
+            self.Model = Model
+            self.mapper = inspect(self.Model).mapper
+            self.primary_key: Column[Any] = self.mapper.primary_key[0]
+            self.valid_columns = [column.key for column in self.mapper.columns]
 
     def get_model_data(self, entity_data):
         model_data = {
@@ -70,7 +71,15 @@ class Repository[T: Base]:
 
             # Query within same session
             found = await self.select_by_id(session, model.id)  # pyright: ignore [reportAttributeAccessIssue]
-            assert found is not None, "can't find model after session.add"
+            if found is None:  # pragma: no cover
+                logger.error(
+                    "Failed to retrieve model after add",
+                    model_type=self.Model.__name__,
+                    model_id=model.id,  # pyright: ignore
+                )
+                raise ValueError(
+                    f"Can't find {self.Model.__name__} with ID {model.id} after session.add"  # pyright: ignore
+                )
             return found
 
     async def add_all(self, models: List[T]) -> Sequence[T]:
@@ -152,7 +161,15 @@ class Repository[T: Base]:
             await session.flush()
 
             return_instance = await self.select_by_id(session, model.id)  # pyright: ignore [reportAttributeAccessIssue]
-            assert return_instance is not None, "can't find model after session.add"
+            if return_instance is None:  # pragma: no cover
+                logger.error(
+                    "Failed to retrieve model after create",
+                    model_type=self.Model.__name__,
+                    model_id=model.id,  # pyright: ignore
+                )
+                raise ValueError(
+                    f"Can't find {self.Model.__name__} with ID {model.id} after session.add"  # pyright: ignore
+                )
             return return_instance
 
     async def create_all(self, data_list: List[dict]) -> Sequence[T]:

basic_memory/repository/search_repository.py

@@ -35,18 +35,24 @@ class SearchIndexRow:
 
     # Type-specific fields
     title: Optional[str] = None  # entity
-    content: Optional[str] = None  # entity, observation
+    content_stems: Optional[str] = None  # entity, observation
+    content_snippet: Optional[str] = None  # entity, observation
     entity_id: Optional[int] = None  # observations
     category: Optional[str] = None  # observations
     from_id: Optional[int] = None  # relations
     to_id: Optional[int] = None  # relations
     relation_type: Optional[str] = None  # relations
 
+    @property
+    def content(self):
+        return self.content_snippet
+
     def to_insert(self):
         return {
             "id": self.id,
             "title": self.title,
-            "content": self.content,
+            "content_stems": self.content_stems,
+            "content_snippet": self.content_snippet,
             "permalink": self.permalink,
             "file_path": self.file_path,
             "type": self.type,
@@ -88,10 +94,16 @@ class SearchRepository:
         For FTS5:
         - Special characters and phrases need to be quoted
         - Terms with spaces or special chars need quotes
+        - Boolean operators (AND, OR, NOT) and parentheses are preserved
         """
         if "*" in term:
             return term
 
+        # Check for boolean operators - if present, return the term as is
+        boolean_operators = [" AND ", " OR ", " NOT ", "(", ")"]
+        if any(op in f" {term} " for op in boolean_operators):
+            return term
+
         # List of special characters that need quoting (excluding *)
         special_chars = ["/", "-", ".", " ", "(", ")", "[", "]", '"', "'"]
 
@@ -124,9 +136,20 @@ class SearchRepository:
 
         # Handle text search for title and content
         if search_text:
-            search_text = self._prepare_search_term(search_text.strip())
-            params["text"] = search_text
-            conditions.append("(title MATCH :text OR content MATCH :text)")
+            has_boolean = any(
+                op in f" {search_text} " for op in [" AND ", " OR ", " NOT ", "(", ")"]
+            )
+
+            if has_boolean:
+                # If boolean operators are present, use the raw query
+                # No need to prepare it, FTS5 will understand the operators
+                params["text"] = search_text
+                conditions.append("(title MATCH :text OR content_stems MATCH :text)")
+            else:
+                # Standard search with term preparation
+                processed_text = self._prepare_search_term(search_text.strip())
+                params["text"] = processed_text
+                conditions.append("(title MATCH :text OR content_stems MATCH :text)")
 
         # Handle title match search
         if title:
@@ -188,7 +211,7 @@ class SearchRepository:
                 to_id,
                 relation_type,
                 entity_id,
-                content,
+                content_snippet,
                 category,
                 created_at,
                 updated_at,
@@ -200,7 +223,7 @@ class SearchRepository:
             OFFSET :offset
         """
 
-        logger.debug(f"Search {sql} params: {params}")
+        logger.trace(f"Search {sql} params: {params}")
         async with db.scoped_session(self.session_maker) as session:
             result = await session.execute(text(sql), params)
             rows = result.fetchall()
@@ -218,7 +241,7 @@ class SearchRepository:
                 to_id=row.to_id,
                 relation_type=row.relation_type,
                 entity_id=row.entity_id,
-                content=row.content,
+                content_snippet=row.content_snippet,
                 category=row.category,
                 created_at=row.created_at,
                 updated_at=row.updated_at,
@@ -250,12 +273,12 @@ class SearchRepository:
             await session.execute(
                 text("""
                     INSERT INTO search_index (
-                        id, title, content, permalink, file_path, type, metadata,
+                        id, title, content_stems, content_snippet, permalink, file_path, type, metadata,
                         from_id, to_id, relation_type,
                         entity_id, category,
                         created_at, updated_at
                     ) VALUES (
-                        :id, :title, :content, :permalink, :file_path, :type, :metadata,
+                        :id, :title, :content_stems, :content_snippet, :permalink, :file_path, :type, :metadata,
                         :from_id, :to_id, :relation_type,
                         :entity_id, :category,
                         :created_at, :updated_at

basic_memory/schemas/__init__.py

@@ -37,6 +37,13 @@ from basic_memory.schemas.response import (
     DeleteEntitiesResponse,
 )
 
+from basic_memory.schemas.project_info import (
+    ProjectStatistics,
+    ActivityMetrics,
+    SystemStatus,
+    ProjectInfoResponse,
+)
+
 # For convenient imports, export all models
 __all__ = [
     # Base
@@ -59,4 +66,9 @@ __all__ = [
     "DeleteEntitiesResponse",
     # Delete Operations
     "DeleteEntitiesRequest",
+    # Project Info
+    "ProjectStatistics",
+    "ActivityMetrics",
+    "SystemStatus",
+    "ProjectInfoResponse",
 ]