Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
Add Click-based CLI with memory management commands
chopratejasfb4117f3a677
diff --git a/headroom/cli.py b/headroom/cli.pyindex d7c3f4371..c7e8c4775 100644--- a/headroom/cli.py+++ b/headroom/cli.py@@ -1,789 +1,6 @@-#!/usr/bin/env python3-"""Headroom CLI - The Context Optimization Layer for LLM Applications.--Usage:- headroom proxy [OPTIONS] Start the optimization proxy server- headroom memory-eval [OPTIONS] Run LoCoMo memory evaluation- headroom --version Show version- headroom --help Show this help message--Examples:- # Start proxy on default port (8787)- headroom proxy-- # Start proxy on custom port- headroom proxy --port 8080-- # Start with optimization disabled (passthrough mode)- headroom proxy --no-optimize-- # Use with Claude Code- ANTHROPIC_BASE_URL=http://localhost:8787 claude-- # Run memory evaluation on 3 conversations- headroom memory-eval -n 3-- # Run memory evaluation with LLM answering and judging- headroom memory-eval --answer-model gpt-4o --llm-judge-"""--from __future__ import annotations--import argparse-import sys-from collections.abc import Callable---def get_version() -> str:- """Get the current version."""- try:- from headroom import __version__-- return __version__- except ImportError:- return "unknown"---def cmd_proxy(args: argparse.Namespace) -> int:- """Start the proxy server."""- try:- from headroom.proxy.server import ProxyConfig, run_server- except ImportError as e:- print("Error: Proxy dependencies not installed. Run: pip install headroom[proxy]")- print(f"Details: {e}")- return 1-- config = ProxyConfig(- host=args.host,- port=args.port,- optimize=not args.no_optimize,- cache_enabled=not args.no_cache,- rate_limit_enabled=not args.no_rate_limit,- log_file=args.log_file,- budget_limit_usd=args.budget,- # LLMLingua: ON by default (use --no-llmlingua to disable)- llmlingua_enabled=not args.no_llmlingua,- llmlingua_device=args.llmlingua_device,- llmlingua_target_rate=args.llmlingua_rate,- # Code-aware: ON by default (use --no-code-aware to disable)- code_aware_enabled=not args.no_code_aware,- # Intelligent Context: ON by default (use --no-intelligent-context to disable)- intelligent_context=not args.no_intelligent_context,- intelligent_context_scoring=not args.no_intelligent_scoring,- intelligent_context_compress_first=not args.no_compress_first,- # Memory System- memory_enabled=args.memory,- memory_backend=args.memory_backend,- memory_db_path=args.memory_db_path,- memory_inject_tools=not args.no_memory_tools,- memory_inject_context=not args.no_memory_context,- memory_top_k=args.memory_top_k,- # Backend (Anthropic direct, Bedrock, or LiteLLM)- backend=args.backend,- bedrock_region=args.bedrock_region or args.region,- bedrock_profile=args.bedrock_profile,- )-- memory_status = "DISABLED"- if config.memory_enabled:- memory_status = f"ENABLED ({config.memory_backend})"-- region = args.bedrock_region or args.region- backend_status = "Anthropic (direct API)"- if config.backend != "anthropic":- # Normalize: "bedrock" -> "litellm-bedrock"- backend = config.backend- if not backend.startswith("litellm-"):- backend = f"litellm-{backend}"- provider = backend.replace("litellm-", "")- backend_status = f"{provider.upper()} via LiteLLM (region={region})"-- print(f"""-╔═══════════════════════════════════════════════════════════════════════╗-║ HEADROOM PROXY ║-║ The Context Optimization Layer for LLM Applications ║-╚═══════════════════════════════════════════════════════════════════════╝--Starting proxy server...-- URL: http://{config.host}:{config.port}- Backend: {backend_status}- Optimization: {"ENABLED" if config.optimize else "DISABLED"}- Caching: {"ENABLED" if config.cache_enabled else "DISABLED"}- Rate Limit: {"ENABLED" if config.rate_limit_enabled else "DISABLED"}- Memory: {memory_status}--Usage with Claude Code:- {"unset CLAUDE_CODE_USE_BEDROCK # Important!" if config.backend == "bedrock" else ""}- ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude--Usage with OpenAI-compatible clients:- OPENAI_BASE_URL=http://{config.host}:{config.port}/v1 your-app-{- ""- if not config.memory_enabled- else f'''-Memory:- - Memories are scoped per user. Set x-headroom-user-id header (defaults to 'default').- - Tools: {"ENABLED" if config.memory_inject_tools else "DISABLED"} Context: {"ENABLED" if config.memory_inject_context else "DISABLED"}-'''- + (- " - NOTE: Memory tools require ANTHROPIC_API_KEY (Claude Code subscription credentials have restrictions)."- + chr(10)- if config.memory_inject_tools- else ""- )- }-Endpoints:- GET /health Health check- GET /stats Detailed statistics- GET /metrics Prometheus metrics- POST /v1/messages Anthropic API- POST /v1/chat/completions OpenAI API--Press Ctrl+C to stop.-""")-- try:- run_server(config)- except KeyboardInterrupt:- print("\nShutting down...")- return 0-- return 0---def cmd_version(args: argparse.Namespace) -> int:- """Print version information."""- print(f"headroom {get_version()}")- return 0---def cmd_memory_eval(args: argparse.Namespace) -> int:- """Run LoCoMo memory evaluation."""- # Suppress noisy pydantic warnings from litellm- import warnings-- warnings.filterwarnings("ignore", message=".*Pydantic serializer warnings.*")- warnings.filterwarnings("ignore", category=UserWarning, module="pydantic")-- try:- from headroom.evals.memory import (- LoCoMoEvaluator,- MemoryEvalConfig,- create_anthropic_judge,- create_litellm_judge,- create_openai_judge,- simple_judge,- )- from headroom.memory import MemoryConfig- except ImportError as e:- print("Error: Memory eval dependencies not installed.")- print("Run: pip install headroom[memory,evals]")- print(f"Details: {e}")- return 1-- import asyncio-- # Build configuration- categories = None- if args.categories:- categories = [int(c) for c in args.categories.split(",")]-- memory_config = MemoryConfig()-- eval_config = MemoryEvalConfig(- n_conversations=args.n_conversations,- categories=categories,- skip_adversarial=not args.include_adversarial,- top_k_memories=args.top_k,- llm_judge_enabled=args.llm_judge,- llm_judge_model=args.judge_model,- memory_config=memory_config,- f1_threshold=args.f1_threshold,- extract_memories=not args.no_extract,- extraction_model=args.extraction_model,- pass_all_memories=args.pass_all,- parallel_workers=args.parallel,- debug=args.debug,- )-- # Create answer function based on provider- answer_fn = None- if args.answer_model:- try:- import litellm-- def answer_fn(question: str, memories: list[str]) -> str:- if not memories:- return "I don't have information about that."-- # Format memories - use all if pass_all, else top 10- context = "\n".join(f"- {m}" for m in memories)-- prompt = f"""You are answering questions about a conversation between two people based on extracted memories/facts.--## Memories from the conversation:-{context}--## Question: {question}--## Instructions:-1. Find the specific fact(s) in the memories that answer this question-2. Answer with JUST the key information requested - be concise-3. For "when" questions: give the specific date if mentioned (e.g., "7 May 2023", "2022")-4. For "what" questions: give the specific thing/action-5. For "who" questions: give the name-6. If the exact answer is in the memories, use those exact words/dates-7. If you cannot find the answer, say "Information not found"--## Answer (be concise - just the facts):"""-- response = litellm.completion(- model=args.answer_model,- messages=[{"role": "user", "content": prompt}],- temperature=0.0,- max_tokens=150,- )- return response.choices[0].message.content or ""-- except ImportError:- print("Error: litellm required for --answer-model. Run: pip install litellm")- return 1-- # Create LLM judge if enabled- llm_judge_fn: Callable[[str, str, str], tuple[float, str]] | None = None- if args.llm_judge:- # Use answer model for judge if not explicitly set- judge_model = args.judge_model- if args.answer_model and args.judge_model == "gpt-4o":- judge_model = args.answer_model # Match the answer model-- if args.judge_provider == "simple":- llm_judge_fn = simple_judge- elif args.judge_provider == "openai":- llm_judge_fn = create_openai_judge(model=judge_model)- elif args.judge_provider == "anthropic":- llm_judge_fn = create_anthropic_judge(model=judge_model)- else:- llm_judge_fn = create_litellm_judge(model=judge_model)-- # Determine judge info for display- judge_info = "DISABLED"- if args.llm_judge:- if args.judge_provider == "simple":- judge_info = "ENABLED (rule-based F1)"- else:- jm = args.judge_model- if args.answer_model and args.judge_model == "gpt-4o":- jm = args.answer_model- judge_info = f"ENABLED ({args.judge_provider}: {jm})"-- extract_info = (- f"ENABLED ({args.extraction_model})" if not args.no_extract else "DISABLED (raw dialogue)"- )- retrieval_info = "ALL memories (Path A)" if args.pass_all else f"Top-{args.top_k} retrieval"-- print(f"""-╔═══════════════════════════════════════════════════════════════════════╗-║ HEADROOM MEMORY EVALUATION ║-║ LoCoMo Benchmark ║-╚═══════════════════════════════════════════════════════════════════════╝--Configuration:- Conversations: {args.n_conversations or "all"}- Categories: {categories or "[1,2,3,4]"}- Retrieval: {retrieval_info}- Memory Extract: {extract_info}- Answer Model: {args.answer_model or "default (retrieval)"}- LLM Judge: {judge_info}- Parallelism: {args.parallel} workers- Debug: {"ENABLED" if args.debug else "DISABLED"}--Running evaluation...-""")-- # Run evaluation- evaluator = LoCoMoEvaluator(- answer_fn=answer_fn,- llm_judge_fn=llm_judge_fn,- config=eval_config,- )-- try:- result = asyncio.run(evaluator.run())- except KeyboardInterrupt:- print("\nEvaluation interrupted.")- return 1-- # Print results- print(result.summary())-- # Save results if output path specified- if args.output:- result.save(args.output)- print(f"\nResults saved to: {args.output}")-- return 0---def cmd_memory_eval_v2(args: argparse.Namespace) -> int:- """Run LoCoMo V2 memory evaluation (LLM-controlled tools)."""- # Suppress noisy pydantic warnings from litellm- import warnings-- warnings.filterwarnings("ignore", message=".*Pydantic serializer warnings.*")- warnings.filterwarnings("ignore", category=UserWarning, module="pydantic")-- try:- from headroom.evals.memory import (- LoCoMoEvaluatorV2,- MemoryEvalConfigV2,- )- except ImportError as e:- print("Error: Memory eval V2 dependencies not installed.")- print("Run: pip install headroom[memory,evals]")- print(f"Details: {e}")- return 1-- import asyncio-- # Build configuration- categories = None- if args.categories:- categories = [int(c) for c in args.categories.split(",")]-- eval_config = MemoryEvalConfigV2(- n_conversations=args.n_conversations,- categories=categories,- skip_adversarial=not args.include_adversarial,- llm_judge_enabled=args.llm_judge,- llm_judge_model=args.judge_model,- f1_threshold=args.f1_threshold,- parallel_workers=args.parallel,- debug=args.debug,- save_model=args.save_model,- answer_model=args.answer_model,- max_search_results=args.max_results,- include_graph_expansion=not args.no_graph,- )-- print(f"""-╔═══════════════════════════════════════════════════════════════════════╗-║ HEADROOM MEMORY EVALUATION V2 ║-║ LLM-Controlled Memory Architecture ║-╚═══════════════════════════════════════════════════════════════════════╝--Configuration:- Conversations: {args.n_conversations or "all"}- Categories: {categories or "[1,2,3,4]"}- Save Model: {args.save_model}- Answer Model: {args.answer_model}- Max Results: {args.max_results}- Graph Expansion: {"DISABLED" if args.no_graph else "ENABLED"}- LLM Judge: {"ENABLED" if args.llm_judge else "DISABLED"}- Parallelism: {args.parallel} workers- Debug: {"ENABLED" if args.debug else "DISABLED"}--Key Differences from V1:- - LLM decides WHAT to save (memory_save tool)- - LLM decides HOW to search (memory_search tool)- - Graph expansion enables multi-hop reasoning--Running evaluation...-""")-- # Run evaluation- evaluator = LoCoMoEvaluatorV2(- answer_model=args.answer_model,- config=eval_config,- )-- try:- result = asyncio.run(evaluator.run())- except KeyboardInterrupt:- print("\nEvaluation interrupted.")- return 1-- # Print results- print(result.summary())-- # Save results if output path specified- if args.output:- result.save(args.output)- print(f"\nResults saved to: {args.output}")-- return 0---def main(argv: list[str] | None = None) -> int:- """Main CLI entry point."""- parser = argparse.ArgumentParser(- prog="headroom",- description="The Context Optimization Layer for LLM Applications",- formatter_class=argparse.RawDescriptionHelpFormatter,- epilog="""-Examples:- headroom proxy Start proxy on port 8787- headroom proxy --port 8080 Start proxy on port 8080- headroom proxy --no-optimize Passthrough mode (no optimization)--Environment Variables:- ANTHROPIC_API_KEY Your Anthropic API key (for proxying)- OPENAI_API_KEY Your OpenAI API key (for proxying)--Documentation: https://github.com/headroom-sdk/headroom- """,- )-- parser.add_argument(- "--version",- "-V",- action="store_true",- help="Show version and exit",- )-- subparsers = parser.add_subparsers(dest="command", help="Commands")-- # Proxy command- proxy_parser = subparsers.add_parser(- "proxy",- help="Start the optimization proxy server",- formatter_class=argparse.RawDescriptionHelpFormatter,- )- proxy_parser.add_argument(- "--host",- default="127.0.0.1",- help="Host to bind to (default: 127.0.0.1)",- )- proxy_parser.add_argument(- "--port",- "-p",- type=int,- default=8787,- help="Port to bind to (default: 8787)",- )- proxy_parser.add_argument(- "--no-optimize",- action="store_true",- help="Disable optimization (passthrough mode)",- )- proxy_parser.add_argument(- "--no-cache",- action="store_true",- help="Disable semantic caching",- )- proxy_parser.add_argument(- "--no-rate-limit",- action="store_true",- help="Disable rate limiting",- )- proxy_parser.add_argument(- "--log-file",- help="Path to JSONL log file",- )- proxy_parser.add_argument(- "--budget",- type=float,- help="Daily budget limit in USD",- )- # LLMLingua ML-based compression (ON by default if installed)- proxy_parser.add_argument(- "--no-llmlingua",- action="store_true",- help="Disable LLMLingua-2 ML-based compression",- )- proxy_parser.add_argument(- "--llmlingua-device",- choices=["auto", "cuda", "cpu", "mps"],- default="auto",- help="Device for LLMLingua model (default: auto)",- )- proxy_parser.add_argument(- "--llmlingua-rate",- type=float,- default=0.3,- help="LLMLingua compression rate 0.0-1.0 (default: 0.3 = keep 30%%)",- )- # Code-aware compression (ON by default if installed)- proxy_parser.add_argument(- "--no-code-aware",- action="store_true",- help="Disable AST-based code compression",- )- # Intelligent Context Management (ON by default)- proxy_parser.add_argument(- "--no-intelligent-context",- action="store_true",- help="Disable IntelligentContextManager (fall back to RollingWindow)",- )- proxy_parser.add_argument(- "--no-intelligent-scoring",- action="store_true",- help="Disable multi-factor importance scoring (use position-based)",- )- proxy_parser.add_argument(- "--no-compress-first",- action="store_true",- help="Disable trying deeper compression before dropping messages",- )- # Memory System- proxy_parser.add_argument(- "--memory",- action="store_true",- help="Enable persistent user memory (uses x-headroom-user-id header if set, otherwise 'default')",- )- proxy_parser.add_argument(- "--memory-backend",- choices=["local", "qdrant-neo4j"],- default="local",- help="Memory storage backend: local (SQLite+HNSW) or qdrant-neo4j (default: local)",- )- proxy_parser.add_argument(- "--memory-db-path",- default="headroom_memory.db",- help="Path to memory database file for local backend (default: headroom_memory.db)",- )- proxy_parser.add_argument(- "--no-memory-tools",- action="store_true",- help="Disable automatic memory tool injection",- )- proxy_parser.add_argument(- "--no-memory-context",- action="store_true",- help="Disable automatic memory context injection",- )- proxy_parser.add_argument(- "--memory-top-k",- type=int,- default=10,- help="Number of memories to inject as context (default: 10)",- )- # Backend configuration- proxy_parser.add_argument(- "--backend",- default="anthropic",- help=(- "API backend: 'anthropic' (direct), 'bedrock' (AWS), "- "or 'litellm-<provider>' (e.g., litellm-bedrock, litellm-vertex)"- ),- )- proxy_parser.add_argument(- "--region",- default="us-west-2",- help="Cloud region for Bedrock/Vertex/etc (default: us-west-2)",- )- proxy_parser.add_argument(- "--bedrock-region",- default=None,- help="(deprecated, use --region) AWS region for Bedrock",- )- proxy_parser.add_argument(- "--bedrock-profile",- help="AWS profile name for Bedrock (default: use default credentials)",- )- proxy_parser.set_defaults(func=cmd_proxy)-- # Memory eval command- eval_parser = subparsers.add_parser(- "memory-eval",- help="Run LoCoMo memory evaluation benchmark",- formatter_class=argparse.RawDescriptionHelpFormatter,- description="""-Run the LoCoMo memory benchmark to evaluate the Headroom memory system.--LoCoMo (Long-term Conversational Memory) tests memory across:-- Single-hop questions (simple fact recall)-- Temporal questions (time-based)-- Multi-hop questions (reasoning across memories)-- Open-domain questions (interpretation required)--Example:- headroom memory-eval --n-conversations 3- headroom memory-eval --answer-model gpt-4o --llm-judge- """,- )- eval_parser.add_argument(- "--n-conversations",- "-n",- type=int,- help="Number of conversations to evaluate (default: all 10)",- )- eval_parser.add_argument(- "--categories",- help="Comma-separated list of categories 1-5 (default: 1,2,3,4)",- )- eval_parser.add_argument(- "--include-adversarial",- action="store_true",- help="Include category 5 (unanswerable questions)",- )- eval_parser.add_argument(- "--top-k",- type=int,- default=10,- help="Number of memories to retrieve per question (default: 10)",- )- eval_parser.add_argument(- "--f1-threshold",- type=float,- default=0.5,- help="F1 score threshold for 'correct' (default: 0.5)",- )- eval_parser.add_argument(- "--answer-model",- help="LLM model for generating answers (e.g., gpt-4o, claude-sonnet-4-20250514)",- )- eval_parser.add_argument(- "--llm-judge",- action="store_true",- help="Use LLM-as-judge scoring",- )- eval_parser.add_argument(- "--judge-provider",- choices=["openai", "anthropic", "litellm", "simple"],- default="litellm",- help="LLM judge provider (default: litellm - uses same model as answer-model)",- )- eval_parser.add_argument(- "--judge-model",- default="gpt-4o",- help="Model for LLM judge (default: gpt-4o)",- )- eval_parser.add_argument(- "--output",- "-o",- help="Path to save JSON results",- )- eval_parser.add_argument(- "--no-extract",- action="store_true",- help="Disable LLM memory extraction (store raw dialogue instead)",- )- eval_parser.add_argument(- "--extraction-model",- default="gpt-4o-mini",- help="Model for memory extraction (default: gpt-4o-mini)",- )- eval_parser.add_argument(- "--pass-all",- action="store_true",- help="Pass ALL memories to LLM (Path A: no retrieval bottleneck)",- )- eval_parser.add_argument(- "--parallel",- type=int,- default=10,- help="Number of parallel workers for LLM calls (default: 10)",- )- eval_parser.add_argument(- "--debug",- action="store_true",- help="Enable debug logging (saved to results JSON)",- )- eval_parser.set_defaults(func=cmd_memory_eval)-- # Memory eval V2 command (LLM-controlled tools)- eval_v2_parser = subparsers.add_parser(- "memory-eval-v2",- help="Run LoCoMo V2 evaluation with LLM-controlled memory tools",- formatter_class=argparse.RawDescriptionHelpFormatter,- description="""-Run the LoCoMo V2 memory benchmark with LLM-controlled memory architecture.--This evaluator tests the new architecture where:-- LLM decides what to save (memory_save tool)-- LLM decides when to search (memory_search tool)-- Graph relationships enable multi-hop reasoning--Example:- headroom memory-eval-v2 --n-conversations 3- headroom memory-eval-v2 --answer-model gpt-4o --save-model gpt-4o-mini- """,- )- eval_v2_parser.add_argument(- "--n-conversations",- "-n",- type=int,- help="Number of conversations to evaluate (default: all 10)",- )- eval_v2_parser.add_argument(- "--categories",- help="Comma-separated list of categories 1-5 (default: 1,2,3,4)",- )- eval_v2_parser.add_argument(- "--include-adversarial",- action="store_true",- help="Include category 5 (unanswerable questions)",- )- eval_v2_parser.add_argument(- "--f1-threshold",- type=float,- default=0.5,- help="F1 score threshold for 'correct' (default: 0.5)",- )- eval_v2_parser.add_argument(- "--save-model",- default="gpt-4o-mini",- help="LLM model for deciding what to save (default: gpt-4o-mini)",- )- eval_v2_parser.add_argument(- "--answer-model",- default="gpt-4o",- help="LLM model for answering questions (default: gpt-4o)",- )- eval_v2_parser.add_argument(- "--max-results",- type=int,- default=10,- help="Maximum memories to retrieve per search (default: 10)",- )- eval_v2_parser.add_argument(- "--no-graph",- action="store_true",- help="Disable graph expansion in search",- )- eval_v2_parser.add_argument(- "--llm-judge",- action="store_true",- help="Use LLM-as-judge scoring",- )- eval_v2_parser.add_argument(- "--judge-model",- default="gpt-4o",- help="Model for LLM judge (default: gpt-4o)",- )- eval_v2_parser.add_argument(- "--output",- "-o",- help="Path to save JSON results",- )- eval_v2_parser.add_argument(- "--parallel",- type=int,- default=5,- help="Number of parallel workers for LLM calls (default: 5)",- )- eval_v2_parser.add_argument(- "--debug",- action="store_true",- help="Enable debug logging (saved to results JSON)",- )- eval_v2_parser.set_defaults(func=cmd_memory_eval_v2)-- args = parser.parse_args(argv)-- if args.version:- return cmd_version(args)-- if args.command is None:- parser.print_help()- return 0-- result = args.func(args)- return int(result) if result is not None else 0+"""Backwards compatibility - CLI moved to headroom.cli package."""+from headroom.cli import mainif __name__ == "__main__":- sys.exit(main())+ main()diff --git a/headroom/cli/__init__.py b/headroom/cli/__init__.pynew file mode 100644index 000000000..cc774f527--- /dev/null+++ b/headroom/cli/__init__.py@@ -0,0 +1,5 @@+"""Headroom CLI - Command-line interface for memory and proxy management."""++from .main import main++__all__ = ["main"]diff --git a/headroom/cli/__main__.py b/headroom/cli/__main__.pynew file mode 100644index 000000000..deda627d3--- /dev/null+++ b/headroom/cli/__main__.py@@ -0,0 +1,6 @@+"""Allow running CLI with python -m headroom.cli."""++from .main import main++if __name__ == "__main__":+ main()diff --git a/headroom/cli/_utils/__init__.py b/headroom/cli/_utils/__init__.pynew file mode 100644index 000000000..92b675116--- /dev/null+++ b/headroom/cli/_utils/__init__.py@@ -0,0 +1,27 @@+"""CLI utilities for formatting and parsing."""++from .formatting import (+ console,+ format_age,+ format_bytes,+ print_error,+ print_stats,+ print_success,+ print_table,+ print_warning,+ truncate,+)+from .parsers import parse_duration++__all__ = [+ "console",+ "print_table",+ "print_stats",+ "print_error",+ "print_success",+ "print_warning",+ "truncate",+ "format_age",+ "format_bytes",+ "parse_duration",+]diff --git a/headroom/cli/_utils/formatting.py b/headroom/cli/_utils/formatting.pynew file mode 100644index 000000000..6e30d22f5--- /dev/null+++ b/headroom/cli/_utils/formatting.py@@ -0,0 +1,142 @@+"""Formatting utilities for CLI output using Rich."""++from datetime import datetime+from typing import Any++from rich.console import Console+from rich.panel import Panel+from rich.table import Table++# Shared console instance for consistent output+console = Console()+++def print_table(+ headers: list[str],+ rows: list[list[str]],+ title: str | None = None,+) -> None:+ """Print a Rich table with headers and rows.++ Args:+ headers: Column headers for the table.+ rows: List of rows, where each row is a list of cell values.+ title: Optional title to display above the table.+ """+ table = Table(title=title)++ for header in headers:+ table.add_column(header)++ for row in rows:+ table.add_row(*row)++ console.print(table)+++def print_stats(stats: dict[str, Any], title: str = "Statistics") -> None:+ """Print statistics in a nicely formatted panel.++ Args:+ stats: Dictionary of stat names to values.+ title: Title for the panel.+ """+ lines = [f"[bold]{key}:[/bold] {value}" for key, value in stats.items()]+ content = "\n".join(lines)+ console.print(Panel(content, title=title))+++def print_error(msg: str) -> None:+ """Print an error message in red.++ Args:+ msg: The error message to display.+ """+ console.print(f"[bold red]Error:[/bold red] {msg}")+++def print_success(msg: str) -> None:+ """Print a success message in green.++ Args:+ msg: The success message to display.+ """+ console.print(f"[bold green]Success:[/bold green] {msg}")+++def print_warning(msg: str) -> None:+ """Print a warning message in yellow.++ Args:+ msg: The warning message to display.+ """+ console.print(f"[bold yellow]Warning:[/bold yellow] {msg}")+++def truncate(text: str, max_len: int = 50) -> str:+ """Truncate text to a maximum length with ellipsis.++ Args:+ text: The text to truncate.+ max_len: Maximum length including ellipsis.++ Returns:+ Truncated text with ellipsis if it exceeded max_len.+ """+ if len(text) <= max_len:+ return text+ return text[: max_len - 3] + "..."+++def format_age(dt: datetime) -> str:+ """Format a datetime as a human-readable age string.++ Args:+ dt: The datetime to format.++ Returns:+ A string like "2d", "5h", "30m" representing time elapsed.+ """+ now = datetime.now(tz=dt.tzinfo)+ delta = now - dt++ total_seconds = int(delta.total_seconds())++ if total_seconds < 0:+ return "now"++ minutes = total_seconds // 60+ hours = total_seconds // 3600+ days = total_seconds // 86400++ if days > 0:+ return f"{days}d"+ if hours > 0:+ return f"{hours}h"+ if minutes > 0:+ return f"{minutes}m"+ return "now"+++def format_bytes(num_bytes: int) -> str:+ """Format a byte count as a human-readable string.++ Args:+ num_bytes: Number of bytes to format.++ Returns:+ A string like "1.2 MB", "500 KB", "256 B".+ """+ if num_bytes < 0:+ return "0 B"++ units = [("GB", 1024**3), ("MB", 1024**2), ("KB", 1024), ("B", 1)]++ for unit, threshold in units:+ if num_bytes >= threshold:+ value = num_bytes / threshold+ if value >= 10:+ return f"{value:.0f} {unit}"+ return f"{value:.1f} {unit}"++ return "0 B"diff --git a/headroom/cli/_utils/parsers.py b/headroom/cli/_utils/parsers.pynew file mode 100644index 000000000..cf82054e1--- /dev/null+++ b/headroom/cli/_utils/parsers.py@@ -0,0 +1,49 @@+"""Parsing utilities for CLI input."""++import re+from datetime import timedelta++import click+++def parse_duration(duration_str: str) -> timedelta:+ """Parse a duration string into a timedelta.++ Supported formats:+ - "7d" - 7 days+ - "2w" - 2 weeks+ - "1m" - 1 month (30 days)+ - "3h" - 3 hours++ Args:+ duration_str: Duration string to parse.++ Returns:+ A timedelta representing the duration.++ Raises:+ click.BadParameter: If the format is invalid.+ """+ pattern = r"^(\d+)([dwmh])$"+ match = re.match(pattern, duration_str.strip().lower())++ if not match:+ raise click.BadParameter(+ f"Invalid duration format: '{duration_str}'. "+ "Use format like '7d' (days), '2w' (weeks), '1m' (months), '3h' (hours)."+ )++ value = int(match.group(1))+ unit = match.group(2)++ if value <= 0:+ raise click.BadParameter("Duration value must be positive.")++ unit_to_timedelta = {+ "h": timedelta(hours=value),+ "d": timedelta(days=value),+ "w": timedelta(weeks=value),+ "m": timedelta(days=value * 30), # Approximate month as 30 days+ }++ return unit_to_timedelta[unit]diff --git a/headroom/cli/evals.py b/headroom/cli/evals.pynew file mode 100644index 000000000..97001e414--- /dev/null+++ b/headroom/cli/evals.py@@ -0,0 +1,663 @@+"""Evaluation CLI commands."""++from __future__ import annotations++from collections.abc import Callable++import click++from .main import main+++def evals() -> None:+ """Memory evaluation commands.++ \b+ Examples:+ headroom evals memory Run LoCoMo memory evaluation+ headroom evals memory-v2 Run V2 evaluation with LLM-controlled tools+ """+ pass++[email protected]("memory")+ "--n-conversations",+ "-n",+ type=int,+ help="Number of conversations to evaluate (default: all 10)",+)+ "--categories",+ help="Comma-separated list of categories 1-5 (default: 1,2,3,4)",+)+ "--include-adversarial",+ is_flag=True,+ help="Include category 5 (unanswerable questions)",+)+ "--top-k",+ type=int,+ default=10,+ help="Number of memories to retrieve per question (default: 10)",+)+ "--f1-threshold",+ type=float,+ default=0.5,+ help="F1 score threshold for 'correct' (default: 0.5)",+)+ "--answer-model",+ help="LLM model for generating answers (e.g., gpt-4o, claude-sonnet-4-20250514)",+)+ "--llm-judge",+ is_flag=True,+ help="Use LLM-as-judge scoring",+)+ "--judge-provider",+ type=click.Choice(["openai", "anthropic", "litellm", "simple"]),+ default="litellm",+ help="LLM judge provider (default: litellm - uses same model as answer-model)",+)+ "--judge-model",+ default="gpt-4o",+ help="Model for LLM judge (default: gpt-4o)",+)+ "--output",+ "-o",+ help="Path to save JSON results",+)+ "--no-extract",+ is_flag=True,+ help="Disable LLM memory extraction (store raw dialogue instead)",+)+ "--extraction-model",+ default="gpt-4o-mini",+ help="Model for memory extraction (default: gpt-4o-mini)",+)+ "--pass-all",+ is_flag=True,+ help="Pass ALL memories to LLM (Path A: no retrieval bottleneck)",+)+ "--parallel",+ type=int,+ default=10,+ help="Number of parallel workers for LLM calls (default: 10)",+)+ "--debug",+ is_flag=True,+ help="Enable debug logging (saved to results JSON)",+)+def memory_eval(+ n_conversations: int | None,+ categories: str | None,+ include_adversarial: bool,+ top_k: int,+ f1_threshold: float,+ answer_model: str | None,+ llm_judge: bool,+ judge_provider: str,+ judge_model: str,+ output: str | None,+ no_extract: bool,+ extraction_model: str,+ pass_all: bool,+ parallel: int,+ debug: bool,+) -> None:+ """Run LoCoMo memory evaluation benchmark.++ \b+ LoCoMo (Long-term Conversational Memory) tests memory across:+ - Single-hop questions (simple fact recall)+ - Temporal questions (time-based)+ - Multi-hop questions (reasoning across memories)+ - Open-domain questions (interpretation required)++ \b+ Examples:+ headroom evals memory -n 3+ headroom evals memory --answer-model gpt-4o --llm-judge+ """+ _run_memory_eval(+ n_conversations=n_conversations,+ categories=categories,+ include_adversarial=include_adversarial,+ top_k=top_k,+ f1_threshold=f1_threshold,+ answer_model=answer_model,+ llm_judge=llm_judge,+ judge_provider=judge_provider,+ judge_model=judge_model,+ output=output,+ no_extract=no_extract,+ extraction_model=extraction_model,+ pass_all=pass_all,+ parallel=parallel,+ debug=debug,+ )++[email protected]("memory-v2")+ "--n-conversations",+ "-n",+ type=int,+ help="Number of conversations to evaluate (default: all 10)",+)+ "--categories",+ help="Comma-separated list of categories 1-5 (default: 1,2,3,4)",+)+ "--include-adversarial",+ is_flag=True,+ help="Include category 5 (unanswerable questions)",+)+ "--f1-threshold",+ type=float,+ default=0.5,+ help="F1 score threshold for 'correct' (default: 0.5)",+)+ "--save-model",+ default="gpt-4o-mini",+ help="LLM model for deciding what to save (default: gpt-4o-mini)",+)+ "--answer-model",+ default="gpt-4o",+ help="LLM model for answering questions (default: gpt-4o)",+)+ "--max-results",+ type=int,+ default=10,+ help="Maximum memories to retrieve per search (default: 10)",+)+ "--no-graph",+ is_flag=True,+ help="Disable graph expansion in search",+)+ "--llm-judge",+ is_flag=True,+ help="Use LLM-as-judge scoring",+)+ "--judge-model",+ default="gpt-4o",+ help="Model for LLM judge (default: gpt-4o)",+)+ "--output",+ "-o",+ help="Path to save JSON results",+)+ "--parallel",+ type=int,+ default=5,+ help="Number of parallel workers for LLM calls (default: 5)",+)+ "--debug",+ is_flag=True,+ help="Enable debug logging (saved to results JSON)",+)+def memory_eval_v2(+ n_conversations: int | None,+ categories: str | None,+ include_adversarial: bool,+ f1_threshold: float,+ save_model: str,+ answer_model: str,+ max_results: int,+ no_graph: bool,+ llm_judge: bool,+ judge_model: str,+ output: str | None,+ parallel: int,+ debug: bool,+) -> None:+ """Run LoCoMo V2 evaluation with LLM-controlled memory tools.++ \b+ This evaluator tests the new architecture where:+ - LLM decides what to save (memory_save tool)+ - LLM decides when to search (memory_search tool)+ - Graph relationships enable multi-hop reasoning++ \b+ Examples:+ headroom evals memory-v2 -n 3+ headroom evals memory-v2 --answer-model gpt-4o --save-model gpt-4o-mini+ """+ _run_memory_eval_v2(+ n_conversations=n_conversations,+ categories=categories,+ include_adversarial=include_adversarial,+ f1_threshold=f1_threshold,+ save_model=save_model,+ answer_model=answer_model,+ max_results=max_results,+ no_graph=no_graph,+ llm_judge=llm_judge,+ judge_model=judge_model,+ output=output,+ parallel=parallel,+ debug=debug,+ )+++# -----------------------------------------------------------------------------+# Backwards compatibility: old command names (hidden)+# -----------------------------------------------------------------------------++[email protected]("memory-eval", hidden=True)[email protected]("--n-conversations", "-n", type=int)[email protected]("--categories")[email protected]("--include-adversarial", is_flag=True)[email protected]("--top-k", type=int, default=10)[email protected]("--f1-threshold", type=float, default=0.5)[email protected]("--answer-model")[email protected]("--llm-judge", is_flag=True)+ "--judge-provider",+ type=click.Choice(["openai", "anthropic", "litellm", "simple"]),+ default="litellm",+)[email protected]("--judge-model", default="gpt-4o")[email protected]("--output", "-o")[email protected]("--no-extract", is_flag=True)[email protected]("--extraction-model", default="gpt-4o-mini")[email protected]("--pass-all", is_flag=True)[email protected]("--parallel", type=int, default=10)[email protected]("--debug", is_flag=True)+def memory_eval_compat(+ n_conversations: int | None,+ categories: str | None,+ include_adversarial: bool,+ top_k: int,+ f1_threshold: float,+ answer_model: str | None,+ llm_judge: bool,+ judge_provider: str,+ judge_model: str,+ output: str | None,+ no_extract: bool,+ extraction_model: str,+ pass_all: bool,+ parallel: int,+ debug: bool,+) -> None:+ """Deprecated: Use 'headroom evals memory' instead."""+ click.echo("Note: 'memory-eval' is deprecated. Use 'headroom evals memory'", err=True)+ _run_memory_eval(+ n_conversations=n_conversations,+ categories=categories,+ include_adversarial=include_adversarial,+ top_k=top_k,+ f1_threshold=f1_threshold,+ answer_model=answer_model,+ llm_judge=llm_judge,+ judge_provider=judge_provider,+ judge_model=judge_model,+ output=output,+ no_extract=no_extract,+ extraction_model=extraction_model,+ pass_all=pass_all,+ parallel=parallel,+ debug=debug,+ )++[email protected]("memory-eval-v2", hidden=True)[email protected]("--n-conversations", "-n", type=int)[email protected]("--categories")[email protected]("--include-adversarial", is_flag=True)[email protected]("--f1-threshold", type=float, default=0.5)[email protected]("--save-model", default="gpt-4o-mini")[email protected]("--answer-model", default="gpt-4o")[email protected]("--max-results", type=int, default=10)[email protected]("--no-graph", is_flag=True)[email protected]("--llm-judge", is_flag=True)[email protected]("--judge-model", default="gpt-4o")[email protected]("--output", "-o")[email protected]("--parallel", type=int, default=5)[email protected]("--debug", is_flag=True)+def memory_eval_v2_compat(+ n_conversations: int | None,+ categories: str | None,+ include_adversarial: bool,+ f1_threshold: float,+ save_model: str,+ answer_model: str,+ max_results: int,+ no_graph: bool,+ llm_judge: bool,+ judge_model: str,+ output: str | None,+ parallel: int,+ debug: bool,+) -> None:+ """Deprecated: Use 'headroom evals memory-v2' instead."""+ click.echo("Note: 'memory-eval-v2' is deprecated. Use 'headroom evals memory-v2'", err=True)+ _run_memory_eval_v2(+ n_conversations=n_conversations,+ categories=categories,+ include_adversarial=include_adversarial,+ f1_threshold=f1_threshold,+ save_model=save_model,+ answer_model=answer_model,+ max_results=max_results,+ no_graph=no_graph,+ llm_judge=llm_judge,+ judge_model=judge_model,+ output=output,+ parallel=parallel,+ debug=debug,+ )+++# -----------------------------------------------------------------------------+# Implementation functions (shared by new and compat commands)+# -----------------------------------------------------------------------------+++def _run_memory_eval(+ *,+ n_conversations: int | None,+ categories: str | None,+ include_adversarial: bool,+ top_k: int,+ f1_threshold: float,+ answer_model: str | None,+ llm_judge: bool,+ judge_provider: str,+ judge_model: str,+ output: str | None,+ no_extract: bool,+ extraction_model: str,+ pass_all: bool,+ parallel: int,+ debug: bool,+) -> None:+ """Run LoCoMo memory evaluation."""+ # Suppress noisy pydantic warnings from litellm+ import warnings++ warnings.filterwarnings("ignore", message=".*Pydantic serializer warnings.*")+ warnings.filterwarnings("ignore", category=UserWarning, module="pydantic")++ try:+ from headroom.evals.memory import (+ LoCoMoEvaluator,+ MemoryEvalConfig,+ create_anthropic_judge,+ create_litellm_judge,+ create_openai_judge,+ simple_judge,+ )+ from headroom.memory import MemoryConfig+ except ImportError as e:+ click.echo("Error: Memory eval dependencies not installed.")+ click.echo("Run: pip install headroom[memory,evals]")+ click.echo(f"Details: {e}")+ raise SystemExit(1) from None++ import asyncio++ # Build configuration+ parsed_categories = None+ if categories:+ parsed_categories = [int(c) for c in categories.split(",")]++ memory_config = MemoryConfig()++ eval_config = MemoryEvalConfig(+ n_conversations=n_conversations,+ categories=parsed_categories,+ skip_adversarial=not include_adversarial,+ top_k_memories=top_k,+ llm_judge_enabled=llm_judge,+ llm_judge_model=judge_model,+ memory_config=memory_config,+ f1_threshold=f1_threshold,+ extract_memories=not no_extract,+ extraction_model=extraction_model,+ pass_all_memories=pass_all,+ parallel_workers=parallel,+ debug=debug,+ )++ # Create answer function based on provider+ answer_fn = None+ if answer_model:+ try:+ import litellm++ def answer_fn(question: str, memories: list[str]) -> str:+ if not memories:+ return "I don't have information about that."++ # Format memories - use all if pass_all, else top 10+ context = "\n".join(f"- {m}" for m in memories)++ prompt = f"""You are answering questions about a conversation between two people based on extracted memories/facts.++## Memories from the conversation:+{context}++## Question: {question}++## Instructions:+1. Find the specific fact(s) in the memories that answer this question+2. Answer with JUST the key information requested - be concise+3. For "when" questions: give the specific date if mentioned (e.g., "7 May 2023", "2022")+4. For "what" questions: give the specific thing/action+5. For "who" questions: give the name+6. If the exact answer is in the memories, use those exact words/dates+7. If you cannot find the answer, say "Information not found"++## Answer (be concise - just the facts):"""++ response = litellm.completion(+ model=answer_model,+ messages=[{"role": "user", "content": prompt}],+ temperature=0.0,+ max_tokens=150,+ )+ return response.choices[0].message.content or ""++ except ImportError:+ click.echo("Error: litellm required for --answer-model. Run: pip install litellm")+ raise SystemExit(1) from None++ # Create LLM judge if enabled+ llm_judge_fn: Callable[[str, str, str], tuple[float, str]] | None = None+ if llm_judge:+ # Use answer model for judge if not explicitly set+ effective_judge_model = judge_model+ if answer_model and judge_model == "gpt-4o":+ effective_judge_model = answer_model # Match the answer model++ if judge_provider == "simple":+ llm_judge_fn = simple_judge+ elif judge_provider == "openai":+ llm_judge_fn = create_openai_judge(model=effective_judge_model)+ elif judge_provider == "anthropic":+ llm_judge_fn = create_anthropic_judge(model=effective_judge_model)+ else:+ llm_judge_fn = create_litellm_judge(model=effective_judge_model)++ # Determine judge info for display+ judge_info = "DISABLED"+ if llm_judge:+ if judge_provider == "simple":+ judge_info = "ENABLED (rule-based F1)"+ else:+ jm = judge_model+ if answer_model and judge_model == "gpt-4o":+ jm = answer_model+ judge_info = f"ENABLED ({judge_provider}: {jm})"++ extract_info = f"ENABLED ({extraction_model})" if not no_extract else "DISABLED (raw dialogue)"+ retrieval_info = "ALL memories (Path A)" if pass_all else f"Top-{top_k} retrieval"++ click.echo(f"""+╔═══════════════════════════════════════════════════════════════════════╗+║ HEADROOM MEMORY EVALUATION ║+║ LoCoMo Benchmark ║+╚═══════════════════════════════════════════════════════════════════════╝++Configuration:+ Conversations: {n_conversations or "all"}+ Categories: {parsed_categories or "[1,2,3,4]"}+ Retrieval: {retrieval_info}+ Memory Extract: {extract_info}+ Answer Model: {answer_model or "default (retrieval)"}+ LLM Judge: {judge_info}+ Parallelism: {parallel} workers+ Debug: {"ENABLED" if debug else "DISABLED"}++Running evaluation...+""")++ # Run evaluation+ evaluator = LoCoMoEvaluator(+ answer_fn=answer_fn,+ llm_judge_fn=llm_judge_fn,+ config=eval_config,+ )++ try:+ result = asyncio.run(evaluator.run())+ except KeyboardInterrupt:+ click.echo("\nEvaluation interrupted.")+ raise SystemExit(1) from None++ # Print results+ click.echo(result.summary())++ # Save results if output path specified+ if output:+ result.save(output)+ click.echo(f"\nResults saved to: {output}")+++def _run_memory_eval_v2(+ *,+ n_conversations: int | None,+ categories: str | None,+ include_adversarial: bool,+ f1_threshold: float,+ save_model: str,+ answer_model: str,+ max_results: int,+ no_graph: bool,+ llm_judge: bool,+ judge_model: str,+ output: str | None,+ parallel: int,+ debug: bool,+) -> None:+ """Run LoCoMo V2 memory evaluation (LLM-controlled tools)."""+ # Suppress noisy pydantic warnings from litellm+ import warnings++ warnings.filterwarnings("ignore", message=".*Pydantic serializer warnings.*")+ warnings.filterwarnings("ignore", category=UserWarning, module="pydantic")++ try:+ from headroom.evals.memory import (+ LoCoMoEvaluatorV2,+ MemoryEvalConfigV2,+ )+ except ImportError as e:+ click.echo("Error: Memory eval V2 dependencies not installed.")+ click.echo("Run: pip install headroom[memory,evals]")+ click.echo(f"Details: {e}")+ raise SystemExit(1) from None++ import asyncio++ # Build configuration+ parsed_categories = None+ if categories:+ parsed_categories = [int(c) for c in categories.split(",")]++ eval_config = MemoryEvalConfigV2(+ n_conversations=n_conversations,+ categories=parsed_categories,+ skip_adversarial=not include_adversarial,+ llm_judge_enabled=llm_judge,+ llm_judge_model=judge_model,+ f1_threshold=f1_threshold,+ parallel_workers=parallel,+ debug=debug,+ save_model=save_model,+ answer_model=answer_model,+ max_search_results=max_results,+ include_graph_expansion=not no_graph,+ )++ click.echo(f"""+╔═══════════════════════════════════════════════════════════════════════╗+║ HEADROOM MEMORY EVALUATION V2 ║+║ LLM-Controlled Memory Architecture ║+╚═══════════════════════════════════════════════════════════════════════╝++Configuration:+ Conversations: {n_conversations or "all"}+ Categories: {parsed_categories or "[1,2,3,4]"}+ Save Model: {save_model}+ Answer Model: {answer_model}+ Max Results: {max_results}+ Graph Expansion: {"DISABLED" if no_graph else "ENABLED"}+ LLM Judge: {"ENABLED" if llm_judge else "DISABLED"}+ Parallelism: {parallel} workers+ Debug: {"ENABLED" if debug else "DISABLED"}++Key Differences from V1:+ - LLM decides WHAT to save (memory_save tool)+ - LLM decides HOW to search (memory_search tool)+ - Graph expansion enables multi-hop reasoning++Running evaluation...+""")++ # Run evaluation+ evaluator = LoCoMoEvaluatorV2(+ answer_model=answer_model,+ config=eval_config,+ )++ try:+ result = asyncio.run(evaluator.run())+ except KeyboardInterrupt:+ click.echo("\nEvaluation interrupted.")+ raise SystemExit(1) from None++ # Print results+ click.echo(result.summary())++ # Save results if output path specified+ if output:+ result.save(output)+ click.echo(f"\nResults saved to: {output}")diff --git a/headroom/cli/main.py b/headroom/cli/main.pynew file mode 100644index 000000000..4dc16e131--- /dev/null+++ b/headroom/cli/main.py@@ -0,0 +1,46 @@+"""Main CLI entry point for Headroom."""++import click+++def get_version() -> str:+ """Get the current version."""+ try:+ from headroom import __version__++ return __version__+ except ImportError:+ return "unknown"++[email protected]_option(version=get_version(), prog_name="headroom")[email protected]_context+def main(ctx: click.Context) -> None:+ """Headroom - The Context Optimization Layer for LLM Applications.++ Manage memories, run the optimization proxy, and analyze metrics.++ \b+ Examples:+ headroom proxy Start the optimization proxy+ headroom memory list List stored memories+ headroom memory stats Show memory statistics+ """+ ctx.ensure_object(dict)+++# Import subcommands - these register themselves with the main group+def _register_commands() -> None:+ """Register all subcommand groups."""+ from . import (+ evals, # noqa: F401+ memory, # noqa: F401+ proxy, # noqa: F401+ )+++_register_commands()++if __name__ == "__main__":+ main()diff --git a/headroom/cli/memory.py b/headroom/cli/memory.pynew file mode 100644index 000000000..e176d61ae--- /dev/null+++ b/headroom/cli/memory.py@@ -0,0 +1,895 @@+"""Memory management CLI commands."""++from __future__ import annotations++import asyncio+import json+import os+import sys+from datetime import datetime, timedelta+from pathlib import Path+from typing import Any++import click++from ..memory.adapters.sqlite import SQLiteMemoryStore+from ..memory.models import Memory, ScopeLevel+from ..memory.ports import MemoryFilter+from ._utils.formatting import (+ console,+ format_age,+ format_bytes,+ print_error,+ print_stats,+ print_success,+ print_table,+ print_warning,+ truncate,+)+from ._utils.parsers import parse_duration+from .main import main+++def db_path_option(fn: Any) -> Any:+ """Shared --db-path option for memory commands."""+ return click.option(+ "--db-path",+ type=click.Path(),+ default="headroom_memory.db",+ help="Path to the memory database file.",+ show_default=True,+ )(fn)+++def get_store(db_path: str) -> SQLiteMemoryStore:+ """Get a SQLiteMemoryStore instance."""+ return SQLiteMemoryStore(db_path)+++def get_scope_label(memory: Memory) -> str:+ """Get a human-readable scope label for a memory."""+ if memory.turn_id is not None:+ return "TURN"+ if memory.agent_id is not None:+ return "AGENT"+ if memory.session_id is not None:+ return "SESSION"+ return "USER"+++def _get_stats(store: SQLiteMemoryStore) -> dict[str, Any]:+ """Get statistics about the memory store.++ This is a helper function that directly queries the database+ to get stats, since SQLiteMemoryStore doesn't have a get_stats method.+ """+ stats: dict[str, Any] = {}++ with store._get_conn() as conn:+ # Total count+ cursor = conn.execute("SELECT COUNT(*) FROM memories")+ stats["total_count"] = cursor.fetchone()[0]++ # Database file size+ try:+ stats["db_size_bytes"] = os.path.getsize(store.db_path)+ except OSError:+ stats["db_size_bytes"] = 0++ # Count by scope level+ by_scope: dict[str, int] = {}++ cursor = conn.execute(+ "SELECT COUNT(*) FROM memories "+ "WHERE session_id IS NULL AND agent_id IS NULL AND turn_id IS NULL"+ )+ by_scope["USER"] = cursor.fetchone()[0]++ cursor = conn.execute(+ "SELECT COUNT(*) FROM memories "+ "WHERE session_id IS NOT NULL AND agent_id IS NULL AND turn_id IS NULL"+ )+ by_scope["SESSION"] = cursor.fetchone()[0]++ cursor = conn.execute(+ "SELECT COUNT(*) FROM memories WHERE agent_id IS NOT NULL AND turn_id IS NULL"+ )+ by_scope["AGENT"] = cursor.fetchone()[0]++ cursor = conn.execute("SELECT COUNT(*) FROM memories WHERE turn_id IS NOT NULL")+ by_scope["TURN"] = cursor.fetchone()[0]++ stats["by_scope"] = by_scope++ # Count by age buckets+ now = datetime.utcnow()+ by_age: dict[str, int] = {}++ one_day_ago = (now - timedelta(days=1)).isoformat()+ seven_days_ago = (now - timedelta(days=7)).isoformat()+ thirty_days_ago = (now - timedelta(days=30)).isoformat()++ cursor = conn.execute("SELECT COUNT(*) FROM memories WHERE created_at > ?", (one_day_ago,))+ by_age["< 1 day"] = cursor.fetchone()[0]++ cursor = conn.execute(+ "SELECT COUNT(*) FROM memories WHERE created_at <= ? AND created_at > ?",+ (one_day_ago, seven_days_ago),+ )+ by_age["1-7 days"] = cursor.fetchone()[0]++ cursor = conn.execute(+ "SELECT COUNT(*) FROM memories WHERE created_at <= ? AND created_at > ?",+ (seven_days_ago, thirty_days_ago),+ )+ by_age["7-30 days"] = cursor.fetchone()[0]++ cursor = conn.execute(+ "SELECT COUNT(*) FROM memories WHERE created_at <= ?", (thirty_days_ago,)+ )+ by_age["> 30 days"] = cursor.fetchone()[0]++ stats["by_age"] = by_age++ # Oldest memory age+ cursor = conn.execute("SELECT MIN(created_at) FROM memories")+ oldest = cursor.fetchone()[0]+ if oldest:+ oldest_dt = datetime.fromisoformat(oldest)+ delta = now - oldest_dt+ stats["oldest_memory_age_days"] = delta.total_seconds() / 86400.0+ else:+ stats["oldest_memory_age_days"] = None++ # Average importance+ cursor = conn.execute("SELECT AVG(importance) FROM memories")+ avg_imp = cursor.fetchone()[0]+ stats["avg_importance"] = float(avg_imp) if avg_imp is not None else 0.0++ return stats+++def _search_content(store: SQLiteMemoryStore, query: str, limit: int = 50) -> list[Memory]:+ """Search memories by content using LIKE.++ This is a helper function that directly queries the database.+ """+ escaped_query = query.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")+ search_pattern = f"%{escaped_query}%"++ with store._get_conn() as conn:+ cursor = conn.execute(+ """+ SELECT * FROM memories+ WHERE content LIKE ? ESCAPE '\\'+ ORDER BY created_at DESC+ LIMIT ?+ """,+ (search_pattern, limit),+ )+ return [store._row_to_memory(row) for row in cursor]+++def _export_all(store: SQLiteMemoryStore) -> list[dict[str, Any]]:+ """Export all memories as a list of dictionaries."""+ with store._get_conn() as conn:+ cursor = conn.execute("SELECT * FROM memories ORDER BY created_at ASC")+ memories = [store._row_to_memory(row) for row in cursor]++ return [m.to_dict() for m in memories]+++def _import_memories(store: SQLiteMemoryStore, memories: list[dict[str, Any]]) -> int:+ """Import memories from a list of dictionaries."""+ if not memories:+ return 0++ imported_count = 0+ with store._get_conn() as conn:+ for mem_dict in memories:+ try:+ memory = Memory.from_dict(mem_dict)+ row = store._memory_to_row(memory)+ conn.execute(+ """+ INSERT OR REPLACE INTO memories (+ id, content, user_id, session_id, agent_id, turn_id,+ created_at, valid_from, valid_until,+ category, importance,+ supersedes, superseded_by, promoted_from, promotion_chain,+ access_count, last_accessed,+ entity_refs, embedding, metadata+ ) VALUES (+ :id, :content, :user_id, :session_id, :agent_id, :turn_id,+ :created_at, :valid_from, :valid_until,+ :category, :importance,+ :supersedes, :superseded_by, :promoted_from, :promotion_chain,+ :access_count, :last_accessed,+ :entity_refs, :embedding, :metadata+ )+ """,+ row,+ )+ imported_count += 1+ except (KeyError, ValueError, TypeError):+ # Skip malformed entries+ continue++ conn.commit()++ return imported_count++[email protected]_context+def memory(ctx: click.Context) -> None:+ """Manage memories stored in Headroom.++ \b+ Examples:+ headroom memory list List all stored memories+ headroom memory list --limit 10 List the 10 most recent memories+ headroom memory list --scope USER List only USER-level memories+ headroom memory list --since 7d List memories from the last 7 days+ headroom memory show <id> Show full details of a memory+ headroom memory stats Show memory statistics+ headroom memory edit <id> --content ... Edit a memory's content+ headroom memory delete <id> Delete a memory+ headroom memory prune --older-than 30d Delete memories older than 30 days+ headroom memory purge --confirm Delete ALL memories+ headroom memory export --output file.json Export all memories to JSON+ headroom memory import file.json Import memories from JSON+ """+ pass++[email protected]("list")+@db_path_option[email protected]("--limit", "-n", type=int, default=50, help="Maximum number of memories to show.")[email protected]("--session", "-s", "session_id", type=str, help="Filter by session ID.")+ "--scope",+ type=click.Choice(["USER", "SESSION", "AGENT", "TURN"], case_sensitive=False),+ help="Filter by scope level.",+)+ "--since",+ "since_duration",+ type=str,+ help="Show memories created within duration (e.g., 7d, 2w, 1m).",+)[email protected]("--search", "-q", "search_query", type=str, help="Search memories by content.")[email protected]_context+def list_memories(+ ctx: click.Context,+ db_path: str,+ limit: int,+ session_id: str | None,+ scope: str | None,+ since_duration: str | None,+ search_query: str | None,+) -> None:+ """List stored memories with optional filters.++ \b+ Examples:+ headroom memory list List most recent memories+ headroom memory list --limit 10 Show only 10 memories+ headroom memory list --scope USER Show only USER-level memories+ headroom memory list --since 7d Show memories from the last 7 days+ headroom memory list --search "api" Search for memories containing "api"+ """+ store = get_store(db_path)++ try:+ if search_query:+ # Use text search+ memories = _search_content(store, search_query, limit=limit)+ else:+ # Build filter+ filter_kwargs: dict[str, Any] = {+ "limit": limit,+ "order_by": "created_at",+ "order_desc": True,+ }++ if session_id:+ filter_kwargs["session_id"] = session_id++ if scope:+ scope_level = ScopeLevel[scope.upper()]+ filter_kwargs["scope_levels"] = [scope_level]++ if since_duration:+ duration = parse_duration(since_duration)+ cutoff = datetime.utcnow() - duration+ filter_kwargs["created_after"] = cutoff++ mem_filter = MemoryFilter(**filter_kwargs)+ memories = asyncio.run(store.query(mem_filter))++ if not memories:+ click.echo("No memories found.")+ return++ # Build table+ headers = ["ID", "SCOPE", "AGE", "IMPORTANCE", "CONTENT"]+ rows: list[list[str]] = []++ for mem in memories:+ rows.append(+ [+ mem.id[:8],+ get_scope_label(mem),+ format_age(mem.created_at),+ f"{mem.importance:.2f}",+ truncate(mem.content.replace("\n", " "), 50),+ ]+ )++ title = f"Memories ({len(memories)} shown)"+ if search_query:+ title = f"Search results for '{search_query}' ({len(memories)} found)"++ print_table(headers, rows, title=title)++ except click.BadParameter as e:+ print_error(str(e))+ sys.exit(1)+ except Exception as e:+ print_error(f"Failed to list memories: {e}")+ sys.exit(1)++[email protected]("show")+@db_path_option[email protected]("memory_id", type=str)[email protected]("--json", "output_json", is_flag=True, help="Output as raw JSON.")[email protected]_context+def show_memory(+ ctx: click.Context,+ db_path: str,+ memory_id: str,+ output_json: bool,+) -> None:+ """Show full details of a single memory.++ \b+ Examples:+ headroom memory show abc123 Show memory details+ headroom memory show abc123 --json Output as raw JSON+ """+ store = get_store(db_path)++ try:+ # Try to find the memory - support partial IDs+ mem = asyncio.run(store.get(memory_id))++ # If not found with exact ID, try partial match+ if mem is None:+ # Query all and filter by prefix+ all_memories = asyncio.run(store.query(MemoryFilter(limit=1000)))+ matches = [m for m in all_memories if m.id.startswith(memory_id)]++ if len(matches) == 0:+ print_error(f"Memory not found: {memory_id}")+ sys.exit(1)+ elif len(matches) > 1:+ print_error(f"Ambiguous ID '{memory_id}'. Matches: {[m.id[:8] for m in matches]}")+ sys.exit(1)+ else:+ mem = matches[0]++ if output_json:+ click.echo(json.dumps(mem.to_dict(), indent=2, default=str))+ return++ # Display formatted output+ console.print(f"\n[bold]Memory ID:[/bold] {mem.id}")+ console.print(f"[bold]Scope:[/bold] {get_scope_label(mem)}")+ console.print(f"[bold]User ID:[/bold] {mem.user_id}")++ if mem.session_id:+ console.print(f"[bold]Session ID:[/bold] {mem.session_id}")+ if mem.agent_id:+ console.print(f"[bold]Agent ID:[/bold] {mem.agent_id}")+ if mem.turn_id:+ console.print(f"[bold]Turn ID:[/bold] {mem.turn_id}")++ console.print(f"[bold]Created:[/bold] {mem.created_at.isoformat()}")+ console.print(f"[bold]Valid From:[/bold] {mem.valid_from.isoformat()}")+ if mem.valid_until:+ console.print(f"[bold]Valid Until:[/bold] {mem.valid_until.isoformat()}")++ console.print(f"[bold]Importance:[/bold] {mem.importance:.2f}")+ console.print(f"[bold]Access Count:[/bold] {mem.access_count}")++ if mem.last_accessed:+ console.print(f"[bold]Last Accessed:[/bold] {mem.last_accessed.isoformat()}")++ if mem.supersedes:+ console.print(f"[bold]Supersedes:[/bold] {mem.supersedes}")+ if mem.superseded_by:+ console.print(f"[bold]Superseded By:[/bold] {mem.superseded_by}")+ if mem.promoted_from:+ console.print(f"[bold]Promoted From:[/bold] {mem.promoted_from}")++ if mem.entity_refs:+ console.print(f"[bold]Entity Refs:[/bold] {', '.join(mem.entity_refs)}")++ if mem.metadata:+ console.print(f"[bold]Metadata:[/bold] {json.dumps(mem.metadata, indent=2)}")++ console.print(f"\n[bold]Content:[/bold]\n{mem.content}")++ except Exception as e:+ print_error(f"Failed to show memory: {e}")+ sys.exit(1)++[email protected]("stats")+@db_path_option[email protected]_context+def show_stats(ctx: click.Context, db_path: str) -> None:+ """Show memory store statistics.++ Displays counts by scope level, age distribution, and storage information.+ """+ store = get_store(db_path)++ try:+ stats = _get_stats(store)++ # Format stats for display+ formatted: dict[str, Any] = {}++ formatted["Total Memories"] = stats["total_count"]+ formatted["Database Size"] = format_bytes(stats["db_size_bytes"])++ # By scope+ by_scope = stats.get("by_scope", {})+ formatted["USER scope"] = by_scope.get("USER", 0)+ formatted["SESSION scope"] = by_scope.get("SESSION", 0)+ formatted["AGENT scope"] = by_scope.get("AGENT", 0)+ formatted["TURN scope"] = by_scope.get("TURN", 0)++ # By age+ by_age = stats.get("by_age", {})+ formatted["< 1 day old"] = by_age.get("< 1 day", 0)+ formatted["1-7 days old"] = by_age.get("1-7 days", 0)+ formatted["7-30 days old"] = by_age.get("7-30 days", 0)+ formatted["> 30 days old"] = by_age.get("> 30 days", 0)++ # Other stats+ oldest = stats.get("oldest_memory_age_days")+ if oldest is not None:+ formatted["Oldest Memory"] = f"{oldest:.1f} days"+ else:+ formatted["Oldest Memory"] = "N/A"++ formatted["Avg Importance"] = f"{stats.get('avg_importance', 0):.2f}"++ print_stats(formatted, title="Memory Statistics")++ # Helpful tips+ old_count = by_age.get("> 30 days", 0)+ if old_count > 0:+ console.print(+ f"\n[dim]Tip: You have {old_count} memories older than 30 days. "+ f"Consider running: headroom memory prune --older-than 30d[/dim]"+ )++ except Exception as e:+ print_error(f"Failed to get stats: {e}")+ sys.exit(1)++[email protected]("edit")+@db_path_option[email protected]("memory_id", type=str)[email protected]("--content", "-c", type=str, help="New content for the memory.")[email protected]("--importance", "-i", type=float, help="New importance score (0.0 - 1.0).")[email protected]_context+def edit_memory(+ ctx: click.Context,+ db_path: str,+ memory_id: str,+ content: str | None,+ importance: float | None,+) -> None:+ """Edit a memory's content or importance.++ \b+ Examples:+ headroom memory edit abc123 --content "Updated content"+ headroom memory edit abc123 --importance 0.8+ headroom memory edit abc123 -c "New content" -i 0.9+ """+ if content is None and importance is None:+ print_error("At least one of --content or --importance must be provided.")+ sys.exit(1)++ if importance is not None and (importance < 0.0 or importance > 1.0):+ print_error("Importance must be between 0.0 and 1.0.")+ sys.exit(1)++ store = get_store(db_path)++ try:+ # Find the memory+ mem = asyncio.run(store.get(memory_id))++ # Try partial match if not found+ if mem is None:+ all_memories = asyncio.run(store.query(MemoryFilter(limit=1000)))+ matches = [m for m in all_memories if m.id.startswith(memory_id)]++ if len(matches) == 0:+ print_error(f"Memory not found: {memory_id}")+ sys.exit(1)+ elif len(matches) > 1:+ print_error(f"Ambiguous ID '{memory_id}'. Matches: {[m.id[:8] for m in matches]}")+ sys.exit(1)+ else:+ mem = matches[0]++ # Update fields+ if content is not None:+ mem.content = content+ if importance is not None:+ mem.importance = importance++ # Save+ asyncio.run(store.save(mem))+ print_success(f"Updated memory {mem.id[:8]}")++ except Exception as e:+ print_error(f"Failed to edit memory: {e}")+ sys.exit(1)++[email protected]("delete")+@db_path_option[email protected]("memory_ids", type=str, nargs=-1, required=True)[email protected]("--force", "-f", is_flag=True, help="Skip confirmation prompt.")[email protected]_context+def delete_memories(+ ctx: click.Context,+ db_path: str,+ memory_ids: tuple[str, ...],+ force: bool,+) -> None:+ """Delete one or more memories by ID.++ \b+ Examples:+ headroom memory delete abc123 Delete one memory+ headroom memory delete abc123 def456 Delete multiple memories+ headroom memory delete abc123 --force Skip confirmation+ """+ store = get_store(db_path)++ try:+ # Resolve all IDs (support partial matching)+ resolved_ids: list[str] = []+ all_memories: list[Memory] | None = None++ for memory_id in memory_ids:+ mem = asyncio.run(store.get(memory_id))++ if mem is not None:+ resolved_ids.append(mem.id)+ else:+ # Try partial match+ if all_memories is None:+ all_memories = asyncio.run(store.query(MemoryFilter(limit=10000)))++ matches = [m for m in all_memories if m.id.startswith(memory_id)]++ if len(matches) == 0:+ print_warning(f"Memory not found: {memory_id}")+ elif len(matches) > 1:+ print_error(+ f"Ambiguous ID '{memory_id}'. Matches: {[m.id[:8] for m in matches]}"+ )+ sys.exit(1)+ else:+ resolved_ids.append(matches[0].id)++ if not resolved_ids:+ print_error("No valid memory IDs provided.")+ sys.exit(1)++ # Confirm+ if not force:+ count = len(resolved_ids)+ ids_preview = ", ".join(id[:8] for id in resolved_ids[:5])+ if count > 5:+ ids_preview += f" ... and {count - 5} more"++ click.confirm(+ f"Delete {count} memory(ies)? ({ids_preview})",+ abort=True,+ )++ # Delete+ deleted = asyncio.run(store.delete_batch(resolved_ids))+ print_success(f"Deleted {deleted} memory(ies).")++ except click.Abort:+ click.echo("Aborted.")+ sys.exit(0)+ except Exception as e:+ print_error(f"Failed to delete memories: {e}")+ sys.exit(1)++[email protected]("prune")+@db_path_option+ "--older-than",+ "older_than",+ type=str,+ help="Delete memories older than duration (e.g., 30d, 2w).",+)+ "--scope",+ type=click.Choice(["USER", "SESSION", "AGENT", "TURN"], case_sensitive=False),+ help="Delete only memories at this scope level.",+)+ "--low-importance",+ "low_importance",+ type=float,+ help="Delete memories with importance below threshold.",+)+ "--session", "-s", "session_id", type=str, help="Limit pruning to a specific session."+)[email protected]("--dry-run", is_flag=True, help="Show what would be deleted without deleting.")[email protected]("--force", "-f", is_flag=True, help="Skip confirmation prompt.")[email protected]_context+def prune_memories(+ ctx: click.Context,+ db_path: str,+ older_than: str | None,+ scope: str | None,+ low_importance: float | None,+ session_id: str | None,+ dry_run: bool,+ force: bool,+) -> None:+ """Prune memories matching specified criteria.++ Multiple filters can be combined (AND logic).++ \b+ Examples:+ headroom memory prune --older-than 30d Delete memories older than 30 days+ headroom memory prune --scope TURN Delete all TURN-level memories+ headroom memory prune --low-importance 0.3 Delete low-importance memories+ headroom memory prune --older-than 7d --scope TURN Combine filters+ headroom memory prune --older-than 30d --dry-run Preview what would be deleted+ """+ if older_than is None and scope is None and low_importance is None:+ print_error(+ "At least one filter (--older-than, --scope, --low-importance) must be specified."+ )+ sys.exit(1)++ if low_importance is not None and (low_importance < 0.0 or low_importance > 1.0):+ print_error("--low-importance must be between 0.0 and 1.0.")+ sys.exit(1)++ store = get_store(db_path)++ try:+ # Build filter to find matching memories+ filter_kwargs: dict[str, Any] = {+ "limit": 100000, # High limit for pruning+ "include_superseded": True, # Include all memories+ }++ if older_than:+ duration = parse_duration(older_than)+ cutoff = datetime.utcnow() - duration+ filter_kwargs["created_before"] = cutoff++ if scope:+ scope_level = ScopeLevel[scope.upper()]+ filter_kwargs["scope_levels"] = [scope_level]++ if low_importance is not None:+ filter_kwargs["max_importance"] = low_importance++ if session_id:+ filter_kwargs["session_id"] = session_id++ mem_filter = MemoryFilter(**filter_kwargs)+ memories = asyncio.run(store.query(mem_filter))++ if not memories:+ click.echo("No memories match the specified criteria.")+ return++ # Show preview+ count = len(memories)+ click.echo(f"\nFound {count} memory(ies) matching criteria:")++ # Show sample+ for mem in memories[:5]:+ click.echo(f" - {mem.id[:8]}: {truncate(mem.content.replace(chr(10), ' '), 40)}")+ if count > 5:+ click.echo(f" ... and {count - 5} more")++ if dry_run:+ print_warning(f"DRY RUN: Would delete {count} memory(ies).")+ return++ # Confirm+ if not force:+ click.confirm(+ f"\nDelete {count} memory(ies)?",+ abort=True,+ )++ # Delete+ ids_to_delete = [m.id for m in memories]+ deleted = asyncio.run(store.delete_batch(ids_to_delete))+ print_success(f"Deleted {deleted} memory(ies).")++ except click.BadParameter as e:+ print_error(str(e))+ sys.exit(1)+ except click.Abort:+ click.echo("Aborted.")+ sys.exit(0)+ except Exception as e:+ print_error(f"Failed to prune memories: {e}")+ sys.exit(1)++[email protected]("purge")+@db_path_option+ "--confirm",+ "confirm_flag",+ is_flag=True,+ help="Confirm that you want to delete ALL memories.",+)[email protected]_context+def purge_memories(ctx: click.Context, db_path: str, confirm_flag: bool) -> None:+ """Delete ALL memories from the database.++ This is a destructive operation that cannot be undone.+ Requires the --confirm flag.++ \b+ Example:+ headroom memory purge --confirm+ """+ if not confirm_flag:+ print_error("This will delete ALL memories. Use --confirm to proceed.")+ sys.exit(1)++ store = get_store(db_path)++ try:+ # Get count first+ stats = _get_stats(store)+ total = stats["total_count"]++ if total == 0:+ click.echo("No memories to delete.")+ return++ # Final confirmation+ click.confirm(+ f"Are you sure you want to delete ALL {total} memories? This cannot be undone.",+ abort=True,+ )++ # Purge+ deleted = asyncio.run(store.clear_all())+ print_success(f"Purged {deleted} memory(ies).")++ except click.Abort:+ click.echo("Aborted.")+ sys.exit(0)+ except Exception as e:+ print_error(f"Failed to purge memories: {e}")+ sys.exit(1)++[email protected]("export")+@db_path_option+ "--output",+ "-o",+ type=click.Path(),+ help="Output file path. If not specified, outputs to stdout.",+)[email protected]_context+def export_memories(ctx: click.Context, db_path: str, output: str | None) -> None:+ """Export all memories to JSON.++ \b+ Examples:+ headroom memory export Output to stdout+ headroom memory export --output backup.json Save to file+ headroom memory export -o backup.json Save to file (short form)+ """+ store = get_store(db_path)++ try:+ memories = _export_all(store)++ json_output = json.dumps(memories, indent=2, default=str)++ if output:+ output_path = Path(output)+ output_path.write_text(json_output)+ print_success(f"Exported {len(memories)} memory(ies) to {output_path}")+ else:+ click.echo(json_output)++ except Exception as e:+ print_error(f"Failed to export memories: {e}")+ sys.exit(1)++[email protected]("import")+@db_path_option[email protected]("file", type=click.Path(exists=True))[email protected]("--force", "-f", is_flag=True, help="Skip confirmation prompt.")[email protected]_context+def import_memories(ctx: click.Context, db_path: str, file: str, force: bool) -> None:+ """Import memories from a JSON file.++ The JSON file should contain an array of memory objects (as exported by 'export').+ Existing memories with the same ID will be overwritten.++ \b+ Examples:+ headroom memory import backup.json Import from file+ headroom memory import backup.json --force Skip confirmation+ """+ file_path = Path(file)++ try:+ # Read and parse file+ content = file_path.read_text()+ memories_data = json.loads(content)++ if not isinstance(memories_data, list):+ print_error("Invalid JSON: Expected an array of memory objects.")+ sys.exit(1)++ count = len(memories_data)+ if count == 0:+ click.echo("No memories to import.")+ return++ # Confirm+ if not force:+ click.confirm(+ f"Import {count} memory(ies) from {file_path}? Existing memories with same IDs will be overwritten.",+ abort=True,+ )++ store = get_store(db_path)+ imported = _import_memories(store, memories_data)+ print_success(f"Imported {imported} memory(ies).")++ if imported < count:+ print_warning(f"Skipped {count - imported} malformed entries.")++ except json.JSONDecodeError as e:+ print_error(f"Invalid JSON file: {e}")+ sys.exit(1)+ except click.Abort:+ click.echo("Aborted.")+ sys.exit(0)+ except Exception as e:+ print_error(f"Failed to import memories: {e}")+ sys.exit(1)diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pynew file mode 100644index 000000000..810d6bc75--- /dev/null+++ b/headroom/cli/proxy.py@@ -0,0 +1,247 @@+"""Proxy server CLI commands."""++import click++from .main import main++[email protected]("--host", default="127.0.0.1", help="Host to bind to (default: 127.0.0.1)")[email protected]("--port", "-p", default=8787, type=int, help="Port to bind to (default: 8787)")[email protected]("--no-optimize", is_flag=True, help="Disable optimization (passthrough mode)")[email protected]("--no-cache", is_flag=True, help="Disable semantic caching")[email protected]("--no-rate-limit", is_flag=True, help="Disable rate limiting")[email protected]("--log-file", default=None, help="Path to JSONL log file")[email protected]("--budget", type=float, default=None, help="Daily budget limit in USD")+# LLMLingua ML-based compression (ON by default if installed)[email protected]("--no-llmlingua", is_flag=True, help="Disable LLMLingua-2 ML-based compression")+ "--llmlingua-device",+ type=click.Choice(["auto", "cuda", "cpu", "mps"]),+ default="auto",+ help="Device for LLMLingua model (default: auto)",+)+ "--llmlingua-rate",+ type=float,+ default=0.3,+ help="LLMLingua compression rate 0.0-1.0 (default: 0.3 = keep 30%)",+)+# Code-aware compression (ON by default if installed)[email protected]("--no-code-aware", is_flag=True, help="Disable AST-based code compression")+# Intelligent Context Management (ON by default)+ "--no-intelligent-context",+ is_flag=True,+ help="Disable IntelligentContextManager (fall back to RollingWindow)",+)+ "--no-intelligent-scoring",+ is_flag=True,+ help="Disable multi-factor importance scoring (use position-based)",+)+ "--no-compress-first",+ is_flag=True,+ help="Disable trying deeper compression before dropping messages",+)+# Memory System+ "--memory",+ is_flag=True,+ help="Enable persistent user memory (uses x-headroom-user-id header if set, otherwise 'default')",+)+ "--memory-backend",+ type=click.Choice(["local", "qdrant-neo4j"]),+ default="local",+ help="Memory storage backend: local (SQLite+HNSW) or qdrant-neo4j (default: local)",+)+ "--memory-db-path",+ default="headroom_memory.db",+ help="Path to memory database file for local backend (default: headroom_memory.db)",+)[email protected]("--no-memory-tools", is_flag=True, help="Disable automatic memory tool injection")+ "--no-memory-context", is_flag=True, help="Disable automatic memory context injection"+)+ "--memory-top-k",+ type=int,+ default=10,+ help="Number of memories to inject as context (default: 10)",+)+# Backend configuration+ "--backend",+ default="anthropic",+ help=(+ "API backend: 'anthropic' (direct), 'bedrock' (AWS), "+ "or 'litellm-<provider>' (e.g., litellm-bedrock, litellm-vertex)"+ ),+)+ "--region",+ default="us-west-2",+ help="Cloud region for Bedrock/Vertex/etc (default: us-west-2)",+)+ "--bedrock-region",+ default=None,+ help="(deprecated, use --region) AWS region for Bedrock",+)+ "--bedrock-profile",+ default=None,+ help="AWS profile name for Bedrock (default: use default credentials)",+)[email protected]_context+def proxy(+ ctx: click.Context,+ host: str,+ port: int,+ no_optimize: bool,+ no_cache: bool,+ no_rate_limit: bool,+ log_file: str | None,+ budget: float | None,+ no_llmlingua: bool,+ llmlingua_device: str,+ llmlingua_rate: float,+ no_code_aware: bool,+ no_intelligent_context: bool,+ no_intelligent_scoring: bool,+ no_compress_first: bool,+ memory: bool,+ memory_backend: str,+ memory_db_path: str,+ no_memory_tools: bool,+ no_memory_context: bool,+ memory_top_k: int,+ backend: str,+ region: str,+ bedrock_region: str | None,+ bedrock_profile: str | None,+) -> None:+ """Start the optimization proxy server.++ \b+ Examples:+ headroom proxy Start proxy on port 8787+ headroom proxy --port 8080 Start proxy on port 8080+ headroom proxy --no-optimize Passthrough mode (no optimization)++ \b+ Usage with Claude Code:+ ANTHROPIC_BASE_URL=http://localhost:8787 claude++ \b+ Usage with OpenAI-compatible clients:+ OPENAI_BASE_URL=http://localhost:8787/v1 your-app+ """+ # Import here to avoid slow startup+ try:+ from headroom.proxy.server import ProxyConfig, run_server+ except ImportError as e:+ click.echo("Error: Proxy dependencies not installed. Run: pip install headroom[proxy]")+ click.echo(f"Details: {e}")+ raise SystemExit(1) from None++ config = ProxyConfig(+ host=host,+ port=port,+ optimize=not no_optimize,+ cache_enabled=not no_cache,+ rate_limit_enabled=not no_rate_limit,+ log_file=log_file,+ budget_limit_usd=budget,+ # LLMLingua: ON by default (use --no-llmlingua to disable)+ llmlingua_enabled=not no_llmlingua,+ llmlingua_device=llmlingua_device,+ llmlingua_target_rate=llmlingua_rate,+ # Code-aware: ON by default (use --no-code-aware to disable)+ code_aware_enabled=not no_code_aware,+ # Intelligent Context: ON by default (use --no-intelligent-context to disable)+ intelligent_context=not no_intelligent_context,+ intelligent_context_scoring=not no_intelligent_scoring,+ intelligent_context_compress_first=not no_compress_first,+ # Memory System+ memory_enabled=memory,+ memory_backend=memory_backend, # type: ignore[arg-type]+ memory_db_path=memory_db_path,+ memory_inject_tools=not no_memory_tools,+ memory_inject_context=not no_memory_context,+ memory_top_k=memory_top_k,+ # Backend (Anthropic direct, Bedrock, or LiteLLM)+ backend=backend,+ bedrock_region=bedrock_region or region,+ bedrock_profile=bedrock_profile,+ )++ memory_status = "DISABLED"+ if config.memory_enabled:+ memory_status = f"ENABLED ({config.memory_backend})"++ effective_region = bedrock_region or region+ backend_status = "Anthropic (direct API)"+ if config.backend != "anthropic":+ # Normalize: "bedrock" -> "litellm-bedrock"+ backend_name = config.backend+ if not backend_name.startswith("litellm-"):+ backend_name = f"litellm-{backend_name}"+ provider = backend_name.replace("litellm-", "")+ backend_status = f"{provider.upper()} via LiteLLM (region={effective_region})"++ # Build memory section if enabled+ memory_section = ""+ if config.memory_enabled:+ memory_section = f"""+Memory:+ - Memories are scoped per user. Set x-headroom-user-id header (defaults to 'default').+ - Tools: {"ENABLED" if config.memory_inject_tools else "DISABLED"} Context: {"ENABLED" if config.memory_inject_context else "DISABLED"}+"""+ if config.memory_inject_tools:+ memory_section += " - NOTE: Memory tools require ANTHROPIC_API_KEY (Claude Code subscription credentials have restrictions).\n"++ # Build usage note for Bedrock+ bedrock_note = ""+ if config.backend == "bedrock":+ bedrock_note = "unset CLAUDE_CODE_USE_BEDROCK # Important!"++ click.echo(f"""+╔═══════════════════════════════════════════════════════════════════════╗+║ HEADROOM PROXY ║+║ The Context Optimization Layer for LLM Applications ║+╚═══════════════════════════════════════════════════════════════════════╝++Starting proxy server...++ URL: http://{config.host}:{config.port}+ Backend: {backend_status}+ Optimization: {"ENABLED" if config.optimize else "DISABLED"}+ Caching: {"ENABLED" if config.cache_enabled else "DISABLED"}+ Rate Limit: {"ENABLED" if config.rate_limit_enabled else "DISABLED"}+ Memory: {memory_status}++Usage with Claude Code:+ {bedrock_note}+ ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude++Usage with OpenAI-compatible clients:+ OPENAI_BASE_URL=http://{config.host}:{config.port}/v1 your-app+{memory_section}+Endpoints:+ GET /health Health check+ GET /stats Detailed statistics+ GET /metrics Prometheus metrics+ POST /v1/messages Anthropic API+ POST /v1/chat/completions OpenAI API++Press Ctrl+C to stop.+""")++ try:+ run_server(config)+ except KeyboardInterrupt:+ click.echo("\nShutting down...")diff --git a/pyproject.toml b/pyproject.tomlindex 65782bac3..daab7a1b4 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -56,6 +56,8 @@ dependencies = ["pillow>=10.0.0", # Image processing for compression"datasets>=4.5.0","hnswlib>=0.8.0", # HNSW vector index for memory system+ "click>=8.1.0", # CLI framework+ "rich>=13.0.0", # Rich terminal output][project.optional-dependencies]@@ -88,6 +90,18 @@ code = [agno = ["agno>=1.0.0",]+# Voice filler detection (training and inference)+voice = [+ "onnxruntime>=1.16.0", # Fast CPU inference+ "transformers>=4.30.0", # Model loading and tokenization+ "torch>=2.0.0", # Training+]+# Voice training only (includes voice deps + training extras)+voice-train = [+ "headroom-ai[voice]",+ "datasets>=2.14.0", # Data loading+ "accelerate>=0.20.0", # Training acceleration+]# Evaluation framework for testing compression accuracyevals = ["datasets>=2.14.0", # HuggingFace datasets@@ -101,6 +115,10 @@ evals = [memory = ["hnswlib>=0.8.0", # HNSW vector index for semantic search]+# AWS Bedrock backend+bedrock = [+ "boto3>=1.28.0",+]# Development dependenciesdev = ["pytest>=7.0.0",@@ -117,7 +135,7 @@ dev = []# All optional dependenciesall = [- "headroom-ai[relevance,proxy,reports,llmlingua,code,evals,memory]",+ "headroom-ai[relevance,proxy,reports,llmlingua,code,evals,memory,voice]",][project.scripts]diff --git a/tests/cli/__init__.py b/tests/cli/__init__.pynew file mode 100644index 000000000..f1352830e--- /dev/null+++ b/tests/cli/__init__.py@@ -0,0 +1 @@+"""CLI tests package."""diff --git a/tests/cli/test_memory.py b/tests/cli/test_memory.pynew file mode 100644index 000000000..6a9acb65a--- /dev/null+++ b/tests/cli/test_memory.py@@ -0,0 +1,472 @@+"""Tests for memory CLI commands.++These tests use real SQLite databases (temp files) - no mocks.+"""++import asyncio+import json+from datetime import datetime, timedelta+from pathlib import Path++import pytest+from click.testing import CliRunner++from headroom.cli.main import main+from headroom.memory.adapters.sqlite import SQLiteMemoryStore+from headroom.memory.models import Memory+++def runner() -> CliRunner:+ """Create a CLI test runner."""+ return CliRunner()+++def temp_db(tmp_path: Path) -> str:+ """Create a temporary database path."""+ return str(tmp_path / "test_memory.db")+++def populated_db(temp_db: str) -> str:+ """Create a database with sample memories."""+ store = SQLiteMemoryStore(temp_db)++ # Create memories at different scopes and ages+ memories = [+ # USER scope (no session/agent/turn)+ Memory(+ id="user-mem-001",+ content="User prefers TypeScript over JavaScript",+ user_id="test-user",+ session_id=None,+ agent_id=None,+ turn_id=None,+ importance=0.9,+ created_at=datetime.now() - timedelta(days=5),+ valid_from=datetime.now() - timedelta(days=5),+ ),+ # SESSION scope+ Memory(+ id="session-mem-001",+ content="Working on authentication feature",+ user_id="test-user",+ session_id="session-123",+ agent_id=None,+ turn_id=None,+ importance=0.7,+ created_at=datetime.now() - timedelta(hours=2),+ valid_from=datetime.now() - timedelta(hours=2),+ ),+ Memory(+ id="session-mem-002",+ content="Database uses PostgreSQL",+ user_id="test-user",+ session_id="session-123",+ agent_id=None,+ turn_id=None,+ importance=0.6,+ created_at=datetime.now() - timedelta(days=10),+ valid_from=datetime.now() - timedelta(days=10),+ ),+ # AGENT scope+ Memory(+ id="agent-mem-001",+ content="Agent is exploring code structure",+ user_id="test-user",+ session_id="session-123",+ agent_id="agent-456",+ turn_id=None,+ importance=0.4,+ created_at=datetime.now() - timedelta(hours=1),+ valid_from=datetime.now() - timedelta(hours=1),+ ),+ # TURN scope (ephemeral)+ Memory(+ id="turn-mem-001",+ content="Tool output from grep search",+ user_id="test-user",+ session_id="session-123",+ agent_id="agent-456",+ turn_id="turn-789",+ importance=0.2,+ created_at=datetime.now() - timedelta(minutes=5),+ valid_from=datetime.now() - timedelta(minutes=5),+ ),+ # Low importance memory for pruning tests+ Memory(+ id="low-importance-001",+ content="Temporary note",+ user_id="test-user",+ session_id="session-123",+ agent_id=None,+ turn_id=None,+ importance=0.1,+ created_at=datetime.now() - timedelta(days=45),+ valid_from=datetime.now() - timedelta(days=45),+ ),+ ]++ for mem in memories:+ asyncio.run(store.save(mem))++ return temp_db+++class TestMemoryList:+ """Tests for 'headroom memory list' command."""++ def test_list_all(self, runner: CliRunner, populated_db: str) -> None:+ """List all memories."""+ result = runner.invoke(main, ["memory", "list", "--db-path", populated_db])+ assert result.exit_code == 0+ # IDs are truncated to 8 chars in display, check for partial matches+ assert "user-mem" in result.output+ assert "session-" in result.output # "session-mem" truncated to "session-"++ def test_list_with_limit(self, runner: CliRunner, populated_db: str) -> None:+ """List with limit."""+ result = runner.invoke(main, ["memory", "list", "--db-path", populated_db, "--limit", "2"])+ assert result.exit_code == 0+ # Should show limited results+ assert "2 shown" in result.output or "Memories" in result.output++ def test_list_by_scope(self, runner: CliRunner, populated_db: str) -> None:+ """Filter by scope level."""+ result = runner.invoke(+ main, ["memory", "list", "--db-path", populated_db, "--scope", "USER"]+ )+ assert result.exit_code == 0+ assert "TypeScript" in result.output # USER scope memory content++ def test_list_empty_db(self, runner: CliRunner, temp_db: str) -> None:+ """List from empty database."""+ # Initialize empty db+ SQLiteMemoryStore(temp_db)+ result = runner.invoke(main, ["memory", "list", "--db-path", temp_db])+ assert result.exit_code == 0+ assert "No memories found" in result.output+++class TestMemoryShow:+ """Tests for 'headroom memory show' command."""++ def test_show_by_id(self, runner: CliRunner, populated_db: str) -> None:+ """Show memory by full ID."""+ result = runner.invoke(main, ["memory", "show", "--db-path", populated_db, "user-mem-001"])+ assert result.exit_code == 0+ assert "TypeScript" in result.output+ assert "0.9" in result.output or "0.90" in result.output # importance++ def test_show_by_partial_id(self, runner: CliRunner, populated_db: str) -> None:+ """Show memory by partial ID."""+ result = runner.invoke(main, ["memory", "show", "--db-path", populated_db, "user-mem"])+ assert result.exit_code == 0+ assert "TypeScript" in result.output++ def test_show_json_output(self, runner: CliRunner, populated_db: str) -> None:+ """Show memory as JSON."""+ result = runner.invoke(+ main, ["memory", "show", "--db-path", populated_db, "user-mem-001", "--json"]+ )+ assert result.exit_code == 0+ # Should be valid JSON+ data = json.loads(result.output)+ assert data["id"] == "user-mem-001"+ assert "TypeScript" in data["content"]++ def test_show_not_found(self, runner: CliRunner, populated_db: str) -> None:+ """Show non-existent memory."""+ result = runner.invoke(+ main, ["memory", "show", "--db-path", populated_db, "nonexistent-id"]+ )+ assert result.exit_code != 0 or "not found" in result.output.lower()+++class TestMemoryStats:+ """Tests for 'headroom memory stats' command."""++ def test_stats(self, runner: CliRunner, populated_db: str) -> None:+ """Show stats for populated database."""+ result = runner.invoke(main, ["memory", "stats", "--db-path", populated_db])+ assert result.exit_code == 0+ assert "Total" in result.output or "Memories" in result.output+ assert "6" in result.output # 6 memories++ def test_stats_empty_db(self, runner: CliRunner, temp_db: str) -> None:+ """Stats for empty database."""+ SQLiteMemoryStore(temp_db)+ result = runner.invoke(main, ["memory", "stats", "--db-path", temp_db])+ assert result.exit_code == 0+ assert "0" in result.output+++class TestMemoryEdit:+ """Tests for 'headroom memory edit' command."""++ def test_edit_content(self, runner: CliRunner, populated_db: str) -> None:+ """Edit memory content."""+ result = runner.invoke(+ main,+ [+ "memory",+ "edit",+ "--db-path",+ populated_db,+ "user-mem-001",+ "--content",+ "Updated content",+ ],+ )+ assert result.exit_code == 0++ # Verify change+ show_result = runner.invoke(+ main, ["memory", "show", "--db-path", populated_db, "user-mem-001"]+ )+ assert "Updated content" in show_result.output++ def test_edit_importance(self, runner: CliRunner, populated_db: str) -> None:+ """Edit memory importance."""+ result = runner.invoke(+ main,+ ["memory", "edit", "--db-path", populated_db, "user-mem-001", "--importance", "0.5"],+ )+ assert result.exit_code == 0++ # Verify change+ show_result = runner.invoke(+ main, ["memory", "show", "--db-path", populated_db, "user-mem-001"]+ )+ assert "0.5" in show_result.output++ def test_edit_not_found(self, runner: CliRunner, populated_db: str) -> None:+ """Edit non-existent memory."""+ result = runner.invoke(+ main,+ ["memory", "edit", "--db-path", populated_db, "nonexistent", "--content", "test"],+ )+ assert result.exit_code != 0 or "not found" in result.output.lower()+++class TestMemoryDelete:+ """Tests for 'headroom memory delete' command."""++ def test_delete_single(self, runner: CliRunner, populated_db: str) -> None:+ """Delete single memory with force."""+ result = runner.invoke(+ main,+ ["memory", "delete", "--db-path", populated_db, "turn-mem-001", "--force"],+ )+ assert result.exit_code == 0++ # Verify deleted+ show_result = runner.invoke(+ main, ["memory", "show", "--db-path", populated_db, "turn-mem-001"]+ )+ assert "not found" in show_result.output.lower() or show_result.exit_code != 0++ def test_delete_multiple(self, runner: CliRunner, populated_db: str) -> None:+ """Delete multiple memories."""+ result = runner.invoke(+ main,+ [+ "memory",+ "delete",+ "--db-path",+ populated_db,+ "turn-mem-001",+ "agent-mem-001",+ "--force",+ ],+ )+ assert result.exit_code == 0++ def test_delete_requires_confirmation(self, runner: CliRunner, populated_db: str) -> None:+ """Delete prompts for confirmation without --force."""+ # Invoke delete and say no to confirmation+ runner.invoke(+ main,+ ["memory", "delete", "--db-path", populated_db, "turn-mem-001"],+ input="n\n", # Say no+ )+ # Verify memory still exists since we said no+ show_result = runner.invoke(+ main, ["memory", "show", "--db-path", populated_db, "turn-mem-001"]+ )+ # Memory should still exist since we said no+ assert "Tool output" in show_result.output or show_result.exit_code == 0+++class TestMemoryPrune:+ """Tests for 'headroom memory prune' command."""++ def test_prune_dry_run(self, runner: CliRunner, populated_db: str) -> None:+ """Prune with dry-run shows what would be deleted."""+ result = runner.invoke(+ main,+ ["memory", "prune", "--db-path", populated_db, "--older-than", "30d", "--dry-run"],+ )+ assert result.exit_code == 0+ assert "would" in result.output.lower() or "dry" in result.output.lower()++ def test_prune_by_age(self, runner: CliRunner, populated_db: str) -> None:+ """Prune old memories."""+ result = runner.invoke(+ main,+ ["memory", "prune", "--db-path", populated_db, "--older-than", "30d", "--force"],+ )+ assert result.exit_code == 0+ # Should have deleted the 45-day old memory++ def test_prune_by_scope(self, runner: CliRunner, populated_db: str) -> None:+ """Prune by scope level."""+ result = runner.invoke(+ main,+ ["memory", "prune", "--db-path", populated_db, "--scope", "TURN", "--force"],+ )+ assert result.exit_code == 0++ # Verify TURN memories are gone+ list_result = runner.invoke(+ main, ["memory", "list", "--db-path", populated_db, "--scope", "TURN"]+ )+ assert "No memories found" in list_result.output or "turn-mem" not in list_result.output++ def test_prune_low_importance(self, runner: CliRunner, populated_db: str) -> None:+ """Prune low importance memories."""+ result = runner.invoke(+ main,+ ["memory", "prune", "--db-path", populated_db, "--low-importance", "0.3", "--force"],+ )+ assert result.exit_code == 0+++class TestMemoryPurge:+ """Tests for 'headroom memory purge' command."""++ def test_purge_requires_confirm_flag(self, runner: CliRunner, populated_db: str) -> None:+ """Purge requires --confirm flag."""+ result = runner.invoke(main, ["memory", "purge", "--db-path", populated_db])+ assert result.exit_code != 0 or "confirm" in result.output.lower()++ def test_purge_with_confirm(self, runner: CliRunner, populated_db: str) -> None:+ """Purge deletes all memories."""+ result = runner.invoke(+ main,+ ["memory", "purge", "--db-path", populated_db, "--confirm"],+ input="y\n", # Confirm+ )+ assert result.exit_code == 0++ # Verify empty+ stats_result = runner.invoke(main, ["memory", "stats", "--db-path", populated_db])+ assert "0" in stats_result.output+++class TestMemoryExportImport:+ """Tests for export/import commands."""++ def test_export_to_stdout(self, runner: CliRunner, populated_db: str) -> None:+ """Export memories to stdout."""+ result = runner.invoke(main, ["memory", "export", "--db-path", populated_db])+ assert result.exit_code == 0+ # Should be valid JSON array+ data = json.loads(result.output)+ assert isinstance(data, list)+ assert len(data) == 6++ def test_export_to_file(self, runner: CliRunner, populated_db: str, tmp_path: Path) -> None:+ """Export memories to file."""+ output_file = tmp_path / "export.json"+ result = runner.invoke(+ main,+ ["memory", "export", "--db-path", populated_db, "--output", str(output_file)],+ )+ assert result.exit_code == 0++ # Verify file+ with open(output_file) as f:+ data = json.load(f)+ assert len(data) == 6++ def test_import_from_file(self, runner: CliRunner, temp_db: str, tmp_path: Path) -> None:+ """Import memories from file."""+ # Create import file+ import_data = [+ {+ "id": "imported-001",+ "content": "Imported memory",+ "user_id": "test-user",+ "importance": 0.8,+ "created_at": datetime.now().isoformat(),+ "valid_from": datetime.now().isoformat(),+ }+ ]+ import_file = tmp_path / "import.json"+ with open(import_file, "w") as f:+ json.dump(import_data, f)++ # Initialize empty db+ SQLiteMemoryStore(temp_db)++ result = runner.invoke(+ main,+ ["memory", "import", "--db-path", temp_db, str(import_file), "--force"],+ )+ assert result.exit_code == 0++ # Verify imported+ show_result = runner.invoke(main, ["memory", "show", "--db-path", temp_db, "imported-001"])+ assert "Imported memory" in show_result.output++ def test_export_import_roundtrip(+ self, runner: CliRunner, populated_db: str, tmp_path: Path+ ) -> None:+ """Export and import should be lossless."""+ export_file = tmp_path / "roundtrip.json"+ new_db = str(tmp_path / "new.db")++ # Export+ runner.invoke(+ main, ["memory", "export", "--db-path", populated_db, "--output", str(export_file)]+ )++ # Import to new db+ SQLiteMemoryStore(new_db)+ runner.invoke(main, ["memory", "import", "--db-path", new_db, str(export_file), "--force"])++ # Compare stats+ orig_stats = runner.invoke(main, ["memory", "stats", "--db-path", populated_db])+ new_stats = runner.invoke(main, ["memory", "stats", "--db-path", new_db])++ # Should have same count+ assert "6" in orig_stats.output+ assert "6" in new_stats.output+++class TestMemoryHelp:+ """Tests for help output."""++ def test_memory_help(self, runner: CliRunner) -> None:+ """Memory group shows help."""+ result = runner.invoke(main, ["memory", "--help"])+ assert result.exit_code == 0+ assert "list" in result.output+ assert "show" in result.output+ assert "stats" in result.output+ assert "edit" in result.output+ assert "delete" in result.output+ assert "prune" in result.output+ assert "purge" in result.output+ assert "export" in result.output+ assert "import" in result.output++ def test_list_help(self, runner: CliRunner) -> None:+ """List command shows help."""+ result = runner.invoke(main, ["memory", "list", "--help"])+ assert result.exit_code == 0+ assert "--limit" in result.output+ assert "--scope" in result.output+ assert "--since" in result.outputdiff --git a/tests/cli/test_utils.py b/tests/cli/test_utils.pynew file mode 100644index 000000000..be9d3d12a--- /dev/null+++ b/tests/cli/test_utils.py@@ -0,0 +1,170 @@+"""Tests for CLI utilities."""++from datetime import datetime, timedelta++import click+import pytest++from headroom.cli._utils import (+ format_age,+ format_bytes,+ parse_duration,+ truncate,+)+++class TestParseDuration:+ """Tests for parse_duration function."""++ def test_parse_days(self) -> None:+ """Parse days correctly."""+ result = parse_duration("7d")+ assert result == timedelta(days=7)++ def test_parse_weeks(self) -> None:+ """Parse weeks correctly."""+ result = parse_duration("2w")+ assert result == timedelta(weeks=2)++ def test_parse_months(self) -> None:+ """Parse months as 30 days."""+ result = parse_duration("1m")+ assert result == timedelta(days=30)++ def test_parse_hours(self) -> None:+ """Parse hours correctly."""+ result = parse_duration("24h")+ assert result == timedelta(hours=24)++ def test_parse_large_numbers(self) -> None:+ """Parse large duration values."""+ result = parse_duration("365d")+ assert result == timedelta(days=365)++ def test_invalid_format_raises(self) -> None:+ """Invalid format raises BadParameter."""+ with pytest.raises(click.BadParameter):+ parse_duration("invalid")++ def test_empty_string_raises(self) -> None:+ """Empty string raises BadParameter."""+ with pytest.raises(click.BadParameter):+ parse_duration("")++ def test_no_unit_raises(self) -> None:+ """Number without unit raises BadParameter."""+ with pytest.raises(click.BadParameter):+ parse_duration("7")++ def test_invalid_unit_raises(self) -> None:+ """Invalid unit raises BadParameter."""+ with pytest.raises(click.BadParameter):+ parse_duration("7x")++ def test_negative_not_allowed(self) -> None:+ """Negative values raise BadParameter."""+ with pytest.raises(click.BadParameter):+ parse_duration("-7d")+++class TestFormatAge:+ """Tests for format_age function."""++ def test_minutes_ago(self) -> None:+ """Format recent time as minutes."""+ dt = datetime.now() - timedelta(minutes=30)+ result = format_age(dt)+ assert result == "30m"++ def test_hours_ago(self) -> None:+ """Format hours ago."""+ dt = datetime.now() - timedelta(hours=5)+ result = format_age(dt)+ assert result == "5h"++ def test_days_ago(self) -> None:+ """Format days ago."""+ dt = datetime.now() - timedelta(days=3)+ result = format_age(dt)+ assert result == "3d"++ def test_weeks_ago(self) -> None:+ """Format weeks ago for older dates."""+ dt = datetime.now() - timedelta(weeks=2)+ result = format_age(dt)+ assert result == "14d"++ def test_just_now(self) -> None:+ """Very recent time shows as 'now'."""+ dt = datetime.now() - timedelta(seconds=30)+ result = format_age(dt)+ assert result == "now"+++class TestFormatBytes:+ """Tests for format_bytes function."""++ def test_bytes(self) -> None:+ """Format small values as bytes."""+ assert format_bytes(500) == "500 B"++ def test_kilobytes(self) -> None:+ """Format KB correctly."""+ assert format_bytes(1024) == "1.0 KB"+ assert format_bytes(2048) == "2.0 KB"++ def test_megabytes(self) -> None:+ """Format MB correctly."""+ assert format_bytes(1024 * 1024) == "1.0 MB"+ assert format_bytes(5 * 1024 * 1024) == "5.0 MB"++ def test_gigabytes(self) -> None:+ """Format GB correctly."""+ assert format_bytes(1024 * 1024 * 1024) == "1.0 GB"++ def test_zero_bytes(self) -> None:+ """Zero bytes handled correctly."""+ assert format_bytes(0) == "0 B"++ def test_fractional_kb(self) -> None:+ """Fractional KB shows decimal."""+ result = format_bytes(1536) # 1.5 KB+ assert "1.5 KB" == result+++class TestTruncate:+ """Tests for truncate function."""++ def test_short_string_unchanged(self) -> None:+ """Short strings are not modified."""+ result = truncate("hello", max_len=10)+ assert result == "hello"++ def test_exact_length_unchanged(self) -> None:+ """String at exact length is not modified."""+ result = truncate("hello", max_len=5)+ assert result == "hello"++ def test_long_string_truncated(self) -> None:+ """Long strings are truncated with ellipsis."""+ result = truncate("hello world", max_len=8)+ assert result == "hello..."+ assert len(result) == 8++ def test_empty_string(self) -> None:+ """Empty string returns empty."""+ result = truncate("", max_len=10)+ assert result == ""++ def test_default_length(self) -> None:+ """Default max length is 50."""+ long_string = "a" * 100+ result = truncate(long_string)+ assert len(result) == 50+ assert result.endswith("...")++ def test_with_newlines(self) -> None:+ """Truncate works with newlines in text."""+ result = truncate("hello\nworld", max_len=20)+ # Newlines are preserved+ assert result == "hello\nworld"