engram

Engram is a persistent memory layer for AI agents, running in-process, based on local SQLite storage and local embeddings, and claimed to have zero cloud dependency, no API keys required, and no Docker required. The project is MIT licensed.

Purpose To provide long-term memory for AI agents so that they can retain memory content across sessions, across machine restarts, and across different AI clients sharing the same Engram instance.

Main capabilities

1. Storage and recall: engram_remember embeds content locally using all-MiniLM-L6-v2 (about 23 MB, CPU only, cached in ~/.engram/models/ after the first download) after secret detection; embeddings and metadata are stored in SQLite (~/.engram/memory.db). engram_recall embeds the query, obtains candidates through FTS5 and embeddings within the namespace, and returns them scored by (similarity × 0.45) + (recency × 0.15) + (confidence × 0.15) + (access × 0.05) + (feedback × 0.10) + fts_boost.
2. Memory categories: includes five types: fact (objective fact), preference (preference), pattern (pattern), decision (decision), and outcome (outcome).
3. Learning mechanism: engram_feedback allows voting helpful/not helpful on recalled memories; memories accumulate a score in [-1, 1], and confidence is adjusted after 5 votes; memories that remain unhelpful have their confidence automatically decayed.
4. Contradiction detection: when two memories conflict, they are flagged by the consolidation engine; the dashboard Conflicts tab can view them side by side and provides four handling actions: keep A, keep B, keep both, and ignore; after enabling the optional LLM layer, an LLM confirmation step is added to reduce false positives.
5. Deduplication and decay: memories that are exactly the same on insertion (similarity ≥0.95) are rejected, and near-duplicates (0.92–0.95) merge the new content into the existing record; memories that have not been recalled for a long time have their confidence decrease over time.
6. Security protection: every write undergoes pattern-based secret detection (OpenAI/Stripe/AWS/GitHub/Slack/Google keys, private keys, connection strings, JWT, high-entropy strings); detected secrets either cause the memory to be rejected or are redacted.
7. MCP tools: through stdio exposes 6 tools to AI agents.
8. Dashboard: the built-in React dashboard is located at http://localhost:3838，含 Dashboard (statistics, recent activity, health), Memories (browse, filter, inline edit, bulk delete), Search (semantic search and score breakdown), Statistics (charts by category/namespace/time), Health (stale, never recalled, low-feedback memories and one-click cleanup), Conflicts (side-by-side contradiction resolution), Agents (automatically detect installed AI clients and write MCP configuration, with timestamped backups), Import (import cursorrules, .claude files, package.json, git config, SSH config, shell history, Obsidian, .env). The REST API runs by default at http://localhost:3838。
9. Memory skill: The package includes the engram-memory skill, which serves as a judgment layer, teaching the agent to recall at the start of a session, store persistent decisions/corrections/results in real time, and write back results at the end; it is applicable to Claude Code, Claude Desktop, Cowork, or any framework that reads the Agent Skills specification (.agents/skills). It can be managed via engram skill install / engram skill uninstall.
10. Namespace isolation and time queries: Supports namespace isolation; MCP and REST support time range filtering, and engram_recall can pass a time_filter object, supporting after / before (ISO dates or relative strings such as "3 days ago") or period shorthands (today, yesterday, this_week, last_week, this_month, last_month, this_year, last_year).
11. Optional local LLM enhancement (v1.9+): Disabled by default (llm.provider: null), and the zero-configuration path uses rule-based extraction and does not call an LLM. When enabled, it can improve classification/entity/confidence recognition for new memories and adds an LLM confirmation step to reduce contradictory false positives. Use local Ollama (default) or any OpenAI-compatible local server (LM Studio, llama.cpp). The recommended model is henrybarefoot1987/engram-extract (based on Qwen3-1.7B, Apache-2.0, © Alibaba Cloud; Engram only adds extraction prompts and constrained output configuration). If the endpoint is not local (localhost/127.0.0.1), memory content will be sent there, and the AI Enhancement tab on the desktop will display a clear warning; when the model is unreachable, a circuit breaker pauses that layer and falls back to rule-based extraction.

Usage

1. Installation and startup: The repository provides steps for installing and starting the server (see the repository README for specific commands).
2. Connecting an AI agent: For Claude Desktop, add an mcpServers configuration block in ~/Library/Application Support/Claude/claude_desktop_config.json; for Cline / Cursor / Windsurf, add the same mcpServers block in the editor MCP configuration; it can also be done through http://localhost:3838 's built-in dashboard Integration Wizard, which automatically detects installed agents and generates the configuration.
3. Data directory: All content is stored under ~/.engram/; the override priority is --data-dir parameter > ENGRAM_DATA_DIR environment variable > dataDir in ~/.engram/config.json > default ~/.engram.
4. Sandbox evaluation: The data directory can be pointed to a temporary location to avoid touching ~/.engram/memory.db, which is suitable for first-time evaluation, CI runs, or testing the desktop sidecar with a fresh database.
5. Configuration: Works out of the box by default; the custom configuration file is ~/.engram/config.json, and the llm.* block is used for the optional local AI enhancement.
6. Library usage: It can be used as a library within a Node.js application (see the repository documentation for details).
7. CLI: Run engram --help to view the full list of parameters.

Use cases Developers who want to add local-first long-term memory to AI agents without operational infrastructure and who value key protection and keeping data on their own machine; scenarios where unified memory is shared across multiple MCP clients.

Limitations and notes Engram does not compete for rankings with Mem0 or Zep on memory benchmarks; its positioning is reliable recall with zero operational overhead. The author is an independent developer, and priority response for the enterprise tier is best-effort, not a contractual SLA. The performance numbers given in the repository come from tests on an Apple M4 Pro with 1,000 seeded memories (reproducible with npm run bench) and are resource usage and latency data rather than accuracy claims. The optional LLM layer is disabled by default; the zero-configuration path does not call an LLM. Specific installation commands, complete configuration fields, library call examples, etc. are subject to the repository documentation, and this material does not provide them in full.