hindsight-api 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

hindsight_api/mcp_local.py

@@ -0,0 +1,190 @@
+"""
+Local MCP server for use with Claude Code (stdio transport).
+
+This runs a fully local Hindsight instance with embedded PostgreSQL (pg0).
+No external database or server required.
+
+Run with:
+    hindsight-local-mcp
+
+Or with uvx:
+    uvx hindsight-api@latest hindsight-local-mcp
+
+Configure in Claude Code's MCP settings:
+    {
+        "mcpServers": {
+            "hindsight": {
+                "command": "uvx",
+                "args": ["hindsight-api@latest", "hindsight-local-mcp"],
+                "env": {
+                    "HINDSIGHT_API_LLM_API_KEY": "your-openai-key"
+                }
+            }
+        }
+    }
+
+Environment variables:
+    HINDSIGHT_API_LLM_API_KEY: Required. API key for LLM provider.
+    HINDSIGHT_API_LLM_PROVIDER: Optional. LLM provider (default: "openai").
+    HINDSIGHT_API_LLM_MODEL: Optional. LLM model (default: "gpt-4o-mini").
+    HINDSIGHT_API_MCP_LOCAL_BANK_ID: Optional. Memory bank ID (default: "mcp").
+    HINDSIGHT_API_LOG_LEVEL: Optional. Log level (default: "info").
+"""
+
+import logging
+import os
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from hindsight_api.config import (
+    DEFAULT_MCP_LOCAL_BANK_ID,
+    ENV_MCP_LOCAL_BANK_ID,
+)
+
+# Configure logging - default to info
+_log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "info").lower()
+_log_level_map = {
+    "critical": logging.CRITICAL,
+    "error": logging.ERROR,
+    "warning": logging.WARNING,
+    "info": logging.INFO,
+    "debug": logging.DEBUG,
+}
+logging.basicConfig(
+    level=_log_level_map.get(_log_level_str, logging.WARNING),
+    format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+    stream=sys.stderr,  # MCP uses stdout for protocol, logs go to stderr
+)
+logger = logging.getLogger(__name__)
+
+
+def create_local_mcp_server(bank_id: str, memory=None) -> FastMCP:
+    """
+    Create a stdio MCP server with retain/recall tools.
+
+    Args:
+        bank_id: The memory bank ID to use for all operations.
+        memory: Optional MemoryEngine instance. If not provided, creates one with pg0.
+
+    Returns:
+        Configured FastMCP server instance.
+    """
+    # Import here to avoid slow startup if just checking --help
+    from hindsight_api import MemoryEngine
+    from hindsight_api.engine.memory_engine import Budget
+    from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES
+
+    # Create memory engine with pg0 embedded database if not provided
+    if memory is None:
+        memory = MemoryEngine(db_url="pg0://hindsight-mcp")
+
+    mcp = FastMCP("hindsight")
+
+    @mcp.tool()
+    async def retain(content: str, context: str = "general") -> dict:
+        """
+        Store important information to long-term memory.
+
+        Use this tool PROACTIVELY whenever the user shares:
+        - Personal facts, preferences, or interests
+        - Important events or milestones
+        - User history, experiences, or background
+        - Decisions, opinions, or stated preferences
+        - Goals, plans, or future intentions
+        - Relationships or people mentioned
+        - Work context, projects, or responsibilities
+
+        Args:
+            content: The fact/memory to store (be specific and include relevant details)
+            context: Category for the memory (e.g., 'preferences', 'work', 'hobbies', 'family'). Default: 'general'
+        """
+        import asyncio
+
+        async def _retain():
+            try:
+                await memory.retain_batch_async(bank_id=bank_id, contents=[{"content": content, "context": context}])
+            except Exception as e:
+                logger.error(f"Error storing memory: {e}", exc_info=True)
+
+        # Fire and forget - don't block on memory storage
+        asyncio.create_task(_retain())
+        return {"status": "accepted", "message": "Memory storage initiated"}
+
+    @mcp.tool()
+    async def recall(query: str, max_tokens: int = 4096, budget: str = "low") -> dict:
+        """
+        Search memories to provide personalized, context-aware responses.
+
+        Use this tool PROACTIVELY to:
+        - Check user's preferences before making suggestions
+        - Recall user's history to provide continuity
+        - Remember user's goals and context
+        - Personalize responses based on past interactions
+
+        Args:
+            query: Natural language search query (e.g., "user's food preferences", "what projects is user working on")
+            max_tokens: Maximum tokens to return in results (default: 4096)
+            budget: Search budget level - "low", "mid", or "high" (default: "low")
+        """
+        try:
+            # Map string budget to enum
+            budget_map = {"low": Budget.LOW, "mid": Budget.MID, "high": Budget.HIGH}
+            budget_enum = budget_map.get(budget.lower(), Budget.LOW)
+
+            search_result = await memory.recall_async(
+                bank_id=bank_id,
+                query=query,
+                fact_type=list(VALID_RECALL_FACT_TYPES),
+                budget=budget_enum,
+                max_tokens=max_tokens,
+            )
+
+            return search_result.model_dump()
+        except Exception as e:
+            logger.error(f"Error searching: {e}", exc_info=True)
+            return {"error": str(e), "results": []}
+
+    return mcp
+
+
+async def _initialize_and_run(bank_id: str):
+    """Initialize memory and run the MCP server."""
+    from hindsight_api import MemoryEngine
+
+    # Create and initialize memory engine with pg0 embedded database
+    print("Initializing memory engine...", file=sys.stderr)
+    memory = MemoryEngine(db_url="pg0://hindsight-mcp")
+    await memory.initialize()
+    print("Memory engine initialized.", file=sys.stderr)
+
+    # Create and run the server
+    mcp = create_local_mcp_server(bank_id, memory=memory)
+    await mcp.run_stdio_async()
+
+
+def main():
+    """Main entry point for the stdio MCP server."""
+    import asyncio
+
+    from hindsight_api.config import ENV_LLM_API_KEY, get_config
+
+    # Check for required environment variables
+    config = get_config()
+    if not config.llm_api_key:
+        print(f"Error: {ENV_LLM_API_KEY} environment variable is required", file=sys.stderr)
+        print("Set it in your MCP configuration or shell environment", file=sys.stderr)
+        sys.exit(1)
+
+    # Get bank ID from environment, default to "mcp"
+    bank_id = os.environ.get(ENV_MCP_LOCAL_BANK_ID, DEFAULT_MCP_LOCAL_BANK_ID)
+
+    # Print startup message to stderr (stdout is reserved for MCP protocol)
+    print(f"Hindsight MCP server starting (bank_id={bank_id})...", file=sys.stderr)
+
+    # Run the async initialization and server
+    asyncio.run(_initialize_and_run(bank_id))
+
+
+if __name__ == "__main__":
+    main()

