basic-memory 0.17.1__py3-none-any.whl

basic_memory/cli/commands/status.py

@@ -0,0 +1,174 @@
+"""Status command for basic-memory CLI."""
+
+from typing import Set, Dict
+from typing import Annotated, Optional
+
+from mcp.server.fastmcp.exceptions import ToolError
+import typer
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+from rich.tree import Tree
+
+from basic_memory.cli.app import app
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.tools.utils import call_post
+from basic_memory.schemas import SyncReportResponse
+from basic_memory.mcp.project_context import get_active_project
+
+# Create rich console
+console = Console()
+
+
+def add_files_to_tree(
+    tree: Tree, paths: Set[str], style: str, checksums: Dict[str, str] | None = 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: SyncReportResponse) -> 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(
+    project_name: str, title: str, changes: SyncReportResponse, verbose: bool = False
+):
+    """Display changes using Rich for better visualization."""
+    tree = Tree(f"{project_name}: {title}")
+
+    if changes.total == 0 and not changes.skipped_files:
+        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")
+        if changes.skipped_files:
+            skip_branch = tree.add("[red]! Skipped (Circuit Breaker)[/red]")
+            for skipped in sorted(changes.skipped_files, key=lambda x: x.path):
+                skip_branch.add(
+                    f"[red]{skipped.path}[/red] "
+                    f"(failures: {skipped.failure_count}, reason: {skipped.reason})"
+                )
+    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)
+            if summary:  # Only show directories with changes
+                tree.add(f"[bold]{dir_name}/[/bold] {summary}")
+
+        # Show skipped files summary in non-verbose mode
+        if changes.skipped_files:
+            skip_count = len(changes.skipped_files)
+            tree.add(
+                f"[red]! {skip_count} file{'s' if skip_count != 1 else ''} "
+                f"skipped due to repeated failures[/red]"
+            )
+
+    console.print(Panel(tree, expand=False))
+
+
+async def run_status(project: Optional[str] = None, verbose: bool = False):  # pragma: no cover
+    """Check sync status of files vs database."""
+
+    try:
+        async with get_client() as client:
+            project_item = await get_active_project(client, project, None)
+            response = await call_post(client, f"{project_item.project_url}/project/status")
+            sync_report = SyncReportResponse.model_validate(response.json())
+
+            display_changes(project_item.name, "Status", sync_report, verbose)
+
+    except (ValueError, ToolError) as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def status(
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project name."),
+    ] = None,
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed file information"),
+):
+    """Show sync status between files and database."""
+    from basic_memory.cli.commands.command_utils import run_with_cleanup
+
+    try:
+        run_with_cleanup(run_status(project, verbose))  # pragma: no cover
+    except Exception as e:
+        logger.error(f"Error checking status: {e}")
+        typer.echo(f"Error checking status: {e}", err=True)
+        raise typer.Exit(code=1)  # pragma: no cover

basic_memory/cli/commands/telemetry.py

@@ -0,0 +1,81 @@
+"""Telemetry commands for basic-memory CLI."""
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from basic_memory.cli.app import app
+from basic_memory.config import ConfigManager
+
+console = Console()
+
+# Create telemetry subcommand group
+telemetry_app = typer.Typer(help="Manage anonymous telemetry settings")
+app.add_typer(telemetry_app, name="telemetry")
+
+
+@telemetry_app.command("enable")
+def enable() -> None:
+    """Enable anonymous telemetry.
+
+    Telemetry helps improve Basic Memory by collecting anonymous usage data.
+    No personal data, note content, or file paths are ever collected.
+    """
+    config_manager = ConfigManager()
+    config = config_manager.config
+    config.telemetry_enabled = True
+    config_manager.save_config(config)
+    console.print("[green]Telemetry enabled[/green]")
+    console.print("[dim]Thank you for helping improve Basic Memory![/dim]")
+
+
+@telemetry_app.command("disable")
+def disable() -> None:
+    """Disable anonymous telemetry.
+
+    You can re-enable telemetry anytime with: bm telemetry enable
+    """
+    config_manager = ConfigManager()
+    config = config_manager.config
+    config.telemetry_enabled = False
+    config_manager.save_config(config)
+    console.print("[yellow]Telemetry disabled[/yellow]")
+
+
+@telemetry_app.command("status")
+def status() -> None:
+    """Show current telemetry status and what's collected."""
+    from basic_memory.telemetry import get_install_id, TELEMETRY_DOCS_URL
+
+    config = ConfigManager().config
+
+    status_text = (
+        "[green]enabled[/green]" if config.telemetry_enabled else "[yellow]disabled[/yellow]"
+    )
+
+    console.print(f"\nTelemetry: {status_text}")
+    console.print(f"Install ID: [dim]{get_install_id()}[/dim]")
+    console.print()
+
+    what_we_collect = """
+[bold]What we collect:[/bold]
+  - App version, Python version, OS, architecture
+  - Feature usage (which MCP tools and CLI commands)
+  - Sync statistics (entity count, duration)
+  - Error types (sanitized, no file paths)
+
+[bold]What we NEVER collect:[/bold]
+  - Note content, file names, or paths
+  - Personal information
+  - IP addresses
+"""
+
+    console.print(
+        Panel(
+            what_we_collect.strip(),
+            title="Telemetry Details",
+            border_style="blue",
+            expand=False,
+        )
+    )
+    console.print(f"[dim]Details: {TELEMETRY_DOCS_URL}[/dim]")

