chore(release): 0.3.0 [skip ci]

.github/workflows/release.yml

@@ -20,6 +20,9 @@ jobs:
     permissions:
       id-token: write
       contents: write
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      tag: ${{ steps.release.outputs.tag }}
 
     steps:
       - uses: actions/checkout@v4
@@ -54,30 +57,40 @@ jobs:
         with:
           ref: ${{ needs.release.outputs.tag }}
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: Set up Python "3.12"
+        uses: actions/setup-python@v4
         with:
-          python-version: '3.12'
+          python-version: "3.12"
+          cache: 'pip'
+
+      - name: Install librsvg
+        run: brew install librsvg
 
       - name: Install uv
         run: |
-          curl -LsSf https://astral.sh/uv/install.sh | sh
-          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+          pip install uv
+
+      - name: Create virtual env
+        run: |
+          uv venv
+
+      - name: Install dependencies
+        run: |
+          uv sync
 
       - name: Build macOS installer
         run: |
-          uv pip install -e ".[dev]"
-          cd installer
-          uv run python setup.py bdist_mac
+          make installer-mac
+          xattr -dr com.apple.quarantine "installer/build/Basic Memory Installer.app"
 
       - name: Zip macOS installer
         run: |
-          cd installer/dist
-          zip -r "Basic-Memory-Installer-${{ needs.release.outputs.tag }}.zip" "Basic Memory Installer.app"
+          cd installer/build
+          zip -ry "Basic-Memory-Installer-${{ needs.release.outputs.tag }}.zip" "Basic Memory Installer.app"
 
       - name: Upload macOS installer
         uses: softprops/action-gh-release@v1
         with:
-          files: installer/dist/Basic-Memory-Installer-${{ needs.release.outputs.tag }}.zip
+          files: installer/build/Basic-Memory-Installer-${{ needs.release.outputs.tag }}.zip
           tag_name: ${{ needs.release.outputs.tag }}
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -42,3 +42,4 @@ ENV/
 
 # macOS
 .DS_Store
+/.coverage.*

CHANGELOG.md

@@ -1,6 +1,187 @@
 # CHANGELOG
 
 
