basic-memory 0.0.0__py3-none-any.whl

basic_memory/__init__.py

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

basic_memory/api/__init__.py

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

basic_memory/api/app.py

@@ -0,0 +1,42 @@
+"""FastAPI application for basic-memory knowledge graph API."""
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException
+from fastapi.exception_handlers import http_exception_handler
+from loguru import logger
+
+from basic_memory import db
+from .routers import knowledge, search, memory, resource
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Lifecycle manager for the FastAPI app."""
+    logger.info("Starting Basic Memory API")
+    yield
+    logger.info("Shutting down Basic Memory API")
+    await db.shutdown_db()
+
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="Basic Memory API",
+    description="Knowledge graph API for basic-memory",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# Include routers
+app.include_router(knowledge.router)
+app.include_router(search.router)
+app.include_router(memory.router)
+app.include_router(resource.router)
+
+
+@app.exception_handler(Exception)
+async def exception_handler(request, exc):
+    logger.exception(
+        f"An unhandled exception occurred for request '{request.url}', exception: {exc}"
+    )
+    return await http_exception_handler(request, HTTPException(status_code=500, detail=str(exc)))

basic_memory/api/routers/__init__.py

@@ -0,0 +1,8 @@
+"""API routers."""
+
+from . import knowledge_router as knowledge
+from . import memory_router as memory
+from . import resource_router as resource
+from . import search_router as search
+
+__all__ = ["knowledge", "memory", "resource", "search"]

basic_memory/api/routers/knowledge_router.py

@@ -0,0 +1,168 @@
+"""Router for knowledge graph operations."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Depends, Query, Response
+from loguru import logger
+
+from basic_memory.deps import (
+    EntityServiceDep,
+    get_search_service,
+    SearchServiceDep,
+    LinkResolverDep,
+)
+from basic_memory.schemas import (
+    EntityListResponse,
+    EntityResponse,
+    DeleteEntitiesResponse,
+    DeleteEntitiesRequest,
+)
+from basic_memory.schemas.base import PathId, Entity
+from basic_memory.services.exceptions import EntityNotFoundError
+
+router = APIRouter(prefix="/knowledge", tags=["knowledge"])
+
+## Create endpoints
+
+
+@router.post("/entities", response_model=EntityResponse)
+async def create_entity(
+        data: Entity,
+        background_tasks: BackgroundTasks,
+        entity_service: EntityServiceDep,
+        search_service: SearchServiceDep,
+) -> EntityResponse:
+    """Create an entity."""
+    logger.info(f"request: create_entity with data={data}")
+
+    entity = await entity_service.create_entity(data)
+
+    # reindex
+    await search_service.index_entity(entity, background_tasks=background_tasks)
+    result = EntityResponse.model_validate(entity)
+
+    logger.info(f"response: create_entity with result={result}")
+    return result
+
+
+@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,
+) -> 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}")
+
+    # Validate permalink matches
+    if data.permalink != permalink:
+        raise HTTPException(status_code=400, detail="Entity permalink must match URL path")
+
+    # Try create_or_update operation
+    entity, created = await entity_service.create_or_update_entity(data)
+    response.status_code = 201 if created else 200
+
+    # reindex
+    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}")
+    return result
+
+
+## Read endpoints
+
+
+@router.get("/entities/{permalink:path}", response_model=EntityResponse)
+async def get_entity(
+        entity_service: EntityServiceDep,
+        permalink: str,
+) -> EntityResponse:
+    """Get a specific entity by ID.
+
+    Args:
+        permalink: Entity path ID
+        content: If True, include full file content
+        :param entity_service: EntityService
+    """
+    logger.info(f"request: get_entity with permalink={permalink}")
+    try:
+        entity = await entity_service.get_by_permalink(permalink)
+        result = EntityResponse.model_validate(entity)
+
+        logger.info(f"response: get_entity with result={result}")
+        return result
+    except EntityNotFoundError:
+        logger.error(f"Error: Entity with {permalink} not found")
+        raise HTTPException(status_code=404, detail=f"Entity with {permalink} not found")
+
+
+@router.get("/entities", response_model=EntityListResponse)
+async def get_entities(
+        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)
+    result = EntityListResponse(
+        entities=[EntityResponse.model_validate(entity) for entity in entities]
+    )
+
+    logger.info(f"response: get_entities with result={result}")
+    return result
+
+
+## Delete endpoints
+
+
+@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),
+) -> DeleteEntitiesResponse:
+    """Delete a single entity and remove from search index."""
+    logger.info(f"request: delete_entity with identifier={identifier}")
+
+    entity = await link_resolver.resolve_link(identifier)
+    if entity is None:
+        logger.info("response: delete_entity with result=DeleteEntitiesResponse(deleted=False)")
+        return DeleteEntitiesResponse(deleted=False)
+
+    # Delete the entity
+    deleted = await entity_service.delete_entity(entity.permalink)
+
+    # Remove from search index
+    background_tasks.add_task(search_service.delete_by_permalink, entity.permalink)
+
+    result = DeleteEntitiesResponse(deleted=deleted)
+    logger.info(f"response: delete_entity with result={result}")
+    return result
+
+
+@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),
+) -> DeleteEntitiesResponse:
+    """Delete entities and remove from search index."""
+    logger.info(f"request: delete_entities with data={data}")
+    deleted = False
+
+    # Remove each deleted entity from search index
+    for permalink in data.permalinks:
+        deleted = await entity_service.delete_entity(permalink)
+        background_tasks.add_task(search_service.delete_by_permalink, permalink)
+
+    result = DeleteEntitiesResponse(deleted=deleted)
+    logger.info(f"response: delete_entities with result={result}")
+    return result

