Persistent memory for AI agents
Hosted Version • MCP Server • Dashboard • Local Embeddings • TypeScript SDK • API Docs
Engram is a memory layer for AI agents — store, recall, and evolve memories with semantic search, knowledge graphs, and autonomous consolidation. It gives your agents persistent, structured memory so they never wake up blank again.
An engram is a hypothetical permanent change in the brain accounting for the existence of memory — a memory trace.
- 🧠 Semantic memory storage with vector embeddings — find memories by meaning, not keywords
- 🔍 Ensemble search (4 models) — Reciprocal Rank Fusion eliminates single-model blind spots
- 🌙 Dream Cycle — autonomous memory consolidation inspired by sleep neuroscience
- 🕸️ Knowledge graph extraction — entities and relationships visualized with D3
- 🔒 Multi-tenant with API key auth — cryptographic user isolation
- 💳 SaaS-ready — usage tracking and cloud features built in
- 🐳 Docker Compose for easy self-hosting — up and running in 3 commands
- 🔗 Hybrid mode — self-hosted + cloud link for backup, sync, and cloud ensemble models
- 🏠 Self-hosted setup wizard — first-run detection, guided setup, zero config
- 📡 Webhooks with HMAC signing — real-time event notifications
- 🛡️ Safety-critical detection — 16 patterns for allergies, medications, legal directives
- ⏰ Temporal reasoning — understands "yesterday," "last week," natural language time
- 📊 Fog Index — cognitive health scoring to monitor memory drift
git clone https://github.com/heybeaux/engram.git && cd engram
cp .env.example .env
docker compose up -dAPI at localhost:3001.
The Compose stack in this repo starts the API and backing services. The dashboard UI is maintained separately in heybeaux/engram-dashboard; run it alongside this API if you want the setup wizard and browser UI.
Protected API endpoints require an agent API key generated by the setup/register flow unless you explicitly enable local LAN bypass for development. See Quickstart for the local auth options.
Hosted cloud coming soon — join the waitlist at openengram.ai.
Run self-hosted with full local features, then link to OpenEngram Cloud from Settings to unlock cloud ensemble models, backup, and cross-device sync. Best of both worlds — your data stays local, premium features from the cloud.
See the Getting Started Guide for detailed walkthroughs.
Store a memory:
curl -X POST http://localhost:3001/v1/memories \
-H "Content-Type: application/json" \
-H "X-AM-API-Key: <api-key-from-register-response>" \
-H "X-AM-User-ID: user_123" \
-d '{"raw": "The user prefers dark mode and is allergic to peanuts"}'Search memories:
curl -X POST http://localhost:3001/v1/memories/query \
-H "Content-Type: application/json" \
-H "X-AM-API-Key: <api-key-from-register-response>" \
-H "X-AM-User-ID: user_123" \
-d '{"query": "What are the user preferences?", "limit": 5}'Hosted cloud coming soon — join the waitlist at openengram.ai.
Self-hosting is fully supported today with no feature limits.
- Getting Started — Self-hosted, cloud, and hybrid setup
- API Reference — Full endpoint documentation
- Deployment Architecture — Mode detection, feature gating, cloud link, sync
- Configuration — All environment variables and deployment modes
- Swagger UI — Interactive API explorer (when running locally)
- Online Docs — Hosted documentation
See docs/QUICKSTART.md for detailed self-hosting instructions including:
- Docker Compose setup
- Building from source
- Fully local mode (Ollama + engram-embed, zero cloud dependency)
- Environment configuration
Engram is built on NestJS with PostgreSQL + pgvector for storage. The system includes:
- Core API — CRUD, search, context generation, 120+ endpoints
- Ensemble Search — 4 embedding models fused via Reciprocal Rank Fusion
- Dream Cycle — 4-stage consolidation: dedup → staleness → patterns → report
- engram-embed — Local Rust embedding server with Metal GPU acceleration (~10ms per vector)
- Dashboard — Next.js app for memory browsing, knowledge graph visualization, and system monitoring
See the Architecture Documentation for the full technical breakdown.
npm install -g @openengram/mcpThis installs the engram-mcp binary. Source: heybeaux/engram-mcp.
6 tools: engram_remember, engram_recall, engram_search, engram_context, engram_observe, engram_forget
Point any AI agent at the API. Works with OpenAI, Anthropic, Ollama, LM Studio — swap LLM providers with one env var.
The TypeScript client lives in heybeaux/engram-client. It is not published to npm yet — install from source until the package ships:
git clone https://github.com/heybeaux/engram-client.gitUntil it is published, you can also call the REST API directly from any language.
| Feature | Engram | Mem0 | Zep | LangMem |
|---|---|---|---|---|
| Self-hosted | ✅ | ✅ | ✅ | ✅ |
| Local embeddings (zero cost) | ✅ Metal GPU | ❌ | ❌ | ❌ |
| Multi-model ensemble search | ✅ 4 models | ❌ | ❌ | ❌ |
| Dream Cycle (consolidation) | ✅ 4-stage | ❌ | ❌ | ❌ |
| Safety-critical detection | ✅ 16 patterns | ❌ | ❌ | ❌ |
| Knowledge graph | ✅ | ❌ | ✅ | ❌ |
| Temporal reasoning | ✅ | ❌ | ❌ | ❌ |
| SaaS-ready (billing, limits) | ✅ | ❌ | ❌ | ❌ |
| License | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT |
Dashboard — Memory stats, Fog Index, API volume
Knowledge Graph — Entities and relationships visualized with D3
Memory Browser — Semantic search, layer filtering, importance scores
Engram is evaluated against LongMemEval, the standard benchmark for long-term conversational memory (500 questions across multi-session chat histories).
78.1% overall accuracy (388/497) on the full 500-question set, end-to-end through Engram's ingest → recall → answer pipeline.
| Category | Accuracy |
|---|---|
| Single-session-user | 95.7% (67/70) |
| Single-session-preference | 90.0% (27/30) |
| Single-session-assistant | 80.4% (45/56) |
| Knowledge-update | 76.0% (57/75) |
| Temporal-reasoning | 72.9% (97/133) |
| Multi-session-user | 71.4% (95/133) |
| Run | Accuracy | Key Changes |
|---|---|---|
| Run 1 | 53.2% | Baseline pipeline |
| Run 2 | 64.0% | Recall + prompt fixes |
| Run 3 | 78.1% | Embedding-dimension guard, recency-aware recall, question-date injection, in-text date extraction, temporal arithmetic rules, preference framing |
Biggest gains came in temporal reasoning (32.3% → 72.9%) and multi-session recall (42.1% → 71.4%).
cd eval/longmemeval
set -a; source .env.local; set +a
pnpm longmemeval --subset full # Full 500-question run
pnpm longmemeval --subset full --batch-ingest --ingest-concurrency 4 # Faster ingest
pnpm longmemeval --subset full --resume results/full-<ts>.jsonl # Resume a crashed runThe recall suite exercises 81 fixture queries in seven categories. Metric version 2 reports required-item coverage@5 on the 57 queries with top-five labels, expected-item coverage@20 on the ten queries with top-20 labels, and reciprocal rank of the first required hit. Missing labels are excluded, not scored as perfect. An empty expected list is not an explicit no-answer judgment.
The previous published 95.1%/96.9% “precision” and associated recall/MRR tables used a different, inflated scoring definition. Those historical numbers are withdrawn as precision claims and must not be compared directly with version 2. Partial required-item labels do not establish conventional precision or exhaustive recall; fully judged held-out queries are still needed.
The real-embedding suite always enforces the unchanged 95% required-coverage gate, forbidden-ID isolation, and any explicitly labelled no-answer cases. Reports include label denominators and a metric version. A passing forbidden-ID fixture does not prove production database-role isolation.
# Requires: PostgreSQL (pgvector), embedding server, reranker servers
pnpm benchmark # Pre-dream-cycle
pnpm test:e2e -- --testPathPatterns=recall-benchmark-dream # Post-dream-cycle
pnpm benchmark:compare # Compare latest vs previous runWe'd love your help! See CONTRIBUTING.md for guidelines.
High-impact areas:
- Python SDK
- Integration adapters (LangChain, CrewAI, AutoGen)
- New embedding/LLM providers
- Documentation and examples
Every agent deserves to remember.