tribalmemory 0.2.0__tar.gz → 0.3.0__tar.gz

{tribalmemory-0.2.0 → tribalmemory-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tribalmemory
-Version: 0.2.0
+Version: 0.3.0
 Summary: Shared memory infrastructure for multi-instance AI agents
 Author-email: Joe <joe@example.com>
 License: Apache-2.0

{tribalmemory-0.2.0 → tribalmemory-0.3.0}/pyproject.toml

@@ -7,7 +7,7 @@ where = ["src"]
 
 [project]
 name = "tribalmemory"
-version = "0.2.0"
+version = "0.3.0"
 description = "Shared memory infrastructure for multi-instance AI agents"
 readme = "README.md"
 license = {text = "Apache-2.0"}

{tribalmemory-0.2.0 → tribalmemory-0.3.0}/src/tribalmemory/interfaces.py

@@ -7,9 +7,12 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
-from typing import Optional
+from typing import Literal, Optional
 import uuid
 
+# Valid retrieval methods for RecallResult
+RetrievalMethod = Literal["vector", "graph", "hybrid", "entity"]
+
 
 class MemorySource(Enum):
     """Source of a memory entry."""
@@ -69,13 +72,21 @@ class MemoryEntry:
 
 @dataclass
 class RecallResult:
-    """Result of a memory recall query."""
+    """Result of a memory recall query.
+    
+    Attributes:
+        memory: The recalled memory entry.
+        similarity_score: Relevance score (0.0-1.0 for vector, 1.0 for exact entity match).
+        retrieval_time_ms: Time taken for retrieval.
+        retrieval_method: How this result was found (see RetrievalMethod type).
+    """
     memory: MemoryEntry
     similarity_score: float
     retrieval_time_ms: float
+    retrieval_method: RetrievalMethod = "vector"
     
     def __repr__(self) -> str:
-        return f"RecallResult(score={self.similarity_score:.3f}, memory_id={self.memory.id[:8]}...)"
+        return f"RecallResult(score={self.similarity_score:.3f}, method={self.retrieval_method}, memory_id={self.memory.id[:8]}...)"
 
 
 @dataclass
@@ -315,6 +326,7 @@ class IMemoryService(ABC):
         limit: int = 5,
         min_relevance: float = 0.7,
         tags: Optional[list[str]] = None,
+        graph_expansion: bool = True,
     ) -> list[RecallResult]:
         """Recall relevant memories for a query.
         
@@ -323,6 +335,13 @@ class IMemoryService(ABC):
             limit: Maximum results
             min_relevance: Minimum similarity score
             tags: Filter by tags (e.g., ["work", "preferences"])
+            graph_expansion: Expand candidates via entity graph (default True)
+        
+        Returns:
+            List of RecallResult objects with retrieval_method indicating source:
+            - "vector": Vector similarity search
+            - "hybrid": Vector + BM25 merge
+            - "graph": Entity graph traversal
         """
         pass
     

{tribalmemory-0.2.0 → tribalmemory-0.3.0}/src/tribalmemory/mcp/server.py

@@ -412,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,