hindsight-api 0.0.15__py3-none-any.whl → 0.0.17__py3-none-any.whl

hindsight_api/api/__init__.py

@@ -62,14 +62,13 @@ def create_app(
     # Mount MCP server if enabled
     if mcp_api_enabled:
         try:
-            from .mcp import create_mcp_server
+            from .mcp import create_mcp_app
 
-            # Create MCP server with shared memory instance
-            mcp_server = create_mcp_server(memory=memory)
-
-            # Mount at specified path using http_app (modern non-SSE alternative)
-            app.mount(mcp_mount_path, mcp_server.http_app())
-            logger.info(f"MCP server enabled at {mcp_mount_path}")
+            # Create MCP app with dynamic bank_id support
+            # Supports: /mcp/{bank_id}/sse (bank-specific SSE endpoint)
+            mcp_app = create_mcp_app(memory=memory)
+            app.mount(mcp_mount_path, mcp_app)
+            logger.info(f"MCP server enabled at {mcp_mount_path}/{{bank_id}}/sse")
         except ImportError as e:
             logger.error(f"MCP server requested but dependencies not available: {e}")
             logger.error("Install with: pip install hindsight-api[mcp]")

hindsight_api/api/mcp.py

@@ -3,6 +3,8 @@
 import json
 import logging
 import os
+from contextvars import ContextVar
+from typing import Optional
 
 from fastmcp import FastMCP
 from hindsight_api import MemoryEngine
@@ -17,6 +19,14 @@ logging.basicConfig(
 )
 logger = logging.getLogger(__name__)
 
+# Context variable to hold the current bank_id from the URL path
+_current_bank_id: ContextVar[Optional[str]] = ContextVar("current_bank_id", default=None)
+
+
+def get_current_bank_id() -> Optional[str]:
+    """Get the current bank_id from context (set from URL path)."""
+    return _current_bank_id.get()
+
 
 def create_mcp_server(memory: MemoryEngine) -> FastMCP:
     """
@@ -28,125 +38,71 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
     Returns:
         Configured FastMCP server instance
     """
-    # Create FastMCP server
     mcp = FastMCP("hindsight-mcp-server")
 
     @mcp.tool()
-    async def hindsight_put(bank_id: str, content: str, context: str, explanation: str = "") -> str:
+    async def retain(content: str, context: str = "general") -> str:
         """
-        **CRITICAL: Store important user information to long-term memory.**
-
-        **⚠️ PER-USER TOOL - REQUIRES USER IDENTIFICATION:**
-        - This tool is STRICTLY per-user. Each user MUST have a unique `bank_id`.
-        - ONLY use this tool if you have a valid user identifier (user ID, email, session ID, etc.) to map to `bank_id`.
-        - DO NOT use this tool if you cannot identify the specific user.
-        - DO NOT share memories between different users - each user's memories are isolated by their `bank_id`.
-        - If you don't have a user identifier, DO NOT use this tool at all.
+        Store important information to long-term memory.
 
         Use this tool PROACTIVELY whenever the user shares:
-        - Personal facts, preferences, or interests (e.g., "I love hiking", "I'm a vegetarian")
-        - Important events or milestones (e.g., "I got promoted", "My birthday is June 15")
-        - User history, experiences, or background (e.g., "I used to work at Google", "I studied CS at MIT")
-        - Decisions, opinions, or stated preferences (e.g., "I prefer Python over JavaScript")
-        - Goals, plans, or future intentions (e.g., "I'm planning to visit Japan next year")
-        - Relationships or people mentioned (e.g., "My manager Sarah", "My wife Alice")
+        - 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
-        - Any other information the user would want remembered for future conversations
-
-        **When to use**: Immediately after user shares personal information. Don't ask permission - just store it naturally.
-
-        **Context guidelines**: Use descriptive contexts like "personal_preferences", "work_history", "family", "hobbies",
-        "career_goals", "project_details", etc. This helps organize and retrieve related memories later.
 
         Args:
-            bank_id: **REQUIRED** - The unique, persistent identifier for this specific user (e.g., user_id, email, session_id).
-                     This MUST be consistent across all interactions with the same user.
-                     Example: "user_12345", "alice@example.com", "session_abc123"
             content: The fact/memory to store (be specific and include relevant details)
-            context: Categorize the memory (e.g., 'personal_preferences', 'work_history', 'hobbies', 'family')
-            explanation: Optional explanation for why this memory is being stored
+            context: Category for the memory (e.g., 'preferences', 'work', 'hobbies', 'family'). Default: 'general'
         """
         try:
-            # Log explanation if provided
-            if explanation:
-                pass  # Explanation provided
-
-            # Store memory using put_batch_async
+            bank_id = get_current_bank_id()
             await memory.put_batch_async(
                 bank_id=bank_id,
                 contents=[{"content": content, "context": context}]
             )
-            return f"Fact stored successfully"
+            return "Memory stored successfully"
         except Exception as e:
-            logger.error(f"Error storing fact: {e}", exc_info=True)
+            logger.error(f"Error storing memory: {e}", exc_info=True)
             return f"Error: {str(e)}"
 
     @mcp.tool()
-    async def hindsight_search(bank_id: str, query: str, max_tokens: int = 4096, explanation: str = "") -> str:
+    async def recall(query: str, max_results: int = 10) -> str:
         """
-        **CRITICAL: Search user's memory to provide personalized, context-aware responses.**
-
-        **⚠️ PER-USER TOOL - REQUIRES USER IDENTIFICATION:**
-        - This tool is STRICTLY per-user. Each user MUST have a unique `bank_id`.
-        - ONLY use this tool if you have a valid user identifier (user ID, email, session ID, etc.) to map to `bank_id`.
-        - DO NOT use this tool if you cannot identify the specific user.
-        - DO NOT search across multiple users - each user's memories are isolated by their `bank_id`.
-        - If you don't have a user identifier, DO NOT use this tool at all.
-
-        Use this tool PROACTIVELY at the start of conversations or when making recommendations to:
-        - Check user's preferences before making suggestions (e.g., "what foods does the user like?")
-        - Recall user's history to provide continuity (e.g., "what projects has the user worked on?")
-        - Remember user's goals and context (e.g., "what is the user trying to accomplish?")
-        - Avoid repeating information or asking questions you should already know
-        - Personalize responses based on user's background, interests, and past interactions
-        - Reference past conversations or events the user mentioned
-
-        **When to use**:
-        - Start of conversation: Search for relevant context about the user
-        - Before recommendations: Check user preferences and past experiences
-        - When user asks about something they may have mentioned before
-        - To provide continuity across conversations
-
-        **Search tips**: Use natural language queries like "user's programming language preferences",
-        "user's work experience", "user's dietary restrictions", "what does the user know about X?"
+        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:
-            bank_id: **REQUIRED** - The unique, persistent identifier for this specific user (e.g., user_id, email, session_id).
-                     This MUST be consistent across all interactions with the same user.
-                     Example: "user_12345", "alice@example.com", "session_abc123"
-            query: Natural language search query to find relevant memories
-            max_tokens: Maximum tokens for search context (default: 4096)
-            explanation: Optional explanation for why this search is being performed
+            query: Natural language search query (e.g., "user's food preferences", "what projects is user working on")
+            max_results: Maximum number of results to return (default: 10)
         """
         try:
-            # Log all parameters for debugging
-            logger.info(f"hindsight_search called with: query={query!r}, max_tokens={max_tokens}, explanation={explanation!r}")
-
-            # Log explanation if provided
-            if explanation:
-                pass  # Explanation provided
-
-            # Search using recall_async
+            bank_id = get_current_bank_id()
             from hindsight_api.engine.memory_engine import Budget
             search_result = await memory.recall_async(
                 bank_id=bank_id,
                 query=query,
-                fact_type=["world", "bank", "opinion"],  # Search all fact types
-                max_tokens=max_tokens,
+                fact_type=["world", "bank", "opinion"],
                 budget=Budget.LOW
             )
 
-            # Convert results to dict format
             results = [
                 {
                     "id": fact.id,
                     "text": fact.text,
                     "type": fact.fact_type,
                     "context": fact.context,
-                    "event_date": fact.event_date,  # Already a string from the database
-                    "document_id": fact.document_id
+                    "event_date": fact.event_date,
                 }
-                for fact in search_result.results
+                for fact in search_result.results[:max_results]
             ]
 
             return json.dumps({"results": results}, indent=2)
@@ -155,3 +111,104 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
             return json.dumps({"error": str(e), "results": []})
 
     return mcp
+
+
+class MCPMiddleware:
+    """ASGI middleware that extracts bank_id from path and sets context."""
+
+    def __init__(self, app, memory: MemoryEngine):
+        self.app = app
+        self.memory = memory
+        self.mcp_server = create_mcp_server(memory)
+        # Use sse_app - http_app requires lifespan management that's complex with middleware
+        import warnings
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            self.mcp_app = self.mcp_server.sse_app()
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            await self.mcp_app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+
+        # Strip any mount prefix (e.g., /mcp) that FastAPI might not have stripped
+        root_path = scope.get("root_path", "")
+        if root_path and path.startswith(root_path):
+            path = path[len(root_path):] or "/"
+
+        # Also handle case where mount path wasn't stripped (e.g., /mcp/...)
+        if path.startswith("/mcp/"):
+            path = path[4:]  # Remove /mcp prefix
+
+        # Extract bank_id from path: /{bank_id}/ or /{bank_id}
+        # http_app expects requests at /
+        if not path.startswith("/") or len(path) <= 1:
+            # No bank_id in path - return error
+            await self._send_error(send, 400, "bank_id required in path: /mcp/{bank_id}/")
+            return
+
+        # Extract bank_id from first path segment
+        parts = path[1:].split("/", 1)
+        if not parts[0]:
+            await self._send_error(send, 400, "bank_id required in path: /mcp/{bank_id}/")
+            return
+
+        bank_id = parts[0]
+        new_path = "/" + parts[1] if len(parts) > 1 else "/"
+
+        # Set bank_id context
+        token = _current_bank_id.set(bank_id)
+        try:
+            new_scope = scope.copy()
+            new_scope["path"] = new_path
+
+            # Wrap send to rewrite the SSE endpoint URL to include bank_id
+            # The SSE app sends "event: endpoint\ndata: /messages\n" but we need
+            # the client to POST to /{bank_id}/messages instead
+            async def send_wrapper(message):
+                if message["type"] == "http.response.body":
+                    body = message.get("body", b"")
+                    if body and b"/messages" in body:
+                        # Rewrite /messages to /{bank_id}/messages in SSE endpoint event
+                        body = body.replace(
+                            b"data: /messages",
+                            f"data: /{bank_id}/messages".encode()
+                        )
+                        message = {**message, "body": body}
+                await send(message)
+
+            await self.mcp_app(new_scope, receive, send_wrapper)
+        finally:
+            _current_bank_id.reset(token)
+
+    async def _send_error(self, send, status: int, message: str):
+        """Send an error response."""
+        body = json.dumps({"error": message}).encode()
+        await send({
+            "type": "http.response.start",
+            "status": status,
+            "headers": [(b"content-type", b"application/json")],
+        })
+        await send({
+            "type": "http.response.body",
+            "body": body,
+        })
+
+
+def create_mcp_app(memory: MemoryEngine):
+    """
+    Create an ASGI app that handles MCP requests.
+
+    URL pattern: /mcp/{bank_id}/
+
+    The bank_id is extracted from the URL path and made available to tools.
+
+    Args:
+        memory: MemoryEngine instance
+
+    Returns:
+        ASGI application
+    """
+    return MCPMiddleware(None, memory)

hindsight_api/cli.py

@@ -0,0 +1,128 @@
+"""
+Command-line interface for Hindsight API.
+
+Run the server with:
+    hindsight-api
+
+Stop with Ctrl+C.
+"""
+import argparse
+import asyncio
+import atexit
+import os
+import signal
+import sys
+from typing import Optional
+
+import uvicorn
+
+from . import MemoryEngine
+from .api import create_app
+
+
+# Disable tokenizers parallelism to avoid warnings
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+# Global reference for cleanup
+_memory: Optional[MemoryEngine] = None
+
+
+def _cleanup():
+    """Synchronous cleanup function to stop resources on exit."""
+    global _memory
+    if _memory is not None and _memory._pg0 is not None:
+        try:
+            loop = asyncio.new_event_loop()
+            loop.run_until_complete(_memory._pg0.stop())
+            loop.close()
+            print("\npg0 stopped.")
+        except Exception as e:
+            print(f"\nError stopping pg0: {e}")
+
+
+def _signal_handler(signum, frame):
+    """Handle SIGINT/SIGTERM to ensure cleanup."""
+    print(f"\nReceived signal {signum}, shutting down...")
+    _cleanup()
+    sys.exit(0)
+
+
+def main():
+    """Main entry point for the CLI."""
+    global _memory
+
+    parser = argparse.ArgumentParser(
+        prog="hindsight-api",
+        description="Hindsight API Server",
+    )
+    parser.add_argument(
+        "--host", default="0.0.0.0",
+        help="Host to bind to (default: 0.0.0.0)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=8888,
+        help="Port to bind to (default: 8888)"
+    )
+    parser.add_argument(
+        "--log-level", default="info",
+        choices=["critical", "error", "warning", "info", "debug", "trace"],
+        help="Log level (default: info)"
+    )
+    parser.add_argument(
+        "--access-log", action="store_true",
+        help="Enable access log"
+    )
+
+    args = parser.parse_args()
+
+    # Register cleanup handlers
+    atexit.register(_cleanup)
+    signal.signal(signal.SIGINT, _signal_handler)
+    signal.signal(signal.SIGTERM, _signal_handler)
+
+    # Get configuration from environment variables
+    db_url = os.getenv("HINDSIGHT_API_DATABASE_URL", "pg0")
+    llm_provider = os.getenv("HINDSIGHT_API_LLM_PROVIDER", "groq")
+    llm_api_key = os.getenv("HINDSIGHT_API_LLM_API_KEY", "")
+    llm_model = os.getenv("HINDSIGHT_API_LLM_MODEL", "openai/gpt-oss-20b")
+    llm_base_url = os.getenv("HINDSIGHT_API_LLM_BASE_URL") or None
+
+    # Create MemoryEngine
+    _memory = MemoryEngine(
+        db_url=db_url,
+        memory_llm_provider=llm_provider,
+        memory_llm_api_key=llm_api_key,
+        memory_llm_model=llm_model,
+        memory_llm_base_url=llm_base_url,
+    )
+
+    # Create FastAPI app
+    app = create_app(
+        memory=_memory,
+        http_api_enabled=True,
+        mcp_api_enabled=True,
+        mcp_mount_path="/mcp",
+        run_migrations=True,
+        initialize_memory=True,
+    )
+
+    # Prepare uvicorn config
+    uvicorn_config = {
+        "app": app,
+        "host": args.host,
+        "port": args.port,
+        "log_level": args.log_level,
+        "access_log": args.access_log,
+    }
+
+    print(f"\nStarting Hindsight API...")
+    print(f"  URL: http://{args.host}:{args.port}")
+    print(f"  Database: {db_url}")
+    print(f"  LLM Provider: {llm_provider}")
+    print()
+
+    uvicorn.run(**uvicorn_config)
+
+
+if __name__ == "__main__":
+    main()

hindsight_api/web/server.py

@@ -10,13 +10,9 @@ import warnings
 warnings.filterwarnings("ignore", message="websockets.legacy is deprecated")
 warnings.filterwarnings("ignore", message="websockets.server.WebSocketServerProtocol is deprecated")
 
-import asyncio
-import atexit
 import logging
 import os
 import argparse
-import signal
-import sys
 
 from hindsight_api import MemoryEngine
 from hindsight_api.api import create_app
@@ -25,36 +21,6 @@ from hindsight_api.api import create_app
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
 
 
-def _cleanup_pg0():
-    """Synchronous cleanup function to stop pg0 on exit."""
-    global _memory
-    if _memory is not None and _memory._pg0 is not None:
-        try:
-            # Run async stop in a new event loop
-            loop = asyncio.new_event_loop()
-            loop.run_until_complete(_memory._pg0.stop())
-            loop.close()
-            print("\npg0 stopped.")
-        except Exception as e:
-            print(f"\nError stopping pg0: {e}")
-
-
-# Register cleanup on normal exit
-atexit.register(_cleanup_pg0)
-
-
-def _signal_handler(signum, frame):
-    """Handle SIGINT/SIGTERM to ensure pg0 cleanup."""
-    print(f"\nReceived signal {signum}, shutting down...")
-    _cleanup_pg0()
-    sys.exit(0)
-
-
-# Register signal handlers for graceful shutdown
-signal.signal(signal.SIGINT, _signal_handler)
-signal.signal(signal.SIGTERM, _signal_handler)
-
-
 # Create app at module level (required for uvicorn import string)
 _memory = MemoryEngine(
     db_url=os.getenv("HINDSIGHT_API_DATABASE_URL", "pg0"),
@@ -85,7 +51,7 @@ if __name__ == "__main__":
         env_log_level = "info"
 
     # Parse CLI arguments
-    parser = argparse.ArgumentParser(description="Memory Graph API Server")
+    parser = argparse.ArgumentParser(description="Hindsight API Server")
     parser.add_argument("--host", default="0.0.0.0", help="Host to bind to (default: 0.0.0.0)")
     parser.add_argument("--port", type=int, default=8888, help="Port to bind to (default: 8888)")
     parser.add_argument("--reload", action="store_true", help="Enable auto-reload on code changes")

{hindsight_api-0.0.15.dist-info → hindsight_api-0.0.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hindsight-api
-Version: 0.0.15
+Version: 0.0.17
 Summary: Temporal + Semantic + Entity Memory System for AI agents using PostgreSQL
 Requires-Python: >=3.11
 Requires-Dist: alembic>=1.17.1

{hindsight_api-0.0.15.dist-info → hindsight_api-0.0.17.dist-info}/RECORD

@@ -1,11 +1,12 @@
 hindsight_api/__init__.py,sha256=yQWYWUWEhvs1OY1coENhZV_CuOAWmN_YKZXQMIvGN94,851
+hindsight_api/cli.py,sha256=-dxAHsET_pHd6NlA3ufI4KEKQA3fL3YapCvDB_x2ax8,3303
 hindsight_api/metrics.py,sha256=j4-eeqVjjcGQxAxS_GgEaBNm10KdUxrGS_I2d1IM1hY,7255
 hindsight_api/migrations.py,sha256=VY-ILJLWEY1IaeJgQ2jlAVUtPLzq_41Dytg_DjuF0GA,6402
 hindsight_api/models.py,sha256=1vMn9jmDQvohfmxZXr1SYnhz5vhz52nrTd93A_lkVNE,12606
 hindsight_api/pg0.py,sha256=scFcYngOwbZ2oOQb7TysnUHgNgPyiN30pjPcIqMDmao,14158
-hindsight_api/api/__init__.py,sha256=cDqM1tXOk1aq5Hy__vJ97O4XOQUB4Qt-ea_szTnbQ3o,3037
+hindsight_api/api/__init__.py,sha256=lXxJythXFV1DXIQ--4QfIo5pHYmDYJnd41dfAssNTTA,3017
 hindsight_api/api/http.py,sha256=anjh8axWcWF1dyqW3CnE9TUObLKxryjeQxT_keQEMak,71551
-hindsight_api/api/mcp.py,sha256=NbRSbEGih7zCFMmwddLgD_UYv-WjvwYWHLq2-vzz4SA,7862
+hindsight_api/api/mcp.py,sha256=1fqeKBh3K0lJ5jodYysOTnDOWNjSzA08g8v2_k8HOlU,7734
 hindsight_api/engine/__init__.py,sha256=5DU5DvnJdzkrgNgKchpzkiJr-37I-kE1tegJg2LF04k,1214
 hindsight_api/engine/cross_encoder.py,sha256=kfwLiqlQUfvOgLyrkRReO1wWlO020lGbLXY8U0jKiPA,2875
 hindsight_api/engine/db_utils.py,sha256=p1Ne70wPP327xdPI_XjMfnagilY8sknbkhEIZuED6DU,2724
@@ -42,7 +43,8 @@ hindsight_api/engine/search/trace.py,sha256=GT86_LVKMyG2mw6EJzPjafvbqaot6XVy5fZ0
 hindsight_api/engine/search/tracer.py,sha256=mcM9qZpj3YFudrBCESwc6YKNAiWIMx1lScXWn5ru-ok,15017
 hindsight_api/engine/search/types.py,sha256=qIeHW_gT7f291vteTZXygAM8oAaPp2dq6uEdvOyOwzs,5488
 hindsight_api/web/__init__.py,sha256=WABqyqiAVFJJWOhKCytkj5Vcb61eAsRib3Ek7IMX6_U,378
-hindsight_api/web/server.py,sha256=oPNJ_z4DO38MdK7Juyh2LdH0ipZ_BQF48cUM-4B_Uw0,5379
-hindsight_api-0.0.15.dist-info/METADATA,sha256=bXvuwqAtqB2mCaDUCkiJ8t5tw085gMLWDLsGhFHF9Bo,1496
-hindsight_api-0.0.15.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-hindsight_api-0.0.15.dist-info/RECORD,,
+hindsight_api/web/server.py,sha256=l-Tw8G9IRdcSay-KWiUT4VlIJBzxbe-TV0rjX0fwLMc,4464
+hindsight_api-0.0.17.dist-info/METADATA,sha256=zan_1uOEwAxlipqrDA0Rc65zs-e-AqxRoT38ihKtLQw,1496
+hindsight_api-0.0.17.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+hindsight_api-0.0.17.dist-info/entry_points.txt,sha256=53Fn-VxtkqreZhOPTJB_FupH7e5GyiMY3gzEp22d8xs,57
+hindsight_api-0.0.17.dist-info/RECORD,,

hindsight_api-0.0.17.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hindsight-api = hindsight_api.cli:main