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

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

@@ -12,6 +12,7 @@ from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
     import_claude_conversations,
     import_claude_projects,
     import_chatgpt,
+    tools,
 )
 
 

basic_memory/config.py

@@ -9,7 +9,7 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 DATABASE_NAME = "memory.db"
 DATA_DIR_NAME = ".basic-memory"
 
-Environment = Literal["test", "dev", "prod"]
+Environment = Literal["test", "dev", "user"]
 
 
 class ProjectConfig(BaseSettings):

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

basic_memory/mcp/tools/search.py

@@ -1,5 +1,6 @@
 """Search tools for Basic Memory MCP server."""
 
+import logfire
 from loguru import logger
 
 from basic_memory.mcp.server import mcp
@@ -11,7 +12,7 @@ from basic_memory.mcp.async_client import client
 @mcp.tool(
     description="Search across all content in basic-memory, including documents and entities",
 )
-async def search(query: SearchQuery) -> SearchResponse:
+async def search(query: SearchQuery, page: int = 1, page_size: int = 10) -> SearchResponse:
     """Search across all content in basic-memory.
 
     Args:
@@ -20,10 +21,18 @@ async def search(query: SearchQuery) -> SearchResponse:
             - types: Optional list of content types to search ("document" or "entity")
             - entity_types: Optional list of entity types to filter by
             - after_date: Optional date filter for recent content
+        page: the page number of results to return (default 1)
+        page_size: the number of results to return per page (default 10)
 
     Returns:
         SearchResponse with search results and metadata
     """
-    logger.info(f"Searching for {query.text}")
-    response = await call_post(client, "/search/", json=query.model_dump())
-    return SearchResponse.model_validate(response.json())
+    with logfire.span("Searching for {query}", query=query):  # pyright: ignore [reportGeneralTypeIssues]
+        logger.info(f"Searching for {query}")
+        response = await call_post(
+            client,
+            "/search/",
+            json=query.model_dump(),
+            params={"page": page, "page_size": page_size},
+        )
+        return SearchResponse.model_validate(response.json())

basic_memory/repository/search_repository.py

@@ -114,6 +114,7 @@ class SearchRepository:
         after_date: Optional[datetime] = None,
         entity_types: Optional[List[str]] = None,
         limit: int = 10,
+        offset: int = 0,
     ) -> List[SearchIndexRow]:
         """Search across all indexed content with fuzzy matching."""
         conditions = []
@@ -169,6 +170,7 @@ class SearchRepository:
 
         # set limit on search query
         params["limit"] = limit
+        params["offset"] = offset
 
         # Build WHERE clause
         where_clause = " AND ".join(conditions) if conditions else "1=1"
@@ -194,6 +196,7 @@ class SearchRepository:
             WHERE {where_clause}
             ORDER BY score ASC {order_by_clause}
             LIMIT :limit
+            OFFSET :offset
         """
 
         logger.debug(f"Search {sql} params: {params}")

basic_memory/schemas/memory.py

@@ -111,3 +111,6 @@ class GraphContext(BaseModel):
 
     # Context metadata
     metadata: MemoryMetadata
+
+    page: int = 1
+    page_size: int = 1

basic_memory/schemas/request.py

@@ -51,7 +51,7 @@ class GetEntitiesRequest(BaseModel):
     discovered through search.
     """
 
-    permalinks: Annotated[List[Permalink], MinLen(1)]
+    permalinks: Annotated[List[Permalink], MinLen(1), MaxLen(10)]
 
 
 class CreateRelationsRequest(BaseModel):

basic_memory/schemas/search.py

@@ -102,6 +102,8 @@ class SearchResponse(BaseModel):
     """Wrapper for search results."""
 
     results: List[SearchResult]
+    current_page: int
+    page_size: int
 
 
 # Schema for future advanced search endpoint