amfs-cli 0.1.0__tar.gz

amfs_cli-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+node_modules/
+.next/
+!uv.lock
+!pnpm-lock.yaml
+.amfs/
+test.py

amfs_cli-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: amfs-cli
+Version: 0.1.0
+Summary: AMFS CLI — snapshot, inspect, and manage agent memory
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: amfs
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich<14,>=13
+Requires-Dist: typer<1,>=0.12

amfs_cli-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "amfs-cli"
+version = "0.1.0"
+description = "AMFS CLI — snapshot, inspect, and manage agent memory"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+dependencies = [
+    "amfs",
+    "typer>=0.12,<1",
+    "rich>=13,<14",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+amfs = "amfs_cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/amfs_cli"]

amfs_cli-0.1.0/src/amfs_cli/__init__.py

@@ -0,0 +1 @@
+"""AMFS CLI — snapshot, inspect, and manage agent memory."""

amfs_cli-0.1.0/src/amfs_cli/init.py

@@ -0,0 +1,77 @@
+"""amfs init — scaffold an AMFS project in one command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+_DEFAULT_CONFIG = """\
+# AMFS Configuration
+# Docs: https://github.com/raia-live/amfs
+
+namespace: {namespace}
+
+layers:
+  primary:
+    adapter: filesystem
+    options:
+      root: .amfs
+"""
+
+_GITIGNORE = """\
+# AMFS local memory store
+.amfs/
+"""
+
+
+def init_command(
+    directory: Path = typer.Argument(
+        Path("."), help="Directory to initialise (default: current dir)"
+    ),
+    namespace: str = typer.Option(
+        "default", "--namespace", "-n", help="Namespace for this project"
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Overwrite existing config"
+    ),
+) -> None:
+    """Initialise an AMFS project — creates config file and data directory."""
+    directory = directory.resolve()
+    config_path = directory / "amfs.yaml"
+    amfs_dir = directory / ".amfs"
+
+    if config_path.exists() and not force:
+        console.print(
+            f"[yellow]amfs.yaml already exists at {config_path}. "
+            f"Use --force to overwrite.[/yellow]"
+        )
+        raise typer.Exit(code=1)
+
+    directory.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(_DEFAULT_CONFIG.format(namespace=namespace), encoding="utf-8")
+    amfs_dir.mkdir(exist_ok=True)
+
+    gitignore = directory / ".gitignore"
+    if gitignore.exists():
+        content = gitignore.read_text(encoding="utf-8")
+        if ".amfs/" not in content:
+            with open(gitignore, "a", encoding="utf-8") as f:
+                f.write("\n" + _GITIGNORE)
+            console.print("[dim]Updated .gitignore with .amfs/[/dim]")
+    else:
+        gitignore.write_text(_GITIGNORE, encoding="utf-8")
+        console.print("[dim]Created .gitignore[/dim]")
+
+    console.print("[green bold]AMFS initialised![/green bold]")
+    console.print(f"  Config:    {config_path}")
+    console.print(f"  Data dir:  {amfs_dir}")
+    console.print(f"  Namespace: {namespace}")
+    console.print()
+    console.print("[dim]Quick start:[/dim]")
+    console.print('  from amfs import AgentMemory')
+    console.print('  mem = AgentMemory(agent_id="my-agent")')
+    console.print('  mem.write("my-service", "key", {"hello": "world"})')

amfs_cli-0.1.0/src/amfs_cli/inspect.py

@@ -0,0 +1,139 @@
+"""Inspect CLI commands — list, read, and diff memory entries."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from amfs.config import load_config_or_default
+from amfs.factory import create_adapter_from_config
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+@app.command("list")
+def list_entries(
+    entity: str | None = typer.Argument(None, help="Filter to entity path"),
+    config: Path | None = typer.Option(None, "--config", "-c", help="AMFS config file"),
+    superseded: bool = typer.Option(False, "--superseded", help="Include superseded versions"),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, json"),
+) -> None:
+    """List memory entries."""
+    cfg = load_config_or_default(config)
+    adapter = create_adapter_from_config(cfg)
+
+    with console.status("[cyan]Loading entries...[/cyan]"):
+        entries = adapter.list(entity, include_superseded=superseded)
+
+    if not entries:
+        console.print("[dim]No entries found.[/dim]")
+        return
+
+    if format == "json":
+        console.print_json(json.dumps(
+            [{"entity_path": e.entity_path, "key": e.key, "version": e.version,
+              "confidence": e.confidence, "agent_id": e.provenance.agent_id,
+              "written_at": e.provenance.written_at.isoformat()}
+             for e in entries],
+            default=str,
+        ))
+        return
+
+    table = Table(title=f"Memory Entries ({len(entries)})")
+    table.add_column("Entity", style="cyan")
+    table.add_column("Key", style="green")
+    table.add_column("Version", justify="right")
+    table.add_column("Confidence", justify="right")
+    table.add_column("Agent", style="magenta")
+    table.add_column("Written At")
+
+    for e in entries:
+        table.add_row(
+            e.entity_path,
+            e.key,
+            str(e.version),
+            f"{e.confidence:.4f}",
+            e.provenance.agent_id,
+            e.provenance.written_at.strftime("%Y-%m-%d %H:%M:%S"),
+        )
+
+    console.print(table)
+
+
+@app.command()
+def read(
+    entity: str = typer.Argument(..., help="Entity path"),
+    key: str = typer.Argument(..., help="Key name"),
+    config: Path | None = typer.Option(None, "--config", "-c", help="AMFS config file"),
+    format: str = typer.Option("panel", "--format", "-f", help="Output format: panel, json"),
+) -> None:
+    """Read a specific memory entry and print its value."""
+    cfg = load_config_or_default(config)
+    adapter = create_adapter_from_config(cfg)
+    entry = adapter.read(entity, key)
+
+    if entry is None:
+        console.print(f"[red]Entry not found: {entity}/{key}[/red]")
+        raise typer.Exit(code=1)
+
+    if format == "json":
+        console.print_json(json.dumps({
+            "entity_path": entry.entity_path, "key": entry.key,
+            "value": entry.value, "version": entry.version,
+            "confidence": entry.confidence,
+            "agent_id": entry.provenance.agent_id,
+            "written_at": entry.provenance.written_at.isoformat(),
+        }, default=str))
+        return
+
+    console.print(f"[bold]{entity}/{key}[/bold] v{entry.version}")
+    console.print(f"Confidence: {entry.confidence:.4f}")
+    console.print(f"Agent: {entry.provenance.agent_id} ({entry.provenance.session_id})")
+    console.print(f"Written: {entry.provenance.written_at}")
+    if entry.ttl_at:
+        console.print(f"TTL: {entry.ttl_at}")
+    console.print()
+    console.print_json(json.dumps(entry.value, default=str))
+
+
+@app.command()
+def diff(
+    entity: str = typer.Argument(..., help="Entity path"),
+    key: str = typer.Argument(..., help="Key name"),
+    config: Path | None = typer.Option(None, "--config", "-c", help="AMFS config file"),
+) -> None:
+    """Show version history diff for a key."""
+    cfg = load_config_or_default(config)
+    adapter = create_adapter_from_config(cfg)
+
+    with console.status("[cyan]Loading history...[/cyan]"):
+        entries = adapter.list(entity, include_superseded=True)
+
+    key_entries = sorted(
+        [e for e in entries if e.key == key],
+        key=lambda e: e.version,
+    )
+
+    if not key_entries:
+        console.print(f"[red]No entries found for {entity}/{key}[/red]")
+        raise typer.Exit(code=1)
+
+    for i, entry in enumerate(key_entries):
+        console.print(f"[bold]v{entry.version}[/bold] (confidence: {entry.confidence:.4f})")
+        console.print(f"  Agent: {entry.provenance.agent_id}")
+        console.print(f"  Written: {entry.provenance.written_at}")
+
+        if i > 0:
+            prev_val = json.dumps(key_entries[i - 1].value, sort_keys=True, default=str)
+            curr_val = json.dumps(entry.value, sort_keys=True, default=str)
+            if prev_val != curr_val:
+                console.print(f"  [red]- {prev_val}[/red]")
+                console.print(f"  [green]+ {curr_val}[/green]")
+            else:
+                console.print("  [dim](value unchanged)[/dim]")
+        console.print()