basic_memory/cli/commands/tool.py

@@ -0,0 +1,341 @@
+"""CLI tool commands for Basic Memory."""
+
+import asyncio
+import sys
+from typing import Annotated, List, Optional
+
+import typer
+from loguru import logger
+from rich import print as rprint
+
+from basic_memory.cli.app import app
+from basic_memory.config import ConfigManager
+
+# Import prompts
+from basic_memory.mcp.prompts.continue_conversation import (
+    continue_conversation as mcp_continue_conversation,
+)
+from basic_memory.mcp.prompts.recent_activity import (
+    recent_activity_prompt as recent_activity_prompt,
+)
+from basic_memory.mcp.tools import build_context as mcp_build_context
+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_notes 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 SearchItemType
+
+tool_app = typer.Typer()
+app.add_typer(tool_app, name="tool", help="Access to MCP tools via CLI")
+
+
+@tool_app.command()
+def write_note(
+    title: Annotated[str, typer.Option(help="The title of the note")],
+    folder: Annotated[str, typer.Option(help="The folder to create the note in")],
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to write to. If not provided, the default project will be used."
+        ),
+    ] = None,
+    content: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The content of the note. If not provided, content will be read from stdin. This allows piping content from other commands, e.g.: cat file.md | basic-memory tools write-note"
+        ),
+    ] = None,
+    tags: Annotated[
+        Optional[List[str]], typer.Option(help="A list of tags to apply to the note")
+    ] = None,
+):
+    """Create or update a markdown note. Content can be provided as an argument or read from stdin.
+
+    Content can be provided in two ways:
+    1. Using the --content parameter
+    2. Piping content through stdin (if --content is not provided)
+
+    Examples:
+
+    # Using content parameter
+    basic-memory tools write-note --title "My Note" --folder "notes" --content "Note content"
+
+    # Using stdin pipe
+    echo "# My Note Content" | basic-memory tools write-note --title "My Note" --folder "notes"
+
+    # Using heredoc
+    cat << EOF | basic-memory tools write-note --title "My Note" --folder "notes"
+    # My Document
+
+    This is my document content.
+
+    - Point 1
+    - Point 2
+    EOF
+
+    # Reading from a file
+    cat document.md | basic-memory tools write-note --title "Document" --folder "docs"
+    """
+    try:
+        # If content is not provided, read from stdin
+        if content is None:
+            # Check if we're getting data from a pipe or redirect
+            if not sys.stdin.isatty():
+                content = sys.stdin.read()
+            else:  # pragma: no cover
+                # If stdin is a terminal (no pipe/redirect), inform the user
+                typer.echo(
+                    "No content provided. Please provide content via --content or by piping to stdin.",
+                    err=True,
+                )
+                raise typer.Exit(1)
+
+        # Also check for empty content
+        if content is not None and not content.strip():
+            typer.echo("Empty content provided. Please provide non-empty content.", err=True)
+            raise typer.Exit(1)
+
+        # look for the project in the config
+        config_manager = ConfigManager()
+        project_name = None
+        if project is not None:
+            project_name, _ = config_manager.get_project(project)
+            if not project_name:
+                typer.echo(f"No project found named: {project}", err=True)
+                raise typer.Exit(1)
+
+        # use the project name, or the default from the config
+        project_name = project_name or config_manager.default_project
+
+        note = asyncio.run(mcp_write_note.fn(title, content, folder, project_name, 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,
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to use for the note. If not provided, the default project will be used."
+        ),
+    ] = None,
+    page: int = 1,
+    page_size: int = 10,
+):
+    """Read a markdown note from the knowledge base."""
+
+    # look for the project in the config
+    config_manager = ConfigManager()
+    project_name = None
+    if project is not None:
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
+
+    # use the project name, or the default from the config
+    project_name = project_name or config_manager.default_project
+
+    try:
+        note = asyncio.run(mcp_read_note.fn(identifier, project_name, 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,
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project to use. If not provided, the default project will be used."),
+    ] = None,
+    depth: Optional[int] = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+):
+    """Get context needed to continue a discussion."""
+
+    # look for the project in the config
+    config_manager = ConfigManager()
+    project_name = None
+    if project is not None:
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
+
+    # use the project name, or the default from the config
+    project_name = project_name or config_manager.default_project
+
+    try:
+        context = asyncio.run(
+            mcp_build_context.fn(
+                project=project_name,
+                url=url,
+                depth=depth,
+                timeframe=timeframe,
+                page=page,
+                page_size=page_size,
+                max_related=max_related,
+            )
+        )
+        # Use json module for more controlled serialization
+        import json
+
+        context_dict = context.model_dump(exclude_none=True)
+        print(json.dumps(context_dict, indent=2, ensure_ascii=True, default=str))
+    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[SearchItemType]], typer.Option()] = None,
+    depth: Optional[int] = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+):
+    """Get recent activity across the knowledge base."""
+    try:
+        result = asyncio.run(
+            mcp_recent_activity.fn(
+                type=type,  # pyright: ignore [reportArgumentType]
+                depth=depth,
+                timeframe=timeframe,
+            )
+        )
+        # The tool now returns a formatted string directly
+        print(result)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during recent_activity: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command("search-notes")
+def search_notes(
+    query: str,
+    permalink: Annotated[bool, typer.Option("--permalink", help="Search permalink values")] = False,
+    title: Annotated[bool, typer.Option("--title", help="Search title values")] = False,
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to use for the note. If not provided, the default project will be used."
+        ),
+    ] = None,
+    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,
+):
+    """Search across all content in the knowledge base."""
+
+    # look for the project in the config
+    config_manager = ConfigManager()
+    project_name = None
+    if project is not None:
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
+
+    # use the project name, or the default from the config
+    project_name = project_name or config_manager.default_project
+
+    if permalink and title:  # pragma: no cover
+        print("Cannot search both permalink and title")
+        raise typer.Abort()
+
+    try:
+        if permalink and title:  # pragma: no cover
+            typer.echo(
+                "Use either --permalink or --title, not both. Exiting.",
+                err=True,
+            )
+            raise typer.Exit(1)
+
+        # set search type
+        search_type = ("permalink" if permalink else None,)
+        search_type = ("permalink_match" if permalink and "*" in query else None,)
+        search_type = ("title" if title else None,)
+        search_type = "text" if search_type is None else search_type
+
+        results = asyncio.run(
+            mcp_search.fn(
+                query,
+                project_name,
+                search_type=search_type,
+                page=page,
+                after_date=after_date,
+                page_size=page_size,
+            )
+        )
+        # Use json module for more controlled serialization
+        import json
+
+        results_dict = results.model_dump(exclude_none=True)
+        print(json.dumps(results_dict, indent=2, ensure_ascii=True, default=str))
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            logger.exception("Error during search", e)
+            typer.echo(f"Error during search: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@tool_app.command(name="continue-conversation")
+def continue_conversation(
+    topic: Annotated[Optional[str], typer.Option(help="Topic or keyword to search for")] = None,
+    timeframe: Annotated[
+        Optional[str], typer.Option(help="How far back to look for activity")
+    ] = None,
+):
+    """Prompt to continue a previous conversation or work session."""
+    try:
+        # Prompt functions return formatted strings directly
+        session = asyncio.run(mcp_continue_conversation.fn(topic=topic, timeframe=timeframe))  # type: ignore
+        rprint(session)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            logger.exception("Error continuing conversation", e)
+            typer.echo(f"Error continuing conversation: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+# @tool_app.command(name="show-recent-activity")
+# def show_recent_activity(
+#     timeframe: Annotated[
+#         str, typer.Option(help="How far back to look for activity")
+#     ] = "7d",
+# ):
+#     """Prompt to show recent activity."""
+#     try:
+#         # Prompt functions return formatted strings directly
+#         session = asyncio.run(recent_activity_prompt(timeframe=timeframe))
+#         rprint(session)
+#     except Exception as e:  # pragma: no cover
+#         if not isinstance(e, typer.Exit):
+#             logger.exception("Error continuing conversation", e)
+#             typer.echo(f"Error continuing conversation: {e}", err=True)
+#             raise typer.Exit(1)
+#         raise

basic_memory/cli/main.py

@@ -0,0 +1,28 @@
+"""Main CLI entry point for basic-memory."""  # pragma: no cover
+
+from basic_memory.cli.app import app  # pragma: no cover
+
+# Register commands
+from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
+    cloud,
+    db,
+    import_chatgpt,
+    import_claude_conversations,
+    import_claude_projects,
+    import_memory_json,
+    mcp,
+    project,
+    status,
+    telemetry,
+    tool,
+)
+
+# Re-apply warning filter AFTER all imports
+# (authlib adds a DeprecationWarning filter that overrides ours)
+import warnings  # pragma: no cover
+
+warnings.filterwarnings("ignore")  # pragma: no cover
+
+if __name__ == "__main__":  # pragma: no cover
+    # start the app
+    app()