tribalmemory 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

tribalmemory/mcp/server.py

@@ -16,11 +16,13 @@ from mcp.server.fastmcp import FastMCP
 from ..interfaces import MemorySource
 from ..server.config import TribalMemoryConfig
 from ..services import create_memory_service, TribalMemoryService
+from ..services.session_store import SessionStore, SessionMessage
 
 logger = logging.getLogger(__name__)
 
 # Global service instance (initialized on first use)
 _memory_service: Optional[TribalMemoryService] = None
+_session_store: Optional[SessionStore] = None
 _service_lock = asyncio.Lock()
 
 
@@ -60,6 +62,32 @@ async def get_memory_service() -> TribalMemoryService:
     return _memory_service
 
 
+async def get_session_store() -> SessionStore:
+    """Get or create the session store singleton (thread-safe)."""
+    global _session_store
+    
+    if _session_store is not None:
+        return _session_store
+    
+    memory_service = await get_memory_service()
+    
+    async with _service_lock:
+        if _session_store is not None:
+            return _session_store
+        
+        config = TribalMemoryConfig.from_env()
+        instance_id = os.environ.get("TRIBAL_MEMORY_INSTANCE_ID", "mcp-claude-code")
+        
+        _session_store = SessionStore(
+            instance_id=instance_id,
+            embedding_service=memory_service.embedding_service,
+            vector_store=memory_service.vector_store,
+        )
+        logger.info("Session store initialized")
+    
+    return _session_store
+
+
 def create_server() -> FastMCP:
     """Create and configure the MCP server with all tools."""
     mcp = FastMCP("tribal-memory")
@@ -127,17 +155,19 @@ def create_server() -> FastMCP:
         limit: int = 5,
         min_relevance: float = 0.3,
         tags: Optional[list[str]] = None,
+        sources: str = "memories",
     ) -> str:
-        """Search memories by semantic similarity.
+        """Search memories and/or session transcripts by semantic similarity.
 
         Args:
             query: Natural language search query (required)
             limit: Maximum number of results (1-50, default 5)
             min_relevance: Minimum similarity score (0.0-1.0, default 0.3)
             tags: Filter results to only memories with these tags
+            sources: What to search - "memories" (default), "sessions", or "all"
 
         Returns:
-            JSON with: results (list of memories with similarity scores), query, count
+            JSON with: results (list of memories/chunks with similarity scores), query, count
         """
         # Input validation
         if not query or not query.strip():
@@ -148,22 +178,33 @@ def create_server() -> FastMCP:
                 "error": "Query cannot be empty",
             })
         
-        service = await get_memory_service()
+        valid_sources = {"memories", "sessions", "all"}
+        if sources not in valid_sources:
+            return json.dumps({
+                "results": [],
+                "query": query,
+                "count": 0,
+                "error": f"Invalid sources: {sources}. Valid options: {', '.join(sorted(valid_sources))}",
+            })
 
         # Clamp limit to valid range
         limit = max(1, min(50, limit))
         min_relevance = max(0.0, min(1.0, min_relevance))
 
-        results = await service.recall(
-            query=query,
-            limit=limit,
-            min_relevance=min_relevance,
-            tags=tags,
-        )
+        all_results = []
 
-        return json.dumps({
-            "results": [
+        # Search memories
+        if sources in ("memories", "all"):
+            service = await get_memory_service()
+            memory_results = await service.recall(
+                query=query,
+                limit=limit,
+                min_relevance=min_relevance,
+                tags=tags,
+            )
+            all_results.extend([
                 {
+                    "type": "memory",
                     "memory_id": r.memory.id,
                     "content": r.memory.content,
                     "similarity_score": round(r.similarity_score, 4),
@@ -173,12 +214,117 @@ def create_server() -> FastMCP:
                     "created_at": r.memory.created_at.isoformat(),
                     "context": r.memory.context,
                 }
-                for r in results
-            ],
+                for r in memory_results
+            ])
+
+        # Search sessions
+        if sources in ("sessions", "all"):
+            session_store = await get_session_store()
+            session_results = await session_store.search(
+                query=query,
+                limit=limit,
+                min_relevance=min_relevance,
+            )
+            all_results.extend([
+                {
+                    "type": "session",
+                    "chunk_id": r["chunk_id"],
+                    "session_id": r["session_id"],
+                    "instance_id": r["instance_id"],
+                    "content": r["content"],
+                    "similarity_score": round(r["similarity_score"], 4),
+                    "start_time": r["start_time"].isoformat() if hasattr(r["start_time"], "isoformat") else str(r["start_time"]),
+                    "end_time": r["end_time"].isoformat() if hasattr(r["end_time"], "isoformat") else str(r["end_time"]),
+                    "chunk_index": r["chunk_index"],
+                }
+                for r in session_results
+            ])
+
+        # Sort combined results by score, take top limit
+        all_results.sort(key=lambda x: x["similarity_score"], reverse=True)
+        all_results = all_results[:limit]
+
+        return json.dumps({
+            "results": all_results,
             "query": query,
-            "count": len(results),
+            "count": len(all_results),
+            "sources": sources,
         })
 
+    @mcp.tool()
+    async def tribal_sessions_ingest(
+        session_id: str,
+        messages: str,
+        instance_id: Optional[str] = None,
+    ) -> str:
+        """Ingest a session transcript for indexing.
+
+        Chunks conversation messages into ~400 token windows and indexes them
+        for semantic search. Supports delta ingestion — only new messages
+        since last ingest are processed.
+
+        Args:
+            session_id: Unique identifier for the session (required)
+            messages: JSON array of messages, each with "role", "content",
+                and optional "timestamp" (ISO 8601). Example:
+                [{"role": "user", "content": "What is Docker?"},
+                 {"role": "assistant", "content": "Docker is a container platform"}]
+            instance_id: Override the agent instance ID (optional)
+
+        Returns:
+            JSON with: success, chunks_created, messages_processed
+        """
+        if not session_id or not session_id.strip():
+            return json.dumps({
+                "success": False,
+                "error": "session_id cannot be empty",
+            })
+
+        try:
+            raw_messages = json.loads(messages)
+        except (json.JSONDecodeError, TypeError) as e:
+            return json.dumps({
+                "success": False,
+                "error": f"Invalid messages JSON: {e}",
+            })
+
+        if not isinstance(raw_messages, list):
+            return json.dumps({
+                "success": False,
+                "error": "messages must be a JSON array",
+            })
+
+        from datetime import datetime, timezone
+        parsed_messages = []
+        for i, msg in enumerate(raw_messages):
+            if not isinstance(msg, dict) or "role" not in msg or "content" not in msg:
+                return json.dumps({
+                    "success": False,
+                    "error": f"Message {i} must have 'role' and 'content' fields",
+                })
+            
+            ts = datetime.now(timezone.utc)
+            if "timestamp" in msg:
+                try:
+                    ts = datetime.fromisoformat(msg["timestamp"])
+                except (ValueError, TypeError):
+                    pass  # Use current time if timestamp is invalid
+            
+            parsed_messages.append(SessionMessage(
+                role=msg["role"],
+                content=msg["content"],
+                timestamp=ts,
+            ))
+
+        session_store = await get_session_store()
+        result = await session_store.ingest(
+            session_id=session_id,
+            messages=parsed_messages,
+            instance_id=instance_id,
+        )
+
+        return json.dumps(result)
+
     @mcp.tool()
     async def tribal_correct(
         original_id: str,
@@ -266,6 +412,118 @@ def create_server() -> FastMCP:
 
         return json.dumps(stats)
 
+    @mcp.tool()
+    async def tribal_recall_entity(
+        entity_name: str,
+        hops: int = 1,
+        limit: int = 10,
+    ) -> str:
+        """Recall memories associated with an entity and its connections.
+
+        Enables entity-centric queries like:
+        - "Tell me everything about auth-service"
+        - "What do we know about PostgreSQL?"
+        - "What services connect to the user database?"
+
+        Args:
+            entity_name: Name of the entity to query (required).
+                Examples: "auth-service", "PostgreSQL", "user-db"
+            hops: Number of relationship hops to traverse (default 1).
+                1 = direct connections only
+                2 = connections of connections
+            limit: Maximum number of results (1-50, default 10)
+
+        Returns:
+            JSON with: results (list of memories), entity, hops, count
+        """
+        if not entity_name or not entity_name.strip():
+            return json.dumps({
+                "results": [],
+                "entity": entity_name,
+                "hops": hops,
+                "count": 0,
+                "error": "Entity name cannot be empty",
+            })
+
+        hops = max(1, min(10, hops))  # Clamp to reasonable range
+        limit = max(1, min(50, limit))
+
+        service = await get_memory_service()
+        
+        if not service.graph_enabled:
+            return json.dumps({
+                "results": [],
+                "entity": entity_name,
+                "hops": hops,
+                "count": 0,
+                "error": "Graph search not enabled. Requires db_path for persistent storage.",
+            })
+
+        results = await service.recall_entity(
+            entity_name=entity_name,
+            hops=hops,
+            limit=limit,
+        )
+
+        return json.dumps({
+            "results": [
+                {
+                    "memory_id": r.memory.id,
+                    "content": r.memory.content,
+                    "source_type": r.memory.source_type.value,
+                    "source_instance": r.memory.source_instance,
+                    "tags": r.memory.tags,
+                    "created_at": r.memory.created_at.isoformat(),
+                }
+                for r in results
+            ],
+            "entity": entity_name,
+            "hops": hops,
+            "count": len(results),
+        })
+
+    @mcp.tool()
+    async def tribal_entity_graph(
+        entity_name: str,
+        hops: int = 2,
+    ) -> str:
+        """Get the relationship graph around an entity.
+
+        Useful for understanding how concepts/services/technologies
+        are connected in your project knowledge base.
+
+        Args:
+            entity_name: Name of the entity to explore (required)
+            hops: How many relationship hops to include (default 2)
+
+        Returns:
+            JSON with: entities (list with name/type), relationships (list with source/target/type)
+        """
+        if not entity_name or not entity_name.strip():
+            return json.dumps({
+                "entities": [],
+                "relationships": [],
+                "error": "Entity name cannot be empty",
+            })
+
+        hops = max(1, min(5, hops))  # Clamp to reasonable range
+
+        service = await get_memory_service()
+        
+        if not service.graph_enabled:
+            return json.dumps({
+                "entities": [],
+                "relationships": [],
+                "error": "Graph search not enabled. Requires db_path for persistent storage.",
+            })
+
+        graph = service.get_entity_graph(
+            entity_name=entity_name,
+            hops=hops,
+        )
+
+        return json.dumps(graph)
+
     @mcp.tool()
     async def tribal_export(
         tags: Optional[list[str]] = None,

tribalmemory/server/app.py

@@ -1,5 +1,6 @@
 """FastAPI application for tribal-memory service."""
 
+import asyncio
 import logging
 from contextlib import asynccontextmanager
 from pathlib import Path
@@ -10,11 +11,13 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from ..services import create_memory_service, TribalMemoryService
+from ..services.session_store import SessionStore
 from .config import TribalMemoryConfig
 from .routes import router
 
 # Global service instance (set during lifespan)
 _memory_service: Optional[TribalMemoryService] = None
+_session_store: Optional[SessionStore] = None
 _instance_id: Optional[str] = None
 
 logger = logging.getLogger("tribalmemory.server")
@@ -23,7 +26,7 @@ logger = logging.getLogger("tribalmemory.server")
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Application lifespan manager."""
-    global _memory_service, _instance_id
+    global _memory_service, _session_store, _instance_id
 
     config: TribalMemoryConfig = app.state.config
 
@@ -43,18 +46,66 @@ async def lifespan(app: FastAPI):
         api_base=config.embedding.api_base,
         embedding_model=config.embedding.model,
         embedding_dimensions=config.embedding.dimensions,
+        hybrid_search=config.search.hybrid_enabled,
+        hybrid_vector_weight=config.search.vector_weight,
+        hybrid_text_weight=config.search.text_weight,
+        hybrid_candidate_multiplier=config.search.candidate_multiplier,
     )
 
-    logger.info(f"Memory service initialized (db: {config.db.path})")
+    # Create session store (shares embedding service and vector store)
+    _session_store = SessionStore(
+        instance_id=config.instance_id,
+        embedding_service=_memory_service.embedding_service,
+        vector_store=_memory_service.vector_store,
+    )
+
+    search_mode = "hybrid (vector + BM25)" if config.search.hybrid_enabled else "vector-only"
+    logger.info(f"Memory service initialized (db: {config.db.path}, search: {search_mode})")
+    logger.info(f"Session store initialized (retention: {config.server.session_retention_days} days)")
+
+    # Start background session cleanup task
+    cleanup_task = asyncio.create_task(
+        _session_cleanup_loop(
+            _session_store,
+            config.server.session_retention_days,
+        )
+    )
 
     yield
 
     # Cleanup
+    cleanup_task.cancel()
+    try:
+        await cleanup_task
+    except asyncio.CancelledError:
+        pass
     logger.info("Shutting down tribal-memory service")
     _memory_service = None
+    _session_store = None
     _instance_id = None
 
 
+async def _session_cleanup_loop(
+    session_store: SessionStore,
+    retention_days: int,
+) -> None:
+    """Background task that periodically cleans up expired session chunks.
+    
+    Runs every 6 hours. Deletes session chunks older than retention_days.
+    """
+    cleanup_interval = 6 * 60 * 60  # 6 hours in seconds
+    while True:
+        try:
+            await asyncio.sleep(cleanup_interval)
+            deleted = await session_store.cleanup(retention_days=retention_days)
+            if deleted > 0:
+                logger.info(f"Session cleanup: deleted {deleted} expired chunks (retention: {retention_days} days)")
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.exception("Session cleanup failed")
+
+
 def create_app(config: Optional[TribalMemoryConfig] = None) -> FastAPI:
     """Create FastAPI application.
     

tribalmemory/server/config.py

@@ -51,6 +51,44 @@ class ServerConfig:
     """HTTP server configuration."""
     host: str = "127.0.0.1"
     port: int = 18790
+    session_retention_days: int = 30  # Days to retain session chunks
+
+
+@dataclass
+class SearchConfig:
+    """Search configuration for hybrid BM25 + vector search."""
+    hybrid_enabled: bool = True
+    vector_weight: float = 0.7
+    text_weight: float = 0.3
+    candidate_multiplier: int = 4
+    # Reranking configuration
+    reranking: str = "heuristic"  # "auto" | "cross-encoder" | "heuristic" | "none"
+    recency_decay_days: float = 30.0  # Half-life for recency boost
+    tag_boost_weight: float = 0.1  # Weight for tag match boost
+    rerank_pool_multiplier: int = 2  # How many candidates to give reranker (N * limit)
+
+    def __post_init__(self):
+        if self.vector_weight < 0:
+            raise ValueError("vector_weight must be non-negative")
+        if self.text_weight < 0:
+            raise ValueError("text_weight must be non-negative")
+        if self.vector_weight == 0 and self.text_weight == 0:
+            raise ValueError(
+                "At least one of vector_weight or text_weight must be > 0"
+            )
+        if self.candidate_multiplier < 1:
+            raise ValueError("candidate_multiplier must be >= 1")
+        if self.reranking not in ("auto", "cross-encoder", "heuristic", "none"):
+            raise ValueError(
+                f"Invalid reranking mode: {self.reranking}. "
+                f"Valid options: 'auto', 'cross-encoder', 'heuristic', 'none'"
+            )
+        if self.recency_decay_days <= 0:
+            raise ValueError("recency_decay_days must be positive")
+        if self.tag_boost_weight < 0:
+            raise ValueError("tag_boost_weight must be non-negative")
+        if self.rerank_pool_multiplier < 1:
+            raise ValueError("rerank_pool_multiplier must be >= 1")
 
 
 @dataclass
@@ -60,6 +98,7 @@ class TribalMemoryConfig:
     db: DatabaseConfig = field(default_factory=DatabaseConfig)
     embedding: EmbeddingConfig = field(default_factory=EmbeddingConfig)
     server: ServerConfig = field(default_factory=ServerConfig)
+    search: SearchConfig = field(default_factory=SearchConfig)
 
     @classmethod
     def from_file(cls, path: str | Path) -> "TribalMemoryConfig":
@@ -79,12 +118,14 @@ class TribalMemoryConfig:
         db_data = data.get("db", {})
         embedding_data = data.get("embedding", {})
         server_data = data.get("server", {})
+        search_data = data.get("search", {})
 
         return cls(
             instance_id=data.get("instance_id", "default"),
             db=DatabaseConfig(**db_data) if db_data else DatabaseConfig(),
             embedding=EmbeddingConfig(**embedding_data) if embedding_data else EmbeddingConfig(),
             server=ServerConfig(**server_data) if server_data else ServerConfig(),
+            search=SearchConfig(**search_data) if search_data else SearchConfig(),
         )
 
     @classmethod

tribalmemory/server/models.py

@@ -204,3 +204,68 @@ class ImportResponse(BaseModel):
     duration_ms: float = 0.0
     error_details: list[str] = Field(default_factory=list)
     error: Optional[str] = None
+
+# =============================================================================
+# Session Indexing Models (Issue #38)
+# =============================================================================
+
+class SessionMessageRequest(BaseModel):
+    """A single message in a session transcript."""
+    role: str = Field(..., description="Message role (user, assistant, system)")
+    content: str = Field(..., description="Message content")
+    timestamp: datetime = Field(..., description="When the message was sent")
+
+
+class SessionIngestRequest(BaseModel):
+    """Request to ingest session transcript."""
+    session_id: str = Field(..., description="Unique session identifier")
+    messages: list[SessionMessageRequest] = Field(
+        ..., description="Conversation messages to index"
+    )
+    instance_id: Optional[str] = Field(
+        default=None,
+        description="Override instance ID (defaults to server's instance_id)"
+    )
+
+
+class SessionIngestResponse(BaseModel):
+    """Response from session ingestion."""
+    success: bool
+    chunks_created: int = 0
+    messages_processed: int = 0
+    error: Optional[str] = None
+
+
+class SessionSearchRequest(BaseModel):
+    """Request to search session transcripts."""
+    query: str = Field(..., description="Natural language search query")
+    session_id: Optional[str] = Field(
+        default=None,
+        description="Filter to specific session (optional)"
+    )
+    limit: int = Field(default=5, ge=1, le=50, description="Maximum results")
+    min_relevance: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Minimum similarity score"
+    )
+
+
+class SessionChunkResponse(BaseModel):
+    """A session transcript chunk result."""
+    chunk_id: str
+    session_id: str
+    instance_id: str
+    content: str
+    similarity_score: float
+    start_time: datetime
+    end_time: datetime
+    chunk_index: int
+
+
+class SessionSearchResponse(BaseModel):
+    """Response from session search."""
+    results: list[SessionChunkResponse]
+    query: str
+    error: Optional[str] = None

tribalmemory/server/routes.py

@@ -7,6 +7,7 @@ from fastapi import APIRouter, HTTPException, Depends
 
 from ..interfaces import MemorySource, MemoryEntry
 from ..services import TribalMemoryService
+from ..services.session_store import SessionStore, SessionMessage
 from .models import (
     RememberRequest,
     RecallRequest,
@@ -24,6 +25,11 @@ from .models import (
     ExportResponse,
     ImportRequest,
     ImportResponse,
+    SessionIngestRequest,
+    SessionIngestResponse,
+    SessionSearchRequest,
+    SessionSearchResponse,
+    SessionChunkResponse,
 )
 
 router = APIRouter(prefix="/v1", tags=["memory"])
@@ -40,6 +46,17 @@ def get_memory_service() -> TribalMemoryService:
     return _memory_service
 
 
+def get_session_store() -> SessionStore:
+    """Dependency injection for session store.
+    
+    This is set by the app during startup.
+    """
+    from .app import _session_store
+    if _session_store is None:
+        raise HTTPException(status_code=503, detail="Session store not initialized")
+    return _session_store
+
+
 def get_instance_id() -> str:
     """Get the current instance ID."""
     from .app import _instance_id
@@ -376,3 +393,54 @@ async def shutdown() -> ShutdownResponse:
         0.5, lambda: os.kill(os.getpid(), signal.SIGTERM)
     )
     return ShutdownResponse(status="shutting_down")
+
+# =============================================================================
+# Session Indexing Routes (Issue #38)
+# =============================================================================
+
+@router.post("/sessions/ingest", response_model=SessionIngestResponse)
+async def ingest_session(
+    request: SessionIngestRequest,
+    store: SessionStore = Depends(get_session_store),
+    instance_id: str = Depends(get_instance_id),
+) -> SessionIngestResponse:
+    """Ingest a session transcript for indexing."""
+    try:
+        messages = [
+            SessionMessage(role=msg.role, content=msg.content, timestamp=msg.timestamp)
+            for msg in request.messages
+        ]
+        
+        result = await store.ingest(
+            session_id=request.session_id,
+            messages=messages,
+            instance_id=request.instance_id or instance_id,
+        )
+        
+        return SessionIngestResponse(
+            success=result.get("success", False),
+            chunks_created=result.get("chunks_created", 0),
+            messages_processed=result.get("messages_processed", 0),
+            error=result.get("error"),
+        )
+    except Exception as e:
+        return SessionIngestResponse(success=False, error=str(e))
+
+
+@router.get("/sessions/search", response_model=SessionSearchResponse)
+async def search_sessions(
+    query: str,
+    session_id: Optional[str] = None,
+    limit: int = 5,
+    min_relevance: float = 0.0,
+    store: SessionStore = Depends(get_session_store),
+) -> SessionSearchResponse:
+    """Search session transcripts by semantic similarity."""
+    try:
+        results = await store.search(query, session_id, limit, min_relevance)
+        return SessionSearchResponse(
+            results=[SessionChunkResponse(**r) for r in results],
+            query=query,
+        )
+    except Exception as e:
+        return SessionSearchResponse(results=[], query=query, error=str(e))