tribalmemory 0.1.0__py3-none-any.whl

tribalmemory/cli.py

@@ -0,0 +1,298 @@
+"""Tribal Memory CLI — init, serve, and MCP entry points.
+
+Usage:
+    tribalmemory init [--local]     # Set up config + MCP integration
+    tribalmemory serve              # Start the HTTP server
+    tribalmemory mcp                # Start the MCP server (stdio)
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+try:
+    import tomllib  # Python 3.11+
+except ImportError:
+    tomllib = None  # type: ignore
+
+try:
+    import tomli_w  # For writing TOML
+except ImportError:
+    tomli_w = None  # type: ignore
+
+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)
+CLAUDE_CODE_MCP_CONFIG = {
+    "mcpServers": {
+        "tribal-memory": {
+            "command": "tribalmemory-mcp",
+            "env": {}
+        }
+    }
+}
+
+OPENAI_CONFIG_TEMPLATE = """\
+# Tribal Memory Configuration
+# Docs: https://github.com/abbudjoe/TribalMemory
+
+instance_id: {instance_id}
+
+embedding:
+  provider: openai
+  model: text-embedding-3-small
+  dimensions: 1536
+  # api_key: sk-...  # Or set OPENAI_API_KEY env var
+
+db:
+  provider: lancedb
+  path: {db_path}
+
+server:
+  host: 127.0.0.1
+  port: 18790
+"""
+
+LOCAL_CONFIG_TEMPLATE = """\
+# Tribal Memory Configuration — Local Mode (Zero Cloud)
+# Uses Ollama for embeddings — no API keys needed!
+# Docs: https://github.com/abbudjoe/TribalMemory
+
+instance_id: {instance_id}
+
+embedding:
+  provider: openai          # Uses OpenAI-compatible API
+  model: nomic-embed-text   # Run: ollama pull nomic-embed-text
+  api_base: http://localhost:11434/v1
+  dimensions: 768
+  # api_key not needed for local Ollama
+
+db:
+  provider: lancedb
+  path: {db_path}
+
+server:
+  host: 127.0.0.1
+  port: 18790
+"""
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Initialize Tribal Memory config and MCP integration."""
+    instance_id = args.instance_id or DEFAULT_INSTANCE_ID
+    db_path = str(TRIBAL_DIR / "lancedb")
+
+    # Create config directory
+    TRIBAL_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Choose template
+    if args.local:
+        config_content = LOCAL_CONFIG_TEMPLATE.format(
+            instance_id=instance_id,
+            db_path=db_path,
+        )
+    else:
+        config_content = OPENAI_CONFIG_TEMPLATE.format(
+            instance_id=instance_id,
+            db_path=db_path,
+        )
+
+    # Write config
+    if CONFIG_FILE.exists() and not args.force:
+        print(f"⚠️  Config already exists: {CONFIG_FILE}")
+        print("   Use --force to overwrite.")
+        return 1
+    
+    CONFIG_FILE.write_text(config_content)
+    print(f"✅ Config written: {CONFIG_FILE}")
+
+    if args.local:
+        print()
+        print("📦 Local mode — make sure Ollama is running:")
+        print("   curl -fsSL https://ollama.com/install.sh | sh")
+        print("   ollama pull nomic-embed-text")
+        print("   ollama serve  # if not already running")
+
+    # Set up MCP integrations
+    if args.claude_code:
+        _setup_claude_code_mcp(args.local)
+    
+    if args.codex:
+        _setup_codex_mcp(args.local)
+
+    print()
+    print("🚀 Start the server:")
+    print("   tribalmemory serve")
+    print()
+    print("🧠 Or use with Claude Code (MCP):")
+    print("   tribalmemory-mcp")
+    
+    return 0
+
+
+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)
+    ]
+
+    config_path = None
+    for p in claude_config_paths:
+        if p.exists():
+            config_path = p
+            break
+
+    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
+    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}"
+            )
+            print(f"   Creating fresh config at {config_path}")
+            existing = {}
+    else:
+        existing = {}
+
+    # 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:
+    """Add Tribal Memory to Codex CLI's MCP configuration (~/.codex/config.toml)."""
+    codex_config_path = Path.home() / ".codex" / "config.toml"
+    codex_config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Build the TOML section manually (avoid tomli_w dependency)
+    # Codex uses [mcp_servers.name] sections in config.toml
+    section_marker = "[mcp_servers.tribal-memory]"
+    
+    mcp_lines = [
+        "",
+        "# Tribal Memory — shared memory for AI agents",
+        section_marker,
+        'command = "tribalmemory-mcp"',
+    ]
+    
+    if is_local:
+        mcp_lines.append("")
+        mcp_lines.append("[mcp_servers.tribal-memory.env]")
+        mcp_lines.append('TRIBAL_MEMORY_EMBEDDING_API_BASE = "http://localhost:11434/v1"')
+    
+    mcp_block = "\n".join(mcp_lines) + "\n"
+
+    if codex_config_path.exists():
+        existing = codex_config_path.read_text()
+        if section_marker in existing:
+            print(f"⚠️  Codex config already has tribal-memory: {codex_config_path}")
+            print("   Remove the existing section first, or edit manually.")
+            return
+        # Append to existing config
+        if not existing.endswith("\n"):
+            existing += "\n"
+        codex_config_path.write_text(existing + mcp_block)
+    else:
+        codex_config_path.write_text(mcp_block.lstrip("\n"))
+
+    print(f"✅ Codex CLI MCP config updated: {codex_config_path}")
+
+
+def cmd_serve(args: argparse.Namespace) -> None:
+    """Start the HTTP server."""
+    from .server.app import run_server
+    from .server.config import TribalMemoryConfig
+
+    config_path = args.config
+    if config_path:
+        config = TribalMemoryConfig.from_file(config_path)
+    else:
+        config = TribalMemoryConfig.from_env()
+
+    run_server(
+        config=config,
+        host=args.host,
+        port=args.port,
+        log_level=args.log_level or "info",
+    )
+
+
+def cmd_mcp(args: argparse.Namespace) -> None:
+    """Start the MCP server (stdio)."""
+    from .mcp.server import main as mcp_main
+    mcp_main()
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="tribalmemory",
+        description="Tribal Memory — Shared memory for AI agents",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # init
+    init_parser = subparsers.add_parser("init", help="Initialize config and MCP integration")
+    init_parser.add_argument("--local", action="store_true",
+                             help="Use local Ollama embeddings (no API key needed)")
+    init_parser.add_argument("--claude-code", action="store_true",
+                             help="Configure Claude Code MCP integration")
+    init_parser.add_argument("--codex", action="store_true",
+                             help="Configure Codex CLI MCP integration")
+    init_parser.add_argument("--instance-id", type=str, default=None,
+                             help="Instance identifier (default: 'default')")
+    init_parser.add_argument("--force", action="store_true",
+                             help="Overwrite existing config")
+
+    # serve
+    serve_parser = subparsers.add_parser("serve", help="Start the HTTP server")
+    serve_parser.add_argument("--host", type=str, default=None)
+    serve_parser.add_argument("--port", "-p", type=int, default=None)
+    serve_parser.add_argument("--config", "-c", type=str, default=None)
+    serve_parser.add_argument("--log-level", type=str, default=None,
+                              choices=["debug", "info", "warning", "error"])
+
+    # mcp
+    subparsers.add_parser("mcp", help="Start the MCP server (stdio transport)")
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        sys.exit(cmd_init(args))
+    elif args.command == "serve":
+        cmd_serve(args)
+    elif args.command == "mcp":
+        cmd_mcp(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

tribalmemory/interfaces.py

@@ -0,0 +1,306 @@
+"""Core interfaces for Tribal Memory system.
+
+These interfaces define the contract that both A2.1 and A2.2 implementations must satisfy.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+import uuid
+
+
+class MemorySource(Enum):
+    """Source of a memory entry."""
+    USER_EXPLICIT = "user_explicit"  # User said "remember X"
+    AUTO_CAPTURE = "auto_capture"    # System detected important info
+    CORRECTION = "correction"        # Correction to existing memory
+    CROSS_INSTANCE = "cross_instance"  # Propagated from another instance
+    LEGACY = "legacy"                # Pre-tribal-memory import
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class MemoryEntry:
+    """A single memory entry with full provenance.
+    
+    Attributes:
+        id: Unique identifier (UUID by default)
+        content: The actual memory content
+        embedding: Vector embedding (None until generated)
+        source_instance: Which agent instance created this memory
+        source_type: How this memory was captured (user_explicit, auto_capture, etc.)
+        created_at: When the memory was first created
+        updated_at: When the memory was last modified
+        tags: Categorization tags for filtering
+        context: What triggered this memory (conversation context, etc.)
+        confidence: How confident we are in this memory (0.0-1.0).
+                   Currently always 1.0; reserved for future use with
+                   uncertain inferences or low-confidence auto-captures.
+        supersedes: ID of memory this corrects (for correction chains)
+        related_to: IDs of related memories. Reserved for future use with
+                   knowledge graphs and memory clustering.
+    """
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    content: str = ""
+    embedding: Optional[list[float]] = None
+    
+    # Provenance
+    source_instance: str = "unknown"
+    source_type: MemorySource = MemorySource.UNKNOWN
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    updated_at: datetime = field(default_factory=datetime.utcnow)
+    
+    # Metadata
+    tags: list[str] = field(default_factory=list)
+    context: Optional[str] = None
+    confidence: float = 1.0
+    
+    # Relationships
+    supersedes: Optional[str] = None
+    related_to: list[str] = field(default_factory=list)
+    
+    def __repr__(self) -> str:
+        """Concise repr for debugging."""
+        content_preview = self.content[:50] + "..." if len(self.content) > 50 else self.content
+        return f"MemoryEntry(id={self.id[:8]}..., content='{content_preview}', source={self.source_type.value})"
+
+
+@dataclass
+class RecallResult:
+    """Result of a memory recall query."""
+    memory: MemoryEntry
+    similarity_score: float
+    retrieval_time_ms: float
+    
+    def __repr__(self) -> str:
+        return f"RecallResult(score={self.similarity_score:.3f}, memory_id={self.memory.id[:8]}...)"
+
+
+@dataclass
+class StoreResult:
+    """Result of storing a memory."""
+    success: bool
+    memory_id: Optional[str] = None
+    duplicate_of: Optional[str] = None  # If rejected as duplicate
+    error: Optional[str] = None
+    
+    def __repr__(self) -> str:
+        if self.success:
+            return f"StoreResult(success=True, id={self.memory_id[:8] if self.memory_id else None}...)"
+        elif self.duplicate_of:
+            return f"StoreResult(success=False, duplicate_of={self.duplicate_of[:8]}...)"
+        else:
+            return f"StoreResult(success=False, error='{self.error}')"
+
+
+class IEmbeddingService(ABC):
+    """Interface for embedding generation."""
+    
+    @abstractmethod
+    async def embed(self, text: str) -> list[float]:
+        """Generate embedding for text."""
+        pass
+    
+    @abstractmethod
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for multiple texts."""
+        pass
+    
+    @abstractmethod
+    def similarity(self, a: list[float], b: list[float]) -> float:
+        """Calculate cosine similarity between two embeddings."""
+        pass
+
+
+class IVectorStore(ABC):
+    """Interface for vector storage and retrieval."""
+    
+    @abstractmethod
+    async def store(self, entry: MemoryEntry) -> StoreResult:
+        """Store a memory entry."""
+        pass
+    
+    @abstractmethod
+    async def recall(
+        self,
+        query_embedding: list[float],
+        limit: int = 10,
+        min_similarity: float = 0.7,
+        filters: Optional[dict] = None,
+    ) -> list[RecallResult]:
+        """Recall memories similar to query.
+        
+        Args:
+            query_embedding: Vector to search for
+            limit: Maximum results
+            min_similarity: Minimum similarity threshold
+            filters: Optional metadata filters (e.g., tags, source_instance)
+        """
+        pass
+    
+    @abstractmethod
+    async def get(self, memory_id: str) -> Optional[MemoryEntry]:
+        """Get a specific memory by ID."""
+        pass
+    
+    @abstractmethod
+    async def delete(self, memory_id: str) -> bool:
+        """Delete a memory (soft delete with tombstone)."""
+        pass
+
+    async def upsert(self, entry: MemoryEntry) -> StoreResult:
+        """Insert or replace a memory entry by ID.
+
+        Default implementation: delete existing + store new.
+        Subclasses may override for atomic upsert support.
+        """
+        await self.delete(entry.id)
+        return await self.store(entry)
+    
+    @abstractmethod
+    async def list(
+        self,
+        limit: int = 1000,
+        offset: int = 0,
+        filters: Optional[dict] = None,
+    ) -> list[MemoryEntry]:
+        """List memories with pagination and optional filtering."""
+        pass
+    
+    @abstractmethod
+    async def count(self, filters: Optional[dict] = None) -> int:
+        """Count memories matching filters."""
+        pass
+
+
+class IDeduplicationService(ABC):
+    """Interface for detecting duplicate memories."""
+    
+    @abstractmethod
+    async def is_duplicate(
+        self,
+        content: str,
+        embedding: list[float],
+        threshold: float = 0.95
+    ) -> tuple[bool, Optional[str]]:
+        """Check if content is duplicate.
+        
+        Returns:
+            Tuple of (is_duplicate, duplicate_of_id)
+            - is_duplicate: True if content exceeds threshold similarity
+            - duplicate_of_id: ID of the matching memory (or None)
+        
+        .. versionchanged:: 0.2.0
+            Return type changed from 3-tuple to 2-tuple. The similarity_score
+            was removed from the return value. If you need the similarity score,
+            use :meth:`find_similar` to get scored results, or use
+            :meth:`get_duplicate_report` for detailed duplicate analysis.
+        
+        Migration guide:
+            Old: ``is_dup, dup_id, score = await dedup.is_duplicate(...)``
+            New: ``is_dup, dup_id = await dedup.is_duplicate(...)``
+            
+            To get score: ``results = await dedup.find_similar(content, embedding, threshold)``
+            The first result's score is the duplicate's similarity.
+        """
+        pass
+    
+    @abstractmethod
+    async def find_similar(
+        self,
+        content: str,
+        embedding: list[float],
+        threshold: float = 0.85,
+        limit: int = 10,
+    ) -> list[tuple[str, float]]:
+        """Find similar memories.
+        
+        Returns:
+            List of (memory_id, similarity_score) tuples
+        """
+        pass
+
+
+class ITimestampService(ABC):
+    """Interface for RFC 3161 timestamping."""
+    
+    @abstractmethod
+    async def timestamp(self, data: bytes) -> bytes:
+        """Get RFC 3161 timestamp token for data."""
+        pass
+    
+    @abstractmethod
+    async def verify(self, data: bytes, token: bytes) -> tuple[bool, Optional[datetime]]:
+        """Verify timestamp token. Returns (valid, timestamp)."""
+        pass
+
+
+class IMemoryService(ABC):
+    """High-level interface for memory operations.
+    
+    This is the main interface that agents (LLMs) interact with.
+    Designed for intuitive use with simple, verb-based methods.
+    """
+    
+    @abstractmethod
+    async def remember(
+        self,
+        content: str,
+        source_type: MemorySource = MemorySource.AUTO_CAPTURE,
+        context: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        skip_dedup: bool = False,
+    ) -> StoreResult:
+        """Store a new memory.
+        
+        Args:
+            content: The memory content
+            source_type: How this memory was captured
+            context: Additional context about capture
+            tags: Tags for categorization and filtering
+            skip_dedup: If True, store even if similar memory exists
+        """
+        pass
+    
+    @abstractmethod
+    async def recall(
+        self,
+        query: str,
+        limit: int = 5,
+        min_relevance: float = 0.7,
+        tags: Optional[list[str]] = None,
+    ) -> list[RecallResult]:
+        """Recall relevant memories for a query.
+        
+        Args:
+            query: Natural language query
+            limit: Maximum results
+            min_relevance: Minimum similarity score
+            tags: Filter by tags (e.g., ["work", "preferences"])
+        """
+        pass
+    
+    @abstractmethod
+    async def correct(
+        self,
+        original_id: str,
+        corrected_content: str,
+        context: Optional[str] = None
+    ) -> StoreResult:
+        """Store a correction to an existing memory.
+        
+        Creates a correction chain - the new memory supersedes the original.
+        """
+        pass
+    
+    @abstractmethod
+    async def forget(self, memory_id: str) -> bool:
+        """Forget (soft delete) a memory."""
+        pass
+    
+    @abstractmethod
+    async def get(self, memory_id: str) -> Optional[MemoryEntry]:
+        """Get a memory by ID with full provenance."""
+        pass

tribalmemory/mcp/__init__.py

@@ -0,0 +1,9 @@
+"""MCP server for Tribal Memory.
+
+This module provides an MCP (Model Context Protocol) server that exposes
+Tribal Memory as tools for Claude Code and other MCP-compatible clients.
+"""
+
+from .server import create_server, main
+
+__all__ = ["create_server", "main"]

tribalmemory/mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m tribalmemory.mcp."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()