basic-memory 0.1.1__py3-none-any.whl → 0.2.0__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.0.1"
+__version__ = "0.0.1"

basic_memory/alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

basic_memory/alembic/env.py

@@ -0,0 +1,75 @@
+"""Alembic environment configuration."""
+
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+
+from alembic import context
+
+from basic_memory.models import Base
+from basic_memory.config import config as app_config
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Set the SQLAlchemy URL from our app config
+sqlalchemy_url = f"sqlite:///{app_config.database_path}"
+config.set_main_option("sqlalchemy.url", sqlalchemy_url)
+
+# Interpret the config file for Python logging.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+    """
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

basic_memory/alembic/migrations.py

@@ -0,0 +1,29 @@
+"""Functions for managing database migrations."""
+
+import asyncio
+from pathlib import Path
+from loguru import logger
+from alembic.config import Config
+from alembic import command
+
+
+def get_alembic_config() -> Config:  # pragma: no cover
+    """Get alembic config with correct paths."""
+    migrations_path = Path(__file__).parent
+    alembic_ini = migrations_path.parent.parent.parent / "alembic.ini"
+
+    config = Config(alembic_ini)
+    config.set_main_option("script_location", str(migrations_path))
+    return config
+
+
+async def reset_database():  # pragma: no cover
+    """Drop and recreate all tables."""
+    logger.info("Resetting database...")
+    config = get_alembic_config()
+
+    def _reset(cfg):
+        command.downgrade(cfg, "base")
+        command.upgrade(cfg, "head")
+
+    await asyncio.get_event_loop().run_in_executor(None, _reset, config)

basic_memory/alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

basic_memory/alembic/versions/3dae7c7b1564_initial_schema.py

@@ -0,0 +1,93 @@
+"""initial schema
+
+Revision ID: 3dae7c7b1564
+Revises:
+Create Date: 2025-02-12 21:23:00.336344
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "3dae7c7b1564"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "entity",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("title", sa.String(), nullable=False),
+        sa.Column("entity_type", sa.String(), nullable=False),
+        sa.Column("entity_metadata", sa.JSON(), nullable=True),
+        sa.Column("content_type", sa.String(), nullable=False),
+        sa.Column("permalink", sa.String(), nullable=False),
+        sa.Column("file_path", sa.String(), nullable=False),
+        sa.Column("checksum", sa.String(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("permalink", name="uix_entity_permalink"),
+    )
+    op.create_index("ix_entity_created_at", "entity", ["created_at"], unique=False)
+    op.create_index(op.f("ix_entity_file_path"), "entity", ["file_path"], unique=True)
+    op.create_index(op.f("ix_entity_permalink"), "entity", ["permalink"], unique=True)
+    op.create_index("ix_entity_title", "entity", ["title"], unique=False)
+    op.create_index("ix_entity_type", "entity", ["entity_type"], unique=False)
+    op.create_index("ix_entity_updated_at", "entity", ["updated_at"], unique=False)
+    op.create_table(
+        "observation",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("entity_id", sa.Integer(), nullable=False),
+        sa.Column("content", sa.Text(), nullable=False),
+        sa.Column("category", sa.String(), nullable=False),
+        sa.Column("context", sa.Text(), nullable=True),
+        sa.Column("tags", sa.JSON(), server_default="[]", nullable=True),
+        sa.ForeignKeyConstraint(["entity_id"], ["entity.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_observation_category", "observation", ["category"], unique=False)
+    op.create_index("ix_observation_entity_id", "observation", ["entity_id"], unique=False)
+    op.create_table(
+        "relation",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("from_id", sa.Integer(), nullable=False),
+        sa.Column("to_id", sa.Integer(), nullable=True),
+        sa.Column("to_name", sa.String(), nullable=False),
+        sa.Column("relation_type", sa.String(), nullable=False),
+        sa.Column("context", sa.Text(), nullable=True),
+        sa.ForeignKeyConstraint(["from_id"], ["entity.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["to_id"], ["entity.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("from_id", "to_id", "relation_type", name="uix_relation"),
+    )
+    op.create_index("ix_relation_from_id", "relation", ["from_id"], unique=False)
+    op.create_index("ix_relation_to_id", "relation", ["to_id"], unique=False)
+    op.create_index("ix_relation_type", "relation", ["relation_type"], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index("ix_relation_type", table_name="relation")
+    op.drop_index("ix_relation_to_id", table_name="relation")
+    op.drop_index("ix_relation_from_id", table_name="relation")
+    op.drop_table("relation")
+    op.drop_index("ix_observation_entity_id", table_name="observation")
+    op.drop_index("ix_observation_category", table_name="observation")
+    op.drop_table("observation")
+    op.drop_index("ix_entity_updated_at", table_name="entity")
+    op.drop_index("ix_entity_type", table_name="entity")
+    op.drop_index("ix_entity_title", table_name="entity")
+    op.drop_index(op.f("ix_entity_permalink"), table_name="entity")
+    op.drop_index(op.f("ix_entity_file_path"), table_name="entity")
+    op.drop_index("ix_entity_created_at", table_name="entity")
+    op.drop_table("entity")
+    # ### end Alembic commands ###

basic_memory/api/__init__.py

@@ -1,4 +1,5 @@
 """Basic Memory API module."""
+
 from .app import app
 
-__all__ = ["app"]
+__all__ = ["app"]

basic_memory/api/app.py

@@ -7,40 +7,42 @@ 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
-from basic_memory.config import config
-from basic_memory.services import DatabaseService
+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):
+async def lifespan(app: FastAPI):  # pragma: no cover
     """Lifecycle manager for the FastAPI app."""
     logger.info("Starting Basic Memory API")
-    
-    # check the db state
-    await check_db(app)
+    await run_migrations()
     yield
     logger.info("Shutting down Basic Memory API")
     await db.shutdown_db()
 
 
-async def check_db(app: FastAPI):
-    logger.info("Checking database state")
-
-    # Initialize DB management service
-    db_service = DatabaseService(
-        config=config,
-    )
-
-    # Check and initialize DB if needed
-    if not await db_service.check_db():
-        raise RuntimeError("Database initialization failed")
-
-    # Clean up old backups on shutdown
-    await db_service.cleanup_backups()
-
-
-
 # Initialize FastAPI app
 app = FastAPI(
     title="Basic Memory API",
@@ -57,7 +59,7 @@ app.include_router(resource.router)
 
 
 @app.exception_handler(Exception)
-async def exception_handler(request, exc):
+async def exception_handler(request, exc):  # pragma: no cover
     logger.exception(
         f"An unhandled exception occurred for request '{request.url}', exception: {exc}"
     )

basic_memory/api/routers/knowledge_router.py

@@ -17,7 +17,7 @@ from basic_memory.schemas import (
     DeleteEntitiesResponse,
     DeleteEntitiesRequest,
 )
-from basic_memory.schemas.base import PathId, Entity
+from basic_memory.schemas.base import Permalink, Entity
 from basic_memory.services.exceptions import EntityNotFoundError
 
 router = APIRouter(prefix="/knowledge", tags=["knowledge"])
@@ -27,10 +27,10 @@ router = APIRouter(prefix="/knowledge", tags=["knowledge"])
 
 @router.post("/entities", response_model=EntityResponse)
 async def create_entity(
-        data: Entity,
-        background_tasks: BackgroundTasks,
-        entity_service: EntityServiceDep,
-        search_service: SearchServiceDep,
+    data: Entity,
+    background_tasks: BackgroundTasks,
+    entity_service: EntityServiceDep,
+    search_service: SearchServiceDep,
 ) -> EntityResponse:
     """Create an entity."""
     logger.info(f"request: create_entity with data={data}")
@@ -47,12 +47,12 @@ async def create_entity(
 
 @router.put("/entities/{permalink:path}", response_model=EntityResponse)
 async def create_or_update_entity(
-        permalink: PathId,
-        data: Entity,
-        response: Response,
-        background_tasks: BackgroundTasks,
-        entity_service: EntityServiceDep,
-        search_service: SearchServiceDep,
+    permalink: Permalink,
+    data: Entity,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    entity_service: EntityServiceDep,
+    search_service: SearchServiceDep,
 ) -> EntityResponse:
     """Create or update an entity. If entity exists, it will be updated, otherwise created."""
     logger.info(f"request: create_or_update_entity with permalink={permalink}, data={data}")
@@ -69,7 +69,9 @@ async def create_or_update_entity(
     await search_service.index_entity(entity, background_tasks=background_tasks)
     result = EntityResponse.model_validate(entity)
 
-    logger.info(f"response: create_or_update_entity with result={result}, status_code={response.status_code}")
+    logger.info(
+        f"response: create_or_update_entity with result={result}, status_code={response.status_code}"
+    )
     return result
 
 
@@ -78,8 +80,8 @@ async def create_or_update_entity(
 
 @router.get("/entities/{permalink:path}", response_model=EntityResponse)
 async def get_entity(
-        entity_service: EntityServiceDep,
-        permalink: str,
+    entity_service: EntityServiceDep,
+    permalink: str,
 ) -> EntityResponse:
     """Get a specific entity by ID.
 
