tribalmemory 0.1.0__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tribalmemory
-Version: 0.1.0
+Version: 0.2.0
 Summary: Shared memory infrastructure for multi-instance AI agents
 Author-email: Joe <joe@example.com>
 License: Apache-2.0
@@ -48,12 +48,48 @@ Dynamic: license-file
 
 One memory store, many agents. Teach Claude Code something — Codex already knows it. That's not just persistence — it's **cross-agent intelligence**.
 
+<p align="center">
+  <img src="docs/assets/one-brain-two-agents.gif" alt="One Brain, Two Agents — Claude Code stores memories, Codex recalls them" width="700">
+  <br>
+  <em>Claude Code stores architecture decisions → Codex recalls them instantly</em>
+</p>
+
+[![asciinema demo](https://img.shields.io/badge/demo-asciinema-d40000)](https://asciinema.org/a/ZM74iIXzM07SV21P)
+[![PyPI](https://img.shields.io/pypi/v/tribalmemory)](https://pypi.org/project/tribalmemory/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
 ## Why
 
 Every AI coding assistant starts fresh. Claude Code doesn't know what you told Codex. Codex doesn't know what you told Claude. You repeat yourself constantly.
 
 Tribal Memory is a shared memory server that any AI agent can connect to. Store a memory from one agent, recall it from another. It just works.
 
+## Install
+
+**macOS:**
+```bash
+# Install uv (https://docs.astral.sh/uv/)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Restart your terminal, or run:
+source ~/.zshrc
+
+# Install tribalmemory
+uv tool install tribalmemory
+```
+
+> **Why uv?** macOS blocks `pip install` into the system Python with "externally-managed-environment" errors. `uv tool install` handles isolated environments automatically.
+
+**Linux:**
+```bash
+pip install tribalmemory
+
+# Or with uv:
+# curl -LsSf https://astral.sh/uv/install.sh | sh
+# source ~/.bashrc
+# uv tool install tribalmemory
+```
+
 ## Quick Start
 
 ### Option A: Local Mode (Zero Cloud, Zero Cost)
@@ -61,8 +97,6 @@ Tribal Memory is a shared memory server that any AI agent can connect to. Store
 No API keys. No cloud. Everything runs on your machine.
 
 ```bash
-pip install tribalmemory
-
 # Set up with local Ollama embeddings
 tribalmemory init --local
 
@@ -76,8 +110,6 @@ tribalmemory serve
 ### Option B: OpenAI Embeddings
 
 ```bash
-pip install tribalmemory
-
 # Set up with OpenAI
 export OPENAI_API_KEY=sk-...
 tribalmemory init
@@ -224,19 +256,40 @@ await service.correct(
 )
 ```
 
+## Demo
+
+See cross-agent memory sharing in action:
+
+```bash
+# Start the server
+tribalmemory serve
+
+# Run the interactive demo
+./demo.sh
+```
+
+See [docs/demo-output.md](docs/demo-output.md) for example output.
+
 ## HTTP API
 
+All endpoints are under the `/v1` prefix.
+
 ```bash
 # Store a memory
-curl -X POST http://localhost:18790/memories \
+curl -X POST http://localhost:18790/v1/remember \
   -H "Content-Type: application/json" \
   -d '{"content": "The database uses Postgres 16", "tags": ["infra"]}'
 
 # Search memories
-curl "http://localhost:18790/memories/search?query=what+database&limit=5"
+curl -X POST http://localhost:18790/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query": "what database", "limit": 5}'
 
 # Get stats
-curl http://localhost:18790/stats
+curl http://localhost:18790/v1/stats
+
+# Health check
+curl http://localhost:18790/v1/health
 ```
 
 ## OpenClaw Integration

{tribalmemory-0.1.0 → tribalmemory-0.2.0}/README.md

@@ -4,12 +4,48 @@
 
 One memory store, many agents. Teach Claude Code something — Codex already knows it. That's not just persistence — it's **cross-agent intelligence**.
 
+<p align="center">
+  <img src="docs/assets/one-brain-two-agents.gif" alt="One Brain, Two Agents — Claude Code stores memories, Codex recalls them" width="700">
+  <br>
+  <em>Claude Code stores architecture decisions → Codex recalls them instantly</em>
+</p>
+
+[![asciinema demo](https://img.shields.io/badge/demo-asciinema-d40000)](https://asciinema.org/a/ZM74iIXzM07SV21P)
+[![PyPI](https://img.shields.io/pypi/v/tribalmemory)](https://pypi.org/project/tribalmemory/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+
 ## Why
 
 Every AI coding assistant starts fresh. Claude Code doesn't know what you told Codex. Codex doesn't know what you told Claude. You repeat yourself constantly.
 
 Tribal Memory is a shared memory server that any AI agent can connect to. Store a memory from one agent, recall it from another. It just works.
 
+## Install
+
+**macOS:**
+```bash
+# Install uv (https://docs.astral.sh/uv/)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Restart your terminal, or run:
+source ~/.zshrc
+
+# Install tribalmemory
+uv tool install tribalmemory
+```
+
+> **Why uv?** macOS blocks `pip install` into the system Python with "externally-managed-environment" errors. `uv tool install` handles isolated environments automatically.
+
+**Linux:**
+```bash
+pip install tribalmemory
+
+# Or with uv:
+# curl -LsSf https://astral.sh/uv/install.sh | sh
+# source ~/.bashrc
+# uv tool install tribalmemory
+```
+
 ## Quick Start
 
 ### Option A: Local Mode (Zero Cloud, Zero Cost)
@@ -17,8 +53,6 @@ Tribal Memory is a shared memory server that any AI agent can connect to. Store
 No API keys. No cloud. Everything runs on your machine.
 
 ```bash
-pip install tribalmemory
-
 # Set up with local Ollama embeddings
 tribalmemory init --local
 
@@ -32,8 +66,6 @@ tribalmemory serve
 ### Option B: OpenAI Embeddings
 
 ```bash
-pip install tribalmemory
-
 # Set up with OpenAI
 export OPENAI_API_KEY=sk-...
 tribalmemory init
@@ -180,19 +212,40 @@ await service.correct(
 )
 ```
 
+## Demo
+
+See cross-agent memory sharing in action:
+
+```bash
+# Start the server
+tribalmemory serve
+
+# Run the interactive demo
+./demo.sh
+```
+
+See [docs/demo-output.md](docs/demo-output.md) for example output.
+
 ## HTTP API
 
+All endpoints are under the `/v1` prefix.
+
 ```bash
 # Store a memory
-curl -X POST http://localhost:18790/memories \
+curl -X POST http://localhost:18790/v1/remember \
   -H "Content-Type: application/json" \
   -d '{"content": "The database uses Postgres 16", "tags": ["infra"]}'
 
 # Search memories
-curl "http://localhost:18790/memories/search?query=what+database&limit=5"
+curl -X POST http://localhost:18790/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query": "what database", "limit": 5}'
 
 # Get stats
-curl http://localhost:18790/stats
+curl http://localhost:18790/v1/stats
+
+# Health check
+curl http://localhost:18790/v1/health
 ```
 
 ## OpenClaw Integration

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

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

{tribalmemory-0.1.0 → tribalmemory-0.2.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,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-0.1.0 → tribalmemory-0.2.0}/src/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."""