basic-memory 0.7.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.error(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,11 +198,33 @@ async def call_put(
             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, "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(
@@ -102,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,
@@ -117,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(
@@ -136,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,
@@ -147,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/knowledge.py

@@ -12,6 +12,7 @@ from sqlalchemy import (
     DateTime,
     Index,
     JSON,
+    text,
 )
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
@@ -32,11 +33,18 @@ class Entity(Base):
 
     __tablename__ = "entity"
     __table_args__ = (
-        UniqueConstraint("permalink", name="uix_entity_permalink"),  # Make permalink unique
+        # Regular indexes
         Index("ix_entity_type", "entity_type"),
         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(
+            "uix_entity_permalink",
+            "permalink",
+            unique=True,
+            sqlite_where=text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
+        ),
     )
 
     # Core identity
@@ -46,8 +54,8 @@ class Entity(Base):
     entity_metadata: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True)
     content_type: Mapped[str] = mapped_column(String)
 
-    # Normalized path for URIs
-    permalink: Mapped[str] = mapped_column(String, unique=True, index=True)
+    # 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)
     # checksum of file
@@ -79,6 +87,11 @@ class Entity(Base):
         """Get all relations (incoming and outgoing) for this entity."""
         return self.incoming_relations + self.outgoing_relations
 
+    @property
+    def is_markdown(self):
+        """Check if the entity is a markdown file."""
+        return self.content_type == "text/markdown"
+
     def __repr__(self) -> str:
         return f"Entity(id={self.id}, name='{self.title}', type='{self.entity_type}'"
 
@@ -127,7 +140,10 @@ class Relation(Base):
 
     __tablename__ = "relation"
     __table_args__ = (
-        UniqueConstraint("from_id", "to_id", "relation_type", name="uix_relation"),
+        UniqueConstraint("from_id", "to_id", "relation_type", name="uix_relation_from_id_to_id"),
+        UniqueConstraint(
+            "from_id", "to_name", "relation_type", name="uix_relation_from_id_to_name"
+        ),
         Index("ix_relation_type", "relation_type"),
         Index("ix_relation_from_id", "from_id"),  # Add FK indexes
         Index("ix_relation_to_id", "to_id"),
@@ -155,13 +171,13 @@ class Relation(Base):
         Format: source/relation_type/target
         Example: "specs/search/implements/features/search-ui"
         """
+        # Only create permalinks when both source and target have permalinks
+        from_permalink = self.from_entity.permalink or self.from_entity.file_path
+
         if self.to_entity:
-            return generate_permalink(
-                f"{self.from_entity.permalink}/{self.relation_type}/{self.to_entity.permalink}"
-            )
-        return generate_permalink(
-            f"{self.from_entity.permalink}/{self.relation_type}/{self.to_name}"
-        )
+            to_permalink = self.to_entity.permalink or self.to_entity.file_path
+            return generate_permalink(f"{from_permalink}/{self.relation_type}/{to_permalink}")
+        return generate_permalink(f"{from_permalink}/{self.relation_type}/{self.to_name}")
 
     def __repr__(self) -> str:
-        return f"Relation(id={self.id}, from_id={self.from_id}, to_id={self.to_id}, to_name={self.to_name}, type='{self.relation_type}')"
+        return f"Relation(id={self.id}, from_id={self.from_id}, to_id={self.to_id}, to_name={self.to_name}, type='{self.relation_type}')"  # pragma: no cover

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]:
@@ -97,7 +106,7 @@ class Repository[T: Base]:
             entities = (self.Model,)
         return select(*entities)
 
-    async def find_all(self, skip: int = 0, limit: Optional[int] = 0) -> Sequence[T]:
+    async def find_all(self, skip: int = 0, limit: Optional[int] = None) -> Sequence[T]:
         """Fetch records from the database with pagination."""
         logger.debug(f"Finding all {self.Model.__name__} (skip={skip}, limit={limit})")
 
@@ -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]: