engram

Engram is a universal memory layer for AI agents, positioned as "remember, recall, consolidate," with the goal of providing agents with knowledge graph, memory consolidation, and spreading activation capabilities, not just storage.

Purpose Engram is used to provide AI agents with long-term memory capabilities, enabling them to remember, recall, and consolidate information, thereby maintaining an understanding of context in scenarios such as long conversations.

Main capabilities

• Semantic vector search: stores memories in a local SQLite and supports semantic recall.
• Knowledge graph: provides knowledge graph capabilities and supports graph neighbor queries.
• Memory consolidation: LLM-driven consolidation.
• Spreading activation: supports spreading activation, with configurable parameters such as spread, spread hops, spread decay, and spread entity hops.
• Contradiction detection and bitemporal knowledge graph: according to the description, it has contradiction detection and bitemporal knowledge graph capabilities.
• MCP tools: provides 17 memory tools via MCP.
• REST API: provides a REST API for non-Node environments; the server runs by default on http://127.0.0.1:3800。

Usage It is recommended to install via MCP in Claude Code / Cursor. After installation, engram init can be used to complete configuration such as MCP registration, CLAUDE.md instructions, automatic tool approval, and a consolidation hook at session end. After installation, running engram doctor can confirm whether all checks (vault, API key, embeddings, MCP registration, CLAUDE.md) pass.

REST API endpoints (base URL:http://127.0.0.1:3800，均返回 JSON):

• POST /v1/memories — store a memory
• GET /v1/memories/recall — recall memories; query parameters: context (required), entities, topics, types, limit, spread, spreadHops, spreadDecay, spreadEntityHops
• POST /v1/memories/recall — recall (complex query); the response structure is the same as GET recall
• DELETE /v1/memories/:id — forget a memory
• GET /v1/memories/:id/neighbors — graph neighbors
• POST /v1/consolidate — run consolidation
• GET /v1/briefing — session briefing; POST /v1/briefing with a JSON request body can also be used
• GET /v1/stats — Vault statistics
• GET /v1/entities — list entities
• GET /health — health check

Data and configuration The default database location is ~/.engram/, which can be overridden via environment variables. Embeddings, consolidation, and LLM-driven extraction require configuring an LLM provider (default Gemini, using the user's own API key). The model can be set via ENGRAM_LLM_MODEL, which must be set before running engram init; this setting is written to the MCP server configuration. The npm version check every 4 hours can be disabled via ENGRAM_NO_UPDATE_CHECK=1.

Applicable scenarios Suitable for developers and projects that need to provide AI agents with long-term memory, semantic recall, knowledge graphs, and memory consolidation, especially in environments that support MCP such as Claude Code / Cursor.

Limitations and notes

• Data is stored locally in SQLite (~/.engram/).
• Network calls include only: calls to the user-configured LLM provider (default Gemini, using the user's own API key) for embeddings, extraction, and consolidation, as well as a version check against the npm registry every 4 hours (can be disabled with ENGRAM_NO_UPDATE_CHECK=1 disabled). No telemetry.
• When using the Gemini free tier, be aware of rate limits: gemini-2.5-flash free tier is about 20 requests/minute, about 1,500 requests/day; embedding calls also count toward the limit. Lighter models such as gemini-3.1-flash-lite have a higher free-tier RPM.
• Built-in retry logic: when rate limits are encountered, it automatically waits and retries up to 3 times.
• If used frequently (rapid consecutive remember + recall), it is recommended to upgrade to a paid Gemini API key to get higher limits.
• The project uses the MIT license and is open source.

Benchmark performance (LOCOMO long-conversation memory recall)

• Engram: 80.0% accuracy, 776 tokens/query
• File-based memory (appending raw facts to a markdown file): 28.8% accuracy
• Human memory file (manually curated summaries): 74.5% accuracy, 1,373 tokens/query
• Mem0: 66.9% accuracy Engram reduces tokens by 44% compared with human memory files (776 vs 1,373 per query). Full context (dumping the entire conversation history) scores the highest, but uses 30x the tokens and cannot scale beyond the context window limit; Engram closes most of the gap while reducing tokens by 96.6%.