amfs_cli-0.1.0/src/amfs_cli/login.py

@@ -0,0 +1,43 @@
+"""amfs login — store credentials for remote AMFS access."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from amfs_cli.remote import save_credentials, get_client
+
+console = Console()
+
+
+def login_command(
+    url: str = typer.Option(..., "--url", "-u", prompt="AMFS server URL", help="AMFS HTTP API URL"),
+    api_key: str = typer.Option(..., "--key", "-k", prompt="API key", hide_input=True, help="AMFS API key"),
+) -> None:
+    """Store AMFS credentials for remote CLI access."""
+    with console.status("[cyan]Verifying connection...[/cyan]"):
+        try:
+            client = get_client.__wrapped__ if hasattr(get_client, "__wrapped__") else None  # noqa: F841
+            import httpx
+            with httpx.Client(
+                base_url=url.rstrip("/"),
+                headers={"X-AMFS-API-Key": api_key},
+                timeout=10.0,
+            ) as client:
+                resp = client.get("/api/v1/health")
+                resp.raise_for_status()
+        except Exception as exc:
+            console.print(f"[red]Connection failed:[/red] {exc}")
+            raise typer.Exit(code=1)
+
+    path = save_credentials(url, api_key)
+    console.print(
+        Panel(
+            f"[green]Credentials saved to[/green] {path}\n\n"
+            f"  Server: [cyan]{url}[/cyan]\n"
+            f"  Key:    [dim]{api_key[:12]}{'•' * 20}[/dim]",
+            title="[bold green]Login successful[/bold green]",
+            border_style="green",
+        )
+    )

amfs_cli-0.1.0/src/amfs_cli/main.py

@@ -0,0 +1,55 @@
+"""AMFS CLI entry point."""
+
+from __future__ import annotations
+
+import typer
+
+from amfs_cli.init import init_command
+from amfs_cli.login import login_command
+from amfs_cli.recall import recall_command
+from amfs_cli.search import search_command
+from amfs_cli.snapshot import app as snapshot_app
+from amfs_cli.inspect import app as inspect_app
+from amfs_cli.stats import stats_command
+from amfs_cli.status import status_command
+from amfs_cli.watch import watch_command
+from amfs_cli.write import write_command
+
+app = typer.Typer(
+    name="amfs",
+    help="AMFS — Agent Memory File System CLI",
+    no_args_is_help=True,
+)
+
+app.command(name="init", help="Initialise an AMFS project")(init_command)
+app.command(name="login", help="Store credentials for remote access")(login_command)
+app.command(name="write", help="Write a memory entry")(write_command)
+app.command(name="search", help="Search memory entries")(search_command)
+app.command(name="recall", help="Recall an agent-scoped entry")(recall_command)
+app.command(name="stats", help="Show memory statistics")(stats_command)
+app.command(name="status", help="Show config and connection health")(status_command)
+app.command(name="watch", help="Live-stream memory changes (SSE)")(watch_command)
+app.add_typer(snapshot_app, name="snapshot", help="Export and restore memory snapshots")
+app.add_typer(inspect_app, name="inspect", help="List, read, and diff memory entries")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        from importlib.metadata import version
+
+        typer.echo(f"amfs-cli {version('amfs-cli')}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", "-V", callback=_version_callback,
+        is_eager=True, help="Show version and exit",
+    ),
+) -> None:
+    """AMFS — Agent Memory File System CLI."""
+
+
+if __name__ == "__main__":
+    app()

amfs_cli-0.1.0/src/amfs_cli/recall.py

@@ -0,0 +1,74 @@
+"""amfs recall — recall agent-scoped memory."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+
+def recall_command(
+    entity: str = typer.Argument(..., help="Entity path"),
+    key: str = typer.Argument(..., help="Memory key"),
+    agent_id: str = typer.Option("cli", "--agent", "-a", help="Agent ID to recall as"),
+    format: str = typer.Option("panel", "--format", "-f", help="Output format: panel, json"),
+    remote: bool = typer.Option(False, "--remote", "-r", help="Recall via HTTP API"),
+) -> None:
+    """Recall an agent-scoped memory entry."""
+    if remote:
+        from amfs_cli.remote import api_get
+
+        with console.status("[cyan]Recalling...[/cyan]"):
+            result = api_get(
+                f"/api/v1/entries/{entity}/{key}",
+                params={"agent_id": agent_id},
+            )
+
+        if format == "json":
+            console.print_json(json.dumps(result, default=str))
+            return
+
+        if not result:
+            console.print(f"[dim]No entry found for {entity}/{key}[/dim]")
+            return
+
+        console.print(Panel(
+            f"[bold]{entity}/{key}[/bold] v{result.get('version', '?')}\n"
+            f"Confidence: [green]{result.get('confidence', 0):.4f}[/green]\n"
+            f"Agent: [magenta]{result.get('agent_id', '')}[/magenta]\n\n"
+            f"{json.dumps(result.get('value'), indent=2, default=str)}",
+            title="[bold cyan]Recall[/bold cyan]",
+            border_style="cyan",
+        ))
+    else:
+        from amfs import AgentMemory
+
+        with console.status("[cyan]Recalling...[/cyan]"):
+            mem = AgentMemory(agent_id=agent_id)
+            entry = mem.recall(entity, key)
+
+        if entry is None:
+            console.print(f"[dim]No entry found for {entity}/{key}[/dim]")
+            raise typer.Exit(code=1)
+
+        if format == "json":
+            console.print_json(json.dumps({
+                "entity_path": entry.entity_path, "key": entry.key,
+                "value": entry.value, "version": entry.version,
+                "confidence": entry.confidence,
+                "agent_id": entry.provenance.agent_id,
+            }, default=str))
+            return
+
+        console.print(Panel(
+            f"[bold]{entity}/{key}[/bold] v{entry.version}\n"
+            f"Confidence: [green]{entry.confidence:.4f}[/green]\n"
+            f"Agent: [magenta]{entry.provenance.agent_id}[/magenta]\n\n"
+            f"{json.dumps(entry.value, indent=2, default=str)}",
+            title="[bold cyan]Recall[/bold cyan]",
+            border_style="cyan",
+        ))

amfs_cli-0.1.0/src/amfs_cli/remote.py

@@ -0,0 +1,71 @@
+"""Shared HTTP client helper for remote AMFS operations."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import httpx
+from rich.console import Console
+
+console = Console(stderr=True)
+
+_CRED_DIR = Path.home() / ".config" / "amfs"
+_CRED_FILE = _CRED_DIR / "credentials.json"
+
+
+def _load_credentials() -> dict[str, str]:
+    if _CRED_FILE.exists():
+        return json.loads(_CRED_FILE.read_text(encoding="utf-8"))
+    return {}
+
+
+def save_credentials(url: str, api_key: str) -> Path:
+    _CRED_DIR.mkdir(parents=True, exist_ok=True)
+    _CRED_FILE.write_text(
+        json.dumps({"url": url, "api_key": api_key}, indent=2),
+        encoding="utf-8",
+    )
+    _CRED_FILE.chmod(0o600)
+    return _CRED_FILE
+
+
+def get_client() -> httpx.Client:
+    """Build an httpx client from env vars or stored credentials."""
+    url = os.environ.get("AMFS_HTTP_URL")
+    api_key = os.environ.get("AMFS_API_KEY")
+
+    if not url:
+        creds = _load_credentials()
+        url = creds.get("url")
+        api_key = api_key or creds.get("api_key")
+
+    if not url:
+        console.print(
+            "[red]No AMFS server configured.[/red]\n"
+            "Run [bold]amfs login[/bold] or set AMFS_HTTP_URL.",
+        )
+        sys.exit(1)
+
+    headers: dict[str, str] = {}
+    if api_key:
+        headers["X-AMFS-API-Key"] = api_key
+
+    return httpx.Client(base_url=url.rstrip("/"), headers=headers, timeout=30.0)
+
+
+def api_get(path: str, params: dict[str, Any] | None = None) -> Any:
+    with get_client() as client:
+        resp = client.get(path, params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def api_post(path: str, payload: dict[str, Any]) -> Any:
+    with get_client() as client:
+        resp = client.post(path, json=payload)
+        resp.raise_for_status()
+        return resp.json()

amfs_cli-0.1.0/src/amfs_cli/search.py

@@ -0,0 +1,103 @@
+"""amfs search — search memory entries."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+app = typer.Typer(no_args_is_help=False)
+
+
+def search_command(
+    query: str = typer.Argument(None, help="Search query text"),
+    entity: str | None = typer.Option(None, "--entity", "-e", help="Filter by entity path"),
+    agent_id: str | None = typer.Option(None, "--agent", "-a", help="Filter by agent ID"),
+    min_confidence: float = typer.Option(0.0, "--min-confidence", help="Minimum confidence"),
+    limit: int = typer.Option(50, "--limit", "-l", help="Max results"),
+    format: str = typer.Option("table", "--format", "-f", help="Output format: table, json"),
+    remote: bool = typer.Option(False, "--remote", "-r", help="Search via HTTP API"),
+) -> None:
+    """Search memory entries by query, entity, agent, or confidence."""
+    if remote:
+        from amfs_cli.remote import api_post
+
+        with console.status("[cyan]Searching...[/cyan]"):
+            results = api_post("/api/v1/search", {
+                "query": query,
+                "entity_path": entity,
+                "agent_id": agent_id,
+                "min_confidence": min_confidence,
+                "limit": limit,
+            })
+
+        if format == "json":
+            console.print_json(json.dumps(results, default=str))
+            return
+
+        if not results:
+            console.print("[dim]No results found.[/dim]")
+            return
+
+        table = Table(title=f"Search Results ({len(results)} entries)")
+        table.add_column("Entity", style="cyan")
+        table.add_column("Key", style="green")
+        table.add_column("Confidence", justify="right")
+        table.add_column("Agent", style="magenta")
+        table.add_column("Value", max_width=50)
+
+        for r in results:
+            table.add_row(
+                r.get("entity_path", ""),
+                r.get("key", ""),
+                f"{r.get('confidence', 0):.4f}",
+                r.get("agent_id", ""),
+                str(r.get("value", ""))[:50],
+            )
+        console.print(table)
+    else:
+        from amfs import AgentMemory
+
+        with console.status("[cyan]Searching...[/cyan]"):
+            mem = AgentMemory(agent_id="cli")
+            results = mem.search(
+                query=query,
+                entity_path=entity,
+                agent_id=agent_id,
+                min_confidence=min_confidence,
+                limit=limit,
+            )
+
+        if format == "json":
+            console.print_json(json.dumps(
+                [{"entity_path": e.entity_path, "key": e.key, "value": e.value,
+                  "confidence": e.confidence, "agent_id": e.provenance.agent_id}
+                 for e in results],
+                default=str,
+            ))
+            return
+
+        if not results:
+            console.print("[dim]No results found.[/dim]")
+            return
+
+        table = Table(title=f"Search Results ({len(results)} entries)")
+        table.add_column("Entity", style="cyan")
+        table.add_column("Key", style="green")
+        table.add_column("Confidence", justify="right")
+        table.add_column("Agent", style="magenta")
+        table.add_column("Value", max_width=50)
+
+        for e in results:
+            table.add_row(
+                e.entity_path,
+                e.key,
+                f"{e.confidence:.4f}",
+                e.provenance.agent_id,
+                str(e.value)[:50],
+            )
+        console.print(table)

amfs_cli-0.1.0/src/amfs_cli/snapshot.py

@@ -0,0 +1,62 @@
+"""Snapshot CLI commands — export and restore."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
+
+from amfs.config import load_config_or_default
+from amfs.factory import create_adapter_from_config
+from amfs_core.snapshot import SnapshotExporter, SnapshotImporter
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+@app.command()
+def export(
+    output: Path = typer.Argument(..., help="Output snapshot file path"),
+    config: Path | None = typer.Option(None, "--config", "-c", help="AMFS config file"),
+    entity: str | None = typer.Option(None, "--entity", "-e", help="Filter to entity path"),
+    include_superseded: bool = typer.Option(False, "--superseded", help="Include superseded versions"),
+) -> None:
+    """Export current memory state to a JSON snapshot."""
+    cfg = load_config_or_default(config)
+    adapter = create_adapter_from_config(cfg)
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("{task.completed} entries"),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Exporting...", total=None)
+        exporter = SnapshotExporter(adapter)
+        count = exporter.export(output, entity_path=entity, include_superseded=include_superseded)
+        progress.update(task, completed=count, total=count)
+    console.print(f"[green]Exported {count} entries to {output}[/green]")
+
+
+@app.command()
+def restore(
+    input_path: Path = typer.Argument(..., help="Snapshot file to restore"),
+    config: Path | None = typer.Option(None, "--config", "-c", help="AMFS config file"),
+) -> None:
+    """Restore memory entries from a snapshot file."""
+    cfg = load_config_or_default(config)
+    adapter = create_adapter_from_config(cfg)
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("{task.completed} entries"),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Restoring...", total=None)
+        importer = SnapshotImporter(adapter)
+        count = importer.restore(input_path)
+        progress.update(task, completed=count, total=count)
+    console.print(f"[green]Restored {count} entries from {input_path}[/green]")

amfs_cli-0.1.0/src/amfs_cli/stats.py

@@ -0,0 +1,58 @@
+"""amfs stats — display memory statistics."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+console = Console()
+
+
+def stats_command(
+    format: str = typer.Option("panel", "--format", "-f", help="Output format: panel, json"),
+    remote: bool = typer.Option(False, "--remote", "-r", help="Fetch via HTTP API"),
+) -> None:
+    """Show memory statistics (entries, agents, entities)."""
+    if remote:
+        from amfs_cli.remote import api_get
+
+        with console.status("[cyan]Fetching stats...[/cyan]"):
+            data = api_get("/api/v1/stats")
+    else:
+        from amfs import AgentMemory
+
+        with console.status("[cyan]Computing stats...[/cyan]"):
+            mem = AgentMemory(agent_id="cli")
+            s = mem.stats()
+            data = {
+                "total_entries": s.total_entries,
+                "total_entities": s.total_entities,
+                "total_agents": s.total_agents,
+                "avg_confidence": round(s.avg_confidence, 4) if s.avg_confidence else 0,
+                "memory_types": s.memory_types if hasattr(s, "memory_types") else {},
+            }
+
+    if format == "json":
+        console.print_json(json.dumps(data, default=str))
+        return
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Metric", style="bold cyan")
+    table.add_column("Value", justify="right", style="green")
+
+    table.add_row("Total Entries", str(data.get("total_entries", 0)))
+    table.add_row("Total Entities", str(data.get("total_entities", 0)))
+    table.add_row("Total Agents", str(data.get("total_agents", 0)))
+    table.add_row("Avg Confidence", f"{data.get('avg_confidence', 0):.4f}")
+
+    types = data.get("memory_types", {})
+    if types:
+        table.add_row("", "")
+        for mt, count in types.items():
+            table.add_row(f"  {mt}", str(count))
+
+    console.print(Panel(table, title="[bold]Memory Statistics[/bold]", border_style="cyan"))

amfs_cli-0.1.0/src/amfs_cli/status.py

@@ -0,0 +1,68 @@
+"""amfs status — show configuration and connection health."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+console = Console()
+
+
+def status_command() -> None:
+    """Show current AMFS configuration, adapter, and connection health."""
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Setting", style="bold")
+    table.add_column("Value")
+
+    config_path = Path("amfs.yaml")
+    table.add_row("Config file", str(config_path) if config_path.exists() else "[dim]not found[/dim]")
+
+    http_url = os.environ.get("AMFS_HTTP_URL")
+    api_key = os.environ.get("AMFS_API_KEY")
+    pg_dsn = os.environ.get("AMFS_POSTGRES_DSN")
+    data_dir = os.environ.get("AMFS_DATA_DIR")
+
+    cred_file = Path.home() / ".config" / "amfs" / "credentials.json"
+    if cred_file.exists():
+        import json
+        creds = json.loads(cred_file.read_text(encoding="utf-8"))
+        if not http_url:
+            http_url = creds.get("url")
+        if not api_key:
+            api_key = creds.get("api_key")
+
+    if http_url:
+        table.add_row("Mode", "[cyan]Remote (HTTP API)[/cyan]")
+        table.add_row("Server URL", f"[green]{http_url}[/green]")
+        table.add_row("API Key", f"[dim]{api_key[:12]}{'•' * 20}[/dim]" if api_key else "[yellow]not set[/yellow]")
+    elif pg_dsn:
+        table.add_row("Mode", "[cyan]Postgres[/cyan]")
+        host = pg_dsn.split("@")[-1].split("/")[0] if "@" in pg_dsn else pg_dsn[:40]
+        table.add_row("DSN", f"[dim]{host}[/dim]")
+    elif data_dir:
+        table.add_row("Mode", "[cyan]Filesystem[/cyan]")
+        table.add_row("Data dir", data_dir)
+    elif config_path.exists():
+        table.add_row("Mode", "[cyan]Config file[/cyan]")
+    else:
+        table.add_row("Mode", "[yellow]Default (filesystem .amfs/)[/yellow]")
+
+    if http_url:
+        with console.status("[cyan]Checking connection...[/cyan]"):
+            try:
+                import httpx
+                headers = {"X-AMFS-API-Key": api_key} if api_key else {}
+                resp = httpx.get(f"{http_url.rstrip('/')}/api/v1/health", headers=headers, timeout=5.0)
+                if resp.status_code == 200:
+                    table.add_row("Connection", "[green]Healthy[/green]")
+                else:
+                    table.add_row("Connection", f"[yellow]HTTP {resp.status_code}[/yellow]")
+            except Exception as exc:
+                table.add_row("Connection", f"[red]Failed: {exc}[/red]")
+
+    console.print(Panel(table, title="[bold]AMFS Status[/bold]", border_style="cyan"))

amfs_cli-0.1.0/src/amfs_cli/watch.py

@@ -0,0 +1,74 @@
+"""amfs watch — live-stream memory changes via SSE."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import typer
+from rich.console import Console
+from rich.live import Live
+from rich.table import Table
+
+console = Console()
+
+
+def watch_command(
+    entity: str | None = typer.Argument(None, help="Filter to entity path (default: all)"),
+    limit: int = typer.Option(20, "--limit", "-l", help="Max rows to display"),
+) -> None:
+    """Live-stream memory changes from a remote AMFS server (SSE)."""
+    from amfs_cli.remote import get_client
+
+    client = get_client()
+    params = {"entity_path": entity or "*"}
+
+    events: list[dict] = []
+
+    def _build_table() -> Table:
+        table = Table(title="Live Memory Stream", expand=True)
+        table.add_column("Entity", style="cyan", max_width=30)
+        table.add_column("Key", style="green", max_width=20)
+        table.add_column("Agent", style="magenta", max_width=15)
+        table.add_column("Version", justify="right")
+        table.add_column("Value", max_width=40)
+        for ev in events[-limit:]:
+            table.add_row(
+                ev.get("entity_path", ""),
+                ev.get("key", ""),
+                ev.get("agent_id", ""),
+                str(ev.get("version", "")),
+                str(ev.get("value", ""))[:40],
+            )
+        return table
+
+    console.print(f"[cyan]Connecting to SSE stream...[/cyan] (entity: {entity or '*'})")
+    console.print("[dim]Press Ctrl-C to stop[/dim]\n")
+
+    try:
+        with Live(_build_table(), console=console, refresh_per_second=2) as live:
+            with client.stream(
+                "GET", "/api/v1/stream", params=params, timeout=None
+            ) as resp:
+                resp.raise_for_status()
+                buf = ""
+                for chunk in resp.iter_text():
+                    buf += chunk
+                    while "\n\n" in buf:
+                        msg, buf = buf.split("\n\n", 1)
+                        for line in msg.split("\n"):
+                            if line.startswith("data:"):
+                                raw = line[5:].strip()
+                                if raw:
+                                    try:
+                                        events.append(json.loads(raw))
+                                        live.update(_build_table())
+                                    except json.JSONDecodeError:
+                                        pass
+    except KeyboardInterrupt:
+        console.print(f"\n[dim]Stopped. Received {len(events)} events.[/dim]")
+    except httpx.HTTPStatusError as exc:
+        console.print(f"[red]Stream error:[/red] {exc.response.status_code}")
+        raise typer.Exit(code=1)
+    finally:
+        client.close()

