Skip to content

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.

Add Click-based CLI with memory management commands

chopratejasfb4117f3a677
diff --git a/headroom/cli.py b/headroom/cli.py
index 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 main
if __name__ == "__main__":
- sys.exit(main())
+ main()
diff --git a/headroom/cli/__init__.py b/headroom/cli/__init__.py
new file mode 100644
index 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__.py
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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
+
+
+ "--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.py
new file mode 100644
index 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")
+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.py
new file mode 100644
index 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
+
+
+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
+
+
+@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.")
+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)
+
+
+@db_path_option
[email protected]("memory_id", type=str)
[email protected]("--json", "output_json", is_flag=True, help="Output as raw JSON.")
+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)
+
+
+@db_path_option
+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)
+
+
+@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).")
+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)
+
+
+@db_path_option
[email protected]("memory_ids", type=str, nargs=-1, required=True)
[email protected]("--force", "-f", is_flag=True, help="Skip confirmation prompt.")
+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)
+
+
+@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.")
+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)
+
+
+@db_path_option
+ "--confirm",
+ "confirm_flag",
+ is_flag=True,
+ help="Confirm that you want to delete ALL memories.",
+)
+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)
+
+
+@db_path_option
+ "--output",
+ "-o",
+ type=click.Path(),
+ help="Output file path. If not specified, outputs to stdout.",
+)
+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)
+
+
+@db_path_option
[email protected]("file", type=click.Path(exists=True))
[email protected]("--force", "-f", is_flag=True, help="Skip confirmation prompt.")
+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.py
new file mode 100644
index 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)",
+)
+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.toml
index 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 accuracy
evals = [
"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 dependencies
dev = [
"pytest>=7.0.0",
@@ -117,7 +135,7 @@ dev = [
]
# All optional dependencies
all = [
- "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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.output
diff --git a/tests/cli/test_utils.py b/tests/cli/test_utils.py
new file mode 100644
index 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"