basic_memory/api/routers/memory_router.py

@@ -0,0 +1,123 @@
+"""Routes for memory:// URI operations."""
+
+from datetime import datetime, timedelta
+from typing import Optional, List, 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
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import (
+    GraphContext,
+    RelationSummary,
+    EntitySummary,
+    ObservationSummary,
+    MemoryMetadata, normalize_memory_url,
+)
+from basic_memory.schemas.search import SearchItemType
+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:
+                return EntitySummary(
+                    title=item.title,
+                    permalink=item.permalink,
+                    file_path=item.file_path,
+                    created_at=item.created_at,
+                )
+            case SearchItemType.OBSERVATION:
+                return ObservationSummary(
+                    category=item.category, content=item.content, permalink=item.permalink
+                )
+            case SearchItemType.RELATION:
+                from_entity = await entity_repository.find_by_id(item.from_id)
+                to_entity = await entity_repository.find_by_id(item.to_id)
+
+                return RelationSummary(
+                    permalink=item.permalink,
+                    type=item.type,
+                    from_id=from_entity.permalink,
+                    to_id=to_entity.permalink if to_entity else None,
+                )
+
+    primary_results = [await to_summary(r) for r in context["primary_results"]]
+    related_results = [await to_summary(r) for r in context["related_results"]]
+    metadata = MemoryMetadata.model_validate(context["metadata"])
+    # Transform to GraphContext
+    return GraphContext(
+        primary_results=primary_results, related_results=related_results, metadata=metadata
+    )
+
+
+
+@router.get("/recent", response_model=GraphContext)
+async def recent(
+    context_service: ContextServiceDep,
+    entity_repository: EntityRepositoryDep,
+    type: Annotated[list[SearchItemType] | None, Query()] = None,
+    depth: int = 1,
+    timeframe: TimeFrame = "7d",
+    max_results: int = 10,
+) -> GraphContext:
+    # return all types by default
+    types = (
+        [SearchItemType.ENTITY, SearchItemType.RELATION, SearchItemType.OBSERVATION]
+        if not type
+        else type
+    )
+
+    logger.debug(
+        f"Getting recent context: `{types}` depth: `{depth}` timeframe: `{timeframe}` max_results: `{max_results}`"
+    )
+    # Parse timeframe
+    since = parse(timeframe)
+
+    # Build context
+    context = await context_service.build_context(
+        types=types, depth=depth, since=since, max_results=max_results
+    )
+    return await to_graph_context(context, entity_repository=entity_repository)
+
+
+# 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(
+    context_service: ContextServiceDep,
+    entity_repository: EntityRepositoryDep,
+    uri: str,
+    depth: int = 1,
+    timeframe: TimeFrame = "7d",
+    max_results: int = 10,
+) -> GraphContext:
+    """Get rich context from memory:// URI."""
+    # add the project name from the config to the url as the "host
+    # Parse URI
+    logger.debug(
+        f"Getting context for URI: `{uri}` depth: `{depth}` timeframe: `{timeframe}` max_results: `{max_results}`"
+    )
+    memory_url = normalize_memory_url(uri)
+
+    # Parse timeframe
+    since = parse(timeframe)
+
+    # Build context
+    context = await context_service.build_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/resource_router.py

