Engram

Engram

Persistent memory for AI agents. In-process. No infra.

> Give your AI agent the memory of a colleague who's worked with you for years — without cloud, API keys, or Docker.

⭐ Useful to you? Star it on GitHub — it's the simplest way to help others find Engram.

[](https://github.com/HBarefoot/engram/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@hbarefoot/engram) [](https://next.henrybarefoot.com/engram) [](https://opensource.org/licenses/MIT) [](https://nodejs.org) [](https://modelcontextprotocol.io) [](https://glama.ai/mcp/servers/HBarefoot/engram)

npm install -g @hbarefoot/engram
engram start

Your AI agent now has long-term memory. Two minutes, no setup, no cloud.

• 🧠 In-process — runs inside your agent's stack. No separate server to deploy, no IPC overhead, nothing to fork.
• 📴 Offline — local SQLite + bundled embeddings (~23 MB). No API keys, no data leaving your machine.
• 🔌 MCP-native — first-class Model Context Protocol integration with Claude Desktop, Claude Code, Cursor, Windsurf, and Cline.
• 🔐 Safety by default — automatic secret detection on every write. API keys, private keys, connection strings, JWTs blocked before they hit the database.

---

Why local-first, in numbers

Engram runs inside your agent's process — no service to deploy, no account, nothing leaving your machine. That design choice is measurable:

| Metric | Engram | | |---|---|---| | Cold start → first recall | under 200 ms | import → first answer, model load included (M-series; hardware-dependent) | | Warm recall (p50, 1k memories) | ~4 ms | median query latency once the model is in memory | | Package download | ~571 KB | the npm package (1.3 MB unpacked) | | Embedding model | ~23 MB | all-MiniLM-L6-v2, fetched once, cached at ~/.engram/models | | External services | 0 | no database, broker, or cloud account | | Works offline | ✅ | zero network calls on the default path |

Measured on an Apple M4 Pro over 1,000 seeded memories — reproduce with npm run bench. These are footprint and latency numbers, not an accuracy claim: Engram doesn't try to out-rank Mem0 or Zep on memory benchmarks. The point is solid recall with none of the operational surface.

Optional accuracy lift — still 100% local. If you already run a local model, the opt-in [LLM layer](#optional-local-ai-enhancement-ollama) sharpens fact extraction: entity-extraction accuracy climbs from 45.8% (rule-based) to 95.8% with the recommended henrybarefoot1987/engram-extract model (qwen3:1.7b) — +50 pts — without a single byte leaving your device.

---

Support Engram

Engram is free and MIT-licensed — and always will be. No paywalls, no tier-locked features, no telemetry. Every feature ships in the open-source package. Sponsorship is purely a way to fund continued development, not to unlock anything.

[](https://buy.polar.sh/polarclSJqyRrR9SLdBUQEtdUt0K5j7el8kKVC1eN0wT2S36rH)

If Engram saves you time, you can sponsor it via Polar:

| Tier | Price / month | For | |---|---|---| | 🌱 Supporter | $5 | Individuals who want the project to keep shipping. | | ⚡ Power User | $25 | Heavy users who rely on Engram day to day. | | 👥 Team | $100 | Teams standardizing on Engram across projects. | | 🏢 Enterprise | $499 | Priority response on issues + dedicated integration help. |

About Enterprise. Engram is MIT-licensed, so commercial use is already granted — you don't need to buy a license to use it at work. The Enterprise tier buys priority response on issues and dedicated help wiring Engram into your stack. For organizations whose policy precludes depending on MIT-licensed software, an optional commercial-license override is available on request. (Engram is maintained by a solo developer, so this is best-effort priority response, not a contractual SLA.)

---

Why Engram?

Most agent-memory products are services you run alongside your agent — Postgres, Docker, cloud accounts, API keys. Engram embeds inside your agent's process: a focused, stable npm package with practical guardrails.

| | Engram | Lodis | Mem0 / OpenMemory | Zep | Letta | |---|---|---|---|---|---| | Maturity | v1.9.x, stable | v0.5.x, early | mature / SaaS | v0.x | v0.x | | Infra to operate | None (npm package) | None (npx package) | Cloud account or multi-container Docker | Docker + Postgres + Graphiti | Docker + Postgres | | Install footprint | ~23 MB | ~22 MB | Hundreds of MB containers (self-hosted) | Hundreds of MB | Hundreds of MB | | Works offline | ✅ | ✅ | ❌ Cloud / ✅ if self-hosted | ❌ External embed provider | ❌ External LLM provider | | MCP-native | ✅ Primary | ✅ Primary | 🟡 OpenMemory ships an MCP server | ❌ REST/SDK | ❌ REST/SDK | | REST API alongside MCP | ✅ | ❌ MCP-only | ✅ Cloud | ✅ | ✅ | | Surface area | 6 tools, 5 categories | 40 tools, 14 entity types + 4 permanence tiers + temporal supersession | varies | varies | varies | | Automatic secret detection | ✅ Blocks on every write | 🟡 memory_scrub opt-in tool | 🟡 Not first-class | 🟡 Not first-class | 🟡 Not first-class | | Agent auto-discovery | ✅ Dashboard Integration Wizard | ❌ Manual config | ❌ | ❌ | ❌ | | Desktop app | ✅ macOS Tauri menu bar | ❌ | ❌ | ❌ | ❌ | | LLM-powered extraction | ✅ Optional, on-device (Ollama; rule-based default) | ❌ LLM-free read/write | ✅ Built-in | ✅ Built-in | ✅ Built-in | | Feedback / contradiction workflow | ✅ Side-by-side conflict-resolution UI + feedback loop | 🟡 Programmatic correct/confirm/supersede tools | 🟡 No first-class feedback | 🟡 | 🟡 |

Sources: @sunriselabs/lodis, Sunrise-Labs-Dot-AI/engrams, mem0.ai, github.com/getzep/zep, github.com/letta-ai/letta. See [docs/competitive-intel.md](docs/competitive-intel.md) for the full breakdown. Engram ships optional, on-device LLM extraction (v1.9+): point llm.* at a local model — the recommended henrybarefoot1987/engram-extract (Qwen3-1.7B, Apache-2.0) or any Ollama / OpenAI-compatible endpoint — to sharpen category/entity extraction (entity recognition +50 pts vs rules — 45.8% → 95.8% — with engram-extract (qwen3:1.7b) in our benchmark), still 100% local and off by default (the zero-config path stays rule-based, offline, and infra-free). Mem0/Zep/Letta build LLM extraction in via a cloud model; Lodis is LLM-free read/write with a broader feature surface — we list it honestly.

TL;DR — when each one fits. Pick Engram if you want a focused, stable, local-first memory layer with practical guardrails (secret detection, agent auto-discovery, desktop app), a simple 5-category mental model, and optional on-device LLM extraction when you want it. Pick Lodis if you want a knowledge-graph-style memory with 14 entity types and temporal supersession. Pick Mem0/Zep/Letta if you want cloud-LLM extraction built in and don't mind operating infrastructure for it.

---

Quickstart

1. Install

npm install -g @hbarefoot/engram

2. Start the server

engram start             # MCP + REST + Dashboard on localhost:3838
engram start --mcp-only  # MCP server only, stdio mode (for agent integration)

3. Connect your AI agent

Claude Code:

claude mcp add engram -- engram start --mcp-only

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

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["start", "--mcp-only"]
    }
  }
}