+## v0.3.0 (2025-02-15)
+
+### Bug Fixes
+
+- Refactor db schema migrate handling
+  ([`ca632be`](https://github.com/basicmachines-co/basic-memory/commit/ca632beb6fed5881f4d8ba5ce698bb5bc681e6aa))
+
+
+## v0.2.21 (2025-02-15)
+
+### Bug Fixes
+
+- Fix osx installer github action
+  ([`65ebe5d`](https://github.com/basicmachines-co/basic-memory/commit/65ebe5d19491e5ff047c459d799498ad5dd9cd1a))
+
+- Handle memory:// url format in read_note tool
+  ([`e080373`](https://github.com/basicmachines-co/basic-memory/commit/e0803734e69eeb6c6d7432eea323c7a264cb8347))
+
+- Remove create schema from init_db
+  ([`674dd1f`](https://github.com/basicmachines-co/basic-memory/commit/674dd1fd47be9e60ac17508476c62254991df288))
+
+### Features
+
+- Set version in var, output version at startup
+  ([`a91da13`](https://github.com/basicmachines-co/basic-memory/commit/a91da1396710e62587df1284da00137d156fc05e))
+
+
+## v0.2.20 (2025-02-14)
+
+### Bug Fixes
+
+- Fix installer artifact
+  ([`8de84c0`](https://github.com/basicmachines-co/basic-memory/commit/8de84c0221a1ee32780aa84dac4d3ea60895e05c))
+
+
+## v0.2.19 (2025-02-14)
+
+### Bug Fixes
+
+- Get app artifact for installer
+  ([`fe8c3d8`](https://github.com/basicmachines-co/basic-memory/commit/fe8c3d87b003166252290a87cbe958301cccf797))
+
+
+## v0.2.18 (2025-02-14)
+
+### Bug Fixes
+
+- Don't zip app on release
+  ([`8664c57`](https://github.com/basicmachines-co/basic-memory/commit/8664c57bb331d7f3f7e0239acb5386c7a3c6144e))
+
+
+## v0.2.17 (2025-02-14)
+
+### Bug Fixes
+
+- Fix app zip in installer release
+  ([`8fa197e`](https://github.com/basicmachines-co/basic-memory/commit/8fa197e2ec8a1b6caaf6dbb39c3c6626bba23e2e))
+
+
+## v0.2.16 (2025-02-14)
+
+### Bug Fixes
+
+- Debug inspect build on ci
+  ([`1d6054d`](https://github.com/basicmachines-co/basic-memory/commit/1d6054d30a477a4e6a5d6ac885632e50c01945d3))
+
+
+## v0.2.15 (2025-02-14)
+
+### Bug Fixes
+
+- Debug installer ci
+  ([`dab9573`](https://github.com/basicmachines-co/basic-memory/commit/dab957314aec9ed0e12abca2265552494ae733a2))
+
+
+## v0.2.14 (2025-02-14)
+
+
+## v0.2.13 (2025-02-14)
+
+### Bug Fixes
+
+- Refactor release.yml installer
+  ([`a152657`](https://github.com/basicmachines-co/basic-memory/commit/a15265783e47c22d8c7931396281d023b3694e27))
+
+- Try using symlinks in installer build
+  ([`8dd923d`](https://github.com/basicmachines-co/basic-memory/commit/8dd923d5bc0587276f92b5f1db022ad9c8687e45))
+
+
+## v0.2.12 (2025-02-14)
+
+### Bug Fixes
+
+- Fix cx_freeze options for installer
+  ([`854cf83`](https://github.com/basicmachines-co/basic-memory/commit/854cf8302e2f83578030db05e29b8bdc4348795a))
+
+
+## v0.2.11 (2025-02-14)
+
+### Bug Fixes
+
+- Ci installer app fix #37
+  ([`2e215fe`](https://github.com/basicmachines-co/basic-memory/commit/2e215fe83ca421b921186c7f1989dc2cb5cca278))
+
+
+## v0.2.10 (2025-02-14)
+
+### Bug Fixes
+
+- Fix build on github ci for app installer
+  ([`29a2594`](https://github.com/basicmachines-co/basic-memory/commit/29a259421a0ccb10cfa68e3707eaa506ad5e55c0))
+
+
+## v0.2.9 (2025-02-14)
+
+
+## v0.2.8 (2025-02-14)
+
+### Bug Fixes
+
+- Fix installer on ci, maybe
+  ([`edbc04b`](https://github.com/basicmachines-co/basic-memory/commit/edbc04be601d234bb1f5eb3ba24d6ad55244b031))
+
+
+## v0.2.7 (2025-02-14)
+
+### Bug Fixes
+
+- Try to fix installer ci
+  ([`230738e`](https://github.com/basicmachines-co/basic-memory/commit/230738ee9c110c0509e0a09cb0e101a92cfcb729))
+
+
+## v0.2.6 (2025-02-14)
+
+### Bug Fixes
+
+- Bump project patch version
+  ([`01d4672`](https://github.com/basicmachines-co/basic-memory/commit/01d46727b40c24b017ea9db4b741daef565ac73e))
+
+- Fix installer setup.py change ci to use make
+  ([`3e78fcc`](https://github.com/basicmachines-co/basic-memory/commit/3e78fcc2c208d83467fe7199be17174d7ffcad1a))
+
+
+## v0.2.5 (2025-02-14)
+
+### Bug Fixes
+
+- Refix vitual env in installer build
+  ([`052f491`](https://github.com/basicmachines-co/basic-memory/commit/052f491fff629e8ead629c9259f8cb46c608d584))
+
+
+## v0.2.4 (2025-02-14)
+
+
+## v0.2.3 (2025-02-14)
+
+### Bug Fixes
+
+- Workaround unsigned app
+  ([`41d4d81`](https://github.com/basicmachines-co/basic-memory/commit/41d4d81c1ad1dc2923ba0e903a57454a0c8b6b5c))
+
+
+## v0.2.2 (2025-02-14)
+
+### Bug Fixes
+
+- Fix path to intaller app artifact
+  ([`53d220d`](https://github.com/basicmachines-co/basic-memory/commit/53d220df585561f9edd0d49a9e88f1d4055059cf))
+
+
+## v0.2.1 (2025-02-14)
+
+### Bug Fixes
+
+- Activate vitualenv in installer build
+  ([`d4c8293`](https://github.com/basicmachines-co/basic-memory/commit/d4c8293687a52eaf3337fe02e2f7b80e4cc9a1bb))
+
+- Trigger installer build on release
+  ([`f11bf78`](https://github.com/basicmachines-co/basic-memory/commit/f11bf78f3f600d0e1b01996cf8e1f9c39e3dd218))
+
+
 ## v0.2.0 (2025-02-14)
 
 ### Features

Makefile

@@ -32,6 +32,7 @@ run-dev:
 
 # Build app installer
 installer-mac:
+	cd installer && chmod +x make_icons.sh && ./make_icons.sh
 	cd installer && uv run python setup.py bdist_mac
 
 installer-win:

installer/README.md

@@ -0,0 +1,26 @@
+# Basic Memory Installer
+
+This installer configures Basic Memory to work with Claude Desktop.
+
+## Installation
+
+1. Download the latest installer from the [releases page](https://github.com/basicmachines-co/basic-memory/releases)
+2. Unzip the downloaded file
+3. Since the app is currently unsigned, you'll need to:
+
+   On your Mac, choose Apple menu  > System Settings, then click Privacy & Security in the sidebar. (You may need to
+   scroll down.)
+
+   Go to Security, then click Open.
+
+   Click Open Anyway.
+
+   This button is available for about an hour after you try to open the app.
+
+   Enter your login password, then click OK.
+
+   https://support.apple.com/guide/mac-help/apple-cant-check-app-for-malicious-software-mchleab3a043/mac
+
+5. Restart Claude Desktop
+
+The warning only appears the first time you open the app. Future updates will include proper code signing.

installer/installer.py

@@ -8,6 +8,7 @@ if sys.platform == "darwin":
     import tkinter as tk
     from tkinter import messagebox
 
+
 def ensure_uv_installed():
     """Check if uv is installed, install if not."""
     try:

installer/setup.py

@@ -4,29 +4,24 @@ import sys
 # Build options for all platforms
 build_exe_options = {
     "packages": ["json", "pathlib"],
-    "excludes": [],
+    "excludes": ["unittest", "pydoc", "test"],
 }
 
 # Platform-specific options
 if sys.platform == "win32":
     base = "Win32GUI"  # Use GUI base for Windows
-    build_exe_options.update({
-        "include_msvcr": True,  # Include Visual C++ runtime
-    })
+    build_exe_options.update(
+        {
+            "include_msvcr": True,
+        }
+    )
     target_name = "Basic Memory Installer.exe"
-    icon = None  # We'll add Windows icon later
 else:  # darwin
     base = None  # Don't use GUI base for macOS
     target_name = "Basic Memory Installer"
-    icon = "Basic.icns"
 
 executables = [
-    Executable(
-        script="installer.py",
-        target_name=target_name,
-        base=base,
-        icon=icon
-    )
+    Executable(script="installer.py", target_name=target_name, base=base, icon="Basic.icns")
 ]
 
 setup(
@@ -37,8 +32,9 @@ setup(
         "build_exe": build_exe_options,
         "bdist_mac": {
             "bundle_name": "Basic Memory Installer",
-            "iconfile": icon if sys.platform == "darwin" else None
-        }
+            "iconfile": "Basic.icns",
+            "codesign_identity": "-",  # Force ad-hoc signing
+        },
     },
     executables=executables,
-)
+)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "basic-memory"
-version = "0.2.0"
+version = "0.3.0"
 description = "Local-first knowledge management combining Zettelkasten with knowledge graphs"
 readme = "README.md"
 requires-python = ">=3.12.1"
@@ -84,7 +84,9 @@ pythonVersion = "3.12"
 
 
 [tool.semantic_release]
-version_variable = "src/basic_memory/__init__.py:__version__"
+version_variables = [
+    "src/basic_memory/__init__.py:__version__",
+]
 version_toml = [
     "pyproject.toml:project.version",
 ]

src/basic_memory/__init__.py

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

src/basic_memory/api/app.py

@@ -6,38 +6,17 @@ from fastapi import FastAPI, HTTPException
 from fastapi.exception_handlers import http_exception_handler
 from loguru import logger
 
+import basic_memory
 from basic_memory import db
 from basic_memory.config import config as app_config
 from basic_memory.api.routers import knowledge, search, memory, resource
-from alembic import command
-from alembic.config import Config
-
-from basic_memory.db import DatabaseType
-from basic_memory.repository.search_repository import SearchRepository
-
-
-async def run_migrations():  # pragma: no cover
-    """Run any pending alembic migrations."""
-    logger.info("Running database migrations...")
-    try:
-        config = Config("alembic.ini")
-        command.upgrade(config, "head")
-        logger.info("Migrations completed successfully")
-
-        _, session_maker = await db.get_or_create_db(
-            app_config.database_path, DatabaseType.FILESYSTEM
-        )
-        await SearchRepository(session_maker).init_search_index()
-    except Exception as e:
-        logger.error(f"Error running migrations: {e}")
-        raise
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):  # pragma: no cover
     """Lifecycle manager for the FastAPI app."""
-    logger.info("Starting Basic Memory API")
-    await run_migrations()
+    logger.info(f"Starting Basic Memory API {basic_memory.__version__}")
+    await db.run_migrations(app_config)
     yield
     logger.info("Shutting down Basic Memory API")
     await db.shutdown_db()

src/basic_memory/cli/app.py

@@ -1,3 +1,13 @@
+import asyncio
+
 import typer
 
+from basic_memory import db
+from basic_memory.config import config
+from basic_memory.utils import setup_logging
+
+setup_logging(log_file=".basic-memory/basic-memory-cli.log")  # pragma: no cover
+
+asyncio.run(db.run_migrations(config))
+
 app = typer.Typer()

src/basic_memory/cli/commands/db.py

@@ -22,4 +22,4 @@ def reset(
             from basic_memory.cli.commands.sync import sync
 
             logger.info("Rebuilding search index from filesystem...")
-            asyncio.run(sync())  # pyright: ignore
+            sync(watch=False)  # pyright: ignore

src/basic_memory/cli/commands/mcp.py

@@ -12,9 +12,9 @@ import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
 
 
 @app.command()
-def mcp():
+def mcp():  # pragma: no cover
     """Run the MCP server for Claude Desktop integration."""
     home_dir = config.home
-    logger.info("Starting Basic Memory MCP server")
+    logger.info(f"Starting Basic Memory MCP server {basic_memory.__version__}")
     logger.info(f"Home directory: {home_dir}")
     mcp_server.run()

src/basic_memory/cli/commands/status.py

@@ -25,13 +25,11 @@ async def get_file_change_scanner(
     db_type=DatabaseType.FILESYSTEM,
 ) -> FileChangeScanner:  # pragma: no cover
     """Get sync service instance."""
-    async with db.engine_session_factory(db_path=config.database_path, db_type=db_type) as (
-        engine,
-        session_maker,
-    ):
-        entity_repository = EntityRepository(session_maker)
-        file_change_scanner = FileChangeScanner(entity_repository)
-        return file_change_scanner
+    _, session_maker = await db.get_or_create_db(db_path=config.database_path, db_type=db_type)
+
+    entity_repository = EntityRepository(session_maker)
+    file_change_scanner = FileChangeScanner(entity_repository)
+    return file_change_scanner
 
 
 def add_files_to_tree(

src/basic_memory/cli/commands/sync.py

@@ -14,7 +14,6 @@ from rich.tree import Tree
 from basic_memory import db
 from basic_memory.cli.app import app
 from basic_memory.config import config
-from basic_memory.db import DatabaseType
 from basic_memory.markdown import EntityParser
 from basic_memory.markdown.markdown_processor import MarkdownProcessor
 from basic_memory.repository import (
@@ -39,50 +38,50 @@ class ValidationIssue:
     error: str
 
 
-async def get_sync_service(db_type=DatabaseType.FILESYSTEM):  # pragma: no cover
+async def get_sync_service():  # pragma: no cover
     """Get sync service instance with all dependencies."""
-    async with db.engine_session_factory(db_path=config.database_path, db_type=db_type) as (
-        engine,
-        session_maker,
-    ):
-        entity_parser = EntityParser(config.home)
-        markdown_processor = MarkdownProcessor(entity_parser)
-        file_service = FileService(config.home, markdown_processor)
+    _, session_maker = await db.get_or_create_db(
+        db_path=config.database_path, db_type=db.DatabaseType.FILESYSTEM
+    )
 
-        # Initialize repositories
-        entity_repository = EntityRepository(session_maker)
-        observation_repository = ObservationRepository(session_maker)
-        relation_repository = RelationRepository(session_maker)
-        search_repository = SearchRepository(session_maker)
+    entity_parser = EntityParser(config.home)
+    markdown_processor = MarkdownProcessor(entity_parser)
+    file_service = FileService(config.home, markdown_processor)
 
-        # Initialize services
-        search_service = SearchService(search_repository, entity_repository, file_service)
-        link_resolver = LinkResolver(entity_repository, search_service)
+    # Initialize repositories
+    entity_repository = EntityRepository(session_maker)
+    observation_repository = ObservationRepository(session_maker)
+    relation_repository = RelationRepository(session_maker)
+    search_repository = SearchRepository(session_maker)
 
-        # Initialize scanner
-        file_change_scanner = FileChangeScanner(entity_repository)
+    # Initialize services
+    search_service = SearchService(search_repository, entity_repository, file_service)
+    link_resolver = LinkResolver(entity_repository, search_service)
 
-        # Initialize services
-        entity_service = EntityService(
-            entity_parser,
-            entity_repository,
-            observation_repository,
-            relation_repository,
-            file_service,
-            link_resolver,
-        )
+    # Initialize scanner
+    file_change_scanner = FileChangeScanner(entity_repository)
 
-        # Create sync service
-        sync_service = SyncService(
-            scanner=file_change_scanner,
-            entity_service=entity_service,
-            entity_parser=entity_parser,
-            entity_repository=entity_repository,
-            relation_repository=relation_repository,
-            search_service=search_service,
-        )
+    # Initialize services
+    entity_service = EntityService(
+        entity_parser,
+        entity_repository,
+        observation_repository,
+        relation_repository,
+        file_service,
+        link_resolver,
+    )
 
-        return sync_service
+    # Create sync service
+    sync_service = SyncService(
+        scanner=file_change_scanner,
+        entity_service=entity_service,
+        entity_parser=entity_parser,
+        entity_repository=entity_repository,
+        relation_repository=relation_repository,
+        search_service=search_service,
+    )
+
+    return sync_service
 
 
 def group_issues_by_directory(issues: List[ValidationIssue]) -> Dict[str, List[ValidationIssue]]:
@@ -154,6 +153,7 @@ def display_detailed_sync_results(knowledge: SyncReport):
 
 async def run_sync(verbose: bool = False, watch: bool = False):
     """Run sync operation."""
+
     sync_service = await get_sync_service()
 
     # Start watching if requested

src/basic_memory/db.py

@@ -4,6 +4,10 @@ from enum import Enum, auto
 from pathlib import Path
 from typing import AsyncGenerator, Optional
 
+from basic_memory.config import ProjectConfig
+from alembic import command
+from alembic.config import Config
+
 from loguru import logger
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import (
@@ -14,8 +18,7 @@ from sqlalchemy.ext.asyncio import (
     async_scoped_session,
 )
 
-from basic_memory.models import Base
-from basic_memory.models.search import CREATE_SEARCH_INDEX
+from basic_memory.repository.search_repository import SearchRepository
 
 # Module level state
 _engine: Optional[AsyncEngine] = None
@@ -35,7 +38,7 @@ class DatabaseType(Enum):
             logger.info("Using in-memory SQLite database")
             return "sqlite+aiosqlite://"
 
-        return f"sqlite+aiosqlite:///{db_path}"
+        return f"sqlite+aiosqlite:///{db_path}"  # pragma: no cover
 
 
 def get_scoped_session_factory(
@@ -69,24 +72,6 @@ async def scoped_session(
         await factory.remove()
 
 
-async def init_db() -> None:
-    """Initialize database with required tables."""
-    if _session_maker is None:  # pragma: no cover
-        raise RuntimeError("Database session maker not initialized")
-
-    logger.info("Initializing database...")
-
-    async with scoped_session(_session_maker) as session:
-        await session.execute(text("PRAGMA foreign_keys=ON"))
-        conn = await session.connection()
-        await conn.run_sync(Base.metadata.create_all)
-
-        # recreate search index
-        await session.execute(CREATE_SEARCH_INDEX)
-
-        await session.commit()
-
-
 async def get_or_create_db(
     db_path: Path,
     db_type: DatabaseType = DatabaseType.FILESYSTEM,
@@ -100,9 +85,6 @@ 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)
 
-        # Initialize database
-        await init_db()
-
     assert _engine is not None  # for type checker
     assert _session_maker is not None  # for type checker
     return _engine, _session_maker
@@ -122,7 +104,6 @@ async def shutdown_db() -> None:  # pragma: no cover
 async def engine_session_factory(
     db_path: Path,
     db_type: DatabaseType = DatabaseType.MEMORY,
-    init: bool = True,
 ) -> AsyncGenerator[tuple[AsyncEngine, async_sessionmaker[AsyncSession]], None]:
     """Create engine and session factory.
 
@@ -139,9 +120,6 @@ async def engine_session_factory(
     try:
         _session_maker = async_sessionmaker(_engine, expire_on_commit=False)
 
-        if init:
-            await init_db()
-
         assert _engine is not None  # for type checker
         assert _session_maker is not None  # for type checker
         yield _engine, _session_maker
@@ -150,3 +128,18 @@ async def engine_session_factory(
             await _engine.dispose()
             _engine = None
             _session_maker = None
+
+
+async def run_migrations(app_config: ProjectConfig, database_type=DatabaseType.FILESYSTEM):
+    """Run any pending alembic migrations."""
+    logger.info("Running database migrations...")
+    try:
+        config = Config("alembic.ini")
+        command.upgrade(config, "head")
+        logger.info("Migrations completed successfully")
+
+        _, session_maker = await get_or_create_db(app_config.database_path, database_type)
+        await SearchRepository(session_maker).init_search_index()
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error running migrations: {e}")
+        raise

src/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 = "http://test"
+BASE_URL = "memory://"
 
 # Create shared async client
 client = AsyncClient(transport=ASGITransport(app=fastapi_app), base_url=BASE_URL)

src/basic_memory/mcp/tools/notes.py

@@ -13,6 +13,7 @@ from basic_memory.mcp.async_client import client
 from basic_memory.schemas import EntityResponse, DeleteEntitiesResponse
 from basic_memory.schemas.base import Entity
 from basic_memory.mcp.tools.utils import call_get, call_put, call_delete
+from basic_memory.schemas.memory import memory_url_path
 
 
 @mcp.tool(
@@ -96,7 +97,9 @@ async def read_note(identifier: str) -> str:
     Raises:
         ValueError: If the note cannot be found
     """
-    response = await call_get(client, f"/resource/{identifier}")
+    logger.info(f"Reading note {identifier}")
+    url = memory_url_path(identifier)
+    response = await call_get(client, f"/resource/{url}")
     return response.text
 
 

src/basic_memory/sync/utils.py

@@ -1,10 +1,7 @@
 """Types and utilities for file sync."""
 
 from dataclasses import dataclass, field
-from typing import Set, Dict, Optional
-
-from watchfiles import Change
-
+from typing import Set, Dict
 
 
 @dataclass

tasks.md

@@ -1,458 +0,0 @@
-# Basic Memory Tasks
-
-## Current Focus
-
-### Observation Management
-
-Implement update/remove functionality for observations with a focus on maintainability and consistency with our "
-filesystem is source of truth" principle.
-
-Options under consideration:
-
-1. Bulk Update Approach
-    - Update all observations at once
-    - Pros:
-        - Simpler file operations
-        - No need to match on observation content
-        - Easier database synchronization
-        - Very consistent with "filesystem is source of truth"
-    - Cons:
-        - Less efficient - rewrites everything for small changes
-        - Potential concurrency implications
-
-2. Tracked Observations Approach
-    - Use markdown comments for observation IDs
-   ```markdown
-   # Entity Name
-   type: entity_type
-   
-   ## Observations
-   - <!-- obs-id: abc123 -->
-     This is an observation
-   ```
-    - Pros:
-        - Can track individual observations
-        - Enables precise updates/deletes
-    - Cons:
-        - More complex markdown parsing
-        - IDs visible in markdown
-
-3. Diff-based Approach
-    - Implement observation-aware diffing
-    - Track changes at observation level
-    - Pros:
-        - More efficient updates
-        - Preserves manual edits
-    - Cons:
-        - More complex implementation
-        - Need to handle merge conflicts
-
-4. Position-based Management
-    - Track observations by their position/order
-    - Pros:
-        - No need for explicit IDs
-        - Clean markdown
-    - Cons:
-        - Fragile if order changes
-        - Hard to handle concurrent edits
-
-## Completed
-
-- [x] Extract file operations to fileio.py module
-- [x] Update EntityService to use fileio functions
-- [x] Initial ObservationService implementation
-- [x] Basic test coverage
-
-## Future Work
-
-- [ ] Implement observation updates/removals (exploring options above)
-- [ ] Proper session management for concurrent operations
-- [ ] EntityService tests using new fileio module
-- [ ] More sophisticated search functionality
-- [ ] Handle markdown formatting edge cases
-
-## TODO
-
-### refactor input schema
-
-1. Observations Format:
-   Old (JSON) way I tried first:
-
-```python
-"observations": ["First observation", "Second observation"]  # Simple string array
-```
-
-New required format:
-
-```python
-"observations": [
-    {"content": "First observation"},
-    {"content": "Second observation"}
-]  # Array of objects with content field
-```
-
-2. Relations Format:
-   Old way:
-
-```python
-"relations": [
-    {"from": "EntityName", "to": "OtherEntity", "relationType": "relates_to"}  # Using names
-]
-```
-
-New format:
-
-```python
-"relations": [
-    {"fromId": "20241210-entity-id", "toId": "20241210-other-id", "relationType": "relates_to"}  # Using IDs
-]
-```
-
-My preferences:
-
-1. For observations: The simple string array felt more intuitive for basic use, but I can see the benefits of the object
-   format:
-    - Allows for additional metadata (context, timestamps, etc.)
-    - More explicit about what each field means
-    - Consistent with how we'd want to store this in a database
-
-2. For relations: Using IDs is technically better but requires an extra lookup step in my workflow:
-    - I have to first create the entities to get their IDs
-    - Then use those IDs to create relations
-    - Makes it harder to create entities and relations in a single step
-
-Suggestions for making it more intuitive:
-
-1. For observations: We could have a helper function that accepts either format:
-
-```python
-# Both would work:
-create_entities([{
-    "name": "Entity",
-    "entityType": "type",
-    "observations": ["Simple string obs"]  # Auto-converted to object format
-}])
-
-create_entities([{
-    "name": "Entity",
-    "entityType": "type",
-    "observations": [{"content": "Full object obs"}]  # Native format
-}])
-```
-
-2. For relations: Maybe allow a name-based helper function:
-
-```python
-# Instead of requiring IDs:
-create_relations_by_name([{
-    "from": "EntityName",
-    "to": "OtherEntity",
-    "relationType": "relates_to"
-}])
-```
-
-3. A combined creation function for when we want to create entities and their relations together:
-
-```python
-create_entity_with_relations({
-    "entity": {
-        "name": "NewEntity",
-        "entityType": "type",
-        "observations": ["Obs 1", "Obs 2"]
-    },
-    "relations": [{
-        "to": "ExistingEntity",
-        "relationType": "relates_to"
-    }]
-})
-```
-
-The current schema is more "correct" from a software engineering perspective, but these helpers could make it more
-natural to use while maintaining the rigorous underlying structure. What do you think about these suggestions? Would you
-prefer to keep it strict for clarity, or add some convenience layers?
-
-### entity file organization
-
-- my problems
-    - wall of text is hard to scan visually
-    - files are not ordered or grouped granular enough. Only `<date>_<entity_name>.md`
-    - hard to tell when a new entity file is added
-
-Possible fixes:
-
-- use subdirectories?
-
-## TASKS
-
-1. **Core Functionality Improvements**
-    - [x] entity.description addition
-    - [x] subdirectories 
-      - Paul needs this for markdown view
-    - [x] refine directory sprawl
-    - [ ] improve tool api
-    - [ ] Choose and implement observation update/removal strategy
-    - [ ] Handle relationship updates in files
-    - [ ] Complete full CRUD operations
-      - delete
-    - [ ] Improve search functionality (currently broken as we discovered)
-
-### Suggested Sequence
-
-1. **Schema Update First**
-   - Add `entity.description` field
-   - rename entity.references?
-   - This affects database, Pydantic models, and file format
-   - Good foundation for other changes
-
-2. **File Organization**
-   - Add subdirectory support
-   - Affects:
-     - File path handling
-     - Entity loading/saving
-     - URI resolution
-   - Will make Paul's markdown viewing experience better
-
-3. **Tool API Improvements**
-   - Cleaner input/output schemas
-   - More consistent patterns
-   - Better error handling
-   - This sets us up for implementing the remaining operations
-
-4. **Core Operations**
-   - Implement delete operations
-   - Update/remove observations
-   - Relationship updates in files
-   - Building on the improved API
-
-5. **Search Fix**
-   - Can properly tackle this after file organization
-   - Will benefit from improved schema
-
-Would you like me to:
-1. Start with the schema update for entity.description?
-2. Plan out the subdirectory implementation?
-3. Or focus on a different area?
-
-I think the schema update would be a clean, contained change to start with, but I'm happy to tackle whichever part you think would be most valuable first.
-
-
-2. **Robustness & Testing**
-    - Fix DI issues
-      - Learn from fastmcp patterns
-    - Markdown service
-      - markdown.py
-      -python-frontmatter
-    - Complete test coverage
-      - Expand testing across services
-      - 100% coverate
-    - Improve error handling and logging
-    - Add comprehensive type hints
-
-3. **Architecture Improvements**
-    - Handle concurrent file operations safely
-    - Implement proper session management
-    - Balance file operations and DB sync
-    - Handle markdown formatting edge cases
-
-4. **Documentation & Infrastructure**
-    - Document core modules
-    - Implement proper backup strategy
-    - Add file change versioning
-    - Improve CLI interface
-
-
-## Ideas
-
-- need update tool
-
-### 2-way sync
-
-- Enable updates to the markdown files to be able to be seen by AI
-    - possible via tool sync
-    - filesystem notifications via agent?
-    - Claude can use `file_write` tool to edit Entity files also
-
-### Projects
-
-- support multiple projects
-- figure out flow
-    - load project at startup?
-    - switch project during chat?
-
-### References
-
-- better support for ref:// references
-- should we call them memory://<project>/<entity>
-- use Prompt to invoke reference uri
-
-### Entity File format
-
-- Consider using wiki link format:
-  [[20241210-ai_human_collaboration_model]] improves
-
-instead of
-[20241210-basic-memory] validates_design_of
-
-- use frontmatter for file header
-
-### Code
-
-- cleanup server.py
-- use markdown.py?
-- fastmcp?
-- Entity.description
-
-### Other Features
-
-- Search
-- webui
-- python notebook?
-- vector eb extension for sqlite
-
-#### Obsidian
-
-- use as file viewer editor
-- create knowledge graph?
-
-#### Save chats
-
-I'll sketch out a potential schema for chat sessions in our system:
-
-```
-{
-  `entities`: [
-    {
-      `name`: `Chat_Entity_Design`,
-      `entityType`: `design_proposal`,
-      `observations`: [
-        {
-          `content`: `Entity Schema:
-type: chat_session
-date: ISO timestamp
-participants: [human, ai]
-topic: string
-context_refs: [memory://<project>/<entity_id>]
-key_decisions: [string]
-summary: string`
-        },
-        {
-          `content`: `File Format (frontmatter):
----
-type: chat_session
-date: 2024-12-10T10:30:00Z
-participants:
-  - human: paul
-  - ai: claude
-topic: Chat Session Storage Design
-context_refs:
-  - memory://basic-memory/20241210-chat-entity-design
-key_decisions:
-  - Store chats as first-class entities
-  - Use memory:// URI scheme
-summary: Designed schema for chat storage
----`
-        },
-        {
-          `content`: `Example Relations:
-- chat_session references design_proposal
-- chat_session implements feature
-- chat_session discusses concept
-- chat_session continues_from previous_chat`
-        },
-        {
-          `content`: `Auto-generation approach:
-1. At end of chat, Claude summarizes key points
-2. Creates chat entity with metadata
-3. Adds relations to referenced entities
-4. Updates any entities modified during chat`
-        },
-        {
-          `content`: `Integration points:
-- memory:// URI scheme for references
-- Relations to track context chain
-- File format matches entity schema
-- Automatic metadata generation`
-        }
-      ]
-    }
-  ]
-} 
-```
-
-```
-{
-  `entities`: [
-    {
-      `name`: `Chat_Session_Workflow`,
-      `entityType`: `process`,
-      `observations`: [
-        {
-          `content`: `Start of chat:
-- Load any referenced context via memory:// URIs
-- Initialize new chat session metadata
-- Track entities being discussed/modified`
-        },
-        {
-          `content`: `During chat:
-- Update references as new entities are mentioned
-- Track key decisions and changes
-- Note any new relations discovered`
-        },
-        {
-          `content`: `End of chat:
-- Generate summary and key points
-- Create chat session entity
-- Add relations to referenced entities
-- Update any modified entities`
-        },
-        {
-          `content`: `Future chat reference:
-- Can reference previous chat via memory:// URI
-- Loads relevant context and decisions
-- Creates continues_from relation automatically`
-        }
-      ]
-    }
-  ]
-}
-```
-
-Key aspects of this design:
-
-1. Chat Session as Entity
-
-- Clear metadata (participants, date, topic)
-- Explicit references to other entities via memory:// URIs
-- Captures key decisions and summary
-- Uses frontmatter for clean file format
-
-2. Rich Relations
-
-- Can track chat-to-chat continuity
-- Links to entities discussed/modified
-- Captures purpose (discusses, implements, etc.)
-- Maintains context chain
-
-3. Automated Workflow
-
-- I could generate metadata during chat
-- Create summary and relations at end
-- Update any modified entities
-- Makes context loading explicit
-
-4. Integration
-
-- memory:// URI scheme fits naturally
-- File format matches our entity pattern
-- Two-way links between chats and entities
-- Clear context persistence model
-
-The nice thing about this design is that it makes chat sessions "first-class citizens" in our knowledge graph while
-keeping everything in human-readable markdown files.
-
-Would you like me to:
-
-1. Sketch out what this chat would look like as an entity?
-2. Detail the MCP tool changes needed?
-3. Mock up the file format more precisely?
-4. Something else?

tests/conftest.py

@@ -7,7 +7,6 @@ from datetime import datetime, timezone
 import pytest
 import pytest_asyncio
 from loguru import logger
-from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, AsyncEngine, async_sessionmaker
 
 from basic_memory import db
@@ -59,10 +58,8 @@ async def engine_factory(
     async with db.engine_session_factory(
         db_path=test_config.database_path, db_type=DatabaseType.MEMORY
     ) as (engine, session_maker):
-        # Initialize database
-        async with db.scoped_session(session_maker) as session:
-            await session.execute(text("PRAGMA foreign_keys=ON"))
-            conn = await session.connection()
+        # Create all tables for the DB the engine is connected to
+        async with engine.begin() as conn:
             await conn.run_sync(Base.metadata.create_all)
 
         yield engine, session_maker

tests/mcp/test_tool_notes.py

@@ -236,3 +236,25 @@ async def test_write_note_verbose(app):
     assert entity.relations[0].from_id == "test/test-note"
     assert entity.relations[0].to_id is None
     assert entity.relations[0].to_name == "Knowledge"
+
+
+@pytest.mark.asyncio
+async def test_read_note_memory_url(app):
+    """Test reading a note using a memory:// URL.
+
+    Should:
+    - Handle memory:// URLs correctly
+    - Normalize the URL before resolving
+    - Return the note content
+    """
+    # First create a note
+    permalink = await notes.write_note(
+        title="Memory URL Test",
+        folder="test",
+        content="Testing memory:// URL handling",
+    )
+
+    # Should be able to read it with a memory:// URL
+    memory_url = f"memory://{permalink}"
+    content = await notes.read_note(memory_url)
+    assert "Testing memory:// URL handling" in content

uv.lock

@@ -70,7 +70,7 @@ wheels = [
 
 [[package]]
 name = "basic-memory"
-version = "0.1.2"
+version = "0.2.21"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },