basic-memory 0.11.0__py3-none-any.whl → 0.12.1__py3-none-any.whl

basic_memory/__init__.py

@@ -1,3 +1,3 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
-__version__ = "0.11.0"
+__version__ = "0.12.1"

basic_memory/api/app.py

@@ -7,16 +7,24 @@ from fastapi.exception_handlers import http_exception_handler
 from loguru import logger
 
 from basic_memory import db
-from basic_memory.config import config as app_config
-from basic_memory.api.routers import knowledge, search, memory, resource, project_info
+from basic_memory.api.routers import knowledge, memory, project_info, resource, search
+from basic_memory.config import config as project_config
+from basic_memory.services.initialization import initialize_app
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):  # pragma: no cover
     """Lifecycle manager for the FastAPI app."""
-    await db.run_migrations(app_config)
+    # Initialize database and file sync services
+    watch_task = await initialize_app(project_config)
+
+    # proceed with startup
     yield
+
     logger.info("Shutting down Basic Memory API")
+    if watch_task:
+        watch_task.cancel()
+
     await db.shutdown_db()
 
 

basic_memory/cli/app.py

@@ -1,18 +1,17 @@
-import asyncio
 from typing import Optional
 
 import typer
 
-from basic_memory import db
-from basic_memory.config import config
-
 
 def version_callback(value: bool) -> None:
     """Show version and exit."""
     if value:  # pragma: no cover
         import basic_memory
+        from basic_memory.config import config
 
         typer.echo(f"Basic Memory version: {basic_memory.__version__}")
+        typer.echo(f"Current project: {config.project}")
+        typer.echo(f"Project path: {config.home}")
         raise typer.Exit()
 
 
