Engram – persistent memory for AI agents, in-process, no cloud

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 1

Star 5

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

113 Commits

113 Commits

.github

.github

assets/brand

assets/brand

bench

bench

bin

bin

dashboard

dashboard

desktop

desktop

docs

docs

examples

examples

models

models

scripts

scripts

skills/engram-memory

skills/engram-memory

src

src

stats

stats

test

test

.dockerignore

.dockerignore

.gitignore

.gitignore

.npmignore

.npmignore

BUSINESS_MODEL.md

BUSINESS_MODEL.md

CHANGELOG.md

CHANGELOG.md

CLA.md

CLA.md

CLAUDE.md

CLAUDE.md

CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

CONTRIBUTING.md

CONTRIBUTING.md

DESIGN_SYSTEM.md

DESIGN_SYSTEM.md

Dockerfile

Dockerfile

LICENSE

LICENSE

QUICKSTART.md

QUICKSTART.md

README.md

README.md

SECURITY.md

SECURITY.md

ecosystem.config.cjs

ecosystem.config.cjs

engram-logo.png

engram-logo.png

eslint.config.js

eslint.config.js

glama.json

glama.json

package-lock.json

package-lock.json

package.json

package.json

server.json

server.json

vitest.config.js

vitest.config.js

Repository files navigation

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.

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

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

1. Start the server

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

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

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

[truncated for AI cost control]