Metadata-Version: 2.4
Name: remembra
Version: 0.8.4
Summary: Universal memory layer for AI applications. Self-host in minutes.
Project-URL: Homepage, https://github.com/remembra-ai/remembra
Project-URL: Documentation, https://github.com/remembra-ai/remembra#readme
Project-URL: Repository, https://github.com/remembra-ai/remembra.git
Project-URL: Issues, https://github.com/remembra-ai/remembra/issues
Project-URL: Changelog, https://github.com/remembra-ai/remembra/blob/main/CHANGELOG.md
Author-email: DolphyTech <admin@dolphytech.com>
Maintainer-email: Damany Dolphy <admin@dolphytech.com>
License: MIT
License-File: LICENSE
Keywords: agent,ai,chatbot,embeddings,langchain,llm,mcp,memory,model-context-protocol,openai,rag,vector-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: bcrypt>=5.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: slowapi>=0.1.9
Provides-Extra: all
Requires-Dist: aiosqlite>=0.20.0; extra == 'all'
Requires-Dist: anthropic>=0.39.0; extra == 'all'
Requires-Dist: bcrypt>=4.0.0; extra == 'all'
Requires-Dist: crewai>=0.80.0; extra == 'all'
Requires-Dist: cryptography>=42.0.0; extra == 'all'
Requires-Dist: email-validator>=2.0.0; extra == 'all'
Requires-Dist: fastapi>=0.115.0; extra == 'all'
Requires-Dist: langchain-core>=0.3.0; extra == 'all'
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: pydantic-settings>=2.6.0; extra == 'all'
Requires-Dist: pydantic>=2.9.0; extra == 'all'
Requires-Dist: pyjwt>=2.8.0; extra == 'all'
Requires-Dist: pyotp>=2.9.0; extra == 'all'
Requires-Dist: python-multipart>=0.0.9; extra == 'all'
Requires-Dist: python-ulid>=3.0.0; extra == 'all'
Requires-Dist: qdrant-client<2.0.0,>=1.12.0; extra == 'all'
Requires-Dist: qrcode[pil]>=7.4.0; extra == 'all'
Requires-Dist: resend>=0.7.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.5.0; extra == 'all'
Requires-Dist: slowapi>=0.1.9; extra == 'all'
Requires-Dist: stripe>=8.0.0; extra == 'all'
Requires-Dist: structlog>=24.4.0; extra == 'all'
Requires-Dist: tiktoken>=0.7.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.39.0; extra == 'anthropic'
Provides-Extra: cloud
Requires-Dist: resend>=0.7.0; extra == 'cloud'
Requires-Dist: stripe>=8.0.0; extra == 'cloud'
Provides-Extra: crewai
Requires-Dist: crewai>=0.80.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: encryption
Requires-Dist: cryptography>=42.0.0; extra == 'encryption'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: rerank
Requires-Dist: sentence-transformers>=2.5.0; extra == 'rerank'
Provides-Extra: server
Requires-Dist: aiosqlite>=0.20.0; extra == 'server'
Requires-Dist: bcrypt>=4.0.0; extra == 'server'
Requires-Dist: email-validator>=2.0.0; extra == 'server'
Requires-Dist: fastapi>=0.115.0; extra == 'server'
Requires-Dist: openai>=1.0.0; extra == 'server'
Requires-Dist: pydantic-settings>=2.6.0; extra == 'server'
Requires-Dist: pydantic>=2.9.0; extra == 'server'
Requires-Dist: pyjwt>=2.8.0; extra == 'server'
Requires-Dist: pyotp>=2.9.0; extra == 'server'
Requires-Dist: python-multipart>=0.0.9; extra == 'server'
Requires-Dist: python-ulid>=3.0.0; extra == 'server'
Requires-Dist: qdrant-client<2.0.0,>=1.12.0; extra == 'server'
Requires-Dist: qrcode[pil]>=7.4.0; extra == 'server'
Requires-Dist: slowapi>=0.1.9; extra == 'server'
Requires-Dist: structlog>=24.4.0; extra == 'server'
Requires-Dist: tiktoken>=0.7.0; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'server'
Provides-Extra: tracing
Requires-Dist: opentelemetry-api>=1.20.0; extra == 'tracing'
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'tracing'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.40b0; extra == 'tracing'
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'tracing'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://remembra.dev/logo.svg" alt="Remembra Logo" width="120">
</p>

<h1 align="center">Remembra</h1>

<p align="center">
  <strong>The memory layer for AI that actually works.</strong><br>
  Persistent memory with entity resolution, temporal decay, and graph-aware recall.<br>
  Self-host in minutes. No vendor lock-in.
</p>

<p align="center">
  <a href="https://pypi.org/project/remembra/"><img src="https://img.shields.io/pypi/v/remembra?color=blue&label=PyPI" alt="PyPI"></a>
  <a href="https://www.npmjs.com/package/remembra"><img src="https://img.shields.io/npm/v/remembra?color=green&label=npm" alt="npm"></a>
  <a href="https://github.com/remembra-ai/remembra/stargazers"><img src="https://img.shields.io/github/stars/remembra-ai/remembra?style=social" alt="GitHub Stars"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://docs.remembra.dev"><img src="https://img.shields.io/badge/docs-remembra.dev-blue" alt="Documentation"></a>
</p>

<p align="center">
  <a href="https://docs.remembra.dev">Documentation</a> •
  <a href="https://remembra.dev">Website</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#why-remembra">Why Remembra?</a> •
  <a href="https://twitter.com/remembradev">Twitter</a> •
  <a href="https://discord.gg/Bzv3JshRa3">Discord</a>
</p>

<!-- mcp-name: io.github.remembra-ai/remembra -->

---

## 🚀 What's New in v0.8.2

- **🔐 AES-256-GCM Field Encryption** — Encrypt memory content at rest with OWASP-compliant key derivation
- **🛡️ Enterprise Security Suite** — PII detection, anomaly monitoring, audit logging
- **📦 MCP Registry Published** — Discoverable as `io.github.remembra-ai/remembra` in Claude Desktop
- **⚡ One-Command Quick Start** — `curl | bash` zero-config setup with Ollama embeddings
- **🔌 Multi-Provider Support** — OpenAI, Anthropic Claude, Ollama for embeddings & entity extraction
- **📊 Usage Warning Banners** — API responses include usage thresholds at 60/80/95%

---

## The Problem

Every AI app needs memory. Your chatbot forgets users between sessions. Your agent can't recall decisions from yesterday. Your assistant asks the same questions over and over.

**Existing solutions have tradeoffs:**
- Mem0: Graph features require $249/mo plan; limited self-hosting documentation
- Zep: Academic approach, complex deployment
- Letta: Research-grade, not production-ready
- LangChain Memory: Too basic, no persistence

## The Solution

```python
from remembra import Memory

memory = Memory(user_id="user_123")

# Store — entities and facts extracted automatically
memory.store("Had a meeting with Sarah from Acme Corp. She prefers email over Slack.")

# Recall — semantic search finds relevant memories
result = memory.recall("How should I contact Sarah?")
print(result.context)
# → "Sarah from Acme Corp prefers email over Slack."

# It knows "Sarah" and "Acme Corp" are entities. It builds relationships.
# It persists across sessions, reboots, context windows. Forever.
```

---

## ⚡ Quick Start (2 Minutes)

### One Command Install

```bash
curl -sSL https://raw.githubusercontent.com/remembra-ai/remembra/main/quickstart.sh | bash
```

That's it. Remembra + Qdrant + Ollama start locally. No API keys needed.

**Or with Docker Compose directly:**

```bash
git clone https://github.com/remembra-ai/remembra && cd remembra
docker compose -f docker-compose.quickstart.yml up -d
```

**Try it:**

```bash
# Store a memory
curl -X POST http://localhost:8787/api/v1/memories/store \
  -H "Content-Type: application/json" \
  -d '{"content": "Alice is CEO of Acme Corp", "user_id": "demo"}'

# Recall it
curl -X POST http://localhost:8787/api/v1/memories/recall \
  -H "Content-Type: application/json" \
  -d '{"query": "Who runs Acme?", "user_id": "demo"}'
```

### Connect to Claude (MCP)

**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "remembra": {
      "command": "remembra-mcp",
      "env": {
        "REMEMBRA_URL": "http://localhost:8787",
        "REMEMBRA_USER_ID": "default"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add remembra -e REMEMBRA_URL=http://localhost:8787 -- remembra-mcp
```

**Cursor** — add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "remembra": {
      "command": "remembra-mcp",
      "env": {
        "REMEMBRA_URL": "http://localhost:8787"
      }
    }
  }
}
```

Now ask Claude: *"Remember that Alice is CEO of Acme Corp"* — then later: *"Who runs Acme?"*

### Python SDK

```bash
pip install remembra
```

```python
from remembra import Memory

memory = Memory(user_id="user_123")
memory.store("Had a meeting with Sarah from Acme Corp. She prefers email over Slack.")
result = memory.recall("How should I contact Sarah?")
print(result.context)  # "Sarah from Acme Corp prefers email over Slack."
```

### TypeScript SDK

```bash
npm install remembra
```

```typescript
import { Remembra } from 'remembra';

const memory = new Remembra({ url: 'http://localhost:8787' });
await memory.store('User prefers dark mode');
const result = await memory.recall('preferences');
```

---

## 🔥 Why Remembra?

### Feature Comparison

| Feature | Remembra | Mem0 | Zep/Graphiti | Letta | Engram |
|---------|----------|------|-------------|-------|--------|
| **One-Command Install** | ✅ `curl \| bash` | ✅ pip | ✅ pip | ⚠️ Complex | ✅ brew |
| **Entity Resolution** | ✅ Free | 💰 $249/mo | ✅ | ❌ | ❌ |
| **Conflict Detection** | ✅ Unique | ❌ | ❌ | ❌ | ❌ |
| **PII Detection** | ✅ Built-in | ❌ | ❌ | ❌ | ❌ |
| **Hybrid Search** | ✅ BM25+Vector | ❌ | ✅ | ❌ | ❌ |
| **6 Embedding Providers** | ✅ Hot-swap | ❌ (1-2) | ❌ (1) | ❌ | ❌ |
| **Plugin System** | ✅ | ❌ | ❌ | ✅ | ❌ |
| **Sleep-Time Compute** | ✅ | ❌ | ❌ | ✅ | ❌ |
| **Self-Host + Billing** | ✅ Stripe | ❌ | ❌ | ❌ | ❌ |
| **Memory Spaces** | ✅ Multi-tenant | ❌ | ❌ | ❌ | ❌ |
| **MCP Server** | ✅ Native | ✅ | ❌ | ❌ | ✅ |
| **Pricing** | Free / $49 / $99 | $19 → $249 | $25+ | Free | Free |
| **License** | MIT | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT |

### Core Features

🧠 **Smart Extraction** — LLM-powered fact extraction from raw text

👥 **Entity Resolution** — "Adam", "Mr. Smith", "my husband" → same person

⏱️ **Temporal Memory** — TTL, decay curves, historical queries

🔍 **Hybrid Search** — Semantic + keyword for accurate recall

🔒 **Security** — PII detection, anomaly monitoring, audit logs

📊 **Dashboard** — Visual memory browser, entity graphs, analytics

---

## 📊 Benchmark Results

Tested on the [LoCoMo benchmark](https://github.com/snap-research/locomo) (Snap Research, ACL 2024) — the standard academic benchmark for AI memory systems.

| Category | Accuracy | Questions |
|----------|----------|-----------|
| **Single-hop** (direct recall) | **100%** | 37 |
| **Multi-hop** (cross-session reasoning) | **100%** | 32 |
| **Temporal** (time-based queries) | **100%** | 13 |
| **Open-domain** (world knowledge + memory) | **100%** | 70 |
| **Overall (memory categories)** | **100%** | **152** |

> Scored with LLM judge (GPT-4o-mini). Adversarial detection not yet implemented. Run your own: `python benchmarks/locomo_runner.py --data /tmp/locomo/data/locomo10.json`

---

## 📖 Documentation

| Resource | Description |
|----------|-------------|
| [Quick Start](https://docs.remembra.dev/getting-started/quickstart/) | Get running in minutes |
| [Python SDK](https://docs.remembra.dev/guides/python-sdk/) | Full Python reference |
| [TypeScript SDK](https://docs.remembra.dev/guides/javascript-sdk/) | JavaScript/TypeScript guide |
| [MCP Server](https://docs.remembra.dev/integrations/mcp-server/) | Tool reference + setup guides for 9 tools |
| [REST API](https://docs.remembra.dev/guides/rest-api/) | API reference |
| [Self-Hosting](https://docs.remembra.dev/getting-started/docker/) | Docker deployment guide |

---

## 🛠️ MCP Server

Give any AI coding tool persistent memory with one command. Works with **Claude Code**, **Cursor**, **VS Code + Copilot**, **Windsurf**, **JetBrains**, **Zed**, **OpenAI Codex**, and any MCP-compatible client.

```bash
pip install remembra[mcp]
claude mcp add remembra -e REMEMBRA_URL=http://localhost:8787 -- remembra-mcp
```

**Available Tools:**

| Tool | Description |
|------|-------------|
| `store_memory` | Save facts, decisions, context |
| `recall_memories` | Semantic search across memories |
| `forget_memories` | GDPR-compliant deletion |
| `ingest_conversation` | Auto-extract from chat history |
| `health_check` | Verify connection |

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Your Application                          │
├──────────┬──────────────┬───────────────────────────────────┤
│ Python   │ TypeScript   │ MCP Server (Claude/Cursor)        │
│ SDK      │ SDK          │ remembra-mcp                      │
├──────────┴──────────────┴───────────────────────────────────┤
│                   Remembra REST API                          │
├──────────────┬──────────────┬───────────────┬───────────────┤
│  Extraction  │   Entities   │   Retrieval   │   Security    │
│  (LLM)       │  (Graph)     │ (Hybrid)      │  (PII/Audit)  │
├──────────────┴──────────────┴───────────────┴───────────────┤
│                    Storage Layer                             │
│         Qdrant (vectors) + SQLite (metadata/graph)          │
└─────────────────────────────────────────────────────────────┘
```

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
# Clone
git clone https://github.com/remembra-ai/remembra
cd remembra

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Start dev server
remembra-server --reload
```

---

## 📄 License

MIT License — Use it however you want.

---

## ⭐ Star History

If Remembra helps you, please star the repo! It helps others discover the project.

[![Star History Chart](https://api.star-history.com/svg?repos=remembra-ai/remembra&type=Date)](https://star-history.com/#remembra-ai/remembra&Date)

---

<p align="center">
  Built with ❤️ by <a href="https://dolphytech.com">DolphyTech</a><br>
  <a href="https://remembra.dev">remembra.dev</a> • <a href="https://docs.remembra.dev">docs</a> • <a href="https://twitter.com/remembradev">twitter</a> • <a href="https://discord.gg/Bzv3JshRa3">discord</a>
</p>
