Metadata-Version: 2.5
Name: remembra
Version: 0.16.0
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<2,>=1.23; extra == 'all'
Requires-Dist: openai<3,>=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: redis>=5.0.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: 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: redis>=5.0.0; extra == 'cloud'
Requires-Dist: resend>=0.7.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'
Requires-Dist: types-dateparser>=1.2.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: langgraph
Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.23; extra == 'mcp'
Requires-Dist: structlog>=24.4.0; extra == 'mcp'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.1.0; extra == 'openai-agents'
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<3,>=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="assets/logo.png" alt="Remembra Logo" width="140">
</p>

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

<p align="center">
  <strong>One agent stops. The next one already knows.</strong><br>
  When an agent's session ends, Remembra Relay saves a handoff built from what git says happened.<br>
  The next agent, on another machine, from another vendor, or next week, starts from it.
</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://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://remembra.dev">Website</a> •
  <a href="https://docs.remembra.dev/guides/relay/">Relay guide</a> •
  <a href="https://docs.remembra.dev">Docs</a> •
  <a href="https://remembra.dev/changelog">Changelog</a> •
  <a href="https://discord.gg/mPYQRKzXz5">Discord</a>
</p>

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

---

## Install

```bash
pipx install --force 'remembra[mcp]>=0.16'
remembra-install --all
remembra-relay connect
```

Get a free key at [app.remembra.dev](https://app.remembra.dev/signup), or [host the server yourself](https://docs.remembra.dev/getting-started/docker/).
`remembra-install` asks for the key at a hidden prompt (or reads `REMEMBRA_API_KEY`) and shows its changes before it writes.
`connect` is a dry run that shows exactly what it would change; add `--apply` to write the hooks. `remembra-relay` ships in remembra 0.16.0.

## What the next agent sees

Claude Code finished a session and wrote in its summary that the work was done and pushed. Git disagreed. The next agent's brief starts with:

<!-- readme-brief: generated by remembra.relay.handoff.render_last_session; tests/test_readme_relay.py keeps it true -->
```text
Last session: claude-code (key-verified), 12m ago, on feat/pdf-export@a41f2c9: done: a41f2c9 Add PDF export for invoices; 77c01aa Embed fonts in exported PDFs; tests passing: pytest tests/test_pdf.py (12 passed); changed 3 file(s): invoices/pdf.py, invoices/fonts.py, tests/test_pdf.py / NOT done: 2 commit(s) not pushed to origin/feat/pdf-export / failing: none / next (derived from the recorded facts): push 2 commit(s) to origin/feat/pdf-export (facts collected by remembra-relay from git and the session transcript) (the agent's summary contradicts these recorded facts)
```

The done, not done and failing sections come from git and the session's test runs, never from an LLM. The agent's own summary is optional; it is checked against those facts and shown as unverified, or, as here, contradicted.

## How it works

1. **Close.** When a session ends, `remembra-relay close` reads the branch, commits, changed and uncommitted files and unpushed commits from git, and for Claude Code the test runs and open items in the local transcript. The transcript never leaves your machine; secrets are redacted before anything does.
2. **Brief.** When the next session starts, in any tool, `remembra-relay brief` (or the `session_brief` MCP tool) gives the agent who worked last, what is done, what is failing and the next step, in about 1,500 tokens. Everything another agent recorded is wrapped as untrusted data.
3. **Trail.** Every handoff stays in order: `remembra-relay trail`, or the Trail page in the dashboard. A git log for your agents.

The same repository on a laptop, a server or in a worktree is one project, because it is identified by its git remote. Give each agent its own scoped key and its handoffs show as key-verified.

## Agents

| Agent | Session hooks | How it reads and writes handoffs today |
|---|---|---|
| Claude Code | **verified** | Hooks: brief at start, close at end, with test results from the transcript |
| Codex | **verified** (codex-cli 0.155.0-alpha.16.4, a prerelease) | Hooks: brief at start, close at end, with commands and test runs from the rollout; trust them once with `/hooks` in Codex |
| Cursor, Gemini CLI, Qwen Code, Kimi | unverified | MCP tools (`session_brief`, `close_session`) |
| Any other MCP agent | none | MCP tools |

Claude Code's and Codex's session hooks are verified (Codex with codex-cli 0.155.0-alpha.16.4, a prerelease; no stable Codex release has been run yet). The hooks for Cursor, Gemini CLI, Qwen Code and Kimi are unverified: they follow each tool's docs but have not been run against it yet. `connect` leaves them out unless you add `--include-unverified`. Until they are tested, those agents read the brief and write their handoff through Remembra's MCP tools, as does any MCP agent.

## How it compares

| | Remembra Relay | Vendor memory (Claude Code, Codex, Copilot, Windsurf) | Local handoff tools | Memory APIs (Mem0, Zep, Letta) |
|---|---|---|---|---|
| Works across machines | Yes, by git remote | Mostly no | No | Yes |
| Works across vendors | Yes | No, one vendor each | Yes | Through their API |
| Handoff facts from git | Yes, with the summary checked | No | Transcript or diff | No |
| Durable trail of sessions | Yes | No | No | No |
| Enforced coordination between agents | Crew mode, in build | Claude-only agent teams | No | No |

Details, with a source and date for every claim: [Remembra and other handoff tools](docs/comparisons/handoff-tools.md) and [the competitive landscape](docs/competitive-analysis-2026.md). claude-mem and agentmemory are larger projects that also carry memory between sessions; the comparison says where each is the better pick.

## Pricing

Handoffs, briefs, the inbox, the trail and search are free on every plan. Remembra Cloud: Free, Solo $12/mo, Pro $29/mo, Team $15/seat/mo ([pricing](https://remembra.dev/pricing)). Self-hosting is free under the MIT license.

---

# The memory API underneath

Remembra Relay runs on Remembra's memory layer, which you can also use directly: store facts, recall them by meaning, and let it pull out the people, projects and relationships in them.

```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."
```

In v0.16.0 the memory layer also keeps the exact source text of every derived fact, points each fact back to it, and flags a fact that does not match its source as unverified.

## Self-host the server (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 \
  -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 ALL Your AI Agents (NEW in v0.10.0)

**One command configures everything:**

```bash
pip install remembra
remembra-install --all --url http://localhost:8787
```

This auto-detects and configures: Claude Desktop, Claude Code, Codex CLI, Cursor, Gemini CLI. (Windsurf is unverified: `remembra-install --agent windsurf` writes it, `--all` does not.)

**Verify setup:**

```bash
remembra-doctor all
```

<details>
<summary>Manual MCP Config (if needed)</summary>

**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"
      }
    }
  }
}
```
</details>

**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');
```

