tribalmemory 0.1.0__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,7 +27,37 @@ TRIBAL_DIR = Path.home() / ".tribal-memory"
 CONFIG_FILE = TRIBAL_DIR / "config.yaml"
 DEFAULT_INSTANCE_ID = "default"
 
-# MCP config for Claude Code (claude_desktop_config.json)
+# 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": {
         "tribal-memory": {
@@ -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,65 +162,185 @@ 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."""
-    # Claude Code MCP config paths by platform
-    claude_config_paths = [
-        Path.home() / ".claude" / "claude_desktop_config.json",  # Claude Code CLI (all platforms)
-        Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",  # Claude Desktop (macOS)
-        Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json",  # Claude Desktop (Windows)
+    """Add Tribal Memory to Claude Code's MCP configuration.
+    
+    Claude Code CLI reads MCP servers from ~/.claude.json (user scope).
+    Claude Desktop reads from platform-specific claude_desktop_config.json.
+    We update both if they exist, and always ensure ~/.claude.json is set.
+    """
+    # Claude Code CLI config (primary — this is what `claude` CLI reads)
+    claude_cli_config = Path.home() / ".claude.json"
+    
+    # Claude Desktop config paths (secondary — update if they exist)
+    claude_desktop_paths = [
+        Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",  # macOS
+        Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json",  # Windows
+        Path.home() / ".claude" / "claude_desktop_config.json",  # Legacy / Linux
     ]
 
-    config_path = None
-    for p in claude_config_paths:
-        if p.exists():
-            config_path = p
-            break
+    # 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": mcp_command,
+        "env": {},
+    }
+    
+    if is_local:
+        mcp_entry["env"]["TRIBAL_MEMORY_EMBEDDING_API_BASE"] = "http://localhost:11434/v1"
+
+    # Always update Claude Code CLI config (~/.claude.json)
+    _update_mcp_config(claude_cli_config, mcp_entry, create_if_missing=True)
+    print(f"✅ Claude Code CLI config updated: {claude_cli_config}")
+
+    # Also update Claude Desktop config (create platform-appropriate path)
+    desktop_path = _get_claude_desktop_config_path()
+    _update_mcp_config(desktop_path, mcp_entry, create_if_missing=True)
+    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"
 
-    if config_path is None:
-        # Create default location
-        config_path = claude_config_paths[0]
-        config_path.parent.mkdir(parents=True, exist_ok=True)
 
-    # Read existing config or start fresh
+def _get_claude_desktop_config_path() -> Path:
+    """Get the platform-appropriate Claude Desktop config path."""
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    elif sys.platform == "win32":
+        return Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json"
+    else:
+        return Path.home() / ".claude" / "claude_desktop_config.json"
+
+
+def _update_mcp_config(
+    config_path: Path, mcp_entry: dict, create_if_missing: bool = False
+) -> None:
+    """Update an MCP config file with the tribal-memory server entry."""
     if config_path.exists():
         try:
             existing = json.loads(config_path.read_text())
         except json.JSONDecodeError as e:
-            print(
-                f"⚠️  Existing config has invalid JSON: {e}"
-            )
+            backup_path = config_path.with_suffix(".json.bak")
+            config_path.rename(backup_path)
+            print(f"⚠️  Existing config has invalid JSON: {e}")
+            print(f"   Backed up to {backup_path}")
             print(f"   Creating fresh config at {config_path}")
             existing = {}
-    else:
+    elif create_if_missing:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
         existing = {}
+    else:
+        return
 
-    # Merge MCP server config
     if "mcpServers" not in existing:
         existing["mcpServers"] = {}
 
-    mcp_entry = {
-        "command": "tribalmemory-mcp",
-        "env": {},
-    }
-    
-    if is_local:
-        mcp_entry["env"]["TRIBAL_MEMORY_EMBEDDING_API_BASE"] = "http://localhost:11434/v1"
-
     existing["mcpServers"]["tribal-memory"] = mcp_entry
-
     config_path.write_text(json.dumps(existing, indent=2) + "\n")
-    print(f"✅ Claude Code MCP config updated: {config_path}")
 
 
 def _setup_codex_mcp(is_local: bool) -> None:
@@ -190,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]"
@@ -198,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:
@@ -265,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,