hindsight_api/metrics.py

@@ -6,16 +6,15 @@ This module provides metrics for:
 - Token usage (input/output) per operation
 - Per-bank granularity via labels
 """
+
 import logging
-from typing import Dict, Any, Optional
-from contextlib import contextmanager
 import time
+from contextlib import contextmanager
 
 from opentelemetry import metrics
+from opentelemetry.exporter.prometheus import PrometheusMetricReader
 from opentelemetry.sdk.metrics import MeterProvider
 from opentelemetry.sdk.resources import Resource
-from opentelemetry.exporter.prometheus import PrometheusMetricReader
-from prometheus_client import REGISTRY
 
 logger = logging.getLogger(__name__)
 
@@ -39,19 +38,18 @@ def initialize_metrics(service_name: str = "hindsight-api", service_version: str
     global _meter
 
     # Create resource with service information
-    resource = Resource.create({
-        "service.name": service_name,
-        "service.version": service_version,
-    })
+    resource = Resource.create(
+        {
+            "service.name": service_name,
+            "service.version": service_version,
+        }
+    )
 
     # Create Prometheus metric reader
     prometheus_reader = PrometheusMetricReader()
 
     # Create meter provider with Prometheus exporter
-    provider = MeterProvider(
-        resource=resource,
-        metric_readers=[prometheus_reader]
-    )
+    provider = MeterProvider(resource=resource, metric_readers=[prometheus_reader])
 
     # Set the global meter provider
     metrics.set_meter_provider(provider)
@@ -73,11 +71,19 @@ class MetricsCollectorBase:
     """Base class for metrics collectors."""
 
     @contextmanager
-    def record_operation(self, operation: str, bank_id: str, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+    def record_operation(self, operation: str, bank_id: str, budget: str | None = None, max_tokens: int | None = None):
         """Context manager to record operation duration and status."""
         raise NotImplementedError
 
-    def record_tokens(self, operation: str, bank_id: str, input_tokens: int = 0, output_tokens: int = 0, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+    def record_tokens(
+        self,
+        operation: str,
+        bank_id: str,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        budget: str | None = None,
+        max_tokens: int | None = None,
+    ):
         """Record token usage for an operation."""
         raise NotImplementedError
 
@@ -86,11 +92,19 @@ class NoOpMetricsCollector(MetricsCollectorBase):
     """No-op metrics collector that does nothing. Used when metrics are disabled."""
 
     @contextmanager
-    def record_operation(self, operation: str, bank_id: str, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+    def record_operation(self, operation: str, bank_id: str, budget: str | None = None, max_tokens: int | None = None):
         """No-op context manager."""
         yield
 
-    def record_tokens(self, operation: str, bank_id: str, input_tokens: int = 0, output_tokens: int = 0, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+    def record_tokens(
+        self,
+        operation: str,
+        bank_id: str,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        budget: str | None = None,
+        max_tokens: int | None = None,
+    ):
         """No-op token recording."""
         pass
 
@@ -108,33 +122,25 @@ class MetricsCollector(MetricsCollectorBase):
         # Operation latency histogram (in seconds)
         # Records duration of retain, recall, reflect operations
         self.operation_duration = self.meter.create_histogram(
-            name="hindsight.operation.duration",
-            description="Duration of Hindsight operations in seconds",
-            unit="s"
+            name="hindsight.operation.duration", description="Duration of Hindsight operations in seconds", unit="s"
         )
 
         # Token usage counters
         self.tokens_input = self.meter.create_counter(
-            name="hindsight.tokens.input",
-            description="Number of input tokens consumed",
-            unit="tokens"
+            name="hindsight.tokens.input", description="Number of input tokens consumed", unit="tokens"
         )
 
         self.tokens_output = self.meter.create_counter(
-            name="hindsight.tokens.output",
-            description="Number of output tokens generated",
-            unit="tokens"
+            name="hindsight.tokens.output", description="Number of output tokens generated", unit="tokens"
         )
 
         # Operation counter (success/failure)
         self.operation_total = self.meter.create_counter(
-            name="hindsight.operation.total",
-            description="Total number of operations executed",
-            unit="operations"
+            name="hindsight.operation.total", description="Total number of operations executed", unit="operations"
         )
 
     @contextmanager
-    def record_operation(self, operation: str, bank_id: str, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+    def record_operation(self, operation: str, bank_id: str, budget: str | None = None, max_tokens: int | None = None):
         """
         Context manager to record operation duration and status.
 
