basic-memory 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

basic_memory/cli/commands/sync.py

@@ -151,7 +151,7 @@ def display_detailed_sync_results(knowledge: SyncReport):
         console.print(knowledge_tree)
 
 
-async def run_sync(verbose: bool = False, watch: bool = False):
+async def run_sync(verbose: bool = False, watch: bool = False, console_status: bool = False):
     """Run sync operation."""
 
     sync_service = await get_sync_service()
@@ -164,7 +164,7 @@ async def run_sync(verbose: bool = False, watch: bool = False):
             config=config,
         )
         await watch_service.handle_changes(config.home)
-        await watch_service.run()  # pragma: no cover
+        await watch_service.run(console_status=console_status)  # pragma: no cover
     else:
         # one time sync
         knowledge_changes = await sync_service.sync(config.home)
@@ -189,11 +189,14 @@ def sync(
         "-w",
         help="Start watching for changes after sync.",
     ),
+    console_status: bool = typer.Option(
+        False, "--console-status", "-c", help="Show live console status"
+    ),
 ) -> None:
     """Sync knowledge files with the database."""
     try:
         # Run sync
-        asyncio.run(run_sync(verbose=verbose, watch=watch))
+        asyncio.run(run_sync(verbose=verbose, watch=watch, console_status=console_status))
 
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):

basic_memory/cli/commands/tools.py

@@ -0,0 +1,157 @@
+"""Database management commands."""
+
+import asyncio
+from typing import Optional, List, Annotated
+
+import typer
+from rich import print as rprint
+
+from basic_memory.cli.app import app
+from basic_memory.mcp.tools import build_context as mcp_build_context
+from basic_memory.mcp.tools import get_entity as mcp_get_entity
+from basic_memory.mcp.tools import read_note as mcp_read_note
+from basic_memory.mcp.tools import recent_activity as mcp_recent_activity
+from basic_memory.mcp.tools import search as mcp_search
+from basic_memory.mcp.tools import write_note as mcp_write_note
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import MemoryUrl
+from basic_memory.schemas.search import SearchQuery
+
+tool_app = typer.Typer()
+app.add_typer(tool_app, name="tools", help="cli versions mcp tools")
+
+
+@tool_app.command()
+def write_note(
+    title: Annotated[str, typer.Option(help="The title of the note")],
+    content: Annotated[str, typer.Option(help="The content of the note")],
+    folder: Annotated[str, typer.Option(help="The folder to create the note in")],
+    tags: Annotated[
+        Optional[List[str]], typer.Option(help="A list of tags to apply to the note")
+    ] = None,
+):
+    try:
+        note = asyncio.run(mcp_write_note(title, content, folder, tags))
+        rprint(note)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during write_note: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command()
+def read_note(identifier: str, page: int = 1, page_size: int = 10):
+    try:
+        note = asyncio.run(mcp_read_note(identifier, page, page_size))
+        rprint(note)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during read_note: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command()
+def build_context(
+    url: MemoryUrl,
+    depth: Optional[int] = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+):
+    try:
+        context = asyncio.run(
+            mcp_build_context(
+                url=url,
+                depth=depth,
+                timeframe=timeframe,
+                page=page,
+                page_size=page_size,
+                max_related=max_related,
+            )
+        )
+        rprint(context.model_dump())
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during build_context: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command()
+def recent_activity(
+    type: Annotated[Optional[List[str]], typer.Option()] = ["entity", "observation", "relation"],
+    depth: Optional[int] = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+):
+    assert type is not None, "type is required"
+    if any(t not in ["entity", "observation", "relation"] for t in type):  # pragma: no cover
+        print("type must be one of ['entity', 'observation', 'relation']")
+        raise typer.Abort()
+
+    try:
+        context = asyncio.run(
+            mcp_recent_activity(
+                type=type,  # pyright: ignore [reportArgumentType]
+                depth=depth,
+                timeframe=timeframe,
+                page=page,
+                page_size=page_size,
+                max_related=max_related,
+            )
+        )
+        rprint(context.model_dump())
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during build_context: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command()
+def search(
+    query: str,
+    permalink: Annotated[bool, typer.Option("--permalink", help="Search permalink values")] = False,
+    title: Annotated[bool, typer.Option("--title", help="Search title values")] = False,
+    after_date: Annotated[
+        Optional[str],
+        typer.Option("--after_date", help="Search results after date, eg. '2d', '1 week'"),
+    ] = None,
+    page: int = 1,
+    page_size: int = 10,
+):
+    if permalink and title:  # pragma: no cover
+        print("Cannot search both permalink and title")
+        raise typer.Abort()
+
+    try:
+        search_query = SearchQuery(
+            permalink_match=query if permalink else None,
+            text=query if query else None,
+            title=query if title else None,
+            after_date=after_date,
+        )
+        results = asyncio.run(mcp_search(query=search_query, page=page, page_size=page_size))
+        rprint(results.model_dump())
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during search: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command()
+def get_entity(identifier: str):
+    try:
+        entity = asyncio.run(mcp_get_entity(identifier=identifier))
+        rprint(entity.model_dump())
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during get_entity: {e}", err=True)
+            raise typer.Exit(1)
+        raise