@@ -0,0 +1,34 @@
+"""Routes for getting entity content."""
+
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+from loguru import logger
+
+from basic_memory.deps import ProjectConfigDep, LinkResolverDep
+
+router = APIRouter(prefix="/resource", tags=["resources"])
+
+
+@router.get("/{identifier:path}")
+async def get_resource_content(
+    config: ProjectConfigDep,
+    link_resolver: LinkResolverDep,
+    identifier: str,
+) -> FileResponse:
+    """Get resource content by identifier: name or permalink."""
+    logger.debug(f"Getting content for permalink: {identifier}")
+
+    # Find entity by permalink
+    entity = await link_resolver.resolve_link(identifier)
+    if not entity:
+        raise HTTPException(status_code=404, detail=f"Entity not found: {identifier}")
+
+    file_path = Path(f"{config.home}/{entity.file_path}")
+    if not file_path.exists():
+        raise HTTPException(
+            status_code=404,
+            detail=f"File not found: {file_path}",
+        )
+    return FileResponse(path=file_path)

basic_memory/api/routers/search_router.py

@@ -0,0 +1,34 @@
+"""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)
+):
+    """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)
+):
+    """Recreate and populate the search index."""
+    await search_service.reindex_all(background_tasks=background_tasks)
+    return {
+        "status": "ok",
+        "message": "Reindex initiated"
+    }

basic_memory/cli/__init__.py

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

basic_memory/cli/app.py

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

basic_memory/cli/commands/__init__.py

@@ -0,0 +1,9 @@
+"""CLI commands package."""
+
+from . import init, status
+
+
+__all__ = [
+    "init",
+    "status",
+]

basic_memory/cli/commands/init.py

@@ -0,0 +1,38 @@
+"""Initialize command for basic-memory CLI."""
+
+import asyncio
+from pathlib import Path
+
+import typer
+from loguru import logger
+
+from basic_memory.cli.app import app
+from basic_memory.db import engine_session_factory, DatabaseType
+from basic_memory.config import config
+
+
+async def _init(force: bool = False):
+    """Initialize the database."""
+    db_path = config.database_path
+
+    if db_path.exists() and not force:
+        typer.echo(f"Database already exists at {db_path}. Use --force to reinitialize.")
+        raise typer.Exit(1)
+        
+    # Create data directory if needed
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        async with engine_session_factory(db_path, db_type=DatabaseType.FILESYSTEM, init=True):
+            typer.echo(f"Initialized database at {db_path}")
+    except Exception as e:
+        logger.error(f"Error initializing database: {e}")
+        typer.echo(f"Error initializing database: {e}")
+        raise typer.Exit(1)
+
+@app.command()
+def init(
+    force: bool = typer.Option(False, "--force", "-f", help="Force reinitialization if database exists")
+):
+    """Initialize a new basic-memory database."""
+    asyncio.run(_init(force))

basic_memory/cli/commands/status.py

