tribalmemory 0.1.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tribalmemory
-Version: 0.1.1
+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.1.1 → tribalmemory-0.3.0}/pyproject.toml

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

{tribalmemory-0.1.1 → tribalmemory-0.3.0}/src/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-0.1.1 → 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
@@ -174,6 +185,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."""
@@ -271,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.
         
@@ -279,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