@@ -102,13 +104,13 @@ async def get_entity(
 
 @router.get("/entities", response_model=EntityListResponse)
 async def get_entities(
-        entity_service: EntityServiceDep,
-        permalink: Annotated[list[str] | None, Query()] = None,
+    entity_service: EntityServiceDep,
+    permalink: Annotated[list[str] | None, Query()] = None,
 ) -> EntityListResponse:
     """Open specific entities"""
     logger.info(f"request: get_entities with permalinks={permalink}")
 
-    entities = await entity_service.get_entities_by_permalinks(permalink)
+    entities = await entity_service.get_entities_by_permalinks(permalink) if permalink else []
     result = EntityListResponse(
         entities=[EntityResponse.model_validate(entity) for entity in entities]
     )
@@ -122,11 +124,11 @@ async def get_entities(
 
 @router.delete("/entities/{identifier:path}", response_model=DeleteEntitiesResponse)
 async def delete_entity(
-        identifier: str,
-        background_tasks: BackgroundTasks,
-        entity_service: EntityServiceDep,
-        link_resolver: LinkResolverDep,
-        search_service=Depends(get_search_service),
+    identifier: str,
+    background_tasks: BackgroundTasks,
+    entity_service: EntityServiceDep,
+    link_resolver: LinkResolverDep,
+    search_service=Depends(get_search_service),
 ) -> DeleteEntitiesResponse:
     """Delete a single entity and remove from search index."""
     logger.info(f"request: delete_entity with identifier={identifier}")
@@ -149,10 +151,10 @@ async def delete_entity(
 
 @router.post("/entities/delete", response_model=DeleteEntitiesResponse)
 async def delete_entities(
-        data: DeleteEntitiesRequest,
-        background_tasks: BackgroundTasks,
-        entity_service: EntityServiceDep,
-        search_service=Depends(get_search_service),
+    data: DeleteEntitiesRequest,
+    background_tasks: BackgroundTasks,
+    entity_service: EntityServiceDep,
+    search_service=Depends(get_search_service),
 ) -> DeleteEntitiesResponse:
     """Delete entities and remove from search index."""
     logger.info(f"request: delete_entities with data={data}")

basic_memory/api/routers/memory_router.py

@@ -1,13 +1,11 @@
 """Routes for memory:// URI operations."""
 
-from datetime import datetime, timedelta
-from typing import Optional, List, Annotated
+from typing import Annotated
 
 from dateparser import parse
 from fastapi import APIRouter, Query
 from loguru import logger
 
-from basic_memory.config import config
 from basic_memory.deps import ContextServiceDep, EntityRepositoryDep
 from basic_memory.repository import EntityRepository
 from basic_memory.repository.search_repository import SearchIndexRow
@@ -17,7 +15,8 @@ from basic_memory.schemas.memory import (
     RelationSummary,
     EntitySummary,
     ObservationSummary,
-    MemoryMetadata, normalize_memory_url,
+    MemoryMetadata,
+    normalize_memory_url,
 )
 from basic_memory.schemas.search import SearchItemType
 from basic_memory.services.context_service import ContextResultRow
@@ -25,12 +24,14 @@ from basic_memory.services.context_service import ContextResultRow
 router = APIRouter(prefix="/memory", tags=["memory"])
 
 
-
 async def to_graph_context(context, entity_repository: EntityRepository):
     # return results
     async def to_summary(item: SearchIndexRow | ContextResultRow):
         match item.type:
             case SearchItemType.ENTITY:
+                assert item.title is not None
+                assert item.created_at is not None
+
                 return EntitySummary(
                     title=item.title,
                     permalink=item.permalink,
@@ -38,12 +39,18 @@ async def to_graph_context(context, entity_repository: EntityRepository):
                     created_at=item.created_at,
                 )
             case SearchItemType.OBSERVATION:
+                assert item.category is not None
+                assert item.content is not None
+
                 return ObservationSummary(
                     category=item.category, content=item.content, permalink=item.permalink
                 )
             case SearchItemType.RELATION:
+                assert item.from_id is not None
                 from_entity = await entity_repository.find_by_id(item.from_id)
-                to_entity = await entity_repository.find_by_id(item.to_id)
+                assert from_entity is not None
+
+                to_entity = await entity_repository.find_by_id(item.to_id) if item.to_id else None
 
                 return RelationSummary(
                     permalink=item.permalink,
@@ -51,6 +58,8 @@ async def to_graph_context(context, entity_repository: EntityRepository):
                     from_id=from_entity.permalink,
                     to_id=to_entity.permalink if to_entity else None,
                 )
+            case _:  # pragma: no cover
+                raise ValueError(f"Unexpected type: {item.type}")
 
     primary_results = [await to_summary(r) for r in context["primary_results"]]
     related_results = [await to_summary(r) for r in context["related_results"]]
@@ -61,7 +70,6 @@ async def to_graph_context(context, entity_repository: EntityRepository):
     )
 
 
-
 @router.get("/recent", response_model=GraphContext)
 async def recent(
     context_service: ContextServiceDep,
@@ -91,7 +99,8 @@ async def recent(
     return await to_graph_context(context, entity_repository=entity_repository)
 
 
-# get_memory_context needs to be declared last so other paths can match 
+# get_memory_context needs to be declared last so other paths can match
+
 
 @router.get("/{uri:path}", response_model=GraphContext)
 async def get_memory_context(
@@ -118,6 +127,3 @@ async def get_memory_context(
         memory_url, depth=depth, since=since, max_results=max_results
     )
     return await to_graph_context(context, entity_repository=entity_repository)
-
-
-

basic_memory/api/routers/search_router.py

@@ -1,34 +1,28 @@
 """Router for search operations."""
+
 from dataclasses import asdict
 
 from fastapi import APIRouter, Depends, BackgroundTasks
-from typing import List
 
-from loguru import logger
 from basic_memory.services.search_service import SearchService
 from basic_memory.schemas.search import SearchQuery, SearchResult, SearchResponse
 from basic_memory.deps import get_search_service
 
 router = APIRouter(prefix="/search", tags=["search"])
 
+
 @router.post("/", response_model=SearchResponse)
-async def search(
-    query: SearchQuery,
-    search_service: SearchService = Depends(get_search_service)
-):
+async def search(query: SearchQuery, search_service: SearchService = Depends(get_search_service)):
     """Search across all knowledge and documents."""
     results = await search_service.search(query)
     search_results = [SearchResult.model_validate(asdict(r)) for r in results]
     return SearchResponse(results=search_results)
 
+
 @router.post("/reindex")
 async def reindex(
-    background_tasks: BackgroundTasks,
-    search_service: SearchService = Depends(get_search_service)
+    background_tasks: BackgroundTasks, search_service: SearchService = Depends(get_search_service)
 ):
     """Recreate and populate the search index."""
     await search_service.reindex_all(background_tasks=background_tasks)
-    return {
-        "status": "ok",
-        "message": "Reindex initiated"
-    }
+    return {"status": "ok", "message": "Reindex initiated"}

basic_memory/cli/__init__.py

@@ -1 +1 @@
-"""CLI tools for basic-memory"""
+"""CLI tools for basic-memory"""

basic_memory/cli/app.py

@@ -1,4 +1,3 @@
 import typer
 
 app = typer.Typer()
-

basic_memory/cli/commands/__init__.py

@@ -1,5 +1,5 @@
-"""Command module exports."""
+"""CLI commands for basic-memory."""
 
-from . import status, sync, import_memory_json
+from . import status, sync, db, import_memory_json, mcp
 
-__all__ = [ "status", "sync", "import_memory_json.py"]
+__all__ = ["status", "sync", "db", "import_memory_json", "mcp"]

basic_memory/cli/commands/db.py

@@ -0,0 +1,25 @@
+"""Database management commands."""
+
+import asyncio
+import typer
+from loguru import logger
+
+from basic_memory.alembic import migrations
+from basic_memory.cli.app import app
+
+
+@app.command()
+def reset(
+    reindex: bool = typer.Option(False, "--reindex", help="Rebuild indices from filesystem"),
+):  # pragma: no cover
+    """Reset database (drop all tables and recreate)."""
+    if typer.confirm("This will delete all data. Are you sure?"):
+        logger.info("Resetting database...")
+        asyncio.run(migrations.reset_database())
+
+        if reindex:
+            # Import and run sync
+            from basic_memory.cli.commands.sync import sync
+
+            logger.info("Rebuilding search index from filesystem...")
+            asyncio.run(sync())  # pyright: ignore