@@ -0,0 +1,152 @@
+"""Status command for basic-memory CLI."""
+
+import asyncio
+from typing import Set, Dict
+
+import typer
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+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.repository import EntityRepository
+from basic_memory.sync import FileChangeScanner
+from basic_memory.sync.utils import SyncReport
+
+# Create rich console
+console = Console()
+
+
+async def get_file_change_scanner(db_type=DatabaseType.FILESYSTEM) -> FileChangeScanner:
+    """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
+
+
+def add_files_to_tree(tree: Tree, paths: Set[str], style: str, checksums: Dict[str, str] = None):
+    """Add files to tree, grouped by directory."""
+    # Group by directory
+    by_dir = {}
+    for path in sorted(paths):
+        parts = path.split("/", 1)
+        dir_name = parts[0] if len(parts) > 1 else ""
+        file_name = parts[1] if len(parts) > 1 else parts[0]
+        by_dir.setdefault(dir_name, []).append((file_name, path))
+
+    # Add to tree
+    for dir_name, files in sorted(by_dir.items()):
+        if dir_name:
+            branch = tree.add(f"[bold]{dir_name}/[/bold]")
+        else:
+            branch = tree
+
+        for file_name, full_path in sorted(files):
+            if checksums and full_path in checksums:
+                checksum_short = checksums[full_path][:8]
+                branch.add(f"[{style}]{file_name}[/{style}] ({checksum_short})")
+            else:
+                branch.add(f"[{style}]{file_name}[/{style}]")
+
+
+def group_changes_by_directory(changes: SyncReport) -> Dict[str, Dict[str, int]]:
+    """Group changes by directory for summary view."""
+    by_dir = {}
+    for change_type, paths in [
+        ("new", changes.new),
+        ("modified", changes.modified),
+        ("deleted", changes.deleted),
+    ]:
+        for path in paths:
+            dir_name = path.split("/", 1)[0]
+            by_dir.setdefault(dir_name, {"new": 0, "modified": 0, "deleted": 0, "moved": 0})
+            by_dir[dir_name][change_type] += 1
+
+    # Handle moves - count in both source and destination directories
+    for old_path, new_path in changes.moves.items():
+        old_dir = old_path.split("/", 1)[0]
+        new_dir = new_path.split("/", 1)[0]
+        by_dir.setdefault(old_dir, {"new": 0, "modified": 0, "deleted": 0, "moved": 0})
+        by_dir.setdefault(new_dir, {"new": 0, "modified": 0, "deleted": 0, "moved": 0})
+        by_dir[old_dir]["moved"] += 1
+        if old_dir != new_dir:
+            by_dir[new_dir]["moved"] += 1
+
+    return by_dir
+
+
+def build_directory_summary(counts: Dict[str, int]) -> str:
+    """Build summary string for directory changes."""
+    parts = []
+    if counts["new"]:
+        parts.append(f"[green]+{counts['new']} new[/green]")
+    if counts["modified"]:
+        parts.append(f"[yellow]~{counts['modified']} modified[/yellow]")
+    if counts["moved"]:
+        parts.append(f"[blue]↔{counts['moved']} moved[/blue]")
+    if counts["deleted"]:
+        parts.append(f"[red]-{counts['deleted']} deleted[/red]")
+    return " ".join(parts)
+
+
+def display_changes(title: str, changes: SyncReport, verbose: bool = False):
+    """Display changes using Rich for better visualization."""
+    tree = Tree(title)
+
+    if changes.total_changes == 0:
+        tree.add("No changes")
+        console.print(Panel(tree, expand=False))
+        return
+
+    if verbose:
+        # Full file listing with checksums
+        if changes.new:
+            new_branch = tree.add("[green]New Files[/green]")
+            add_files_to_tree(new_branch, changes.new, "green", changes.checksums)
+        if changes.modified:
+            mod_branch = tree.add("[yellow]Modified[/yellow]")
+            add_files_to_tree(mod_branch, changes.modified, "yellow", changes.checksums)
+        if changes.moves:
+            move_branch = tree.add("[blue]Moved[/blue]")
+            for old_path, new_path in sorted(changes.moves.items()):
+                move_branch.add(f"[blue]{old_path}[/blue] → [blue]{new_path}[/blue]")
+        if changes.deleted:
+            del_branch = tree.add("[red]Deleted[/red]")
+            add_files_to_tree(del_branch, changes.deleted, "red")
+    else:
+        # Show directory summaries
+        by_dir = group_changes_by_directory(changes)
+        for dir_name, counts in sorted(by_dir.items()):
+            summary = build_directory_summary(counts)
+            tree.add(f"[bold]{dir_name}/[/bold] {summary}")
+
+    console.print(Panel(tree, expand=False))
+
+
+async def run_status(sync_service: FileChangeScanner, verbose: bool = False):
+    """Check sync status of files vs database."""
+    # Check knowledge/ directory
+    knowledge_changes = await sync_service.find_knowledge_changes(config.home)
+    display_changes("Knowledge Files", knowledge_changes, verbose)
+
+
+@app.command()
+def status(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed file information"),
+):
+    """Show sync status between files and database."""
+    try:
+        sync_service = asyncio.run(get_file_change_scanner())
+        asyncio.run(run_status(sync_service, verbose))
+    except Exception as e:
+        logger.exception(f"Error checking status: {e}")
+        typer.echo(f"Error checking status: {e}", err=True)
+        raise typer.Exit(1)