Metadata-Version: 2.4
Name: tokyo-brain
Version: 0.1.0
Summary: Universal memory infrastructure for AI agents
Project-URL: Homepage, https://tokyobrain.ai
Project-URL: Repository, https://github.com/changfamilyai/tokyo-brain
Project-URL: Documentation, https://tokyobrain.ai/docs
Project-URL: Issues, https://github.com/changfamilyai/tokyo-brain/issues
Author-email: Nexus AI <hello@tokyobrain.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,embeddings,llm,memory,rag,vector
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: requests>=2.20.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://tokyobrain.ai/assets/logo.png" alt="Tokyo Brain" width="200" />
</p>

<h1 align="center">Tokyo Brain</h1>

<p align="center">
  <strong>Give your AI agent a memory that never forgets.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/tokyo-brain/"><img src="https://img.shields.io/pypi/v/tokyo-brain?color=blue" alt="PyPI version" /></a>
  <a href="https://github.com/changfamilyai/tokyo-brain/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License" /></a>
  <a href="https://pypi.org/project/tokyo-brain/"><img src="https://img.shields.io/pypi/pyversions/tokyo-brain" alt="Python versions" /></a>
</p>

---

**Tokyo Brain** is universal memory infrastructure for AI agents. Store, recall, and forget — with one API call.

## Install

```bash
pip install tokyo-brain
```

## Quickstart

```python
from tokyo_brain import Brain

brain = Brain(api_key="tb-...")

# Store a memory
brain.store("User prefers dark mode and speaks Japanese", track="preferences")

# Recall relevant memories
result = brain.recall("What language does the user speak?")
for memory in result.memories:
    print(f"[{memory.score:.2f}] {memory.document}")

# Forget specific memories
brain.forget(ids=["mem_abc123"])

# Health check
health = brain.health()
print(f"Status: {health.status} | Version: {health.version}")
```

## Features

| Feature | Description |
|---------|-------------|
| 🌍 **50+ Languages** | Multilingual embeddings — store in Japanese, recall in English |
| 🏗️ **3-Tier Architecture** | Hot (Redis) → Warm (Postgres+pgvector) → Cold (S3) |
| 🔌 **Plugin-First** | Drop-in memory for LangChain, CrewAI, AutoGen, OpenClaw |
| 🔒 **Encryption at Rest** | AES-256 encryption for all stored memories |
| 📊 **Tracks** | Organise memories by track — `history`, `preferences`, `knowledge` |
| ⚡ **Sub-50ms Recall** | Optimised vector search with HNSW indexing |

## API Reference

### `Brain(api_key, base_url, timeout)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | *required* | Your API key (starts with `tb-`) |
| `base_url` | `str` | `https://api.tokyobrain.ai` | API endpoint |
| `timeout` | `int` | `30` | Request timeout in seconds |

### `brain.store(document, track, metadata)`

Store a memory document. Returns `StoreResult`.

### `brain.recall(query, format, top_k)`

Recall memories matching a natural-language query. Returns `RecallResult` with a list of `Memory` objects.

### `brain.forget(ids, where)`

Delete memories by ID list or filter. Returns `ForgetResult`.

### `brain.health()`

Check API health. Returns `HealthResult`.

## Comparison

| | **Tokyo Brain** | Mem0 | Zep |
|---|---|---|---|
| Multilingual (50+ langs) | ✅ | ❌ | ⚠️ Limited |
| 3-tier storage | ✅ Hot/Warm/Cold | ❌ Single tier | ⚠️ 2-tier |
| Plugin ecosystem | ✅ LangChain, CrewAI, OpenClaw | ⚠️ LangChain only | ⚠️ LangChain only |
| Encryption at rest | ✅ AES-256 | ❌ | ✅ |
| Track-based organisation | ✅ | ❌ | ❌ |
| Sub-50ms recall | ✅ | ❌ | ⚠️ |
| Self-host option | ✅ | ✅ | ✅ |
| Pricing | Free tier + usage | Free tier + usage | Per-seat |

## Self-Hosting

```bash
docker run -p 9500:9500 tokyobrain/server:latest
```

Then point the SDK at your local instance:

```python
brain = Brain(api_key="tb-local", base_url="http://localhost:9500")
```

## Documentation

Full documentation at **[tokyobrain.ai](https://tokyobrain.ai)**.

## License

MIT — see [LICENSE](LICENSE) for details.