@@ -21,11 +20,12 @@ app = typer.Typer(name="basic-memory")
 
 @app.callback()
 def app_callback(
+    ctx: typer.Context,
     project: Optional[str] = typer.Option(
         None,
         "--project",
         "-p",
-        help="Specify which project to use",
+        help="Specify which project to use 1",
         envvar="BASIC_MEMORY_PROJECT",
     ),
     version: Optional[bool] = typer.Option(
@@ -38,6 +38,7 @@ def app_callback(
     ),
 ) -> None:
     """Basic Memory - Local-first personal knowledge management."""
+
     # We use the project option to set the BASIC_MEMORY_PROJECT environment variable
     # The config module will pick this up when loading
     if project:  # pragma: no cover
@@ -57,9 +58,13 @@ def app_callback(
 
         config = new_config
 
+    # Run migrations for every command unless --version was specified
+    if not version and ctx.invoked_subcommand is not None:
+        from basic_memory.config import config
+        from basic_memory.services.initialization import ensure_initialize_database
+
+        ensure_initialize_database(config)
 
-# Run database migrations
-asyncio.run(db.run_migrations(config))
 
 # Register sub-command groups
 import_app = typer.Typer(help="Import data from various sources")

basic_memory/cli/commands/mcp.py

@@ -1,10 +1,7 @@
 """MCP server command."""
 
-from loguru import logger
-
 import basic_memory
 from basic_memory.cli.app import app
-from basic_memory.config import config
 
 # Import mcp instance
 from basic_memory.mcp.server import mcp as mcp_server  # pragma: no cover
@@ -15,12 +12,24 @@ import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
 
 @app.command()
 def mcp():  # pragma: no cover
-    """Run the MCP server for Claude Desktop integration."""
-    home_dir = config.home
-    project_name = config.project
+    """Run the MCP server"""
+    from basic_memory.config import config
+    import asyncio
+    from basic_memory.services.initialization import initialize_database
+
+    # First, run just the database migrations synchronously
+    asyncio.run(initialize_database(config))
+
+    # Load config to check if sync is enabled
+    from basic_memory.config import config_manager
+
+    basic_memory_config = config_manager.load_config()
+
+    if basic_memory_config.sync_changes:
+        # For now, we'll just log that sync will be handled by the MCP server
+        from loguru import logger
 
-    logger.info(f"Starting Basic Memory MCP server {basic_memory.__version__}")
-    logger.info(f"Project: {project_name}")
-    logger.info(f"Project directory: {home_dir}")
+        logger.info("File sync will be handled by the MCP server")
 
+    # Start the MCP server
     mcp_server.run()

basic_memory/cli/commands/sync.py

@@ -70,6 +70,7 @@ async def get_sync_service():  # pragma: no cover
 
     # Create sync service
     sync_service = SyncService(
+        config=config,
         entity_service=entity_service,
         entity_parser=entity_parser,
         entity_repository=entity_repository,
@@ -178,14 +179,14 @@ async def run_sync(verbose: bool = False, watch: bool = False, console_status: b
         )
 
         # full sync - no progress bars in watch mode
-        await sync_service.sync(config.home, show_progress=False)
+        await sync_service.sync(config.home)
 
         # watch changes
         await watch_service.run()  # pragma: no cover
     else:
-        # one time sync - use progress bars for better UX
+        # one time sync
         logger.info("Running one-time sync")
-        knowledge_changes = await sync_service.sync(config.home, show_progress=True)
+        knowledge_changes = await sync_service.sync(config.home)
 
         # Log results
         duration_ms = int((time.time() - start_time) * 1000)
@@ -236,11 +237,11 @@ def sync(
         if not isinstance(e, typer.Exit):
             logger.exception(
                 "Sync command failed",
-                project=config.project,
-                error=str(e),
-                error_type=type(e).__name__,
-                watch_mode=watch,
-                directory=str(config.home),
+                f"project={config.project},"
+                f"error={str(e)},"
+                f"error_type={type(e).__name__},"
+                f"watch_mode={watch},"
+                f"directory={str(config.home)}",
             )
             typer.echo(f"Error during sync: {e}", err=True)
             raise typer.Exit(1)

basic_memory/cli/commands/tool.py

@@ -2,31 +2,29 @@
 
 import asyncio
 import sys
-from typing import Optional, List, Annotated
+from typing import Annotated, List, Optional
 
 import typer
 from loguru import logger
 from rich import print as rprint
 
 from basic_memory.cli.app import app
-from basic_memory.mcp.tools import build_context as mcp_build_context
-from basic_memory.mcp.tools import read_note as mcp_read_note
-from basic_memory.mcp.tools import recent_activity as mcp_recent_activity
-from basic_memory.mcp.tools import search_notes as mcp_search
-from basic_memory.mcp.tools import write_note as mcp_write_note
 
 # Import prompts
 from basic_memory.mcp.prompts.continue_conversation import (
     continue_conversation as mcp_continue_conversation,
 )
-
 from basic_memory.mcp.prompts.recent_activity import (
     recent_activity_prompt as recent_activity_prompt,
 )
-
+from basic_memory.mcp.tools import build_context as mcp_build_context
+from basic_memory.mcp.tools import read_note as mcp_read_note
+from basic_memory.mcp.tools import recent_activity as mcp_recent_activity
+from basic_memory.mcp.tools import search_notes as mcp_search
+from basic_memory.mcp.tools import write_note as mcp_write_note
 from basic_memory.schemas.base import TimeFrame
 from basic_memory.schemas.memory import MemoryUrl
-from basic_memory.schemas.search import SearchQuery, SearchItemType
+from basic_memory.schemas.search import SearchItemType
 
 tool_app = typer.Typer()
 app.add_typer(tool_app, name="tool", help="Access to MCP tools via CLI")
@@ -198,13 +196,28 @@ def search_notes(
         raise typer.Abort()
 
     try:
-        search_query = SearchQuery(
-            permalink_match=query if permalink else None,
-            text=query if not (permalink or title) else None,
-            title=query if title else None,
-            after_date=after_date,
+        if permalink and title:  # pragma: no cover
+            typer.echo(
+                "Use either --permalink or --title, not both. Exiting.",
+                err=True,
+            )
+            raise typer.Exit(1)
+
+        # set search type
+        search_type = ("permalink" if permalink else None,)
+        search_type = ("permalink_match" if permalink and "*" in query else None,)
+        search_type = ("title" if title else None,)
+        search_type = "text" if search_type is None else search_type
+
+        results = asyncio.run(
+            mcp_search(
+                query,
+                search_type=search_type,
+                page=page,
+                after_date=after_date,
+                page_size=page_size,
+            )
         )
-        results = asyncio.run(mcp_search(query=search_query, page=page, page_size=page_size))
         # Use json module for more controlled serialization
         import json
 

basic_memory/cli/main.py

@@ -1,58 +1,26 @@
 """Main CLI entry point for basic-memory."""  # pragma: no cover
 
 from basic_memory.cli.app import app  # pragma: no cover
-import typer
 
 # Register commands
 from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
-    status,
-    sync,
     db,
-    import_memory_json,
-    mcp,
+    import_chatgpt,
     import_claude_conversations,
     import_claude_projects,
-    import_chatgpt,
-    tool,
+    import_memory_json,
+    mcp,
     project,
+    status,
+    sync,
+    tool,
 )
-
-
-# Version command
-@app.callback(invoke_without_command=True)
-def main(
-    ctx: typer.Context,
-    project: str = typer.Option(  # noqa
-        "main",
-        "--project",
-        "-p",
-        help="Specify which project to use",
-        envvar="BASIC_MEMORY_PROJECT",
-    ),
-    version: bool = typer.Option(
-        False,
-        "--version",
-        "-V",
-        help="Show version information and exit.",
-        is_eager=True,
-    ),
-):
-    """Basic Memory - Local-first personal knowledge management system."""
-    if version:  # pragma: no cover
-        from basic_memory import __version__
-        from basic_memory.config import config
-
-        typer.echo(f"Basic Memory v{__version__}")
-        typer.echo(f"Current project: {config.project}")
-        typer.echo(f"Project path: {config.home}")
-        raise typer.Exit()
-
-    # Handle project selection via environment variable
-    if project:
-        import os
-
-        os.environ["BASIC_MEMORY_PROJECT"] = project
-
+from basic_memory.config import config
+from basic_memory.services.initialization import ensure_initialization
 
 if __name__ == "__main__":  # pragma: no cover
+    # Run initialization if we are starting as a module
+    ensure_initialization(config)
+
+    # start the app
     app()

basic_memory/config.py

@@ -35,10 +35,14 @@ class ProjectConfig(BaseSettings):
 
     # Watch service configuration
     sync_delay: int = Field(
-        default=500, description="Milliseconds to wait after changes before syncing", gt=0
+        default=1000, description="Milliseconds to wait after changes before syncing", gt=0
     )
 
-    log_level: str = "DEBUG"
+    # update permalinks on move
+    update_permalinks_on_move: bool = Field(
+        default=False,
+        description="Whether to update permalinks when files are moved or renamed. default (False)",
+    )
 
     model_config = SettingsConfigDict(
         env_prefix="BASIC_MEMORY_",
@@ -77,6 +81,18 @@ class BasicMemoryConfig(BaseSettings):
         description="Name of the default project to use",
     )
 
+    log_level: str = "INFO"
+
+    update_permalinks_on_move: bool = Field(
+        default=False,
+        description="Whether to update permalinks when files are moved or renamed. default (False)",
+    )
+
+    sync_changes: bool = Field(
+        default=True,
+        description="Whether to sync changes in real time. default (True)",
+    )
+
     model_config = SettingsConfigDict(
         env_prefix="BASIC_MEMORY_",
         extra="ignore",
@@ -194,9 +210,14 @@ def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
         "BASIC_MEMORY_PROJECT", project_name or config_manager.default_project
     )
 
+    update_permalinks_on_move = config_manager.load_config().update_permalinks_on_move
     try:
         project_path = config_manager.get_project_path(actual_project_name)
-        return ProjectConfig(home=project_path, project=actual_project_name)
+        return ProjectConfig(
+            home=project_path,
+            project=actual_project_name,
+            update_permalinks_on_move=update_permalinks_on_move,
+        )
     except ValueError:  # pragma: no cover
         logger.warning(f"Project '{actual_project_name}' not found, using default")
         project_path = config_manager.get_project_path(config_manager.default_project)
@@ -225,8 +246,10 @@ def get_process_name():  # pragma: no cover
         return "sync"
     elif "mcp" in sys.argv:
         return "mcp"
-    else:
+    elif "cli" in sys.argv:
         return "cli"
+    else:
+        return "api"
 
 
 process_name = get_process_name()
@@ -234,6 +257,7 @@ process_name = get_process_name()
 # Global flag to track if logging has been set up
 _LOGGING_SETUP = False
 
+
 def setup_basic_memory_logging():  # pragma: no cover
     """Set up logging for basic-memory, ensuring it only happens once."""
     global _LOGGING_SETUP
@@ -245,12 +269,12 @@ def setup_basic_memory_logging():  # pragma: no cover
     setup_logging(
         env=config.env,
         home_dir=user_home,  # Use user home for logs
-        log_level=config.log_level,
+        log_level=config_manager.load_config().log_level,
         log_file=f"{DATA_DIR_NAME}/basic-memory-{process_name}.log",
         console=False,
     )
 
-    logger.info(f"Starting Basic Memory {basic_memory.__version__} (Project: {config.project})")
+    logger.info(f"Basic Memory {basic_memory.__version__} (Project: {config.project})")
     _LOGGING_SETUP = True
 
 

basic_memory/db.py

@@ -146,7 +146,9 @@ async def engine_session_factory(
             _session_maker = None
 
 
-async def run_migrations(app_config: ProjectConfig, database_type=DatabaseType.FILESYSTEM):
+async def run_migrations(
+    app_config: ProjectConfig, database_type=DatabaseType.FILESYSTEM
+):  # pragma: no cover
     """Run any pending alembic migrations."""
     logger.info("Running database migrations...")
     try:

basic_memory/file_utils.py

@@ -104,6 +104,9 @@ def has_frontmatter(content: str) -> bool:
     Returns:
         True if content has valid frontmatter markers (---), False otherwise
     """
+    if not content:
+        return False
+
     content = content.strip()
     if not content.startswith("---"):
         return False

basic_memory/markdown/entity_parser.py

@@ -92,27 +92,36 @@ class EntityParser:
     async def parse_file(self, path: Path | str) -> EntityMarkdown:
         """Parse markdown file into EntityMarkdown."""
 
-        absolute_path = self.base_path / path
+        # TODO move to api endpoint to check if absolute path was requested
+        # Check if the path is already absolute
+        if (
+            isinstance(path, Path)
+            and path.is_absolute()
+            or (isinstance(path, str) and Path(path).is_absolute())
+        ):
+            absolute_path = Path(path)
+        else:
+            absolute_path = self.base_path / path
+
         # Parse frontmatter and content using python-frontmatter
-        post = frontmatter.load(str(absolute_path))
+        file_content = absolute_path.read_text()
+        return await self.parse_file_content(absolute_path, file_content)
 
+    async def parse_file_content(self, absolute_path, file_content):
+        post = frontmatter.loads(file_content)
         # Extract file stat info
         file_stats = absolute_path.stat()
-
         metadata = post.metadata
-        metadata["title"] = post.metadata.get("title", absolute_path.name)
+        metadata["title"] = post.metadata.get("title", absolute_path.stem)
         metadata["type"] = post.metadata.get("type", "note")
         tags = parse_tags(post.metadata.get("tags", []))  # pyright: ignore
         if tags:
             metadata["tags"] = tags
-
         # frontmatter
         entity_frontmatter = EntityFrontmatter(
             metadata=post.metadata,
         )
-
         entity_content = parse(post.content)
-
         return EntityMarkdown(
             frontmatter=entity_frontmatter,
             content=post.content,

basic_memory/markdown/utils.py

@@ -1,14 +1,14 @@
 """Utilities for converting between markdown and entity models."""
 
 from pathlib import Path
-from typing import Optional, Any
+from typing import Any, Optional
 
 from frontmatter import Post
 
-from basic_memory.file_utils import has_frontmatter, remove_frontmatter
+from basic_memory.file_utils import has_frontmatter, remove_frontmatter, parse_frontmatter
 from basic_memory.markdown import EntityMarkdown
-from basic_memory.models import Entity, Observation as ObservationModel
-from basic_memory.utils import generate_permalink
+from basic_memory.models import Entity
+from basic_memory.models import Observation as ObservationModel
 
 
 def entity_model_from_markdown(
@@ -32,16 +32,13 @@ def entity_model_from_markdown(
     if not markdown.created or not markdown.modified:  # pragma: no cover
         raise ValueError("Both created and modified dates are required in markdown")
 
-    # Generate permalink if not provided
-    permalink = markdown.frontmatter.permalink or generate_permalink(file_path)
-
     # Create or update entity
     model = entity or Entity()
 
     # Update basic fields
     model.title = markdown.frontmatter.title
     model.entity_type = markdown.frontmatter.type
-    model.permalink = permalink
+    model.permalink = markdown.frontmatter.permalink
     model.file_path = str(file_path)
     model.content_type = "text/markdown"
     model.created_at = markdown.created
@@ -77,22 +74,33 @@ async def schema_to_markdown(schema: Any) -> Post:
     """
     # Extract content and metadata
     content = schema.content or ""
-    frontmatter_metadata = dict(schema.entity_metadata or {})
+    entity_metadata = dict(schema.entity_metadata or {})
 
     # if the content contains frontmatter, remove it and merge
     if has_frontmatter(content):
+        content_frontmatter = parse_frontmatter(content)
         content = remove_frontmatter(content)
 
+        # Merge content frontmatter with entity metadata
+        # (entity_metadata takes precedence for conflicts)
+        content_frontmatter.update(entity_metadata)
+        entity_metadata = content_frontmatter
+
     # Remove special fields for ordered frontmatter
     for field in ["type", "title", "permalink"]:
-        frontmatter_metadata.pop(field, None)
+        entity_metadata.pop(field, None)
 
-    # Create Post with ordered fields
+    # Create Post with fields ordered by insert order
     post = Post(
         content,
         title=schema.title,
         type=schema.entity_type,
-        permalink=schema.permalink,
-        **frontmatter_metadata,
     )
+    # set the permalink if passed in
+    if schema.permalink:
+        post.metadata["permalink"] = schema.permalink
+
+    if entity_metadata:
+        post.metadata.update(entity_metadata)
+
     return post

basic_memory/mcp/prompts/continue_conversation.py

@@ -5,19 +5,19 @@ providing context from previous interactions to maintain continuity.
 """
 
 from textwrap import dedent
-from typing import Optional, Annotated
+from typing import Annotated, Optional
 
 from loguru import logger
 from pydantic import Field
 
-from basic_memory.mcp.prompts.utils import format_prompt_context, PromptContext, PromptContextItem
+from basic_memory.mcp.prompts.utils import PromptContext, PromptContextItem, format_prompt_context
 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_notes
 from basic_memory.schemas.base import TimeFrame
 from basic_memory.schemas.memory import GraphContext
-from basic_memory.schemas.search import SearchQuery, SearchItemType
+from basic_memory.schemas.search import SearchItemType
 
 
 @mcp.prompt(
@@ -48,7 +48,7 @@ async def continue_conversation(
     # If topic provided, search for it
     if topic:
         search_results = await search_notes(
-            SearchQuery(text=topic, after_date=timeframe, types=[SearchItemType.ENTITY])
+            query=topic, after_date=timeframe, entity_types=[SearchItemType.ENTITY]
         )
 
         # Build context from results

basic_memory/mcp/prompts/search.py

@@ -12,7 +12,7 @@ from pydantic import Field
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.search import search_notes as search_tool
 from basic_memory.schemas.base import TimeFrame
-from basic_memory.schemas.search import SearchQuery, SearchResponse
+from basic_memory.schemas.search import SearchResponse
 
 
 @mcp.prompt(
@@ -40,7 +40,7 @@ async def search_prompt(
     """
     logger.info(f"Searching knowledge base, query: {query}, timeframe: {timeframe}")
 
-    search_results = await search_tool(SearchQuery(text=query, after_date=timeframe))
+    search_results = await search_tool(query=query, after_date=timeframe)
     return format_search_results(query, search_results, timeframe)
 
 

basic_memory/mcp/server.py

@@ -1,11 +1,37 @@
 """Enhanced FastMCP server instance for Basic Memory."""
 
+import asyncio
+from contextlib import asynccontextmanager
+from typing import AsyncIterator, Optional
+
 from mcp.server.fastmcp import FastMCP
-from mcp.server.fastmcp.utilities.logging import configure_logging
+from mcp.server.fastmcp.utilities.logging import configure_logging as mcp_configure_logging
+from dataclasses import dataclass
+
+from basic_memory.config import config as project_config
+from basic_memory.services.initialization import initialize_app
 
 # mcp console logging
-configure_logging(level="INFO")
+mcp_configure_logging(level="ERROR")
+
+
+@dataclass
+class AppContext:
+    watch_task: Optional[asyncio.Task]
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:  # pragma: no cover
+    """Manage application lifecycle with type-safe context"""
+    # Initialize on startup
+    watch_task = await initialize_app(project_config)
+    try:
+        yield AppContext(watch_task=watch_task)
+    finally:
+        # Cleanup on shutdown
+        if watch_task:
+            watch_task.cancel()
 
 
 # Create the shared server instance
-mcp = FastMCP("Basic Memory")
+mcp = FastMCP("Basic Memory", log_level="ERROR", lifespan=app_lifespan)

basic_memory/mcp/tools/read_note.py

@@ -9,7 +9,6 @@ from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas.memory import memory_url_path
-from basic_memory.schemas.search import SearchQuery
 
 
 @mcp.tool(
@@ -63,7 +62,7 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
 
     # Fallback 1: Try title search via API
     logger.info(f"Search title for: {identifier}")
-    title_results = await search_notes(SearchQuery(title=identifier))
+    title_results = await search_notes(query=identifier, search_type="title")
 
     if title_results and title_results.results:
         result = title_results.results[0]  # Get the first/best match
@@ -87,7 +86,7 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
 
     # Fallback 2: Text search as a last resort
     logger.info(f"Title search failed, trying text search for: {identifier}")
-    text_results = await search_notes(SearchQuery(text=identifier))
+    text_results = await search_notes(query=identifier, search_type="text")
 
     # We didn't find a direct match, construct a helpful error message
     if not text_results or not text_results.results: