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

tribalmemory/cli.py

@@ -9,6 +9,7 @@ Usage:
 import argparse
 import json
 import os
+import shutil
 import sys
 from pathlib import Path
 
@@ -26,6 +27,36 @@ TRIBAL_DIR = Path.home() / ".tribal-memory"
 CONFIG_FILE = TRIBAL_DIR / "config.yaml"
 DEFAULT_INSTANCE_ID = "default"
 
+# Paths to global instructions files (relative to home)
+CLAUDE_INSTRUCTIONS_FILE = Path(".claude") / "CLAUDE.md"
+CODEX_INSTRUCTIONS_FILE = Path(".codex") / "AGENTS.md"
+
+# Section marker used to detect if auto-capture instructions already exist
+_AUTO_CAPTURE_MARKER = "## Tribal Memory — Auto-Capture"
+
+AUTO_CAPTURE_INSTRUCTIONS = f"""\
+
+{_AUTO_CAPTURE_MARKER}
+
+You have access to Tribal Memory — a shared memory system for AI agents.
+Use it proactively:
+
+**After completing tasks, making decisions, or learning something:**
+- Call `tribal_remember` to store the insight with relevant tags
+- Good memories: architectural decisions, bug fixes, "gotchas", user preferences,
+  project conventions, API quirks, things that took a while to figure out
+- Bad memories: trivial actions ("I ran the tests"), obvious facts, temporary state
+
+**Before answering questions about prior work:**
+- Call `tribal_recall` to search for relevant context first
+- Search by topic, not exact phrases — it's semantic search
+
+**Tips:**
+- Use tags to organize: `["python", "debugging"]`, `["api", "auth"]`
+- One clear insight per memory is better than a wall of text
+- If you're unsure whether to remember something, remember it — recall is cheap
+"""
+
 # MCP config for Claude Code CLI and Claude Desktop
 CLAUDE_CODE_MCP_CONFIG = {
     "mcpServers": {
@@ -55,7 +86,7 @@ db:
 server:
   host: 127.0.0.1
   port: 18790
-"""
+{auto_capture_line}"""
 
 LOCAL_CONFIG_TEMPLATE = """\
 # Tribal Memory Configuration — Local Mode (Zero Cloud)
@@ -78,7 +109,7 @@ db:
 server:
   host: 127.0.0.1
   port: 18790
-"""
+{auto_capture_line}"""
 
 
 def cmd_init(args: argparse.Namespace) -> int:
@@ -89,16 +120,23 @@ def cmd_init(args: argparse.Namespace) -> int:
     # Create config directory
     TRIBAL_DIR.mkdir(parents=True, exist_ok=True)
 
+    # Auto-capture config line (only included when flag is set)
+    auto_capture_line = ""
+    if args.auto_capture:
+        auto_capture_line = "\nauto_capture: true\n"
+
     # Choose template
     if args.local:
         config_content = LOCAL_CONFIG_TEMPLATE.format(
             instance_id=instance_id,
             db_path=db_path,
+            auto_capture_line=auto_capture_line,
         )
     else:
         config_content = OPENAI_CONFIG_TEMPLATE.format(
             instance_id=instance_id,
             db_path=db_path,
+            auto_capture_line=auto_capture_line,
         )
 
     # Write config
@@ -124,16 +162,74 @@ def cmd_init(args: argparse.Namespace) -> int:
     if args.codex:
         _setup_codex_mcp(args.local)
 
+    # Set up auto-capture instructions
+    if args.auto_capture:
+        _setup_auto_capture(
+            claude_code=args.claude_code,
+            codex=args.codex,
+        )
+
     print()
     print("🚀 Start the server:")
     print("   tribalmemory serve")
     print()
     print("🧠 Or use with Claude Code (MCP):")
     print("   tribalmemory-mcp")
+
+    if not args.auto_capture:
+        print()
+        print("💡 Want your agents to remember things automatically?")
+        print("   tribalmemory init --auto-capture --force")
     
     return 0
 
 
+def _setup_auto_capture(claude_code: bool = False, codex: bool = False) -> None:
+    """Write auto-capture instructions to agent instruction files.
+    
+    Appends memory usage instructions so agents proactively use
+    tribal_remember and tribal_recall without being explicitly asked.
+    
+    Writes to:
+    - ~/.claude/CLAUDE.md (Claude Code) — when --claude-code is set
+    - ~/.codex/AGENTS.md (Codex CLI) — when --codex is set
+    - Both files if neither flag is set (covers the common case)
+    
+    Skips if instructions are already present (idempotent).
+    """
+    # If no specific flag, write to both (default behavior)
+    if not claude_code and not codex:
+        claude_code = codex = True
+
+    targets = []
+    if claude_code:
+        targets.append(("Claude Code", Path.home() / CLAUDE_INSTRUCTIONS_FILE))
+    if codex:
+        targets.append(("Codex CLI", Path.home() / CODEX_INSTRUCTIONS_FILE))
+
+    for label, instructions_path in targets:
+        _write_instructions_file(instructions_path, label)
+
+
+def _write_instructions_file(instructions_path: Path, label: str) -> None:
+    """Write auto-capture instructions to a single instructions file."""
+    instructions_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if instructions_path.exists():
+        existing = instructions_path.read_text()
+        if _AUTO_CAPTURE_MARKER in existing:
+            print(f"✅ Auto-capture already present in {label}: {instructions_path}")
+            return
+        # Append to existing file
+        if not existing.endswith("\n"):
+            existing += "\n"
+        instructions_path.write_text(existing + AUTO_CAPTURE_INSTRUCTIONS)
+    else:
+        instructions_path.write_text(AUTO_CAPTURE_INSTRUCTIONS.lstrip("\n"))
+
+    print(f"✅ Auto-capture instructions written for {label}: {instructions_path}")
+
+
 def _setup_claude_code_mcp(is_local: bool) -> None:
     """Add Tribal Memory to Claude Code's MCP configuration.
     
@@ -151,8 +247,13 @@ def _setup_claude_code_mcp(is_local: bool) -> None:
         Path.home() / ".claude" / "claude_desktop_config.json",  # Legacy / Linux
     ]
 
+    # Resolve full path to tribalmemory-mcp binary.
+    # Claude Desktop doesn't inherit the user's shell PATH (e.g. ~/.local/bin),
+    # so we need the absolute path for it to find the command.
+    mcp_command = _resolve_mcp_command()
+
     mcp_entry = {
-        "command": "tribalmemory-mcp",
+        "command": mcp_command,
         "env": {},
     }
     
@@ -169,6 +270,42 @@ def _setup_claude_code_mcp(is_local: bool) -> None:
     print(f"✅ Claude Desktop config updated: {desktop_path}")
 
 
+def _resolve_mcp_command() -> str:
+    """Resolve the full path to the tribalmemory-mcp binary.
+    
+    Claude Desktop doesn't inherit the user's shell PATH (e.g. ~/.local/bin
+    from uv/pipx installs), so bare command names like "tribalmemory-mcp"
+    fail with "No such file or directory". We resolve the absolute path at
+    init time so the config works regardless of the app's PATH.
+    
+    Falls back to the bare command name if not found on PATH (e.g. user
+    hasn't installed yet and will do so later).
+    """
+    resolved = shutil.which("tribalmemory-mcp")
+    if resolved:
+        return resolved
+    
+    # Check common tool install locations that might not be on PATH
+    base_name = "tribalmemory-mcp"
+    search_dirs = [
+        Path.home() / ".local" / "bin",   # uv/pipx (Linux/macOS)
+        Path.home() / ".cargo" / "bin",    # unlikely but possible
+    ]
+    # On Windows, executables may have .exe/.cmd extensions
+    suffixes = [""]
+    if sys.platform == "win32":
+        suffixes = [".exe", ".cmd", ""]
+    
+    for search_dir in search_dirs:
+        for suffix in suffixes:
+            candidate = search_dir / (base_name + suffix)
+            if candidate.exists() and os.access(candidate, os.X_OK):
+                return str(candidate)
+    
+    # Fall back to bare command — will work if PATH is set correctly
+    return "tribalmemory-mcp"
+
+
 def _get_claude_desktop_config_path() -> Path:
     """Get the platform-appropriate Claude Desktop config path."""
     if sys.platform == "darwin":
@@ -211,6 +348,10 @@ def _setup_codex_mcp(is_local: bool) -> None:
     codex_config_path = Path.home() / ".codex" / "config.toml"
     codex_config_path.parent.mkdir(parents=True, exist_ok=True)
 
+    # Resolve full path (same reason as Claude Desktop — Codex may not
+    # inherit the user's full shell PATH)
+    mcp_command = _resolve_mcp_command()
+
     # Build the TOML section manually (avoid tomli_w dependency)
     # Codex uses [mcp_servers.name] sections in config.toml
     section_marker = "[mcp_servers.tribal-memory]"
@@ -219,7 +360,7 @@ def _setup_codex_mcp(is_local: bool) -> None:
         "",
         "# Tribal Memory — shared memory for AI agents",
         section_marker,
-        'command = "tribalmemory-mcp"',
+        f'command = "{mcp_command}"',
     ]
     
     if is_local:
