What is Engram?

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.

Key Features

• 🧠 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

Quick Start

Self-Hosted

git clone https://github.com/heybeaux/engram.git && cd engram
cp .env.example .env
docker compose up -d

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

Cloud

Hosted cloud coming soon — join the waitlist at openengram.ai.

Hybrid Mode

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.

API Example

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}'

Cloud

Hosted cloud coming soon — join the waitlist at openengram.ai.

Self-hosting is fully supported today with no feature limits.

Documentation

• 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

Self-Hosting

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

Architecture

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.

Integration

MCP (Claude Desktop, Cursor, etc.)

npm install -g @openengram/mcp

This installs the engram-mcp binary. Source: heybeaux/engram-mcp.

6 tools: engram_remember, engram_recall, engram_search, engram_context, engram_observe, engram_forget

REST API

Point any AI agent at the API. Works with OpenAI, Anthropic, Ollama, LM Studio — swap LLM providers with one env var.

TypeScript SDK

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

Until it is published, you can also call the REST API directly from any language.

Comparison

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

Screenshots

LongMemEval Benchmark

Engram is evaluated against LongMemEval, the standard benchmark for long-term conversational memory (500 questions across multi-session chat histories).

Latest Results (June 2026)

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 Progression

| 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%).

Running LongMemEval

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 run

Recall Benchmark

Engram includes a comprehensive recall benchmark suite that tests semantic retrieval quality across 81 queries in 7 categories. Every PR runs the benchmark in CI with real embeddings (bge-base-en-v1.5) and ensemble reranking.

Latest Results (March 2026)

| Metric | Pre-Dream Cycle | Post-Dream Cycle | |--------|:-:|:-:| | Precision@5 | 95.1% ✅ | 96.9% ✅ | | Recall@20 | 95.7% | 96.9% | | MRR | 0.836 | 0.874 | | Isolation | 100% ✅ | 100% ✅ | | Queries Passed | 78/81 | 79/81 |

| Category | Queries | Passed | P@5 | R@20 | MRR | Isolation | |----------|:-------:|:------:|:---:|:----:|:---:|:---------:| | Adversarial | 10 | 10 | 100% | 100% | 1.00 | 100% | | Cross-feature | 10 | 10 | 100% | 100% | 0.88 | 100% | | Edge case | 16 | 16 | 100% | 100% | 0.95 | 100% | | Emotional | 10 | 9 | 85% | 95% | 0.73 | 100% | | RLS isolation | 10 | 10 | 100% | 100% | 0.88 | 100% | | Semantic | 14 | 13 | 93% | 100% | 0.79 | 100% | | Temporal | 11 | 11 | 100% | 82% | 0.87 | 100% |

Benchmark Progression

The recall pipeline evolved through several iterations:

| Phase | P@5 | Notes | |-------|:---:|-------| | Baseline (cosine only) | ~45% | Single-model vector search, no reranking | | + BM25 hybrid | ~65% | Full-text search fusion for keyword recall | | + Sentiment polarity | ~75% | Penalizes opposite-emotion memories | | + Ensemble reranking | ~85% | 2 cross-encoder models via RRF | | + Fixture enrichment | ~90% | Realistic gold memories, noise calibration | | + Temporal patterns | 95.1% | Month/year/week recognition, expanded BM25 pool | | + Dream Cycle | 96.9% | Post-consolidation: cleaner corpus, higher signal |

Running the Benchmark

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

Contributing

We'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

License

Apache License 2.0