basic-memory 0.12.0__tar.gz → 0.12.2__tar.gz

{basic_memory-0.12.0 → basic_memory-0.12.2}/CHANGELOG.md

@@ -1,6 +1,26 @@
 # CHANGELOG
 
 
+## v0.12.2 (2025-04-08)
+
+### Bug Fixes
+
+- Utf8 for all file reads/write/open instead of default platform encoding
+  ([#91](https://github.com/basicmachines-co/basic-memory/pull/91),
+  [`2934176`](https://github.com/basicmachines-co/basic-memory/commit/29341763318408ea8f1e954a41046c4185f836c6))
+
+Signed-off-by: phernandez <paul@basicmachines.co>
+
+
+## v0.12.1 (2025-04-07)
+
+### Bug Fixes
+
+- Run migrations and sync when starting mcp
+  ([#88](https://github.com/basicmachines-co/basic-memory/pull/88),
+  [`78a3412`](https://github.com/basicmachines-co/basic-memory/commit/78a3412bcff83b46e78e26f8b9fce42ed9e05991))
+
+
 ## v0.12.0 (2025-04-06)
 
 ### Bug Fixes

{basic_memory-0.12.0 → basic_memory-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basic-memory
-Version: 0.12.0
+Version: 0.12.2
 Summary: Local-first knowledge management combining Zettelkasten with knowledge graphs
 Project-URL: Homepage, https://github.com/basicmachines-co/basic-memory
 Project-URL: Repository, https://github.com/basicmachines-co/basic-memory
@@ -187,7 +187,7 @@ The note embeds semantic content and links to other topics via simple Markdown f
 
 3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).
 
-- Realtime sync can be enabled via running `basic-memory sync --watch`
+- Realtime sync is enabled by default with the v0.12.0 version
 
 4. In a chat with the LLM, you can reference a topic:
 
@@ -378,13 +378,7 @@ config:
 
 2. Sync your knowledge:
 
-```bash
-# One-time sync of local knowledge updates
-basic-memory sync
-
-# Run realtime sync process (recommended)
-basic-memory sync --watch
-```
+Basic Memory will sync the files in your project in real time if you make manual edits.
 
 3. In Claude Desktop, the LLM can now use these tools:
 

{basic_memory-0.12.0 → basic_memory-0.12.2}/README.md

@@ -153,7 +153,7 @@ The note embeds semantic content and links to other topics via simple Markdown f
 
 3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).
 
-- Realtime sync can be enabled via running `basic-memory sync --watch`
+- Realtime sync is enabled by default with the v0.12.0 version
 
 4. In a chat with the LLM, you can reference a topic:
 
@@ -344,13 +344,7 @@ config:
 
 2. Sync your knowledge:
 
-```bash
-# One-time sync of local knowledge updates
-basic-memory sync
-
-# Run realtime sync process (recommended)
-basic-memory sync --watch
-```
+Basic Memory will sync the files in your project in real time if you make manual edits.
 
 3. In Claude Desktop, the LLM can now use these tools:
 

{basic_memory-0.12.0 → basic_memory-0.12.2}/docs/CLI Reference.md

@@ -29,6 +29,22 @@ Options:
 - `--watch`: Continuously monitor for changes
 - `--verbose`: Show detailed output
 
+**Note**:
+
+As of the v0.12.0 release syncing will occur in real time when the mcp process starts.
+- The real time sync means that it is no longer necessary to run the `basic-memory sync --watch` process in a a terminal to sync changes to the db (so the AI can see them). This will be done automatically.
+
+This behavior can be changed via the config. The config file for Basic Memory is in the home directory under `.basic-memory/config.json`.
+
+To change the properties, set the following values:
+```
+ ~/.basic-memory/config.json 
+{
+  "sync_changes": false,
+}
+```
+
+Thanks for using Basic Memory!
 ### import
 
 Imports external knowledge sources:

{basic_memory-0.12.0 → basic_memory-0.12.2}/docs/Getting Started with Basic Memory.md

@@ -89,22 +89,11 @@ Replace `/absolute/path/to/uvx` with the actual path you found in Step 1.
 
 Close and reopen Claude Desktop for the changes to take effect.
 
-### 3. Start the Sync Service
+### 3. Sync changes in real time
 
-> Note the sync service is optional. You can run it if you want your local change to be available in Claude Desktop
-
-Start the sync service to monitor your files for changes:
-
-```bash
-# One-time sync
-basic-memory sync
-
-# For continuous monitoring (recommended)
-basic-memory sync --watch
-```
-
-The `--watch` flag enables automatic detection of file changes, updating your knowledge in real time.
+> **Note**: The service will sync changes from your project directory in real time so they available for the AI assistant. 
 
+To disable realtime sync, you can update the config. See [[CLI Reference#sync]].
 ### 4. Staying Updated
 
 To update Basic Memory when new versions are released:
@@ -145,8 +134,8 @@ If Claude cannot find Basic Memory tools:
 1. **Check absolute paths**: Ensure you're using complete absolute paths to uvx in the Claude Desktop configuration
 2. **Verify installation**: Run `basic-memory --version` in Terminal to confirm Basic Memory is installed
 3. **Restart applications**: Restart both Terminal and Claude Desktop after making configuration changes
-4. **Check sync status**: Ensure `basic-memory sync --watch` is running
-
+4. **Check sync status**: You can view the sync status by running `basic-memory status
+.
 #### Permission Issues
 
 If you encounter permission errors:
@@ -282,15 +271,15 @@ basic-memory import claude conversations
 basic-memory import chatgpt
 ```
 
-After importing, run `basic-memory sync` to index everything.
+After importing, the changes will be synced. Initial syncs may take a few moments. You can see info about your project by running `basic-memrory project info`.
 
 ## Quick Tips
 
-- Keep `basic-memory sync --watch` running in a terminal window
+- Basic Memory will sync changes from your project in real time.
 - Use special prompts (Continue Conversation, Recent Activity, Search) to start contextual discussions
 - Build connections between notes for a richer knowledge graph
-- Use direct memory:// URLs when you need precise context
-- Use git to version control your knowledge base
+- Use direct `memory://` URLs with a permalink when you need precise context. See [[User Guide#Using memory // URLs]]
+- Use git to version control your knowledge base (git integration is on the roadmap)
 - Review and edit AI-generated notes for accuracy
 
 ## Next Steps

{basic_memory-0.12.0 → basic_memory-0.12.2}/docs/Knowledge Format.md

@@ -144,7 +144,19 @@ permalink: auth-approaches-2024
 ---
 ```
 
-If not specified, one will be generated automatically from the title.
+If not specified, one will be generated automatically from the title, if the note has has a frontmatter section. 
+
+By default a  notes' permalink value will not change if the file is moved. It's a **stable** identifier :). But if you'd rather permalinks are always updated when a file moves, you can set the config setting in the global config. 
+
+The config file for Basic Memory is in the home directory under `.basic-memory/config.json`.
+
+To change the behavior, set the following value:
+```
+ ~/.basic-memory/config.json 
+{
+  "update_permalinks_on_move": true
+}
+```
 
 ### Using memory:// URLs
 

{basic_memory-0.12.0 → basic_memory-0.12.2}/installer/installer.py

@@ -44,7 +44,7 @@ def update_claude_config():
 
     # Load existing config or create new
     if config_path.exists():
-        config = json.loads(config_path.read_text())
+        config = json.loads(config_path.read_text(encoding="utf-8"))
     else:
         config = {"mcpServers": {}}
 

{basic_memory-0.12.0 → basic_memory-0.12.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "basic-memory"
-version = "0.12.0"
+version = "0.12.2"
 description = "Local-first knowledge management combining Zettelkasten with knowledge graphs"
 readme = "README.md"
 requires-python = ">=3.12.1"

{basic_memory-0.12.0 → basic_memory-0.12.2}/src/basic_memory/__init__.py

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

{basic_memory-0.12.0 → basic_memory-0.12.2}/src/basic_memory/api/app.py

@@ -1,6 +1,5 @@
 """FastAPI application for basic-memory knowledge graph API."""
 
-import asyncio
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI, HTTPException
@@ -10,44 +9,14 @@ from loguru import logger
 from basic_memory import db
 from basic_memory.api.routers import knowledge, memory, project_info, resource, search
 from basic_memory.config import config as project_config
-from basic_memory.config import config_manager
-from basic_memory.sync import SyncService, WatchService
-
-
-async def run_background_sync(sync_service: SyncService, watch_service: WatchService): # pragma: no cover
-    logger.info(f"Starting watch service to sync file changes in dir: {project_config.home}")
-    # full sync
-    await sync_service.sync(project_config.home, show_progress=False)
-
-    # watch changes
-    await watch_service.run()
+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(project_config)
-
-    # app config
-    basic_memory_config = config_manager.load_config()
-    logger.info(f"Sync changes enabled: {basic_memory_config.sync_changes}")
-    logger.info(f"Update permalinks on move enabled: {basic_memory_config.update_permalinks_on_move}")
-
-    watch_task = None
-    if basic_memory_config.sync_changes:
-        # import after migrations have run
-        from basic_memory.cli.commands.sync import get_sync_service
-
-        sync_service = await get_sync_service()
-        watch_service = WatchService(
-            sync_service=sync_service,
-            file_service=sync_service.entity_service.file_service,
-            config=project_config,
-        )
-        watch_task = asyncio.create_task(run_background_sync(sync_service, watch_service))
-    else:
-        logger.info("Sync changes disabled. Skipping watch service.")
-
+    # Initialize database and file sync services
+    watch_task = await initialize_app(project_config)
 
     # proceed with startup
     yield

{basic_memory-0.12.0 → basic_memory-0.12.2}/src/basic_memory/cli/app.py

@@ -7,8 +7,11 @@ 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()
 
 
@@ -17,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(
@@ -34,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
@@ -53,6 +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)
+
 
 # Register sub-command groups
 import_app = typer.Typer(help="Import data from various sources")

{basic_memory-0.12.0 → basic_memory-0.12.2}/src/basic_memory/cli/commands/import_memory_json.py

@@ -38,7 +38,7 @@ async def process_memory_json(
         read_task = progress.add_task("Reading memory.json...", total=None)
 
         # First pass - collect entities and relations
-        with open(json_path) as f:
+        with open(json_path, encoding="utf-8") as f:
             lines = f.readlines()
             progress.update(read_task, total=len(lines))
 

basic_memory-0.12.2/src/basic_memory/cli/commands/mcp.py

@@ -0,0 +1,35 @@
+"""MCP server command."""
+
+import basic_memory
+from basic_memory.cli.app import app
+
+# Import mcp instance
+from basic_memory.mcp.server import mcp as mcp_server  # pragma: no cover
+
+# Import mcp tools to register them
+import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
+
+
+@app.command()
+def mcp():  # pragma: no cover
+    """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("File sync will be handled by the MCP server")
+
+    # Start the MCP server
+    mcp_server.run()

{basic_memory-0.12.0 → basic_memory-0.12.2}/src/basic_memory/cli/commands/sync.py

@@ -179,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)
@@ -237,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-0.12.2/src/basic_memory/cli/main.py

@@ -0,0 +1,26 @@
+"""Main CLI entry point for basic-memory."""  # pragma: no cover
+
+from basic_memory.cli.app import app  # pragma: no cover
+
+# Register commands
+from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
+    db,
+    import_chatgpt,
+    import_claude_conversations,
+    import_claude_projects,
+    import_memory_json,
+    mcp,
+    project,
+    status,
+    sync,
+    tool,
+)
+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-0.12.0 → basic_memory-0.12.2}/src/basic_memory/config.py

@@ -35,7 +35,7 @@ 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
     )
 
     # update permalinks on move
@@ -274,7 +274,7 @@ def setup_basic_memory_logging():  # pragma: no cover
         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-0.12.0 → basic_memory-0.12.2}/src/basic_memory/markdown/entity_parser.py

@@ -104,7 +104,7 @@ class EntityParser:
             absolute_path = self.base_path / path
 
         # Parse frontmatter and content using python-frontmatter
-        file_content = absolute_path.read_text()
+        file_content = absolute_path.read_text(encoding="utf-8")
         return await self.parse_file_content(absolute_path, file_content)
 
     async def parse_file_content(self, absolute_path, file_content):

basic_memory-0.12.2/src/basic_memory/mcp/server.py

@@ -0,0 +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 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
+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", log_level="ERROR", lifespan=app_lifespan)

{basic_memory-0.12.0 → basic_memory-0.12.2}/src/basic_memory/repository/repository.py

@@ -137,8 +137,6 @@ class Repository[T: Base]:
 
     async def find_one(self, query: Select[tuple[T]]) -> Optional[T]:
         """Execute a query and retrieve a single record."""
-        logger.debug(f"Finding one {self.Model.__name__} with query: {query}")
-
         # add in load options
         query = query.options(*self.get_load_options())
         result = await self.execute_query(query)
@@ -270,11 +268,9 @@ class Repository[T: Base]:
         """Execute a query asynchronously."""
 
         query = query.options(*self.get_load_options()) if use_query_options else query
-
         logger.debug(f"Executing query: {query}")
         async with db.scoped_session(self.session_maker) as session:
             result = await session.execute(query)
-            logger.debug("Query executed successfully")
             return result
 
     def get_load_options(self) -> List[LoaderOption]:

{basic_memory-0.12.0 → basic_memory-0.12.2}/src/basic_memory/services/file_service.py

@@ -60,7 +60,7 @@ class FileService:
         Returns:
             Raw content string without metadata sections
         """
-        logger.debug("Reading entity content", entity_id=entity.id, permalink=entity.permalink)
+        logger.debug(f"Reading entity content, entity_id={entity.id}, permalink={entity.permalink}")
 
         file_path = self.get_entity_path(entity)
         markdown = await self.markdown_processor.read_file(file_path)

basic_memory-0.12.2/src/basic_memory/services/initialization.py

@@ -0,0 +1,143 @@
+"""Shared initialization service for Basic Memory.
+
+This module provides shared initialization functions used by both CLI and API
+to ensure consistent application startup across all entry points.
+"""
+
+import asyncio
+from typing import Optional
+
+from loguru import logger
+
+from basic_memory import db
+from basic_memory.config import ProjectConfig, config_manager
+from basic_memory.sync import WatchService
+
+# Import this inside functions to avoid circular imports
+# from basic_memory.cli.commands.sync import get_sync_service
+
+
+async def initialize_database(app_config: ProjectConfig) -> None:
+    """Run database migrations to ensure schema is up to date.
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    try:
+        logger.info("Running database migrations...")
+        await db.run_migrations(app_config)
+        logger.info("Migrations completed successfully")
+    except Exception as e:
+        logger.error(f"Error running migrations: {e}")
+        # Allow application to continue - it might still work
+        # depending on what the error was, and will fail with a
+        # more specific error if the database is actually unusable
+
+
+async def initialize_file_sync(
+    app_config: ProjectConfig,
+) -> asyncio.Task:
+    """Initialize file synchronization services.
+
+    Args:
+        app_config: The Basic Memory project configuration
+
+    Returns:
+        Tuple of (sync_service, watch_service, watch_task) if sync is enabled,
+        or (None, None, None) if sync is disabled
+    """
+    # Load app configuration
+    # Import here to avoid circular imports
+    from basic_memory.cli.commands.sync import get_sync_service
+
+    # Initialize sync service
+    sync_service = await get_sync_service()
+
+    # Initialize watch service
+    watch_service = WatchService(
+        sync_service=sync_service,
+        file_service=sync_service.entity_service.file_service,
+        config=app_config,
+        quiet=True,
+    )
+
+    # Create the background task for running sync
+    async def run_background_sync():  # pragma: no cover
+        # Run initial full sync
+        await sync_service.sync(app_config.home)
+        logger.info("Sync completed successfully")
+
+        # Start background sync task
+        logger.info(f"Starting watch service to sync file changes in dir: {app_config.home}")
+
+        # Start watching for changes
+        await watch_service.run()
+
+    watch_task = asyncio.create_task(run_background_sync())
+    logger.info("Watch service started")
+    return watch_task
+
+
+async def initialize_app(
+    app_config: ProjectConfig,
+) -> Optional[asyncio.Task]:
+    """Initialize the Basic Memory application.
+
+    This function handles all initialization steps needed for both API and shor lived CLI commands.
+    For long running commands like mcp, a
+    - Running database migrations
+    - Setting up file synchronization
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    # Initialize database first
+    await initialize_database(app_config)
+
+    basic_memory_config = config_manager.load_config()
+    logger.info(f"Sync changes enabled: {basic_memory_config.sync_changes}")
+    logger.info(
+        f"Update permalinks on move enabled: {basic_memory_config.update_permalinks_on_move}"
+    )
+    if not basic_memory_config.sync_changes:  # pragma: no cover
+        logger.info("Sync changes disabled. Skipping watch service.")
+        return
+
+    # Initialize file sync services
+    return await initialize_file_sync(app_config)
+
+
+def ensure_initialization(app_config: ProjectConfig) -> None:
+    """Ensure initialization runs in a synchronous context.
+
+    This is a wrapper for the async initialize_app function that can be
+    called from synchronous code like CLI entry points.
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    try:
+        asyncio.run(initialize_app(app_config))
+    except Exception as e:
+        logger.error(f"Error during initialization: {e}")
+        # Continue execution even if initialization fails
+        # The command might still work, or will fail with a
+        # more specific error message
+
+
+def ensure_initialize_database(app_config: ProjectConfig) -> None:
+    """Ensure initialization runs in a synchronous context.
+
+    This is a wrapper for the async initialize_database function that can be
+    called from synchronous code like CLI entry points.
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    try:
+        asyncio.run(initialize_database(app_config))
+    except Exception as e:
+        logger.error(f"Error during initialization: {e}")
+        # Continue execution even if initialization fails
+        # The command might still work, or will fail with a
+        # more specific error message