remembra

---

Install

First get a free key at app.remembra.dev, then run:

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

remembra-install asks for the key at a hidden prompt (or reads REMEMBRA_API_KEY) and shows its changes before it writes. connect --apply writes the hooks and keeps a backup of each file; run remembra-relay connect alone first to see every change without writing. Codex runs the hooks only after you trust them: Settings > Hooks > Trust in the Codex app, or /hooks in the Codex CLI. When a hook's command changes, Codex skips it until you trust it again. Hosting the server yourself? Add --url <your server> to remembra-install. remembra-relay ships in remembra 0.16.0.

Handoffs not arriving? remembra-relay doctor says where the baton dropped, from this machine's files and your trail, with one fix per problem; it only reads. Inside your agent the local MCP server has the same checks as read-only tools: remembra_doctor, remembra_setup (the install steps for this machine) and remembra_help. See Doctor.

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 includes this line:

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 reported as collected by remembra-relay from git and the session transcript (not checked)) (the agent's summary contradicts these recorded facts)

With the session hooks, remembra-relay builds the done, not done and failing sections from git and, for Claude Code and Codex, the session's test runs, never from an LLM. The server does not check where the facts came from; the brief says they were reported by remembra-relay. The agent's own summary is optional; it is checked against those facts and shown as unverified, or, as here, contradicted. A handoff written through the close_session MCP tool holds the facts the agent declares, labeled "declared by the agent (not checked)".

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 and Codex, the commands, test runs and open items in the local transcript (Codex's is its rollout file). The transcript itself stays on your machine. Secrets that match Remembra's patterns are redacted from what is sent.
2. Brief. When the next session starts, in the same tool or another, remembra-relay brief (run by the verified session hooks) or the session_brief MCP tool (any MCP agent can call it) gives the agent who worked last, what is done, what is failing and the next step. The text brief is capped at about 1,500 tokens (6,000 characters). session_brief returns only that text with compact=true; by default it also returns the full brief as JSON, which is larger. 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 in Codex (Settings > Hooks, or /hooks in the CLI), and again when one changes
Gemini CLI	verified (Gemini CLI 0.61.0)	Hooks: brief at start (after /clear, with the first prompt), close at end; they run only in folders you trust
Qwen Code	verified (Qwen Code 0.24.6)	Hooks: brief at start, close at end, on a rate-limit or billing stop and before /compress; qwen -p writes no handoff
Kimi Code	verified (Kimi Code 2.1.1)	Hooks: brief with the first prompt, close when the TUI exits; kimi -p writes no handoff
Cursor	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, and the same tests also pass on the stable 0.157.1). The Gemini CLI, Qwen Code and Kimi Code hooks are verified too: each was run against the real tool at the version in the table, with a local stand-in for the model, and put the brief in the model's request and posted the handoff; other versions have not been run. The Cursor hooks are unverified: Cursor's own hook runner ran them, but no logged-in Cursor session has yet. connect leaves them out unless you add --include-unverified. Until they are tested, Cursor reads the brief and writes its 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 claude-mem, agentmemory, the local handoff tools and Claude Code's own features: Remembra and other handoff tools. 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). 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.

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

Since v0.16.0 the memory layer also keeps the exact text that facts were derived from and points each fact back to it. By default a fact that does not match its source is not stored: the store response lists it under dropped_facts. With REMEMBRA_GROUNDING_ACTION=flag such a fact is stored and marked unverified instead.

Self-host the server

One Command Install

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

This starts Remembra, Qdrant and Ollama locally, with auth off and local embeddings, so the server needs no API key. The first start downloads the images and the embedding model, so how long it takes depends on your connection.

Or with Docker Compose directly:

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

Try it:

# 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 your agents (since v0.10.0)

Configure the agents it detects, then add the session hooks:

pipx install --force 'remembra[mcp]>=0.16'
REMEMBRA_API_KEY=local remembra-install --all --url http://localhost:8787
remembra-relay connect --apply

remembra-install needs a key value. The quickstart server runs with auth off and accepts any value, so local is only a placeholder; for a server with auth on, leave REMEMBRA_API_KEY=local out and give a real key at the hidden prompt. It auto-detects and configures Claude Code, Codex CLI, Cursor and Gemini CLI, and Claude Desktop on macOS only (the Windows config is not detected or written). Windsurf is unverified: remembra-install --agent windsurf writes it, --all does not. remembra-relay connect --apply writes the session hooks that save and read handoffs.

Verify setup:

remembra-doctor all

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

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

Claude Code:

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

Cursor — add to .cursor/mcp.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

pip install remembra

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

npm install remembra

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 — an LLM matcher merges name variants that fit the context ("Mr. Smith" and "John Smith"); resolving "my husband" to a named person is best-effort and untested

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

🔍 Hybrid Search — Semantic + keyword for accurate recall

🔒 Security — PII detection and redaction, secret redaction, audit logs

📊 Dashboard — Visual memory browser, entity graphs, analytics

---

📊 Benchmarks

No valid benchmark result has been published yet. In March 2026 we ran 1 of the 10 LoCoMo conversations (199 questions), but that run's scores are not valid: its judge counted every INCORRECT verdict as correct, and it scored the raw recall context instead of an answer. Both bugs are fixed in the runner (commit a19fb29); a fresh run has not been done yet.

Run it yourself: python benchmarks/locomo_runner.py --data /tmp/locomo/data/locomo10.json

---

📖 Documentation

Resource	Description
Quick Start	Get running in minutes
Python SDK	Full Python reference
TypeScript SDK	JavaScript/TypeScript guide
Remembra Relay	Handoffs, briefs and the trail across agents
MCP Server	Tool reference and setup guides for the 31 tools
REST API	API reference
Self-Hosting	Docker deployment guide

---

🛠️ MCP Server

Give an MCP-capable coding agent persistent memory. A standard MCP server (stdio, SSE, streamable HTTP), with setup guides for Claude Code, Cursor, VS Code + Copilot, JetBrains, Zed and OpenAI Codex. It should work with any MCP-compatible client. Windsurf has a guide but is unverified.

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

Available tools (31):

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
Setup and diagnosis (read-only)	remembra_doctor, remembra_setup, remembra_help
Crew mode (when the server runs it)	crew_status, crew_claim, crew_guard, crew_task, crew_say, crew_checkpoint, crew_report

---

🏗️ 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 for guidelines.

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

---