Cline / Cursor / Windsurf — add the same mcpServers block to your editor's MCP config. The built-in dashboard at http://localhost:3838 has an Integration Wizard that auto-detects your installed agents and generates the config for you.

4. Use it

You:    "Remember that our API uses JWT tokens with 24-hour expiry."
Claude: (stores via engram_remember)

You:    (next day) "What authentication approach are we using?"
Claude: (recalls via engram_recall) — "JWT tokens, 24-hour expiry."

Memories persist across sessions, machine restarts, and even between different AI clients sharing the same Engram instance.

---

Memory that improves over time

Most memory systems are append-only stores: write once, retrieve forever, hope for the best. Engram learns.

• Feedback loop (engram_feedback) — when an agent recalls a memory, you or the agent can vote it helpful or unhelpful. Memories accumulate a score in [-1, 1]; consistently-unhelpful memories see their confidence decay automatically.
• Contradiction detection — when two memories conflict ("prefers Fastify" vs "switched to Express"), the consolidation engine flags them. The dashboard's Conflicts tab shows them side-by-side with four resolution actions: keep A, keep B, keep both, or dismiss.
• Deduplication on insert — identical memories (≥0.95 cosine similarity) are rejected. Near-duplicates (0.92–0.95) absorb the new content into the existing record. The store stays clean without manual pruning.
• Decay — memories that aren't recalled lose confidence over time and stop polluting future results.

The longer you use Engram, the sharper its recall gets.

---

MCP Tools

Engram exposes 6 tools to AI agents over stdio:

| Tool | Description | |---|---| | engram_remember | Store a memory with category, entity, confidence, namespace, tags. Auto-runs secret detection. | | engram_recall | Hybrid semantic + FTS5 search. Supports category, namespace, threshold, and time_filter. | | engram_forget | Delete a specific memory by ID. | | engram_feedback | Vote a memory helpful/unhelpful. Drives the feedback loop above. | | engram_context | Pre-formatted context block (markdown / xml / json / plain) with a token budget for system-prompt injection. | | engram_status | Health check: memory count, model status, configuration. |

Memory categories

• fact — Objective truths about setup, architecture, or configuration.
• preference — User likes, dislikes, style choices.
• pattern — Recurring workflows and habits.
• decision — Choices made and the reasoning behind them.
• outcome — Results of actions taken.

---

Teach your agent to use Engram

Connecting the MCP server gives your agent the memory tools — but not the judgment to use them well. The bundled engram-memory skill is that judgment layer: it teaches an agent to recall at the start of a session, store durable decisions, corrections, and outcomes as they happen, and write results back at the end — without being told each time.

engram skill install                     # → ~/.claude/skills/engram-memory/
engram skill install --project           # → ./.claude/skills/  (commit it for your team)
engram skill install --platform agents   # → ~/.agents/skills/  (cross-framework)

Works in Claude Code, Claude Desktop, Cowork, or any framework that reads the Agent Skills spec (.agents/skills). The skill is vendored in the package, so it versions with Engram and updates land on the next engram skill install; engram skill uninstall removes it cleanly.

---

CLI Reference

engram start                       # Start MCP + REST + dashboard
engram start --mcp-only            # MCP server only (stdio mode)
engram start --port 3838           # Custom REST port

engram remember ""        # Store a memory   (-c category -e entity -n namespace --confidence)
engram recall ""            # Search memories  (-l limit -c category -n namespace --threshold)
engram forget                  # Delete by ID
engram list                        # List memories    (-l limit --offset -c category -n namespace)
engram status                      # Health check

engram consolidate                 # Deduplicate, detect contradictions, decay
                                   # (--no-duplicates / --no-contradictions / --no-decay / --cleanup-stale)
engram conflicts                   # List unresolved contradictions
engram export-context              # Export curated context block
                                   # (-o file -f markdown|claude|txt|json -c categories --min-confidence ...)
engram import                      # Import from local sources
                                   # (-s cursorrules|claude|package|git|ssh|shell|obsidian|env --dry-run)

engram skill install               # Install the engram-memory agent skill
                                   # (--project → ./.claude, --platform agents → ~/.agents)
engram skill uninstall             # Remove the engram-memory skill

Run engram --help for the full flag list.

---

REST API

The REST API runs on http://localhost:3838 by default.

| Method | Endpoint | Description | |---|---|---| | GET | /health | Liveness check | | GET | /api/status | System status + stats | | GET | /api/installation-info | Detected agents, runtime, install location | | POST | /api/memories | Create a memory | | GET | /api/memories | List with pagination + filters | | POST | /api/memories/search | Semantic search | | GET | /api/memories/:id | Read a single memory | | DELETE | /api/memories/:id | Delete by ID | | POST | /api/memories/bulk-delete | Bulk-delete by ID list | | POST | /api/consolidate | Run consolidation pipeline | | GET | /api/conflicts | Legacy tag-based conflict view | | GET | /api/contradictions | Unresolved contradictions | | POST | /api/contradictions/:id/resolve | Resolve (keepfirst / keepsecond / keep_both / dismiss) | | GET | /api/contradictions/count | Unresolved count (for badge) | | GET | /api/analytics/overview | Memory health dashboard data | | GET | /api/analytics/stale | Memories with no recent recall | | GET | /api/analytics/never-recalled | Memories never returned by any query | | GET | /api/analytics/duplicates | Detected near-duplicates | | GET | /api/analytics/trends | Time-series creation/recall trends | | POST | /api/export/static | Export context block as a static file | | GET | /api/import/sources | List importable local sources | | POST | /api/import/scan | Two-phase import: preview extracted memories | | POST | /api/import/commit | Two-phase import: commit selected memories |

---

Web Dashboard

A built-in React dashboard at http://localhost:3838:

• Dashboard — Memory stats, recent activity, health gauge.
• Memories — Browse, filter, inline-edit, bulk-delete.
• Search — Semantic search with score breakdown.
• Statistics — Charts by category, namespace, and time.
• Health — Stale, never-recalled, low-feedback memories with one-click cleanup.
• Conflicts — Side-by-side contradiction resolution.
• Agents — Integration wizard that auto-detects installed AI clients and writes their MCP configs (with timestamped backups).
• Import — Wizard for cursorrules, .claude files, package.json, git config, SSH config, shell history, Obsidian, and .env.

---

How it works

1. Store: engram_remember runs content through secret detection, then embeds it locally using all-MiniLM-L6-v2 (~23 MB, CPU-only, downloaded once and cached at ~/.engram/models/). The embedding and metada

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HBarefoot
• Source: HBarefoot/engram
• License: MIT

Install and usage instructions live in the source repository linked above.