hindsight-api 0.1.7__tar.gz → 0.1.9__tar.gz

{hindsight_api-0.1.7 → hindsight_api-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hindsight-api
-Version: 0.1.7
+Version: 0.1.9
 Summary: Hindsight: Agent Memory That Works Like Human Memory
 Requires-Python: >=3.11
 Requires-Dist: alembic>=1.17.1

{hindsight_api-0.1.7 → hindsight_api-0.1.9}/hindsight_api/api/http.py

@@ -506,9 +506,9 @@ class BankListItem(BaseModel):
     """Bank list item with profile summary."""
 
     bank_id: str
-    name: str
+    name: str | None = None
     disposition: DispositionTraits
-    background: str
+    background: str | None = None
     created_at: str | None = None
     updated_at: str | None = None
 
@@ -1452,18 +1452,22 @@ def _register_routes(app: FastAPI):
                     bank_id,
                 )
 
+                def parse_metadata(metadata):
+                    """Parse result_metadata which may be a string or dict."""
+                    if metadata is None:
+                        return {}
+                    if isinstance(metadata, str):
+                        return json.loads(metadata)
+                    return metadata
+
                 return {
                     "bank_id": bank_id,
                     "operations": [
                         {
                             "id": str(row["operation_id"]),
                             "task_type": row["operation_type"],
-                            "items_count": row["result_metadata"].get("items_count", 0)
-                            if row["result_metadata"]
-                            else 0,
-                            "document_id": row["result_metadata"].get("document_id")
-                            if row["result_metadata"]
-                            else None,
+                            "items_count": parse_metadata(row["result_metadata"]).get("items_count", 0),
+                            "document_id": parse_metadata(row["result_metadata"]).get("document_id"),
                             "created_at": row["created_at"].isoformat(),
                             "status": row["status"],
                             "error_message": row["error_message"],
@@ -1499,7 +1503,7 @@ def _register_routes(app: FastAPI):
             async with acquire_with_retry(pool) as conn:
                 # Check if operation exists and belongs to this memory bank
                 result = await conn.fetchrow(
-                    "SELECT bank_id FROM async_operations WHERE id = $1 AND bank_id = $2", op_uuid, bank_id
+                    "SELECT bank_id FROM async_operations WHERE operation_id = $1 AND bank_id = $2", op_uuid, bank_id
                 )
 
                 if not result:
@@ -1508,7 +1512,7 @@ def _register_routes(app: FastAPI):
                     )
 
                 # Delete the operation
-                await conn.execute("DELETE FROM async_operations WHERE id = $1", op_uuid)
+                await conn.execute("DELETE FROM async_operations WHERE operation_id = $1", op_uuid)
 
                 return {
                     "success": True,
@@ -1769,13 +1773,13 @@ def _register_routes(app: FastAPI):
                 async with acquire_with_retry(pool) as conn:
                     await conn.execute(
                         """
-                        INSERT INTO async_operations (id, bank_id, task_type, items_count)
+                        INSERT INTO async_operations (operation_id, bank_id, operation_type, result_metadata)
                         VALUES ($1, $2, $3, $4)
                         """,
                         operation_id,
                         bank_id,
                         "retain",
-                        len(contents),
+                        json.dumps({"items_count": len(contents)}),
                     )
 
                 # Submit task to background queue

{hindsight_api-0.1.7 → hindsight_api-0.1.9}/hindsight_api/config.py

@@ -31,6 +31,7 @@ ENV_LOG_LEVEL = "HINDSIGHT_API_LOG_LEVEL"
 ENV_MCP_ENABLED = "HINDSIGHT_API_MCP_ENABLED"
 ENV_GRAPH_RETRIEVER = "HINDSIGHT_API_GRAPH_RETRIEVER"
 ENV_MCP_LOCAL_BANK_ID = "HINDSIGHT_API_MCP_LOCAL_BANK_ID"
+ENV_MCP_INSTRUCTIONS = "HINDSIGHT_API_MCP_INSTRUCTIONS"
 
 # Default values
 DEFAULT_DATABASE_URL = "pg0"
@@ -50,6 +51,26 @@ DEFAULT_MCP_ENABLED = True
 DEFAULT_GRAPH_RETRIEVER = "bfs"  # Options: "bfs", "mpfp"
 DEFAULT_MCP_LOCAL_BANK_ID = "mcp"
 
+# Default MCP tool descriptions (can be customized via env vars)
+DEFAULT_MCP_RETAIN_DESCRIPTION = """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"""
+
+DEFAULT_MCP_RECALL_DESCRIPTION = """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"""
+
 # Required embedding dimension for database schema
 EMBEDDING_DIMENSION = 384
 
@@ -142,7 +163,9 @@ class HindsightConfig:
     def configure_logging(self) -> None:
         """Configure Python logging based on the log level."""
         logging.basicConfig(
-            level=self.get_python_log_level(), format="%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+            level=self.get_python_log_level(),
+            format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+            force=True,  # Override any existing configuration
         )
 
     def log_config(self) -> None:

{hindsight_api-0.1.7 → hindsight_api-0.1.9}/hindsight_api/engine/llm_wrapper.py

@@ -172,7 +172,7 @@ class LLMProvider:
 
             # Check if model supports reasoning parameter (o1, o3, gpt-5 families)
             model_lower = self.model.lower()
-            is_reasoning_model = any(x in model_lower for x in ["gpt-5", "o1", "o3"])
+            is_reasoning_model = any(x in model_lower for x in ["gpt-5", "o1", "o3", "deepseek"])
 
             # For GPT-4 and GPT-4.1 models, cap max_completion_tokens to 32000
             # For GPT-4o models, cap to 16384
@@ -194,7 +194,7 @@ class LLMProvider:
                 call_params["temperature"] = temperature
 
             # Set reasoning_effort for reasoning models (OpenAI gpt-5, o1, o3)
-            if is_reasoning_model and self.provider == "openai":
+            if is_reasoning_model:
                 call_params["reasoning_effort"] = self.reasoning_effort
 
             # Provider-specific parameters
@@ -203,7 +203,6 @@ class LLMProvider:
                 extra_body = {"service_tier": "auto"}
                 # Only add reasoning parameters for reasoning models
                 if is_reasoning_model:
-                    extra_body["reasoning_effort"] = self.reasoning_effort
                     extra_body["include_reasoning"] = False
                 call_params["extra_body"] = extra_body
 

{hindsight_api-0.1.7 → hindsight_api-0.1.9}/hindsight_api/engine/memory_engine.py

@@ -311,7 +311,7 @@ class MemoryEngine:
                 pool = await self._get_pool()
                 async with acquire_with_retry(pool) as conn:
                     result = await conn.fetchrow(
-                        "SELECT id FROM async_operations WHERE id = $1", uuid.UUID(operation_id)
+                        "SELECT operation_id FROM async_operations WHERE operation_id = $1", uuid.UUID(operation_id)
                     )
                     if not result:
                         # Operation was cancelled, skip processing
@@ -369,7 +369,7 @@ class MemoryEngine:
         try:
             pool = await self._get_pool()
             async with acquire_with_retry(pool) as conn:
-                await conn.execute("DELETE FROM async_operations WHERE id = $1", uuid.UUID(operation_id))
+                await conn.execute("DELETE FROM async_operations WHERE operation_id = $1", uuid.UUID(operation_id))
         except Exception as e:
             logger.error(f"Failed to delete async operation record {operation_id}: {e}")
 
@@ -386,7 +386,7 @@ class MemoryEngine:
                     """
                     UPDATE async_operations
                     SET status = 'failed', error_message = $2
-                    WHERE id = $1
+                    WHERE operation_id = $1
                     """,
                     uuid.UUID(operation_id),
                     truncated_error,

{hindsight_api-0.1.7 → hindsight_api-0.1.9}/hindsight_api/engine/retain/orchestrator.py

@@ -107,6 +107,10 @@ async def retain_batch(
     )
 
     if not extracted_facts:
+        total_time = time.time() - start_time
+        logger.info(
+            f"RETAIN_BATCH COMPLETE: 0 facts extracted from {len(contents)} contents in {total_time:.3f}s (nothing to store)"
+        )
         return [[] for _ in contents]
 
     # Apply fact_type_override if provided

{hindsight_api-0.1.7 → hindsight_api-0.1.9}/hindsight_api/main.py

@@ -127,8 +127,10 @@ def main():
             port=args.port,
             log_level=args.log_level,
             mcp_enabled=config.mcp_enabled,
+            graph_retriever=config.graph_retriever,
         )
     config.configure_logging()
+    config.log_config()
 
     # Register cleanup handlers
     atexit.register(_cleanup)

{hindsight_api-0.1.7 → hindsight_api-0.1.9}/hindsight_api/mcp_local.py

@@ -28,7 +28,15 @@ Environment variables:
     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").
+    HINDSIGHT_API_LOG_LEVEL: Optional. Log level (default: "warning").
+    HINDSIGHT_API_MCP_INSTRUCTIONS: Optional. Additional instructions appended to both retain and recall tools.
+
+Example custom instructions (these are ADDED to the default behavior):
+    To also store assistant actions:
+        HINDSIGHT_API_MCP_INSTRUCTIONS="Also store every action you take, including tool calls, code written, and decisions made."
+
+    To also store conversation summaries:
+        HINDSIGHT_API_MCP_INSTRUCTIONS="Also store summaries of important conversations and their outcomes."
 """
 
 import logging
@@ -36,14 +44,19 @@ import os
 import sys
 
 from mcp.server.fastmcp import FastMCP
+from mcp.types import Icon
 
 from hindsight_api.config import (
     DEFAULT_MCP_LOCAL_BANK_ID,
+    DEFAULT_MCP_RECALL_DESCRIPTION,
+    DEFAULT_MCP_RETAIN_DESCRIPTION,
+    ENV_MCP_INSTRUCTIONS,
     ENV_MCP_LOCAL_BANK_ID,
 )
 
-# Configure logging - default to info
-_log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "info").lower()
+# Configure logging - default to warning to avoid polluting stderr during MCP init
+# MCP clients interpret stderr output as errors, so we suppress INFO logs by default
+_log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "warning").lower()
 _log_level_map = {
     "critical": logging.CRITICAL,
     "error": logging.ERROR,
@@ -79,22 +92,21 @@ def create_local_mcp_server(bank_id: str, memory=None) -> FastMCP:
     if memory is None:
         memory = MemoryEngine(db_url="pg0://hindsight-mcp")
 
+    # Get custom instructions from environment variable (appended to both tools)
+    extra_instructions = os.environ.get(ENV_MCP_INSTRUCTIONS, "")
+
+    retain_description = DEFAULT_MCP_RETAIN_DESCRIPTION
+    recall_description = DEFAULT_MCP_RECALL_DESCRIPTION
+
+    if extra_instructions:
+        retain_description = f"{DEFAULT_MCP_RETAIN_DESCRIPTION}\n\nAdditional instructions: {extra_instructions}"
+        recall_description = f"{DEFAULT_MCP_RECALL_DESCRIPTION}\n\nAdditional instructions: {extra_instructions}"
+
     mcp = FastMCP("hindsight")
 
-    @mcp.tool()
+    @mcp.tool(description=retain_description)
     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'
@@ -111,17 +123,9 @@ def create_local_mcp_server(bank_id: str, memory=None) -> FastMCP:
         asyncio.create_task(_retain())
         return {"status": "accepted", "message": "Memory storage initiated"}
 
-    @mcp.tool()
+    @mcp.tool(description=recall_description)
     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)
@@ -153,10 +157,9 @@ async def _initialize_and_run(bank_id: str):
     from hindsight_api import MemoryEngine
 
     # Create and initialize memory engine with pg0 embedded database
-    print("Initializing memory engine...", file=sys.stderr)
+    # Note: We avoid printing to stderr during init as MCP clients show it as "errors"
     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)
@@ -179,8 +182,8 @@ def main():
     # 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)
+    # Note: We don't print to stderr as MCP clients display it as "error output"
+    # Use HINDSIGHT_API_LOG_LEVEL=debug for verbose startup logging
 
     # Run the async initialization and server
     asyncio.run(_initialize_and_run(bank_id))

{hindsight_api-0.1.7 → hindsight_api-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hindsight-api"
-version = "0.1.7"
+version = "0.1.9"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"