---

## Memory 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

---

## 📊 Benchmarks

One small [LoCoMo](https://github.com/snap-research/locomo) run, not a benchmark result: in March 2026 we ran 1 of the 10 LoCoMo conversations, 199 questions, judged by gpt-4o-mini. **76% overall.** The 47 adversarial questions, whose answer is not in the conversation, all scored 0, because Remembra did not detect them; the other 152 questions scored 100%. The numbers are in [`benchmarks/results_20260307_040346_summary.json`](benchmarks/results_20260307_040346_summary.json). A run over all 10 conversations has not been done yet.

Run it yourself: `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 |
| [Remembra Relay](https://docs.remembra.dev/guides/relay/) | Handoffs, briefs and the trail across agents |
| [MCP Server](https://docs.remembra.dev/integrations/mcp-server/) | Tool reference and setup guides for the 21 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 (21):**

| Group | Tools |
|------|-------|
| Remembra Relay | `session_brief`, `close_session`, `resolve_project`, `store_status`, `list_status` |
| Inbox between agents | `send_to_inbox`, `get_inbox`, `ack_inbox` |
| Memory | `store_memory`, `recall_memories`, `update_memory`, `forget_memories`, `list_memories`, `ingest_conversation` |
| Entities and time | `search_entities`, `timeline`, `relationships_at` |
| Sharing | `share_memory`, `list_spaces`, `create_space` |
| Connection | `health_check` |

---

## 🏗️ 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/mPYQRKzXz5">discord</a>
</p>
