# Tribal Memory

> Your AI tools don't share a brain. Tribal Memory gives them one.

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>

[![PyPI](https://img.shields.io/pypi/v/tribalmemory)](https://pypi.org/project/tribalmemory/)
[![License](https://img.shields.io/badge/license-BSL%201.1-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 via [MCP](https://modelcontextprotocol.io). Store a memory from one agent, recall it from another. It just works.

---

## Install

```bash
pip install tribalmemory    # or: uv tool install tribalmemory
```

---

## Quick Start

**Zero cloud. Zero API keys. Everything runs locally.**

```bash
pip install tribalmemory
tribalmemory init
tribalmemory serve
```

That's it. No config editing required.

> **First run:** FastEmbed downloads a ~130MB ONNX model on first use. After that, embeddings are instant and fully offline.

Server runs on `http://localhost:18790`.

### Running as a Service (Optional)

Keep the server running in the background with automatic restarts:

```bash
# Install and start the service (systemd on Linux, launchd on macOS)
tribalmemory service install

# Check status
tribalmemory service status

# View logs
tribalmemory service logs

# Stop and remove
tribalmemory service uninstall
```

User-level services only — no root/sudo required.

---

## Integrations

Tribal Memory connects to AI agents via [MCP (Model Context Protocol)](https://modelcontextprotocol.io). Set up one or more of these:

### Claude Code (CLI)

```bash
# Auto-configure (recommended)
tribalmemory init --claude-code
```

Or manually — add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "tribal-memory": {
      "command": "tribalmemory-mcp"
    }
  }
}
```

#### Auto-Capture

By default, Claude Code has the MCP tools available but won't use them unless you ask. Add `--auto-capture` to make Claude Code **proactively** store and recall memories:

```bash
tribalmemory init --claude-code --auto-capture
```

This appends instructions to `~/.claude/CLAUDE.md` that tell Claude Code to:
- **Auto-recall** relevant memories at the start of each conversation
- **Auto-store** important decisions, architecture choices, and key facts
- Use `tribal_remember` and `tribal_recall` without being explicitly asked

Without `--auto-capture`, you can still use memory manually by saying "remember that..." or "what do you know about...".

Now Claude Code has persistent memory across sessions:

```
You: Remember that the auth service uses JWT with RS256
Claude: ✅ Stored.

--- next session ---

You: How does the auth service work?
Claude: Based on my memory, the auth service uses JWT with RS256...
```

### Claude Desktop

```bash
# Auto-configure (recommended — resolves the full binary path automatically)
tribalmemory init --claude-desktop
```

Claude Desktop doesn't inherit your shell PATH, so the bare command `tribalmemory-mcp` won't work. The init flag resolves the absolute path and writes it to `claude_desktop_config.json` for you.

### Both Claude Apps

```bash
# Configure Claude Code CLI and Claude Desktop together
tribalmemory init --claude-code --claude-desktop
```

### Codex (CLI & Desktop)

The Codex CLI and desktop app share the same config file (`~/.codex/config.toml`), so one command sets up both:

```bash
# Auto-configure (recommended — works for both CLI and desktop app)
tribalmemory init --codex
```

Or manually — add to `~/.codex/config.toml`:

```toml
[mcp_servers.tribal-memory]
command = "tribalmemory-mcp"
```

> **Note:** The init flag resolves the full binary path automatically, so the desktop app finds the command even if it doesn't inherit your shell PATH.

That's it. Codex now shares the same memory store as Claude Code. Memories stored by one are instantly available to the other.

Auto-capture works for Codex too — it writes instructions to `~/.codex/AGENTS.md`:

```bash
tribalmemory init --codex --auto-capture
```

### Set Up Everything at Once

```bash
# Configure all agents + auto-capture + background service
tribalmemory init --claude-code --codex --auto-capture --service
```

One command: MCP configured for both agents, auto-capture enabled, server running as a service.

### OpenClaw

Tribal Memory includes a plugin for [OpenClaw](https://github.com/openclaw/openclaw):

```bash
openclaw plugins install ./extensions/memory-tribal
openclaw config set plugins.slots.memory=memory-tribal
```

**How memories are saved:**
- **Automatically** — Memories are captured when the agent responds (preferences, decisions, key facts)
- **On demand** — Use `/remember <thing to remember>` for immediate storage

```
/remember Joe's birthday is March 15
/remember Always use TypeScript for new projects
```

### Cloud Setup (Coming Soon)

A hosted Tribal Memory service for teams — no server management, automatic syncing across machines. [Star the repo](https://github.com/abbudjoe/TribalMemory) for updates.

---

## Demo

Run the interactive demo to see Tribal Memory in action:

```bash
./demo.sh
```

See [docs/demo-output.md](docs/demo-output.md) for sample output.

---

## Self-Hosted Setup

### Configuration

Generated by `tribalmemory init`. Lives at `~/.tribal-memory/config.yaml`:

```yaml
instance_id: my-agent

embedding:
  provider: fastembed
  model: BAAI/bge-small-en-v1.5
  dimensions: 384

db:
  provider: lancedb
  path: ~/.tribal-memory/lancedb

server:
  host: 127.0.0.1
  port: 18790

search:
  lazy_spacy: true    # 70x faster ingest (default: true)
```

### Entity Extraction (Optional)

For better recall on personal conversations (finding people, places, dates), install spaCy:

```bash
pip install tribalmemory[spacy]
python -m spacy download en_core_web_sm
```

With **lazy spaCy** (default), entity extraction is blazing fast:
- **Ingest**: Uses fast regex patterns (~2-3 seconds per conversation)
- **Recall**: Runs spaCy NER once on your query for accurate entity matching

This gives you the best of both worlds — fast ingestion AND accurate retrieval for personal conversations.

### Environment Variables

| Variable | Description |
|----------|-------------|
| `TRIBAL_MEMORY_CONFIG` | Path to config file (default: `~/.tribal-memory/config.yaml`) |
| `TRIBAL_MEMORY_INSTANCE_ID` | Override instance ID |

### Docker

```bash
docker compose up -d
```

Mount a custom `config.yaml` to change embedding model or dimensions. See `docker-compose.yml` for all options.

---

## Tribal API

### HTTP Endpoints

All endpoints are under the `/v1` prefix.

```bash
# Store a memory
curl -X POST http://localhost:18790/v1/remember \
  -H "Content-Type: application/json" \
  -d '{"content": "The database uses Postgres 16", "tags": ["infra"]}'

# Batch store (up to 1000 memories)
curl -X POST http://localhost:18790/v1/remember/batch \
  -H "Content-Type: application/json" \
  -d '{"memories": [
    {"content": "Auth uses JWT with RS256"},
    {"content": "Database is Postgres 16", "tags": ["infra"]}
  ]}'

# Search memories (auto-parses dates from query)
curl -X POST http://localhost:18790/v1/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "what did we discuss last week?", "limit": 5}'

# Search with explicit temporal filter
curl -X POST http://localhost:18790/v1/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "database decisions", "after": "2026-01-01", "limit": 5}'

# Health check
curl http://localhost:18790/v1/health

# Get stats
curl http://localhost:18790/v1/stats
```

### MCP Tools

When connected via MCP, your AI gets these tools:

| Tool | Description |
|------|-------------|
| `tribal_store` | Store a new memory with deduplication |
| `tribal_recall` | Search memories (vector + graph expansion) |
| `tribal_recall_entity` | Query by entity name with hop traversal |
| `tribal_entity_graph` | Explore entity relationships |
| `tribal_correct` | Update/correct an existing memory |
| `tribal_forget` | Delete a memory |
| `tribal_stats` | Get memory statistics |
| `tribal_export` | Export memories to portable JSON |
| `tribal_import` | Import memories from a bundle |
| `tribal_sessions_ingest` | Index conversation transcripts |

### Python API

```python
from tribalmemory.services import create_memory_service

# FastEmbed uses BAAI/bge-small-en-v1.5 (384 dims) by default
service = create_memory_service(
    instance_id="my-agent",
    db_path="./memories",
)

# Store
result = await service.remember(
    "User prefers TypeScript for web projects",
    tags=["preference", "coding"]
)

# Recall
results = await service.recall("What language for web?")
for r in results:
    print(f"{r.similarity_score:.2f}: {r.memory.content}")

# Correct
await service.correct(
    original_id=result.memory_id,
    corrected_content="User prefers TypeScript for web, Python for scripts"
)
```

---

## Architecture

```
┌─────────────┐
│  Claude Code │──── MCP ────┐
└─────────────┘              │
┌─────────────┐              ▼
│  Codex CLI   │──── MCP ───► Tribal Memory Server
└─────────────┘              ▲  (localhost:18790)
┌─────────────┐              │
│  OpenClaw    │── plugin ───┘
└─────────────┘
```

The server is the single source of truth. Each agent connects as an instance. Memories are tagged with `source_instance` so you can see *who* learned *what*.

---

## Features

- **Semantic search** — Find memories by meaning, not keywords
- **Cross-agent sharing** — Memories from one agent are available to all
- **Graph search** — Entity extraction + relationship traversal
- **Hybrid retrieval** — Vector + BM25 keyword search combined
- **Zero cloud** — Local ONNX embeddings via FastEmbed, no API keys needed
- **Batch ingestion** — Store up to 1000 memories in a single request
- **Auto-temporal queries** — "What happened last week?" auto-parses dates
- **Session indexing** — Index conversation transcripts for search
- **Automatic deduplication** — Won't store the same thing twice
- **Memory corrections** — Update outdated information with audit trail
- **Temporal reasoning** — Date extraction and time-based filtering
- **Import/export** — Portable JSON bundles with embedding metadata
- **Token budgets** — Smart context management to avoid LLM overload
- **MCP server** — Native integration with Claude Code, Codex, and more
- **Benchmark tested** — [100% accuracy on LoCoMo](docs/memorybench-results.md) (1986 questions, all categories)

---

## Privacy

**Zero data leaves your machine:**
- Embeddings computed locally (FastEmbed + ONNX runtime)
- Memories stored locally in LanceDB
- No API keys, no cloud services, no telemetry

---

## Development

```bash
git clone https://github.com/abbudjoe/TribalMemory.git
cd TribalMemory
pip install -e ".[dev]"

# Run tests
PYTHONPATH=src pytest

# Run linting
ruff check .
black --check .
```

---

## License

Business Source License 1.1 — see [LICENSE](LICENSE)
