feat: Beta work (#17)

feat: Add multiple projects support 
feat: enhanced read_note for when initial result is not found
fix: merge frontmatter when updating note
fix: handle directory removed on sync watch

src/basic_memory/cli/app.py

@@ -1,4 +1,5 @@
 import asyncio
+from typing import Optional
 
 import typer
 
@@ -6,13 +7,63 @@ from basic_memory import db
 from basic_memory.config import config
 
 
-asyncio.run(db.run_migrations(config))
+def version_callback(value: bool) -> None:
+    """Show version and exit."""
+    if value:  # pragma: no cover
+        import basic_memory
+
+        typer.echo(f"Basic Memory version: {basic_memory.__version__}")
+        raise typer.Exit()
+
 
 app = typer.Typer(name="basic-memory")
 
-import_app = typer.Typer()
-app.add_typer(import_app, name="import")
 
+@app.callback()
+def app_callback(
+    project: Optional[str] = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Specify which project to use",
+        envvar="BASIC_MEMORY_PROJECT",
+    ),
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="Show version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Basic Memory - Local-first personal knowledge management."""
+    # We use the project option to set the BASIC_MEMORY_PROJECT environment variable
+    # The config module will pick this up when loading
+    if project:  # pragma: no cover
+        import os
+        import importlib
+        from basic_memory import config as config_module
+
+        # Set the environment variable
+        os.environ["BASIC_MEMORY_PROJECT"] = project
+
+        # Reload the config module to pick up the new project
+        importlib.reload(config_module)
+
+        # Update the local reference
+        global config
+        from basic_memory.config import config as new_config
+
+        config = new_config
+
+
+# Run database migrations
+asyncio.run(db.run_migrations(config))
+
+# Register sub-command groups
+import_app = typer.Typer(help="Import data from various sources")
+app.add_typer(import_app, name="import")
 
 claude_app = typer.Typer()
 import_app.add_typer(claude_app, name="claude")

src/basic_memory/cli/commands/__init__.py

@@ -1,5 +1,17 @@
 """CLI commands for basic-memory."""
 
-from . import status, sync, db, import_memory_json, mcp
+from . import status, sync, db, import_memory_json, mcp, import_claude_conversations
+from . import import_claude_projects, import_chatgpt, tool, project
 
-__all__ = ["status", "sync", "db", "import_memory_json", "mcp"]
+__all__ = [
+    "status",
+    "sync",
+    "db",
+    "import_memory_json",
+    "mcp",
+    "import_claude_conversations",
+    "import_claude_projects",
+    "import_chatgpt",
+    "tool",
+    "project",
+]

src/basic_memory/cli/commands/db.py

@@ -1,7 +1,5 @@
 """Database management commands."""
 
-import asyncio
-
 import logfire
 import typer
 from loguru import logger
@@ -10,19 +8,19 @@ from basic_memory.alembic import migrations
 from basic_memory.cli.app import app
 
 
+@logfire.instrument()
 @app.command()
 def reset(
-    reindex: bool = typer.Option(False, "--reindex", help="Rebuild indices from filesystem"),
+    reindex: bool = typer.Option(False, "--reindex", help="Rebuild db index from filesystem"),
 ):  # pragma: no cover
     """Reset database (drop all tables and recreate)."""
-    with logfire.span("reset"):  # pyright: ignore [reportGeneralTypeIssues]
-        if typer.confirm("This will delete all data in your db. Are you sure?"):
-            logger.info("Resetting database...")
-            asyncio.run(migrations.reset_database())
+    if typer.confirm("This will delete all data in your db. Are you sure?"):
+        logger.info("Resetting database...")
+        migrations.reset_database()
 
-            if reindex:
-                # Import and run sync
-                from basic_memory.cli.commands.sync import sync
+        if reindex:
+            # Import and run sync
+            from basic_memory.cli.commands.sync import sync
 
-                logger.info("Rebuilding search index from filesystem...")
-                sync(watch=False)  # pyright: ignore
+            logger.info("Rebuilding search index from filesystem...")
+            sync(watch=False)  # pyright: ignore

src/basic_memory/cli/commands/import_chatgpt.py

@@ -208,6 +208,7 @@ async def get_markdown_processor() -> MarkdownProcessor:
 
 
 @import_app.command(name="chatgpt", help="Import conversations from ChatGPT JSON export.")
+@logfire.instrument(extract_args=False)
 def import_chatgpt(
     conversations_json: Annotated[
         Path, typer.Argument(help="Path to ChatGPT conversations.json file")
@@ -226,38 +227,35 @@ def import_chatgpt(
     After importing, run 'basic-memory sync' to index the new files.
     """
 
-    with logfire.span("import chatgpt"):  # pyright: ignore [reportGeneralTypeIssues]
-        try:
-            if conversations_json:
-                if not conversations_json.exists():
-                    typer.echo(f"Error: File not found: {conversations_json}", err=True)
-                    raise typer.Exit(1)
+    try:
+        if conversations_json:
+            if not conversations_json.exists():
+                typer.echo(f"Error: File not found: {conversations_json}", err=True)
+                raise typer.Exit(1)
 
-                # Get markdown processor
-                markdown_processor = asyncio.run(get_markdown_processor())
+            # Get markdown processor
+            markdown_processor = asyncio.run(get_markdown_processor())
 
-                # Process the file
-                base_path = config.home / folder
-                console.print(
-                    f"\nImporting chats from {conversations_json}...writing to {base_path}"
-                )
-                results = asyncio.run(
-                    process_chatgpt_json(conversations_json, folder, markdown_processor)
+            # Process the file
+            base_path = config.home / folder
+            console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")
+            results = asyncio.run(
+                process_chatgpt_json(conversations_json, folder, markdown_processor)
+            )
+
+            # Show results
+            console.print(
+                Panel(
+                    f"[green]Import complete![/green]\n\n"
+                    f"Imported {results['conversations']} conversations\n"
+                    f"Containing {results['messages']} messages",
+                    expand=False,
                 )
+            )
 
-                # Show results
-                console.print(
-                    Panel(
-                        f"[green]Import complete![/green]\n\n"
-                        f"Imported {results['conversations']} conversations\n"
-                        f"Containing {results['messages']} messages",
-                        expand=False,
-                    )
-                )
+        console.print("\nRun 'basic-memory sync' to index the new files.")
 
-            console.print("\nRun 'basic-memory sync' to index the new files.")
-
-        except Exception as e:
-            logger.error("Import failed")
-            typer.echo(f"Error during import: {e}", err=True)
-            raise typer.Exit(1)
+    except Exception as e:
+        logger.error("Import failed")
+        typer.echo(f"Error during import: {e}", err=True)
+        raise typer.Exit(1)

src/basic_memory/cli/commands/import_claude_conversations.py

@@ -161,6 +161,7 @@ async def get_markdown_processor() -> MarkdownProcessor:
 
 
 @claude_app.command(name="conversations", help="Import chat conversations from Claude.ai.")
+@logfire.instrument(extract_args=False)
 def import_claude(
     conversations_json: Annotated[
         Path, typer.Argument(..., help="Path to conversations.json file")
@@ -179,35 +180,34 @@ def import_claude(
     After importing, run 'basic-memory sync' to index the new files.
     """
 
-    with logfire.span("import claude conversations"):  # pyright: ignore [reportGeneralTypeIssues]
-        try:
-            if not conversations_json.exists():
-                typer.echo(f"Error: File not found: {conversations_json}", err=True)
-                raise typer.Exit(1)
-
-            # Get markdown processor
-            markdown_processor = asyncio.run(get_markdown_processor())
-
-            # Process the file
-            base_path = config.home / folder
-            console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")
-            results = asyncio.run(
-                process_conversations_json(conversations_json, base_path, markdown_processor)
-            )
-
-            # Show results
-            console.print(
-                Panel(
-                    f"[green]Import complete![/green]\n\n"
-                    f"Imported {results['conversations']} conversations\n"
-                    f"Containing {results['messages']} messages",
-                    expand=False,
-                )
-            )
-
-            console.print("\nRun 'basic-memory sync' to index the new files.")
-
-        except Exception as e:
-            logger.error("Import failed")
-            typer.echo(f"Error during import: {e}", err=True)
+    try:
+        if not conversations_json.exists():
+            typer.echo(f"Error: File not found: {conversations_json}", err=True)
             raise typer.Exit(1)
+
+        # Get markdown processor
+        markdown_processor = asyncio.run(get_markdown_processor())
+
+        # Process the file
+        base_path = config.home / folder
+        console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")
+        results = asyncio.run(
+            process_conversations_json(conversations_json, base_path, markdown_processor)
+        )
+
+        # Show results
+        console.print(
+            Panel(
+                f"[green]Import complete![/green]\n\n"
+                f"Imported {results['conversations']} conversations\n"
+                f"Containing {results['messages']} messages",
+                expand=False,
+            )
+        )
+
+        console.print("\nRun 'basic-memory sync' to index the new files.")
+
+    except Exception as e:
+        logger.error("Import failed")
+        typer.echo(f"Error during import: {e}", err=True)
+        raise typer.Exit(1)

src/basic_memory/cli/commands/import_claude_projects.py

@@ -144,6 +144,7 @@ async def get_markdown_processor() -> MarkdownProcessor:
 
 
 @claude_app.command(name="projects", help="Import projects from Claude.ai.")
+@logfire.instrument(extract_args=False)
 def import_projects(
     projects_json: Annotated[Path, typer.Argument(..., help="Path to projects.json file")] = Path(
         "projects.json"
@@ -161,36 +162,35 @@ def import_projects(
 
     After importing, run 'basic-memory sync' to index the new files.
     """
-    with logfire.span("import claude projects"):  # pyright: ignore [reportGeneralTypeIssues]
-        try:
-            if projects_json:
-                if not projects_json.exists():
-                    typer.echo(f"Error: File not found: {projects_json}", err=True)
-                    raise typer.Exit(1)
+    try:
+        if projects_json:
+            if not projects_json.exists():
+                typer.echo(f"Error: File not found: {projects_json}", err=True)
+                raise typer.Exit(1)
 
-                # Get markdown processor
-                markdown_processor = asyncio.run(get_markdown_processor())
+            # Get markdown processor
+            markdown_processor = asyncio.run(get_markdown_processor())
 
-                # Process the file
-                base_path = config.home / base_folder if base_folder else config.home
-                console.print(f"\nImporting projects from {projects_json}...writing to {base_path}")
-                results = asyncio.run(
-                    process_projects_json(projects_json, base_path, markdown_processor)
+            # Process the file
+            base_path = config.home / base_folder if base_folder else config.home
+            console.print(f"\nImporting projects from {projects_json}...writing to {base_path}")
+            results = asyncio.run(
+                process_projects_json(projects_json, base_path, markdown_processor)
+            )
+
+            # Show results
+            console.print(
+                Panel(
+                    f"[green]Import complete![/green]\n\n"
+                    f"Imported {results['documents']} project documents\n"
+                    f"Imported {results['prompts']} prompt templates",
+                    expand=False,
                 )
+            )
 
-                # Show results
-                console.print(
-                    Panel(
-                        f"[green]Import complete![/green]\n\n"
-                        f"Imported {results['documents']} project documents\n"
-                        f"Imported {results['prompts']} prompt templates",
-                        expand=False,
-                    )
-                )
+        console.print("\nRun 'basic-memory sync' to index the new files.")
 
-            console.print("\nRun 'basic-memory sync' to index the new files.")
-
-        except Exception as e:
-            logger.error("Import failed")
-            typer.echo(f"Error during import: {e}", err=True)
-            raise typer.Exit(1)
+    except Exception as e:
+        logger.error("Import failed")
+        typer.echo(f"Error during import: {e}", err=True)
+        raise typer.Exit(1)

src/basic_memory/cli/commands/import_memory_json.py

@@ -99,6 +99,7 @@ async def get_markdown_processor() -> MarkdownProcessor:
 
 
 @import_app.command()
+@logfire.instrument(extract_args=False)
 def memory_json(
     json_path: Annotated[Path, typer.Argument(..., help="Path to memory.json file")] = Path(
         "memory.json"
@@ -114,33 +115,32 @@ def memory_json(
     After importing, run 'basic-memory sync' to index the new files.
     """
 
-    with logfire.span("import memory_json"):  # pyright: ignore [reportGeneralTypeIssues]
-        if not json_path.exists():
-            typer.echo(f"Error: File not found: {json_path}", err=True)
-            raise typer.Exit(1)
+    if not json_path.exists():
+        typer.echo(f"Error: File not found: {json_path}", err=True)
+        raise typer.Exit(1)
 
-        try:
-            # Get markdown processor
-            markdown_processor = asyncio.run(get_markdown_processor())
+    try:
+        # Get markdown processor
+        markdown_processor = asyncio.run(get_markdown_processor())
 
-            # Process the file
-            base_path = config.home
-            console.print(f"\nImporting from {json_path}...writing to {base_path}")
-            results = asyncio.run(process_memory_json(json_path, base_path, markdown_processor))
+        # Process the file
+        base_path = config.home
+        console.print(f"\nImporting from {json_path}...writing to {base_path}")
+        results = asyncio.run(process_memory_json(json_path, base_path, markdown_processor))
 
-            # Show results
-            console.print(
-                Panel(
-                    f"[green]Import complete![/green]\n\n"
-                    f"Created {results['entities']} entities\n"
-                    f"Added {results['relations']} relations",
-                    expand=False,
-                )
+        # Show results
+        console.print(
+            Panel(
+                f"[green]Import complete![/green]\n\n"
+                f"Created {results['entities']} entities\n"
+                f"Added {results['relations']} relations",
+                expand=False,
             )
+        )
 
-            console.print("\nRun 'basic-memory sync' to index the new files.")
+        console.print("\nRun 'basic-memory sync' to index the new files.")
 
-        except Exception as e:
-            logger.error("Import failed")
-            typer.echo(f"Error during import: {e}", err=True)
-            raise typer.Exit(1)
+    except Exception as e:
+        logger.error("Import failed")
+        typer.echo(f"Error during import: {e}", err=True)
+        raise typer.Exit(1)

src/basic_memory/cli/commands/mcp.py

@@ -1,6 +1,8 @@
 """MCP server command."""
 
 from loguru import logger
+
+import basic_memory
 from basic_memory.cli.app import app
 from basic_memory.config import config
 
@@ -15,6 +17,10 @@ import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
 def mcp():  # pragma: no cover
     """Run the MCP server for Claude Desktop integration."""
     home_dir = config.home
+    project_name = config.project
+
     logger.info(f"Starting Basic Memory MCP server {basic_memory.__version__}")
-    logger.info(f"Home directory: {home_dir}")
+    logger.info(f"Project: {project_name}")
+    logger.info(f"Project directory: {home_dir}")
+
     mcp_server.run()

src/basic_memory/cli/commands/project.py

@@ -0,0 +1,119 @@
+"""Command module for basic-memory project management."""
+
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from basic_memory.cli.app import app
+from basic_memory.config import ConfigManager, config
+
+console = Console()
+
+# Create a project subcommand
+project_app = typer.Typer(help="Manage multiple Basic Memory projects")
+app.add_typer(project_app, name="project")
+
+
+def format_path(path: str) -> str:
+    """Format a path for display, using ~ for home directory."""
+    home = str(Path.home())
+    if path.startswith(home):
+        return path.replace(home, "~", 1)
+    return path
+
+
+@project_app.command("list")
+def list_projects() -> None:
+    """List all configured projects."""
+    config_manager = ConfigManager()
+    projects = config_manager.projects
+
+    table = Table(title="Basic Memory Projects")
+    table.add_column("Name", style="cyan")
+    table.add_column("Path", style="green")
+    table.add_column("Default", style="yellow")
+    table.add_column("Active", style="magenta")
+
+    default_project = config_manager.default_project
+    active_project = config.project
+
+    for name, path in projects.items():
+        is_default = "✓" if name == default_project else ""
+        is_active = "✓" if name == active_project else ""
+        table.add_row(name, format_path(path), is_default, is_active)
+
+    console.print(table)
+
+
+@project_app.command("add")
+def add_project(
+    name: str = typer.Argument(..., help="Name of the project"),
+    path: str = typer.Argument(..., help="Path to the project directory"),
+) -> None:
+    """Add a new project."""
+    config_manager = ConfigManager()
+
+    try:
+        # Resolve to absolute path
+        resolved_path = os.path.abspath(os.path.expanduser(path))
+        config_manager.add_project(name, resolved_path)
+        console.print(f"[green]Project '{name}' added at {format_path(resolved_path)}[/green]")
+
+        # Display usage hint
+        console.print("\nTo use this project:")
+        console.print(f"  basic-memory --project={name} <command>")
+        console.print("  # or")
+        console.print(f"  basic-memory project default {name}")
+    except ValueError as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@project_app.command("remove")
+def remove_project(
+    name: str = typer.Argument(..., help="Name of the project to remove"),
+) -> None:
+    """Remove a project from configuration."""
+    config_manager = ConfigManager()
+
+    try:
+        config_manager.remove_project(name)
+        console.print(f"[green]Project '{name}' removed from configuration[/green]")
+        console.print("[yellow]Note: The project files have not been deleted from disk.[/yellow]")
+    except ValueError as e:  # pragma: no cover
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@project_app.command("default")
+def set_default_project(
+    name: str = typer.Argument(..., help="Name of the project to set as default"),
+) -> None:
+    """Set the default project."""
+    config_manager = ConfigManager()
+
+    try:
+        config_manager.set_default_project(name)
+        console.print(f"[green]Project '{name}' set as default[/green]")
+    except ValueError as e:  # pragma: no cover
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@project_app.command("current")
+def show_current_project() -> None:
+    """Show the current project."""
+    config_manager = ConfigManager()
+    current = os.environ.get("BASIC_MEMORY_PROJECT", config_manager.default_project)
+
+    try:
+        path = config_manager.get_project_path(current)
+        console.print(f"Current project: [cyan]{current}[/cyan]")
+        console.print(f"Path: [green]{format_path(str(path))}[/green]")
+        console.print(f"Database: [blue]{format_path(str(config.database_path))}[/blue]")
+    except ValueError:  # pragma: no cover
+        console.print(f"[yellow]Warning: Project '{current}' not found in configuration[/yellow]")
+        console.print(f"Using default project: [cyan]{config_manager.default_project}[/cyan]")

src/basic_memory/cli/commands/status.py

@@ -130,15 +130,15 @@ async def run_status(sync_service: SyncService, verbose: bool = False):
 
 
 @app.command()
+@logfire.instrument(extract_args=False)
 def status(
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed file information"),
 ):
     """Show sync status between files and database."""
-    with logfire.span("status"):  # pyright: ignore [reportGeneralTypeIssues]
-        try:
-            sync_service = asyncio.run(get_sync_service())
-            asyncio.run(run_status(sync_service, verbose))  # pragma: no cover
-        except Exception as e:
-            logger.exception(f"Error checking status: {e}")
-            typer.echo(f"Error checking status: {e}", err=True)
-            raise typer.Exit(code=1)  # pragma: no cover
+    try:
+        sync_service = asyncio.run(get_sync_service())
+        asyncio.run(run_status(sync_service, verbose))  # pragma: no cover
+    except Exception as e:
+        logger.exception(f"Error checking status: {e}")
+        typer.echo(f"Error checking status: {e}", err=True)
+        raise typer.Exit(code=1)  # pragma: no cover

src/basic_memory/cli/commands/sync.py

@@ -93,8 +93,10 @@ def group_issues_by_directory(issues: List[ValidationIssue]) -> Dict[str, List[V
 def display_sync_summary(knowledge: SyncReport):
     """Display a one-line summary of sync changes."""
     total_changes = knowledge.total
+    project_name = config.project
+
     if total_changes == 0:
-        console.print("[green]Everything up to date[/green]")
+        console.print(f"[green]Project '{project_name}': Everything up to date[/green]")
         return
 
     # Format as: "Synced X files (A new, B modified, C moved, D deleted)"
@@ -113,16 +115,18 @@ def display_sync_summary(knowledge: SyncReport):
     if del_count:
         changes.append(f"[red]{del_count} deleted[/red]")
 
-    console.print(f"Synced {total_changes} files ({', '.join(changes)})")
+    console.print(f"Project '{project_name}': Synced {total_changes} files ({', '.join(changes)})")
 
 
 def display_detailed_sync_results(knowledge: SyncReport):
     """Display detailed sync results with trees."""
+    project_name = config.project
+
     if knowledge.total == 0:
-        console.print("\n[green]Everything up to date[/green]")
+        console.print(f"\n[green]Project '{project_name}': Everything up to date[/green]")
         return
 
-    console.print("\n[bold]Sync Results[/bold]")
+    console.print(f"\n[bold]Sync Results for Project '{project_name}'[/bold]")
 
     if knowledge.total > 0:
         knowledge_tree = Tree("[bold]Knowledge Files[/bold]")
@@ -150,23 +154,52 @@ def display_detailed_sync_results(knowledge: SyncReport):
 
 async def run_sync(verbose: bool = False, watch: bool = False, console_status: bool = False):
     """Run sync operation."""
+    import time
+
+    start_time = time.time()
+
+    logger.info(
+        "Sync command started",
+        project=config.project,
+        watch_mode=watch,
+        verbose=verbose,
+        directory=str(config.home),
+    )
 
     sync_service = await get_sync_service()
 
     # Start watching if requested
     if watch:
+        logger.info("Starting watch service after initial sync")
         watch_service = WatchService(
             sync_service=sync_service,
             file_service=sync_service.entity_service.file_service,
             config=config,
         )
-        # full sync
-        await sync_service.sync(config.home)
+
+        # full sync - no progress bars in watch mode
+        await sync_service.sync(config.home, show_progress=False)
+
         # watch changes
         await watch_service.run()  # pragma: no cover
     else:
-        # one time sync
-        knowledge_changes = await sync_service.sync(config.home)
+        # one time sync - use progress bars for better UX
+        logger.info("Running one-time sync")
+        knowledge_changes = await sync_service.sync(config.home, show_progress=True)
+
+        # Log results
+        duration_ms = int((time.time() - start_time) * 1000)
+        logger.info(
+            "Sync command completed",
+            project=config.project,
+            total_changes=knowledge_changes.total,
+            new_files=len(knowledge_changes.new),
+            modified_files=len(knowledge_changes.modified),
+            deleted_files=len(knowledge_changes.deleted),
+            moved_files=len(knowledge_changes.moves),
+            duration_ms=duration_ms,
+        )
+
         # Display results
         if verbose:
             display_detailed_sync_results(knowledge_changes)
@@ -191,12 +224,24 @@ def sync(
 ) -> None:
     """Sync knowledge files with the database."""
     try:
+        # Show which project we're syncing
+        if not watch:  # Don't show in watch mode as it would break the UI
+            typer.echo(f"Syncing project: {config.project}")
+            typer.echo(f"Project path: {config.home}")
+
         # Run sync
         asyncio.run(run_sync(verbose=verbose, watch=watch))
 
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
-            logger.exception("Sync failed", e)
+            logger.exception(
+                "Sync command failed",
+                project=config.project,
+                error=str(e),
+                error_type=type(e).__name__,
+                watch_mode=watch,
+                directory=str(config.home),
+            )
             typer.echo(f"Error during sync: {e}", err=True)
             raise typer.Exit(1)
         raise

src/basic_memory/cli/commands/tool.py

@@ -1,6 +1,7 @@
 """CLI tool commands for Basic Memory."""
 
 import asyncio
+import sys
 from typing import Optional, List, Annotated
 
 import typer
@@ -19,24 +20,78 @@ 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.schemas.base import TimeFrame
 from basic_memory.schemas.memory import MemoryUrl
 from basic_memory.schemas.search import SearchQuery, SearchItemType
 
 tool_app = typer.Typer()
-app.add_typer(tool_app, name="tools", help="cli versions mcp tools")
+app.add_typer(tool_app, name="tool", help="Direct access to MCP tools via CLI")
 
 
 @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")],
+    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)
+
         note = asyncio.run(mcp_write_note(title, content, folder, tags))
         rprint(note)
     except Exception as e:  # pragma: no cover
@@ -166,7 +221,7 @@ def continue_conversation(
         Optional[str], typer.Option(help="How far back to look for activity")
     ] = None,
 ):
-    """Continue a previous conversation or work session."""
+    """Prompt to continue a previous conversation or work session."""
     try:
         # Prompt functions return formatted strings directly
         session = asyncio.run(mcp_continue_conversation(topic=topic, timeframe=timeframe))
@@ -177,3 +232,22 @@ def continue_conversation(
             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

src/basic_memory/cli/main.py

@@ -1,6 +1,7 @@
 """Main CLI entry point for basic-memory."""  # pragma: no cover
 
 from basic_memory.cli.app import app  # pragma: no cover
+import typer
 
 # Register commands
 from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
@@ -12,8 +13,46 @@ from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
     import_claude_conversations,
     import_claude_projects,
     import_chatgpt,
-    tools,
+    tool,
+    project,
 )
 
+
+# Version command
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    project: str = typer.Option(  # noqa
+        "main",
+        "--project",
+        "-p",
+        help="Specify which project to use",
+        envvar="BASIC_MEMORY_PROJECT",
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show version information and exit.",
+        is_eager=True,
+    ),
+):
+    """Basic Memory - Local-first personal knowledge management system."""
+    if version:  # pragma: no cover
+        from basic_memory import __version__
+        from basic_memory.config import config
+
+        typer.echo(f"Basic Memory v{__version__}")
+        typer.echo(f"Current project: {config.project}")
+        typer.echo(f"Project path: {config.home}")
+        raise typer.Exit()
+
+    # Handle project selection via environment variable
+    if project:
+        import os
+
+        os.environ["BASIC_MEMORY_PROJECT"] = project
+
+
 if __name__ == "__main__":  # pragma: no cover
     app()