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

basic_memory/mcp/prompts/utils.py

@@ -0,0 +1,98 @@
+"""Utility functions for formatting prompt responses.
+
+These utilities help format data from various tools into consistent,
+user-friendly markdown summaries.
+"""
+
+from basic_memory.schemas.memory import GraphContext
+
+
+def format_context_summary(header: str, context: GraphContext) -> str:
+    """Format GraphContext as a helpful markdown summary.
+
+    This creates a user-friendly markdown response that explains the context
+    and provides guidance on how to explore further.
+
+    Args:
+        header: The title to use for the summary
+        context: The GraphContext object to format
+
+    Returns:
+        Formatted markdown string with the context summary
+    """
+    summary = []
+
+    # Extract URI for reference
+    uri = context.metadata.uri or "a/permalink-value"
+
+    # Add header
+    summary.append(f"{header}")
+    summary.append("")
+
+    # Primary document section
+    if context.primary_results:
+        summary.append(f"## Primary Documents ({len(context.primary_results)})")
+
+        for primary in context.primary_results:
+            summary.append(f"### {primary.title}")
+            summary.append(f"- **Type**: {primary.type}")
+            summary.append(f"- **Path**: {primary.file_path}")
+            summary.append(f"- **Created**: {primary.created_at.strftime('%Y-%m-%d %H:%M')}")
+            summary.append("")
+            summary.append(
+                f'To view this document\'s content: `read_note("{primary.permalink}")` or `read_note("{primary.title}")` '
+            )
+            summary.append("")
+    else:
+        summary.append("\nNo primary documents found.")
+
+    # Related documents section
+    if context.related_results:
+        summary.append(f"## Related Documents ({len(context.related_results)})")
+
+        # Group by relation type for better organization
+        relation_types = {}
+        for rel in context.related_results:
+            if hasattr(rel, "relation_type"):
+                rel_type = rel.relation_type  # pyright: ignore
+                if rel_type not in relation_types:
+                    relation_types[rel_type] = []
+                relation_types[rel_type].append(rel)
+
+        # Display relations grouped by type
+        for rel_type, relations in relation_types.items():
+            summary.append(f"### {rel_type.replace('_', ' ').title()} ({len(relations)})")
+
+            for rel in relations:
+                if hasattr(rel, "to_id") and rel.to_id:
+                    summary.append(f"- **{rel.to_id}**")
+                    summary.append(f'  - View document: `read_note("{rel.to_id}")` ')
+                    summary.append(
+                        f'  - Explore connections: `build_context("memory://{rel.to_id}")` '
+                    )
+                else:
+                    summary.append(f"- **Unresolved relation**: {rel.permalink}")
+            summary.append("")
+
+    # Next steps section
+    summary.append("## Next Steps")
+    summary.append("Here are some ways to explore further:")
+
+    search_term = uri.split("/")[-1]
+    summary.append(f'- **Search related topics**: `search({{"text": "{search_term}"}})`')
+
+    summary.append('- **Check recent changes**: `recent_activity(timeframe="3 days")`')
+    summary.append(f'- **Explore all relations**: `build_context("memory://{uri}/*")`')
+
+    # Tips section
+    summary.append("")
+    summary.append("## Tips")
+    summary.append(
+        f'- For more specific context, increase depth: `build_context("memory://{uri}", depth=2)`'
+    )
+    summary.append(
+        "- You can follow specific relation types using patterns like: `memory://document/relation-type/*`"
+    )
+    summary.append("- Look for connected documents by checking relations between them")
+
+    return "\n".join(summary)

basic_memory/mcp/server.py

@@ -1,15 +1,11 @@
 """Enhanced FastMCP server instance for Basic Memory."""
 
 from mcp.server.fastmcp import FastMCP
-
-from basic_memory.utils import setup_logging
+from mcp.server.fastmcp.utilities.logging import configure_logging
 
 # mcp console logging
-# configure_logging(level='INFO')
-
+configure_logging(level="INFO")
 
-# start our out file logging
-setup_logging(log_file=".basic-memory/basic-memory.log")
 
 # Create the shared server instance
-mcp = FastMCP("Basic Memory")
+mcp = FastMCP("Basic Memory")

basic_memory/mcp/tools/__init__.py