@@ -175,7 +181,15 @@ class MetricsCollector(MetricsCollectorBase):
             # Record operation count
             self.operation_total.add(1, attributes)
 
-    def record_tokens(self, operation: str, bank_id: str, input_tokens: int = 0, output_tokens: int = 0, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+    def record_tokens(
+        self,
+        operation: str,
+        bank_id: str,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        budget: str | None = None,
+        max_tokens: int | None = None,
+    ):
         """
         Record token usage for an operation.
 

hindsight_api/migrations.py

@@ -11,11 +11,10 @@ safe rolling deployments.
 
 No alembic.ini required - all configuration is done programmatically.
 """
+
 import logging
 import os
-import shutil
 from pathlib import Path
-from typing import Optional
 
 from alembic import command
 from alembic.config import Config
@@ -31,7 +30,7 @@ def _run_migrations_internal(database_url: str, script_location: str) -> None:
     """
     Internal function to run migrations without locking.
     """
-    logger.info(f"Running database migrations to head...")
+    logger.info("Running database migrations to head...")
     logger.info(f"Database URL: {database_url}")
     logger.info(f"Script location: {script_location}")
 
@@ -57,7 +56,7 @@ def _run_migrations_internal(database_url: str, script_location: str) -> None:
     logger.info("Database migrations completed successfully")
 
 
-def run_migrations(database_url: str, script_location: Optional[str] = None) -> None:
+def run_migrations(database_url: str, script_location: str | None = None) -> None:
     """
     Run database migrations to the latest version using programmatic Alembic configuration.
 
@@ -97,8 +96,7 @@ def run_migrations(database_url: str, script_location: Optional[str] = None) ->
         script_path = Path(script_location)
         if not script_path.exists():
             raise FileNotFoundError(
-                f"Alembic script location not found at {script_location}. "
-                "Database migrations cannot be run."
+                f"Alembic script location not found at {script_location}. Database migrations cannot be run."
             )
 
         # Use PostgreSQL advisory lock to coordinate between distributed workers
@@ -130,7 +128,9 @@ def run_migrations(database_url: str, script_location: Optional[str] = None) ->
         raise RuntimeError("Database migration failed") from e
 
 
-def check_migration_status(database_url: Optional[str] = None, script_location: Optional[str] = None) -> tuple[str | None, str | None]:
+def check_migration_status(
+    database_url: str | None = None, script_location: str | None = None
+) -> tuple[str | None, str | None]:
     """
     Check current database schema version and latest available version.
 
@@ -151,7 +151,9 @@ def check_migration_status(database_url: Optional[str] = None, script_location:
         if database_url is None:
             database_url = os.getenv("HINDSIGHT_API_DATABASE_URL")
         if not database_url:
-            logger.warning("Database URL not provided and HINDSIGHT_API_DATABASE_URL not set, cannot check migration status")
+            logger.warning(
+                "Database URL not provided and HINDSIGHT_API_DATABASE_URL not set, cannot check migration status"
+            )
             return None, None
 
         # Get current revision from database