memri
Persistent, graph-based memory for Claude Code, Cursor, and Codex — in a pip install.
The problem
Every time you start a new session with Claude Code, Cursor, or Codex — it forgets everything. The architecture you designed last week. The library you chose. The bug you already fixed. You repeat yourself. The agent repeats mistakes.
memri fixes this. It gives your AI coding agent a persistent memory that survives across sessions — so it always knows who you are, what you're building, and how you like to work.
Results
Evaluated on LongMemEval-S — 500 QA pairs designed to test AI long-term memory:
| Score | |
|---|---|
| Full context (no memory, 115K tokens) | 70.6% |
| memri v1.0 graph memory | 83% |
Better recall. A fraction of the tokens.
Install
pip install "memri[graph]"
One command to wire it into Claude Code:
memri init --claude-code
That's it. Open a new Claude Code session — memri starts working immediately.
What it does
Every conversation you have with your coding agent gets ingested into a 3-layer memory graph:
Your conversation
│
[Graph Engine]
│
├── Layer 2 raw episode archive (SQLite, zero data loss)
│
├── Layer 1 fact/entity/reflection graph (NetworkX)
│ causal chains · temporal edges · entity linking
│
└── Layer 0 always-in-context routing index (~500 tokens)
entity index · topic clusters · user summary
│
[Retrieval] Layer 0 → BFS traversal → RRF ranking
│ returns only the relevant facts (~500 tokens)
│
Injected at the top of your next session
When you ask a question, memri doesn't dump your entire history into the prompt. It finds the specific facts, entities, and context that matter for that query — and injects only those.
Features
- Graph-based memory — entities, facts, causal chains, and higher-level reflections stored in a queryable graph
- Entity tracking — people, projects, and concepts linked across all sessions
- Three-layer architecture — always-in-context index (Layer 0), fact graph (Layer 1), raw episode archive (Layer 2)
- RRF ranking — Reciprocal Rank Fusion across vector, BM25, importance, and recency signals
- Automatic compression — conversations beyond 30K tokens compressed 5–40× into timestamped observations
- Cross-session recall — memory injected at the start of every session automatically
- Semantic search — find anything from past sessions (
memri search "auth pattern we chose") - Procedural memory — learns how to work with you over time, not just what happened
- Frustration detection — detects when you're frustrated, permanently stores what went wrong
- Works with any LLM — Anthropic, Gemini, OpenAI, or any OpenAI-compatible endpoint
- 100% local — all data on your machine, no cloud, no accounts
- Visual dashboard — interactive graph visualization, Layer 0 index, episode browser
Quick start
# Install
pip install "memri[graph]"
# Wire into Claude Code (one command)
memri init --claude-code
# Open a new Claude Code session — memri is already running
Don't have an API key?
Use your existing Claude subscription — if you've run claude in your terminal, memri detects your credentials automatically. No API key needed.
memri init --claude-code # auto-detects Claude login
Use your Google account — if you've run gcloud auth application-default login:
memri init --claude-code # auto-detects gcloud credentials
Free Gemini API — get a key in 1 minute, no credit card:
# ~/.memri/.env
GEMINI_API_KEY=your-key-here
Passive mode — no API key, no compression, still works:
{ "llm_provider": "passive" }
How it works
Three layers of memory
| Layer | What it stores | Size |
|---|---|---|
| Layer 0 | Entity index, topic clusters, user summary — always in context | ~500 tokens |
| Layer 1 | Fact/entity/reflection graph with causal and temporal edges | grows with sessions |
| Layer 2 | Raw episode archive — zero data loss, full session text | cold storage |
Three types of memory
| Type | What it stores | Example |
|---|---|---|
| Episodic | What happened in past sessions | "Chose PostgreSQL over SQLite on 2026-04-10" |
| Procedural | How to work better with this user | "Always confirm before running destructive commands" |
| Graph | Entity relationships and causal chains | "Deadline stress caused repeated tool failures" |
MCP tools
memri exposes 7 tools to your coding agent via MCP:
| Tool | When to call |
|---|---|
memri_recall |
Start of every session — restores compressed context |
memri_store |
User shares something important to remember |
memri_search |
Looking for context from a different project or thread |
memri_ingest |
Manually process a session into memory |
memri_distill |
End of session — extract generalizable strategies |
memri_status |
Check token savings, cost, session stats |
memri_forget |
Delete memories for a specific thread |
Configuration
Config at ~/.memri/config.json:
{
"llm_provider": "gemini",
"llm_model": "gemini-2.5-flash",
"memory_engine": "graph",
"observe_threshold": 30000
}
Supported providers: anthropic, claude-code-auth, gemini, gemini-adc, openai, openai-compatible (Groq, Ollama, Together, Mistral), passive.
CLI
memri init --claude-code # First-time setup
memri status # Token savings, cost, session count
memri watch # Auto-ingest new sessions in real time
memri ingest # Ingest existing session history
memri observe # Run Observer on all threads
memri embed # Build semantic search index
memri dashboard # Web dashboard at http://localhost:8050
memri config # View / edit config
Benchmarks
Evaluated on LongMemEval-S — 500 QA pairs across 6 question types designed to test AI assistant long-term memory.
| Question type | Raw baseline | memri v1.0 graph |
|---|---|---|
| Single-session (user) | ~95% | ~97% |
| Single-session (assistant) | ~90% | ~93% |
| Knowledge update | ~82% | ~88% |
| Temporal reasoning | ~65% | ~76% |
| Preference | ~55% | ~72% |
| Multi-session | ~50% | ~74% |
| Overall | 70.6% | 83% |
Raw baseline: full ~115K token conversation passed directly to Gemini 2.5 Flash. memri v1.0 graph: sessions ingested into the 3-layer graph, top-k facts retrieved per query (~500 tokens). Better accuracy, 200× fewer tokens.
Comparison
| memri | Mastra OM | mem0 | Full context | |
|---|---|---|---|---|
| Language | Python | TypeScript | Python | — |
| Install | pip install |
framework lock-in | pip install |
— |
| Works with | Claude Code, Cursor, Codex | Mastra only | any | any |
| Storage | local SQLite + graph | cloud | cloud | none |
| Graph-based memory | ✅ v1.0 | ❌ | ❌ | ❌ |
| Entity tracking | ✅ v1.0 | ❌ | partial | ❌ |
| Causal chains | ✅ v1.0 | ❌ | ❌ | ❌ |
| Procedural memory | ✅ v0.2 | ❌ | ❌ | ❌ |
| Frustration detection | ✅ v0.2 | ❌ | ❌ | ❌ |
| Semantic search | ✅ local | ❌ | ✅ cloud | ❌ |
| Dashboard | ✅ | ❌ | ✅ | ❌ |
| Token compression | 200× (graph retrieval) | 5–40× | varies | 1× |
| LongMemEval-S accuracy | 83% | — | — | 70.6% |
| Privacy | 100% local | cloud | cloud | local |
Privacy
Your data never leaves your machine.
- Conversation history and memory live in
~/.memri/— local files only you can read - No servers, no telemetry, no accounts
- The only external calls are to your LLM provider (the same one your coding agent already uses)
- API keys are read from environment variables and never written to the database
memri status # see exactly what's stored
memri forget <thread_id> # delete a specific thread
rm -rf ~/.memri/ # delete everything
Development
git clone https://github.com/SarthakK337/memri
cd memri
pip install -e ".[dev,graph,embeddings]"
pytest
Contributions welcome. Open an issue before starting large changes.
License
MIT © 2026
Metadata
Release files for memri 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| memri-1.0.1.tar.gz | 10.8 MB | Without provenance | Details for memri-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| memri-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for memri-1.0.1-py3-none-any.whl |
Total release size: 10.9 MB
Release files / memri-1.0.1.tar.gz
| Download URL | memri-1.0.1.tar.gz |
|---|---|
| Size | 10.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4b2c5ff99bf5476e9a174377c925b4695ce1bef347c319cdc615f5f1a1e43005
|
|
BLAKE2b-256 checksum How to use checksums |
4f68a1813afa11fa88d718cba25cb1aa3892b8dab6335ee5ec575745d7d59e0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Release files / memri-1.0.1-py3-none-any.whl
| Download URL | memri-1.0.1-py3-none-any.whl |
|---|---|
| Size | 96.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ed520c511ac4332f3b91a58e989337703c605075ef84034164b4f6aa27d1ed15
|
|
BLAKE2b-256 checksum How to use checksums |
1dab4d33b3a0a930eeafa29171dee8f0395f7802cf37d68b1de368d623dde7c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Security for memri 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.