@@ -6,11 +6,11 @@ all tools with the MCP server.
 """
 
 # Import tools to register them with MCP
+from basic_memory.mcp.tools.resource import read_resource
 from basic_memory.mcp.tools.memory import build_context, recent_activity
-
-# from basic_memory.mcp.tools.ai_edit import ai_edit
 from basic_memory.mcp.tools.notes import read_note, write_note
 from basic_memory.mcp.tools.search import search
+from basic_memory.mcp.tools.canvas import canvas
 
 from basic_memory.mcp.tools.knowledge import (
     delete_entities,
@@ -31,6 +31,8 @@ __all__ = [
     # notes
     "read_note",
     "write_note",
-    # file edit
-    # "ai_edit",
+    # files
+    "read_resource",
+    # canvas
+    "canvas",
 ]

basic_memory/mcp/tools/canvas.py

@@ -0,0 +1,99 @@
+"""Canvas creation tool for Basic Memory MCP server.
+
+This tool creates Obsidian canvas files (.canvas) using the JSON Canvas 1.0 spec.
+"""
+
+import json
+from typing import Dict, List, Any
+
+import logfire
+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
+
+
+@mcp.tool(
+    description="Create an Obsidian canvas file to visualize concepts and connections.",
+)
+async def canvas(
+    nodes: List[Dict[str, Any]],
+    edges: List[Dict[str, Any]],
+    title: str,
+    folder: str,
+) -> str:
+    """Create an Obsidian canvas file with the provided nodes and edges.
+
+    This tool creates a .canvas file compatible with Obsidian's Canvas feature,
+    allowing visualization of relationships between concepts or documents.
+
+    For the full JSON Canvas 1.0 specification, see the 'spec://canvas' resource.
+
+    Args:
+        nodes: List of node objects following JSON Canvas 1.0 spec
+        edges: List of edge objects following JSON Canvas 1.0 spec
+        title: The title of the canvas (will be saved as title.canvas)
+        folder: The folder where the file should be saved
+
+    Returns:
+        A summary of the created canvas file
+
+    Important Notes:
+    - When referencing files, use the exact file path as shown in Obsidian
+      Example: "folder/Document Name.md" (not permalink format)
+    - For file nodes, the "file" attribute must reference an existing file
+    - Nodes require id, type, x, y, width, height properties
+    - Edges require id, fromNode, toNode properties
+    - Position nodes in a logical layout (x,y coordinates in pixels)
+    - Use color attributes ("1"-"6" or hex) for visual organization
+
+    Basic Structure:
+    ```json
+    {
+      "nodes": [
+        {
+          "id": "node1",
+          "type": "file",  // Options: "file", "text", "link", "group"
+          "file": "folder/Document.md",
+          "x": 0,
+          "y": 0,
+          "width": 400,
+          "height": 300
+        }
+      ],
+      "edges": [
+        {
+          "id": "edge1",
+          "fromNode": "node1",
+          "toNode": "node2",
+          "label": "connects to"
+        }
+      ]
+    }
+    ```
+    """
+    with logfire.span("Creating canvas", folder=folder, title=title):  # type: ignore
+        # Ensure path has .canvas extension
+        file_title = title if title.endswith(".canvas") else f"{title}.canvas"
+        file_path = f"{folder}/{file_title}"
+
+        # Create canvas data structure
+        canvas_data = {"nodes": nodes, "edges": edges}
+
+        # Convert to JSON
+        canvas_json = json.dumps(canvas_data, indent=2)
+
+        # Write the file using the resource API
+        logger.info(f"Creating canvas file: {file_path}")
+        response = await call_put(client, f"/resource/{file_path}", json=canvas_json)
+
+        # Parse response
+        result = response.json()
+        logger.debug(result)
+
+        # Build summary
+        action = "Created" if response.status_code == 201 else "Updated"
+        summary = [f"# {action}: {file_path}", "\nThe canvas is ready to open in Obsidian."]
+
+        return "\n".join(summary)

basic_memory/mcp/tools/memory.py

@@ -1,6 +1,6 @@
 """Discussion context tools for Basic Memory MCP server."""
 
-from typing import Optional, Literal, List
+from typing import Optional, List
 
 from loguru import logger
 import logfire
@@ -15,6 +15,7 @@ from basic_memory.schemas.memory import (
     normalize_memory_url,
 )
 from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.search import SearchItemType
 
 
 @mcp.tool(
@@ -100,7 +101,7 @@ async def build_context(
     """,
 )
 async def recent_activity(
-    type: List[Literal["entity", "observation", "relation"]] = [],
+    type: Optional[List[SearchItemType]] = None,
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
     page: int = 1,
@@ -153,14 +154,20 @@ async def recent_activity(
             f"Getting recent activity from {type}, depth={depth}, timeframe={timeframe}, page={page}, page_size={page_size}, max_related={max_related}"
         )
         params = {
-            "depth": depth,
-            "timeframe": timeframe,
             "page": page,
             "page_size": page_size,
             "max_related": max_related,
         }
+        if depth:
+            params["depth"] = depth
+        if timeframe:
+            params["timeframe"] = timeframe  # pyright: ignore
+
+        # send enum values if we have an enum, else send string value
         if type:
-            params["type"] = type
+            params["type"] = [  # pyright: ignore
+                type.value if isinstance(type, SearchItemType) else type for type in type
+            ]
 
         response = await call_get(
             client,

basic_memory/mcp/tools/notes.py

@@ -84,9 +84,8 @@ async def write_note(
 
         # Format semantic summary based on status code
         action = "Created" if response.status_code == 201 else "Updated"
-        assert result.checksum is not None
         summary = [
-            f"# {action} {result.file_path} ({result.checksum[:8]})",
+            f"# {action} {result.file_path} ({result.checksum[:8] if result.checksum else 'unknown'})",
             f"permalink: {result.permalink}",
         ]
 

basic_memory/mcp/tools/resource.py

@@ -0,0 +1,192 @@
+from loguru import logger
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.async_client import client
+from basic_memory.mcp.tools.utils import call_get
+from basic_memory.schemas.memory import memory_url_path
+
+import base64
+import io
+from PIL import Image as PILImage
+
+
+def calculate_target_params(content_length):
+    """Calculate initial quality and size based on input file size"""
+    target_size = 350000  # Reduced target for more safety margin
+    ratio = content_length / target_size
+
+    logger.debug(
+        "Calculating target parameters",
+        content_length=content_length,
+        ratio=ratio,
+        target_size=target_size,
+    )
+
+    if ratio > 4:
+        # Very large images - start very aggressive
+        return 50, 600  # Lower initial quality and size
+    elif ratio > 2:
+        return 60, 800
+    else:
+        return 70, 1000
+
+
+def resize_image(img, max_size):
+    """Resize image maintaining aspect ratio"""
+    original_dimensions = {"width": img.width, "height": img.height}
+
+    if img.width > max_size or img.height > max_size:
+        ratio = min(max_size / img.width, max_size / img.height)
+        new_size = (int(img.width * ratio), int(img.height * ratio))
+        logger.debug("Resizing image", original=original_dimensions, target=new_size, ratio=ratio)
+        return img.resize(new_size, PILImage.Resampling.LANCZOS)
+
+    logger.debug("No resize needed", dimensions=original_dimensions)
+    return img
+
+
+def optimize_image(img, content_length, max_output_bytes=350000):
+    """Iteratively optimize image with aggressive size reduction"""
+    stats = {
+        "dimensions": {"width": img.width, "height": img.height},
+        "mode": img.mode,
+        "estimated_memory": (img.width * img.height * len(img.getbands())),
+    }
+
+    initial_quality, initial_size = calculate_target_params(content_length)
+
+    logger.debug(
+        "Starting optimization",
+        image_stats=stats,
+        content_length=content_length,
+        initial_quality=initial_quality,
+        initial_size=initial_size,
+        max_output_bytes=max_output_bytes,
+    )
+
+    quality = initial_quality
+    size = initial_size
+
+    # Convert to RGB if needed
+    if img.mode in ("RGBA", "LA") or (img.mode == "P" and "transparency" in img.info):
+        img = img.convert("RGB")
+        logger.debug("Converted to RGB mode")
+
+    iteration = 0
+    min_size = 300  # Absolute minimum size
+    min_quality = 20  # Absolute minimum quality
+
+    while True:
+        iteration += 1
+        buf = io.BytesIO()
+        resized = resize_image(img, size)
+
+        resized.save(
+            buf,
+            format="JPEG",
+            quality=quality,
+            optimize=True,
+            progressive=True,
+            subsampling="4:2:0",
+        )
+
+        output_size = buf.getbuffer().nbytes
+        reduction_ratio = output_size / content_length
+
+        logger.debug(
+            "Optimization attempt",
+            iteration=iteration,
+            quality=quality,
+            size=size,
+            output_bytes=output_size,
+            target_bytes=max_output_bytes,
+            reduction_ratio=f"{reduction_ratio:.2f}",
+        )
+
+        if output_size < max_output_bytes:
+            logger.info(
+                "Image optimization complete",
+                final_size=output_size,
+                quality=quality,
+                dimensions={"width": resized.width, "height": resized.height},
+                reduction_ratio=f"{reduction_ratio:.2f}",
+            )
+            return buf.getvalue()
+
+        # Very aggressive reduction for large files
+        if content_length > 2000000:  # 2MB+   # pragma: no cover
+            quality = max(min_quality, quality - 20)
+            size = max(min_size, int(size * 0.6))
+        elif content_length > 1000000:  # 1MB+ # pragma: no cover
+            quality = max(min_quality, quality - 15)
+            size = max(min_size, int(size * 0.7))
+        else:
+            quality = max(min_quality, quality - 10)  # pragma: no cover
+            size = max(min_size, int(size * 0.8))  # pragma: no cover
+
+        logger.debug("Reducing parameters", new_quality=quality, new_size=size)  # pragma: no cover
+
+        # If we've hit minimum values and still too big
+        if quality <= min_quality and size <= min_size:  # pragma: no cover
+            logger.warning(
+                "Reached minimum parameters",
+                final_size=output_size,
+                over_limit_by=output_size - max_output_bytes,
+            )
+            return buf.getvalue()
+
+
+@mcp.tool(description="Read a single file's content by path or permalink")
+async def read_resource(path: str) -> dict:
+    """Get a file's raw content."""
+    logger.info("Reading resource", path=path)
+
+    url = memory_url_path(path)
+    response = await call_get(client, f"/resource/{url}")
+    content_type = response.headers.get("content-type", "application/octet-stream")
+    content_length = int(response.headers.get("content-length", 0))
+
+    logger.debug("Resource metadata", content_type=content_type, size=content_length, path=path)
+
+    # Handle text or json
+    if content_type.startswith("text/") or content_type == "application/json":
+        logger.debug("Processing text resource")
+        return {
+            "type": "text",
+            "text": response.text,
+            "content_type": content_type,
+            "encoding": "utf-8",
+        }
+
+    # Handle images
+    elif content_type.startswith("image/"):
+        logger.debug("Processing image")
+        img = PILImage.open(io.BytesIO(response.content))
+        img_bytes = optimize_image(img, content_length)
+
+        return {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": "image/jpeg",
+                "data": base64.b64encode(img_bytes).decode("utf-8"),
+            },
+        }
+
+    # Handle other file types
+    else:
+        logger.debug(f"Processing binary resource content_type {content_type}")
+        if content_length > 350000:
+            logger.warning("Document too large for response", size=content_length)
+            return {
+                "type": "error",
+                "error": f"Document size {content_length} bytes exceeds maximum allowed size",
+            }
+        return {
+            "type": "document",
+            "source": {
+                "type": "base64",
+                "media_type": content_type,
+                "data": base64.b64encode(response.content).decode("utf-8"),
+            },
+        }

basic_memory/mcp/tools/utils.py

@@ -44,7 +44,7 @@ async def call_get(
         response.raise_for_status()
         return response
     except HTTPStatusError as e:
-        logger.error(f"Error calling GET {url}: {e}")
+        logger.exception(f"Error calling GET {url}: {e}")
         raise ToolError(f"Error calling tool: {e}.") from e
 
 
@@ -79,6 +79,7 @@ async def call_put(
             timeout=timeout,
             extensions=extensions,
         )
+        logger.debug(response)
         response.raise_for_status()
         return response
     except HTTPStatusError as e:

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/repository/repository.py

@@ -97,7 +97,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})")
 

basic_memory/repository/search_repository.py

@@ -21,13 +21,14 @@ class SearchIndexRow:
 
     id: int
     type: str
-    permalink: str
     file_path: str
-    metadata: Optional[dict] = None
 
     # date values
-    created_at: Optional[datetime] = None
-    updated_at: Optional[datetime] = None
+    created_at: datetime
+    updated_at: datetime
+
+    permalink: Optional[str] = None
+    metadata: Optional[dict] = None
 
     # assigned in result
     score: Optional[float] = None
@@ -265,6 +266,15 @@ class SearchRepository:
             logger.debug(f"indexed row {search_index_row}")
             await session.commit()
 
+    async def delete_by_entity_id(self, entity_id: int):
+        """Delete an item from the search index by entity_id."""
+        async with db.scoped_session(self.session_maker) as session:
+            await session.execute(
+                text("DELETE FROM search_index WHERE entity_id = :entity_id"),
+                {"entity_id": entity_id},
+            )
+            await session.commit()
+
     async def delete_by_permalink(self, permalink: str):
         """Delete an item from the search index."""
         async with db.scoped_session(self.session_maker) as session:

basic_memory/schemas/__init__.py

@@ -37,13 +37,6 @@ from basic_memory.schemas.response import (
     DeleteEntitiesResponse,
 )
 
-# Discovery and analytics models
-from basic_memory.schemas.discovery import (
-    EntityTypeList,
-    ObservationCategoryList,
-    TypedEntityList,
-)
-
 # For convenient imports, export all models
 __all__ = [
     # Base
@@ -66,8 +59,4 @@ __all__ = [
     "DeleteEntitiesResponse",
     # Delete Operations
     "DeleteEntitiesRequest",
-    # Discovery and Analytics
-    "EntityTypeList",
-    "ObservationCategoryList",
-    "TypedEntityList",
 ]

basic_memory/schemas/base.py

@@ -159,7 +159,10 @@ class Entity(BaseModel):
     @property
     def file_path(self):
         """Get the file path for this entity based on its permalink."""
-        return f"{self.folder}/{self.title}.md" if self.folder else f"{self.title}.md"
+        if self.content_type == "text/markdown":
+            return f"{self.folder}/{self.title}.md" if self.folder else f"{self.title}.md"
+        else:
+            return f"{self.folder}/{self.title}" if self.folder else self.title
 
     @property
     def permalink(self) -> Permalink: