**Three-Tiered Brain for AI agents. Self-hosted. Zero API costs.**
[Docs](https://engrammemory.ai/docs) · [Quickstart](#quick-start) · [Dashboard](https://app.engrammemory.ai) · [Cloud SDKs](#engram-cloud)
---
Engram gives your AI agent persistent memory across sessions. Store, search, recall, and forget memories using semantic embeddings — all running on your own hardware. No API keys, no cloud dependencies, no data leaving your machine.
One container bundles **Qdrant**, **FastEmbed**, and the **MCP server**. One command to install. Works with Claude Code, Cursor, Windsurf, VS Code, OpenClaw, or anything else that speaks MCP.
---
## The Problem
Every AI agent on the market forgets everything when the session ends. You spend 30 minutes explaining your codebase, your preferences, your architectural decisions. You close the tab. Tomorrow you start over.
The current solutions are all bad in different ways. OpenAI's memory is a black box you don't control. Mem0 and Zep charge $19–$249/month for managed cloud memory — your data goes through their servers. Local alternatives (LangChain memory, SQLite stores) don't scale past a few thousand memories and treat every memory equally regardless of how often you access it.
Engram exists because there should be a third option: a serious memory system that runs on your own hardware, costs nothing, and gets faster the more you use it.
---
## How It Works
### The Three-Tiered Brain
Most memory systems do one thing: vector search across everything. That's slow at scale and wasteful for queries you've made before. Engram has three tiers, and a query flows through them in order:
**Tier 1 — Hot-Tier Cache (sub-millisecond lookup)**
The memories you access most often live in an in-memory frequency cache. Each memory has an activation strength that grows with every access and decays exponentially with time — based on the ACT-R cognitive architecture from memory science. When you query, the hot tier checks first. If your query matches a cached memory above the similarity threshold, the tier lookup completes in under a millisecond. No vector search. No disk read.
**Tier 2 — Multi-Head Hash Index (O(1) candidate retrieval)**
If the hot tier misses, the query hits a Locality Sensitive Hashing index. Engram takes the first 64 dimensions of the query embedding (using Matryoshka representation learning from the nomic-embed-text-v1.5 model), runs them through 4 independent hash functions, and looks up candidates in 4 hash buckets simultaneously. This returns a small candidate set in O(1) time. The multi-head design eliminates the false-positive problem that single-hash LSH is known for.
**Tier 3 — Hybrid Vector Search (semantic depth)**
The candidates get re-ranked using full 768-dimensional cosine similarity in Qdrant, combined with BM25 sparse vector search via Reciprocal Rank Fusion. This is the deep semantic search — but it runs on the candidate set from Tier 2, not your entire memory store. Top results get promoted into the hot tier so the next similar query is even faster.
### What this means in practice
The embedding step (generating a vector from your query text) takes ~25ms on Apple Silicon via ONNX. That's the floor for every query. On top of that:
- Repeat query (hot tier hit): **~25ms** total — the tier lookup is sub-ms, embedding dominates
- Similar query (hash + re-rank): **~30ms** total
- Novel query through full MCP pipeline (all tiers + graph expansion): **~190ms**
The more you use it, the more queries hit the fast path. That's the design.
### Community Edition Caps
Engram Community is a real product with deliberate limits:
| Feature | Community | Cloud |
|---|---|---|
| Hot-tier cache | 1,000 entries max | Unlimited |
| Hash index heads | 4 | 8+ with auto-tuning |
| Hash bit size | 12-bit (4,096 buckets) | 16-bit+ adaptive |
| Entity graph | 500 entities, 1-hop | Unlimited, multi-hop |
| Consolidation (dedup) | Manual, fixed 0.95 threshold | Auto-scheduled, tunable |
| Cross-category linking | 3 connections per call | Unlimited |
| ACT-R timestamps | 50 per memory | Unlimited |
| TurboQuant compression | — | ~6x storage reduction |
| Auto category detection | — | LLM-powered |
| Overflow storage | — | Cloud-backed spillover |
| Fleet coordination | — | Multi-agent isolation |
| Analytics dashboard | — | Usage, recall rates, health |
These caps are real. They exist because [Engram Cloud](https://engrammemory.ai) is how the project gets funded. Community is genuinely useful by itself — it just doesn't have the features that matter at scale.
---
## What You Get
Fifteen MCP tools — ten core memory tools and five hive-management tools for multi-device sharing — plus a visual graph command:
| Tool | What it does |
|---|---|
| `memory_store` | Save a memory with semantic embedding, auto-classification, and conflict detection |
| `memory_search` | Three-tier recall search with confidence scoring and match context |
| `memory_recall` | Auto-inject relevant memories into agent context |
| `memory_forget` | Remove memories by ID or search match |
| `memory_consolidate` | Find and merge near-duplicate memories |
| `memory_connect` | Discover cross-category connections via the entity graph |
| `memory_feedback` | Report which search results were useful — improves future recall |
| `memory_get` | Fetch one or more memories by UUID |
| `memory_timeline` | Browse memories chronologically with date-range filtering |
| `memory_answer` | Answer a question from stored memories, with cloud synthesis when API key is set |
| `hive_list` | List all hives this API key has access to (multi-device shared memory pools) |
| `hive_create` | Create a new shared hive (`name`, `slug`) |
| `hive_grant` | Grant another API-key prefix `read` or `readwrite` access to a hive |
| `hive_revoke` | Revoke a granted key prefix from a hive |
| `hive_grants_list` | List active grants on a hive |
| `/graph` | Generate an interactive visual graph of your memories (Claude Code slash command) |
**Categories:** 13 types — `preference`, `fact`, `decision`, `entity`, `goal`, `plan`, `error`, `insight`, `skill`, `event`, `question`, `relationship`, `other` — auto-detected by local keyword classifier across all surfaces (Python engine, TypeScript plugin, MCP tools).
The recall engine includes a Kuzu-backed entity graph for entity tracking, co-retrieval patterns, spreading activation, and `PREFERRED_OVER` edges from feedback signals. The `/graph` command renders your memory graph as an interactive vis.js visualization — the host LLM does entity extraction, the vendored [graphify](https://github.com/safishamsi/graphify) pipeline handles rendering.
---
## Quick Start
### 1. Start the container
```bash
docker run -d \
--name engram-memory \
--restart unless-stopped \
-p 6333:6333 -p 11435:11435 -p 8585:8585 \
-v engram_data:/data \
engrammemory/engram-memory:latest
```
One container. Qdrant, FastEmbed (ONNX, native ARM64 + x86_64), and the MCP server all bundled inside, supervised by s6-overlay. Memories persist in the `engram_data` volume across restarts.
If you've cloned the repo, `bash scripts/setup.sh` does the same thing plus auto-registers the MCP with Claude Code and generates an OpenClaw config.
### 2. Connect your agent
**Claude Code:**
```bash
claude mcp add engrammemory -s user --transport http http://localhost:8585/mcp
# Install slash commands (/graph etc.)
mkdir -p ~/.claude/commands
docker cp engram-memory:/app/commands/. ~/.claude/commands/
```
**Cursor, Windsurf, VS Code, Claude Desktop, Cline, Zed, and 9 other clients** — one command via [`install-mcp`](https://www.npmjs.com/package/install-mcp):
```bash
npx -y install-mcp@latest http://localhost:8585/mcp \
--client