@@ -286,6 +427,8 @@ def main() -> None:
                              help="Configure Claude Code MCP integration")
     init_parser.add_argument("--codex", action="store_true",
                              help="Configure Codex CLI MCP integration")
+    init_parser.add_argument("--auto-capture", action="store_true",
+                             help="Enable auto-capture (writes instructions to agent config files)")
     init_parser.add_argument("--instance-id", type=str, default=None,
                              help="Instance identifier (default: 'default')")
     init_parser.add_argument("--force", action="store_true",

tribalmemory/interfaces.py

@@ -174,6 +174,50 @@ class IVectorStore(ABC):
         """Count memories matching filters."""
         pass
 
+    async def get_stats(self) -> dict:
+        """Compute aggregate statistics over all memories.
+
+        Returns dict with keys:
+            total_memories, by_source_type, by_tag, by_instance, corrections
+
+        Default implementation iterates in pages of 500. Subclasses
+        should override with native queries (SQL GROUP BY, etc.) for
+        stores with >10k entries.
+        """
+        page_size = 500
+        total = 0
+        corrections = 0
+        by_source: dict[str, int] = {}
+        by_instance: dict[str, int] = {}
+        by_tag: dict[str, int] = {}
+
+        offset = 0
+        while True:
+            page = await self.list(limit=page_size, offset=offset)
+            if not page:
+                break
+            total += len(page)
+            for m in page:
+                src = m.source_type.value
+                by_source[src] = by_source.get(src, 0) + 1
+                inst = m.source_instance
+                by_instance[inst] = by_instance.get(inst, 0) + 1
+                for tag in m.tags:
+                    by_tag[tag] = by_tag.get(tag, 0) + 1
+                if m.supersedes:
+                    corrections += 1
+            if len(page) < page_size:
+                break
+            offset += page_size
+
+        return {
+            "total_memories": total,
+            "by_source_type": by_source,
+            "by_tag": by_tag,
+            "by_instance": by_instance,
+            "corrections": corrections,
+        }
+
 
 class IDeduplicationService(ABC):
     """Interface for detecting duplicate memories."""

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,

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