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

basic_memory/db.py

@@ -86,8 +86,16 @@ async def get_or_create_db(
         _engine = create_async_engine(db_url, connect_args={"check_same_thread": False})
         _session_maker = async_sessionmaker(_engine, expire_on_commit=False)
 
-    assert _engine is not None  # for type checker
-    assert _session_maker is not None  # for type checker
+    # These checks should never fail since we just created the engine and session maker
+    # if they were None, but we'll check anyway for the type checker
+    if _engine is None:
+        logger.error("Failed to create database engine", db_path=str(db_path))
+        raise RuntimeError("Database engine initialization failed")
+
+    if _session_maker is None:
+        logger.error("Failed to create session maker", db_path=str(db_path))
+        raise RuntimeError("Session maker initialization failed")
+
     return _engine, _session_maker
 
 
@@ -121,8 +129,15 @@ async def engine_session_factory(
     try:
         _session_maker = async_sessionmaker(_engine, expire_on_commit=False)
 
-        assert _engine is not None  # for type checker
-        assert _session_maker is not None  # for type checker
+        # Verify that engine and session maker are initialized
+        if _engine is None:  # pragma: no cover
+            logger.error("Database engine is None in engine_session_factory")
+            raise RuntimeError("Database engine initialization failed")
+
+        if _session_maker is None:  # pragma: no cover
+            logger.error("Session maker is None in engine_session_factory")
+            raise RuntimeError("Session maker initialization failed")
+
         yield _engine, _session_maker
     finally:
         if _engine:

basic_memory/deps.py

@@ -2,7 +2,6 @@
 
 from typing import Annotated
 
-import logfire
 from fastapi import Depends
 from sqlalchemy.ext.asyncio import (
     AsyncSession,
@@ -16,6 +15,7 @@ from basic_memory.markdown import EntityParser
 from basic_memory.markdown.markdown_processor import MarkdownProcessor
 from basic_memory.repository.entity_repository import EntityRepository
 from basic_memory.repository.observation_repository import ObservationRepository
+from basic_memory.repository.project_info_repository import ProjectInfoRepository
 from basic_memory.repository.relation_repository import RelationRepository
 from basic_memory.repository.search_repository import SearchRepository
 from basic_memory.services import (
@@ -45,8 +45,6 @@ async def get_engine_factory(
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:  # pragma: no cover
     """Get engine and session maker."""
     engine, session_maker = await db.get_or_create_db(project_config.database_path)
-    if project_config.env != "test":
-        logfire.instrument_sqlalchemy(engine=engine)
     return engine, session_maker
 
 
@@ -107,6 +105,15 @@ async def get_search_repository(
 SearchRepositoryDep = Annotated[SearchRepository, Depends(get_search_repository)]
 
 
+def get_project_info_repository(
+    session_maker: SessionMakerDep,
+):
+    """Dependency for StatsRepository."""
+    return ProjectInfoRepository(session_maker)
+
+
+ProjectInfoRepositoryDep = Annotated[ProjectInfoRepository, Depends(get_project_info_repository)]
+
 ## services
 
 

basic_memory/file_utils.py

@@ -2,11 +2,13 @@
 
 import hashlib
 from pathlib import Path
-from typing import Dict, Any
+from typing import Any, Dict, Union
 
 import yaml
 from loguru import logger
 
+from basic_memory.utils import FilePath
+
 
 class FileError(Exception):
     """Base exception for file operations."""
@@ -26,12 +28,12 @@ class ParseError(FileError):
     pass
 
 
-async def compute_checksum(content: str) -> str:
+async def compute_checksum(content: Union[str, bytes]) -> str:
     """
     Compute SHA-256 checksum of content.
 
     Args:
-        content: Text content to hash
+        content: Content to hash (either text string or bytes)
 
     Returns:
         SHA-256 hex digest
@@ -40,48 +42,55 @@ async def compute_checksum(content: str) -> str:
         FileError: If checksum computation fails
     """
     try:
-        return hashlib.sha256(content.encode()).hexdigest()
+        if isinstance(content, str):
+            content = content.encode()
+        return hashlib.sha256(content).hexdigest()
     except Exception as e:  # pragma: no cover
         logger.error(f"Failed to compute checksum: {e}")
         raise FileError(f"Failed to compute checksum: {e}")
 
 
-async def ensure_directory(path: Path) -> None:
+async def ensure_directory(path: FilePath) -> None:
     """
     Ensure directory exists, creating if necessary.
 
     Args:
-        path: Directory path to ensure
+        path: Directory path to ensure (Path or string)
 
     Raises:
         FileWriteError: If directory creation fails
     """
     try:
-        path.mkdir(parents=True, exist_ok=True)
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        path_obj.mkdir(parents=True, exist_ok=True)
     except Exception as e:  # pragma: no cover
-        logger.error(f"Failed to create directory: {path}: {e}")
+        logger.error("Failed to create directory", path=str(path), error=str(e))
         raise FileWriteError(f"Failed to create directory {path}: {e}")
 
 
-async def write_file_atomic(path: Path, content: str) -> None:
+async def write_file_atomic(path: FilePath, content: str) -> None:
     """
     Write file with atomic operation using temporary file.
 
     Args:
-        path: Target file path
+        path: Target file path (Path or string)
         content: Content to write
 
     Raises:
         FileWriteError: If write operation fails
     """
-    temp_path = path.with_suffix(".tmp")
+    # Convert string to Path if needed
+    path_obj = Path(path) if isinstance(path, str) else path
+    temp_path = path_obj.with_suffix(".tmp")
+
     try:
         temp_path.write_text(content)
-        temp_path.replace(path)
-        logger.debug(f"wrote file: {path}")
+        temp_path.replace(path_obj)
+        logger.debug("Wrote file atomically", path=str(path_obj), content_length=len(content))
     except Exception as e:  # pragma: no cover
         temp_path.unlink(missing_ok=True)
-        logger.error(f"Failed to write file: {path}: {e}")
+        logger.error("Failed to write file", path=str(path_obj), error=str(e))
         raise FileWriteError(f"Failed to write file {path}: {e}")
 
 
@@ -171,7 +180,7 @@ def remove_frontmatter(content: str) -> str:
     return parts[2].strip()
 
 
-async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
+async def update_frontmatter(path: FilePath, updates: Dict[str, Any]) -> str:
     """Update frontmatter fields in a file while preserving all content.
 
     Only modifies the frontmatter section, leaving all content untouched.
@@ -179,7 +188,7 @@ async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
     Returns checksum of updated file.
 
     Args:
-        path: Path to markdown file
+        path: Path to markdown file (Path or string)
         updates: Dict of frontmatter fields to update
 
     Returns:
@@ -190,8 +199,11 @@ async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
         ParseError: If frontmatter parsing fails
     """
     try:
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+
         # Read current content
-        content = path.read_text()
+        content = path_obj.read_text()
 
         # Parse current frontmatter
         current_fm = {}
@@ -206,9 +218,15 @@ async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
         yaml_fm = yaml.dump(new_fm, sort_keys=False)
         final_content = f"---\n{yaml_fm}---\n\n{content.strip()}"
 
-        await write_file_atomic(path, final_content)
+        logger.debug("Updating frontmatter", path=str(path_obj), update_keys=list(updates.keys()))
+
+        await write_file_atomic(path_obj, final_content)
         return await compute_checksum(final_content)
 
     except Exception as e:  # pragma: no cover
-        logger.error(f"Failed to update frontmatter in {path}: {e}")
+        logger.error(
+            "Failed to update frontmatter",
+            path=str(path) if isinstance(path, (str, Path)) else "<unknown>",
+            error=str(e),
+        )
         raise FileError(f"Failed to update frontmatter: {e}")

basic_memory/markdown/entity_parser.py

@@ -88,10 +88,10 @@ class EntityParser:
                 return parsed
         return None
 
-    async def parse_file(self, file_path: Path) -> EntityMarkdown:
+    async def parse_file(self, path: Path | str) -> EntityMarkdown:
         """Parse markdown file into EntityMarkdown."""
 
-        absolute_path = self.base_path / file_path
+        absolute_path = self.base_path / path
         # Parse frontmatter and content using python-frontmatter
         post = frontmatter.load(str(absolute_path))
 
@@ -99,7 +99,7 @@ class EntityParser:
         file_stats = absolute_path.stat()
 
         metadata = post.metadata
-        metadata["title"] = post.metadata.get("title", file_path.name)
+        metadata["title"] = post.metadata.get("title", absolute_path.name)
         metadata["type"] = post.metadata.get("type", "note")
         metadata["tags"] = parse_tags(post.metadata.get("tags", []))
 

basic_memory/markdown/utils.py

@@ -5,6 +5,7 @@ from typing import Optional, Any
 
 from frontmatter import Post
 
+from basic_memory.file_utils import has_frontmatter, remove_frontmatter
 from basic_memory.markdown import EntityMarkdown
 from basic_memory.models import Entity, Observation as ObservationModel
 from basic_memory.utils import generate_permalink
@@ -78,6 +79,10 @@ async def schema_to_markdown(schema: Any) -> Post:
     content = schema.content or ""
     frontmatter_metadata = dict(schema.entity_metadata or {})
 
+    # if the content contains frontmatter, remove it and merge
+    if has_frontmatter(content):
+        content = remove_frontmatter(content)
+
     # Remove special fields for ordered frontmatter
     for field in ["type", "title", "permalink"]:
         frontmatter_metadata.pop(field, None)

basic_memory/mcp/async_client.py

@@ -2,7 +2,7 @@ from httpx import ASGITransport, AsyncClient
 
 from basic_memory.api.app import app as fastapi_app
 
-BASE_URL = "memory://"
+BASE_URL = "http://test"
 
 # Create shared async client
 client = AsyncClient(transport=ASGITransport(app=fastapi_app), base_url=BASE_URL)

basic_memory/mcp/main.py

@@ -0,0 +1,24 @@
+"""Main MCP entrypoint for Basic Memory.
+
+Creates and configures the shared MCP instance and handles server startup.
+"""
+
+from loguru import logger  # pragma: no cover
+
+from basic_memory.config import config  # pragma: no cover
+
+# Import shared mcp instance
+from basic_memory.mcp.server import mcp  # pragma: no cover
+
+# Import tools to register them
+import basic_memory.mcp.tools  # noqa: F401 # pragma: no cover
+
+# Import prompts to register them
+import basic_memory.mcp.prompts  # noqa: F401 # pragma: no cover
+
+
+if __name__ == "__main__":  # pragma: no cover
+    home_dir = config.home
+    logger.info("Starting Basic Memory MCP server")
+    logger.info(f"Home directory: {home_dir}")
+    mcp.run()

basic_memory/mcp/prompts/__init__.py

@@ -0,0 +1,19 @@
+"""Basic Memory MCP prompts.
+
+Prompts are a special type of tool that returns a string response
+formatted for a user to read, typically invoking one or more tools
+and transforming their results into user-friendly text.
+"""
+
+# Import individual prompt modules to register them with the MCP server
+from basic_memory.mcp.prompts import continue_conversation
+from basic_memory.mcp.prompts import recent_activity
+from basic_memory.mcp.prompts import search
+from basic_memory.mcp.prompts import ai_assistant_guide
+
+__all__ = [
+    "ai_assistant_guide",
+    "continue_conversation",
+    "recent_activity",
+    "search",
+]

basic_memory/mcp/prompts/ai_assistant_guide.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from loguru import logger
+
+from basic_memory.mcp.server import mcp
+
+
+@mcp.resource(
+    uri="memory://ai_assistant_guide",
+    name="ai assistant guide",
+    description="Give an AI assistant guidance on how to use Basic Memory tools effectively",
+)
+def ai_assistant_guide() -> str:
+    """Return a concise guide on Basic Memory tools and how to use them.
+
+    Args:
+        focus: Optional area to focus on ("writing", "context", "search", etc.)
+
+    Returns:
+        A focused guide on Basic Memory usage.
+    """
+    logger.info("Loading AI assistant guide resource")
+    guide_doc = Path(__file__).parent.parent.parent.parent.parent / "static" / "ai_assistant_guide.md"
+    content = guide_doc.read_text()
+    logger.info(f"Loaded AI assistant guide ({len(content)} chars)")
+    return content

basic_memory/mcp/prompts/continue_conversation.py

@@ -0,0 +1,111 @@
+"""Session continuation prompts for Basic Memory MCP server.
+
+These prompts help users continue conversations and work across sessions,
+providing context from previous interactions to maintain continuity.
+"""
+
+from textwrap import dedent
+from typing import Optional, Annotated
+
+from loguru import logger
+from pydantic import Field
+
+from basic_memory.mcp.prompts.utils import format_prompt_context, PromptContext, PromptContextItem
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.build_context import build_context
+from basic_memory.mcp.tools.recent_activity import recent_activity
+from basic_memory.mcp.tools.search import search
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import GraphContext
+from basic_memory.schemas.search import SearchQuery, SearchItemType
+
+
+@mcp.prompt(
+    name="Continue Conversation",
+    description="Continue a previous conversation",
+)
+async def continue_conversation(
+    topic: Annotated[Optional[str], Field(description="Topic or keyword to search for")] = None,
+    timeframe: Annotated[
+        Optional[TimeFrame],
+        Field(description="How far back to look for activity (e.g. '1d', '1 week')"),
+    ] = None,
+) -> str:
+    """Continue a previous conversation or work session.
+
+    This prompt helps you pick up where you left off by finding recent context
+    about a specific topic or showing general recent activity.
+
+    Args:
+        topic: Topic or keyword to search for (optional)
+        timeframe: How far back to look for activity
+
+    Returns:
+        Context from previous sessions on this topic
+    """
+    logger.info(f"Continuing session, topic: {topic}, timeframe: {timeframe}")
+
+    # If topic provided, search for it
+    if topic:
+        search_results = await search(
+            SearchQuery(text=topic, after_date=timeframe, types=[SearchItemType.ENTITY])
+        )
+
+        # Build context from results
+        contexts = []
+        for result in search_results.results:
+            if hasattr(result, "permalink") and result.permalink:
+                context: GraphContext = await build_context(f"memory://{result.permalink}")
+                if context.primary_results:
+                    contexts.append(
+                        PromptContextItem(
+                            primary_results=context.primary_results[:1],  # pyright: ignore
+                            related_results=context.related_results[:3],  # pyright: ignore
+                        )
+                    )
+
+        # get context for the top 3 results
+        prompt_context = format_prompt_context(
+            PromptContext(topic=topic, timeframe=timeframe, results=contexts)  # pyright: ignore
+        )
+
+    else:
+        # If no topic, get recent activity
+        timeframe = timeframe or "7d"
+        recent: GraphContext = await recent_activity(
+            timeframe=timeframe, type=[SearchItemType.ENTITY]
+        )
+        prompt_context = format_prompt_context(
+            PromptContext(
+                topic=f"Recent Activity from ({timeframe})",
+                timeframe=timeframe,
+                results=[
+                    PromptContextItem(
+                        primary_results=recent.primary_results[:5],  # pyright: ignore
+                        related_results=recent.related_results[:2],  # pyright: ignore
+                    )
+                ],
+            )
+        )
+
+    # Add next steps with strong encouragement to write
+    next_steps = dedent(f"""
+        ## Next Steps
+
+        You can:
+        - Explore more with: `search({{"text": "{topic}"}})`
+        - See what's changed: `recent_activity(timeframe="{timeframe or "7d"}")`
+        - **Record new learnings or decisions from this conversation:** `write_note(title="[Create a meaningful title]", content="[Content with observations and relations]")`
+        
+        ## Knowledge Capture Recommendation
+        
+        As you continue this conversation, **actively look for opportunities to:**
+        1. Record key information, decisions, or insights that emerge
+        2. Link new knowledge to existing topics 
+        3. Suggest capturing important context when appropriate
+        4. Create forward references to topics that might be created later
+        
+        Remember that capturing knowledge during conversations is one of the most valuable aspects of Basic Memory.
+        """)
+
+    return prompt_context + next_steps

basic_memory/mcp/prompts/recent_activity.py

@@ -0,0 +1,88 @@
+"""Recent activity prompts for Basic Memory MCP server.
+
+These prompts help users see what has changed in their knowledge base recently.
+"""
+
+from typing import Annotated
+
+from loguru import logger
+from pydantic import Field
+
+from basic_memory.mcp.prompts.utils import format_prompt_context, PromptContext, PromptContextItem
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.recent_activity import recent_activity
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.search import SearchItemType
+
+
+@mcp.prompt(
+    name="Share Recent Activity",
+    description="Get recent activity from across the knowledge base",
+)
+async def recent_activity_prompt(
+    timeframe: Annotated[
+        TimeFrame,
+        Field(description="How far back to look for activity (e.g. '1d', '1 week')"),
+    ] = "7d",
+) -> str:
+    """Get recent activity from across the knowledge base.
+
+    This prompt helps you see what's changed recently in the knowledge base,
+    showing new or updated documents and related information.
+
+    Args:
+        timeframe: How far back to look for activity (e.g. '1d', '1 week')
+
+    Returns:
+        Formatted summary of recent activity
+    """
+    logger.info(f"Getting recent activity, timeframe: {timeframe}")
+
+    recent = await recent_activity(timeframe=timeframe, type=[SearchItemType.ENTITY])
+
+    prompt_context = format_prompt_context(
+        PromptContext(
+            topic=f"Recent Activity from ({timeframe})",
+            timeframe=timeframe,
+            results=[
+                PromptContextItem(
+                    primary_results=recent.primary_results[:5],
+                    related_results=recent.related_results[:2],
+                )
+            ],
+        )
+    )
+
+    # Add suggestions for summarizing recent activity
+    capture_suggestions = f"""
+    ## Opportunity to Capture Activity Summary
+    
+    Consider creating a summary note of recent activity:
+    
+    ```python
+    await write_note(
+        title="Activity Summary {timeframe}",
+        content='''
+        # Activity Summary for {timeframe}
+        
+        ## Overview
+        [Summary of key changes and developments over this period]
+        
+        ## Key Updates
+        [List main updates and their significance]
+        
+        ## Observations
+        - [trend] [Observation about patterns in recent activity]
+        - [insight] [Connection between different activities]
+        
+        ## Relations
+        - summarizes [[{recent.primary_results[0].title if recent.primary_results else "Recent Topic"}]]
+        - relates_to [[Project Overview]]
+        '''
+    )
+    ```
+    
+    Summarizing periodic activity helps create high-level insights and connections between topics.
+    """
+
+    return prompt_context + capture_suggestions