amfs_cli-0.1.0/src/amfs_cli/write.py

@@ -0,0 +1,54 @@
+"""amfs write — write a memory entry."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def write_command(
+    entity: str = typer.Argument(..., help="Entity path (e.g. myapp/auth)"),
+    key: str = typer.Argument(..., help="Memory key"),
+    value: str = typer.Argument(
+        None, help="JSON value (reads from stdin if omitted)"
+    ),
+    agent_id: str = typer.Option("cli", "--agent", "-a", help="Agent ID"),
+    confidence: float = typer.Option(1.0, "--confidence", "-c", help="Confidence score"),
+    memory_type: str = typer.Option("fact", "--type", "-t", help="Memory type: fact, belief, experience"),
+    remote: bool = typer.Option(False, "--remote", "-r", help="Write via HTTP API instead of local adapter"),
+) -> None:
+    """Write a memory entry to AMFS."""
+    if value is None:
+        if sys.stdin.isatty():
+            console.print("[dim]Enter JSON value (Ctrl-D to finish):[/dim]")
+        value = sys.stdin.read().strip()
+
+    try:
+        parsed = json.loads(value)
+    except json.JSONDecodeError:
+        parsed = value
+
+    if remote:
+        from amfs_cli.remote import api_post
+
+        with console.status("[cyan]Writing entry...[/cyan]"):
+            result = api_post("/api/v1/entries", {
+                "entity_path": entity,
+                "key": key,
+                "value": parsed,
+                "confidence": confidence,
+                "memory_type": memory_type,
+            })
+        console.print(f"[green]Written[/green] {entity}/{key} v{result.get('version', '?')}")
+    else:
+        from amfs import AgentMemory
+
+        with console.status("[cyan]Writing entry...[/cyan]"):
+            mem = AgentMemory(agent_id=agent_id)
+            entry = mem.write(entity, key, parsed, confidence=confidence, memory_type=memory_type)
+        console.print(f"[green]Written[/green] {entity}/{key} v{entry.version}")