basic_memory/cli/main.py

@@ -1,7 +1,6 @@
 """Main CLI entry point for basic-memory."""  # pragma: no cover
 
 from basic_memory.cli.app import app  # pragma: no cover
-from basic_memory.utils import setup_logging  # pragma: no cover
 
 # Register commands
 from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
@@ -13,11 +12,9 @@ from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
     import_claude_conversations,
     import_claude_projects,
     import_chatgpt,
+    tools,
 )
 
 
-# Set up logging when module is imported
-setup_logging(log_file=".basic-memory/basic-memory-cli.log")  # pragma: no cover
-
 if __name__ == "__main__":  # pragma: no cover
     app()

basic_memory/config.py

@@ -1,6 +1,7 @@
 """Configuration management for basic-memory."""
 
 from pathlib import Path
+from typing import Literal
 
 from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -8,10 +9,14 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 DATABASE_NAME = "memory.db"
 DATA_DIR_NAME = ".basic-memory"
 
+Environment = Literal["test", "dev", "user"]
+
 
 class ProjectConfig(BaseSettings):
     """Configuration for a specific basic-memory project."""
 
+    env: Environment = Field(default="dev", description="Environment name")
+
     # Default to ~/basic-memory but allow override with env var: BASIC_MEMORY_HOME
     home: Path = Field(
         default_factory=lambda: Path.home() / "basic-memory",

basic_memory/db.py

@@ -4,6 +4,7 @@ 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

basic_memory/deps.py

@@ -2,6 +2,7 @@
 
 from typing import Annotated
 
+import logfire
 from fastapi import Depends
 from sqlalchemy.ext.asyncio import (
     AsyncSession,
@@ -43,7 +44,10 @@ async def get_engine_factory(
     project_config: ProjectConfigDep,
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:  # pragma: no cover
     """Get engine and session maker."""
-    return await db.get_or_create_db(project_config.database_path)
+    engine, session_maker = await db.get_or_create_db(project_config.database_path)
+    if project_config.env != "test":
+        logfire.instrument_sqlalchemy(engine=engine)
+    return engine, session_maker
 
 
 EngineFactoryDep = Annotated[

basic_memory/mcp/tools/knowledge.py

@@ -1,8 +1,10 @@
 """Knowledge graph management tools for Basic Memory MCP server."""
 
+import logfire
+
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get, call_post
-from basic_memory.schemas.base import Permalink
+from basic_memory.schemas.memory import memory_url_path
 from basic_memory.schemas.request import (
     GetEntitiesRequest,
 )
@@ -16,15 +18,17 @@ from basic_memory.mcp.async_client import client
 @mcp.tool(
     description="Get complete information about a specific entity including observations and relations",
 )
-async def get_entity(permalink: Permalink) -> EntityResponse:
+async def get_entity(identifier: str) -> EntityResponse:
     """Get a specific entity info by its permalink.
 
     Args:
-        permalink: Path identifier for the entity
+        identifier: Path identifier for the entity
     """
-    url = f"/knowledge/entities/{permalink}"
-    response = await call_get(client, url)
-    return EntityResponse.model_validate(response.json())
+    with logfire.span("Getting entity", permalink=identifier):  # pyright: ignore [reportGeneralTypeIssues]
+        permalink = memory_url_path(identifier)
+        url = f"/knowledge/entities/{permalink}"
+        response = await call_get(client, url)
+        return EntityResponse.model_validate(response.json())
 
 
 @mcp.tool(
@@ -39,11 +43,16 @@ async def get_entities(request: GetEntitiesRequest) -> EntityListResponse:
     Returns:
         EntityListResponse containing complete details for each requested entity
     """
-    url = "/knowledge/entities"
-    response = await call_get(
-        client, url, params=[("permalink", permalink) for permalink in request.permalinks]
-    )
-    return EntityListResponse.model_validate(response.json())
+    with logfire.span("Getting multiple entities", permalink_count=len(request.permalinks)):  # pyright: ignore [reportGeneralTypeIssues]
+        url = "/knowledge/entities"
+        response = await call_get(
+            client,
+            url,
+            params=[
+                ("permalink", memory_url_path(identifier)) for identifier in request.permalinks
+            ],
+        )
+        return EntityListResponse.model_validate(response.json())
 
 
 @mcp.tool(
@@ -51,6 +60,9 @@ async def get_entities(request: GetEntitiesRequest) -> EntityListResponse:
 )
 async def delete_entities(request: DeleteEntitiesRequest) -> DeleteEntitiesResponse:
     """Delete entities from the knowledge graph."""
-    url = "/knowledge/entities/delete"
-    response = await call_post(client, url, json=request.model_dump())
-    return DeleteEntitiesResponse.model_validate(response.json())
+    with logfire.span("Deleting entities", permalink_count=len(request.permalinks)):  # pyright: ignore [reportGeneralTypeIssues]
+        url = "/knowledge/entities/delete"
+
+        request.permalinks = [memory_url_path(permlink) for permlink in request.permalinks]
+        response = await call_post(client, url, json=request.model_dump())
+        return DeleteEntitiesResponse.model_validate(response.json())

basic_memory/mcp/tools/memory.py

@@ -3,6 +3,7 @@
 from typing import Optional, Literal, List
 
 from loguru import logger
+import logfire
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
@@ -32,7 +33,9 @@ async def build_context(
     url: MemoryUrl,
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
-    max_results: int = 10,
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
 ) -> GraphContext:
     """Get context needed to continue a discussion.
 
@@ -44,7 +47,9 @@ async def build_context(
         url: memory:// URI pointing to discussion content (e.g. memory://specs/search)
         depth: How many relation hops to traverse (1-3 recommended for performance)
         timeframe: How far back to look. Supports natural language like "2 days ago", "last week"
-        max_results: Maximum number of results to return (default: 10)
+        page: Page number of results to return (default: 1)
+        page_size: Number of results to return per page (default: 10)
+        max_related: Maximum number of related results to return (default: 10)
 
     Returns:
         GraphContext containing:
@@ -65,14 +70,21 @@ async def build_context(
         # Research the history of a feature
         build_context("memory://features/knowledge-graph", timeframe="3 months ago")
     """
-    logger.info(f"Building context from {url}")
-    url = normalize_memory_url(url)
-    response = await call_get(
-        client,
-        f"/memory/{memory_url_path(url)}",
-        params={"depth": depth, "timeframe": timeframe, "max_results": max_results},
-    )
-    return GraphContext.model_validate(response.json())
+    with logfire.span("Building context", url=url, depth=depth, timeframe=timeframe):  # pyright: ignore [reportGeneralTypeIssues]
+        logger.info(f"Building context from {url}")
+        url = normalize_memory_url(url)
+        response = await call_get(
+            client,
+            f"/memory/{memory_url_path(url)}",
+            params={
+                "depth": depth,
+                "timeframe": timeframe,
+                "page": page,
+                "page_size": page_size,
+                "max_related": max_related,
+            },
+        )
+        return GraphContext.model_validate(response.json())
 
 
 @mcp.tool(
@@ -91,7 +103,9 @@ async def recent_activity(
     type: List[Literal["entity", "observation", "relation"]] = [],
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
-    max_results: int = 10,
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
 ) -> GraphContext:
     """Get recent activity across the knowledge base.
 
@@ -106,7 +120,9 @@ async def recent_activity(
             - Relative: "2 days ago", "last week", "yesterday"
             - Points in time: "2024-01-01", "January 1st"
             - Standard format: "7d", "24h"
-        max_results: Maximum number of results to return (default: 10)
+        page: Page number of results to return (default: 1)
+        page_size: Number of results to return per page (default: 10)
+        max_related: Maximum number of related results to return (default: 10)
 
     Returns:
         GraphContext containing:
@@ -132,20 +148,23 @@ async def recent_activity(
         - For focused queries, consider using build_context with a specific URI
         - Max timeframe is 1 year in the past
     """
-    logger.info(
-        f"Getting recent activity from {type}, depth={depth}, timeframe={timeframe}, max_results={max_results}"
-    )
-    params = {
-        "depth": depth,
-        "timeframe": timeframe,
-        "max_results": max_results,
-    }
-    if type:
-        params["type"] = type
-
-    response = await call_get(
-        client,
-        "/memory/recent",
-        params=params,
-    )
-    return GraphContext.model_validate(response.json())
+    with logfire.span("Getting recent activity", type=type, depth=depth, timeframe=timeframe):  # pyright: ignore [reportGeneralTypeIssues]
+        logger.info(
+            f"Getting recent activity from {type}, depth={depth}, timeframe={timeframe}, page={page}, page_size={page_size}, max_related={max_related}"
+        )
+        params = {
+            "depth": depth,
+            "timeframe": timeframe,
+            "page": page,
+            "page_size": page_size,
+            "max_related": max_related,
+        }
+        if type:
+            params["type"] = type
+
+        response = await call_get(
+            client,
+            "/memory/recent",
+            params=params,
+        )
+        return GraphContext.model_validate(response.json())

basic_memory/mcp/tools/notes.py

@@ -7,6 +7,7 @@ while leveraging the underlying knowledge graph structure.
 from typing import Optional, List
 
 from loguru import logger
+import logfire
 
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.async_client import client
@@ -60,75 +61,62 @@ async def write_note(
         - Observation counts by category
         - Relation counts (resolved/unresolved)
         - Tags if present
-
-    Examples:
-        write_note(
-            title="Search Implementation",
-            content="# Search Component\\n\\n"
-                   "Implementation of the search feature, building on [[Core Search]].\\n\\n"
-                   "## Observations\\n"
-                   "- [tech] Using FTS5 for full-text search #implementation\\n"
-                   "- [design] Need pagination support #todo\\n\\n"
-                   "## Relations\\n"
-                   "- implements [[Search Spec]]\\n"
-                   "- depends_on [[Database Schema]]",
-            folder="docs/components"
-        )
     """
-    logger.info(f"Writing note folder:'{folder}' title: '{title}'")
-
-    # Create the entity request
-    metadata = {"tags": [f"#{tag}" for tag in tags]} if tags else None
-    entity = Entity(
-        title=title,
-        folder=folder,
-        entity_type="note",
-        content_type="text/markdown",
-        content=content,
-        entity_metadata=metadata,
-    )
-
-    # Create or update via knowledge API
-    logger.info(f"Creating {entity.permalink}")
-    url = f"/knowledge/entities/{entity.permalink}"
-    response = await call_put(client, url, json=entity.model_dump())
-    result = EntityResponse.model_validate(response.json())
-
-    # Format semantic summary based on status code
-    action = "Created" if response.status_code == 201 else "Updated"
-    assert result.checksum is not None
-    summary = [
-        f"# {action} {result.file_path} ({result.checksum[:8]})",
-        f"permalink: {result.permalink}",
-    ]
-
-    if result.observations:
-        categories = {}
-        for obs in result.observations:
-            categories[obs.category] = categories.get(obs.category, 0) + 1
-
-        summary.append("\n## Observations")
-        for category, count in sorted(categories.items()):
-            summary.append(f"- {category}: {count}")
-
-    if result.relations:
-        unresolved = sum(1 for r in result.relations if not r.to_id)
-        resolved = len(result.relations) - unresolved
-
-        summary.append("\n## Relations")
-        summary.append(f"- Resolved: {resolved}")
-        if unresolved:
-            summary.append(f"- Unresolved: {unresolved}")
-            summary.append("\nUnresolved relations will be retried on next sync.")
-
-    if tags:
-        summary.append(f"\n## Tags\n- {', '.join(tags)}")
-
-    return "\n".join(summary)
+    with logfire.span("Writing note", title=title, folder=folder):  # pyright: ignore [reportGeneralTypeIssues]
+        logger.info(f"Writing note folder:'{folder}' title: '{title}'")
+
+        # Create the entity request
+        metadata = {"tags": [f"#{tag}" for tag in tags]} if tags else None
+        entity = Entity(
+            title=title,
+            folder=folder,
+            entity_type="note",
+            content_type="text/markdown",
+            content=content,
+            entity_metadata=metadata,
+        )
+
+        # Create or update via knowledge API
+        logger.info(f"Creating {entity.permalink}")
+        url = f"/knowledge/entities/{entity.permalink}"
+        response = await call_put(client, url, json=entity.model_dump())
+        result = EntityResponse.model_validate(response.json())
+
+        # Format semantic summary based on status code
+        action = "Created" if response.status_code == 201 else "Updated"
+        assert result.checksum is not None
+        summary = [
+            f"# {action} {result.file_path} ({result.checksum[:8]})",
+            f"permalink: {result.permalink}",
+        ]
+
+        if result.observations:
+            categories = {}
+            for obs in result.observations:
+                categories[obs.category] = categories.get(obs.category, 0) + 1
+
+            summary.append("\n## Observations")
+            for category, count in sorted(categories.items()):
+                summary.append(f"- {category}: {count}")
+
+        if result.relations:
+            unresolved = sum(1 for r in result.relations if not r.to_id)
+            resolved = len(result.relations) - unresolved
+
+            summary.append("\n## Relations")
+            summary.append(f"- Resolved: {resolved}")
+            if unresolved:
+                summary.append(f"- Unresolved: {unresolved}")
+                summary.append("\nUnresolved relations will be retried on next sync.")
+
+        if tags:
+            summary.append(f"\n## Tags\n- {', '.join(tags)}")
+
+        return "\n".join(summary)
 
 
 @mcp.tool(description="Read note content by title, permalink, relation, or pattern")
-async def read_note(identifier: str) -> str:
+async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
     """Get note content in unified diff format.
 
     The content is returned in a unified diff inspired format:
@@ -146,6 +134,8 @@ async def read_note(identifier: str) -> str:
             - Note permalink ("docs/example")
             - Relation path ("docs/example/depends-on/other-doc")
             - Pattern match ("docs/*-architecture")
+        page: the page number of results to return (default 1)
+        page_size: the number of results to return per page (default 10)
 
     Returns:
         Document content in unified diff format. For single documents, returns
@@ -180,10 +170,13 @@ async def read_note(identifier: str) -> str:
     - Last modified timestamp
     - Content checksum
     """
-    logger.info(f"Reading note {identifier}")
-    url = memory_url_path(identifier)
-    response = await call_get(client, f"/resource/{url}")
-    return response.text
+    with logfire.span("Reading note", identifier=identifier):  # pyright: ignore [reportGeneralTypeIssues]
+        logger.info(f"Reading note {identifier}")
+        url = memory_url_path(identifier)
+        response = await call_get(
+            client, f"/resource/{url}", params={"page": page, "page_size": page_size}
+        )
+        return response.text
 
 
 @mcp.tool(description="Delete a note by title or permalink")
@@ -203,6 +196,7 @@ async def delete_note(identifier: str) -> bool:
         # Delete by permalink
         delete_note("notes/project-planning")
     """
-    response = await call_delete(client, f"/knowledge/entities/{identifier}")
-    result = DeleteEntitiesResponse.model_validate(response.json())
-    return result.deleted
+    with logfire.span("Deleting note", identifier=identifier):  # pyright: ignore [reportGeneralTypeIssues]
+        response = await call_delete(client, f"/knowledge/entities/{identifier}")
+        result = DeleteEntitiesResponse.model_validate(response.json())
+        return result.deleted