Engram

MCP memory server for Claude Code, Cursor, and AI agents.

Engram is a Rust, local-first memory layer for teams that need agents to remember proprietary project context across sessions. It ingests meetings, docs, transcripts, and decisions; stores them in SQLite; indexes them with hybrid BM25/vector/fuzzy search and knowledge graph links; and exposes the same source of truth through MCP, HTTP JSON-RPC, CLI, and Python/TypeScript SDKs.

Use Engram when coding agents, research crews, or internal AI tools need durable memory with provenance instead of rebuilding context from chat history.

---

Quick Start

# Install with Homebrew (tracks the GitHub release artifacts)
brew install aiconnai/engram/engram

# Or install from crates.io (may lag the latest GitHub/Homebrew release)
cargo install engram-core

# Or from source
git clone https://github.com/aiconnai/engram.git
cd engram && cargo install --path .

Run as an MCP server:

# stdio transport (Claude Code, Cursor, VS Code MCP clients, etc.)
engram-server --transport stdio

# HTTP JSON-RPC transport
engram-server --transport http --http-port 8080

# Both (default)
engram-server --transport both --http-port 8080

MCP Configuration

Add to your MCP config (e.g. ~/.claude/mcp.json, .cursor/mcp.json, or your VS Code MCP extension config):

{
  "mcpServers": {
    "engram": {
      "command": "engram-server",
      "args": [],
      "env": {
        "ENGRAM_DB_PATH": "~/.local/share/engram/memories.db"
      }
    }
  }
}

By default, tools/list exposes a focused Essential profile plus discover_tools. Set ENGRAM_TOOL_TIER=standard in env when an MCP host needs the broader pre-0.23 tool surface on first connect, or ENGRAM_TOOL_TIER=all for every compiled tool.

If you built from source, use the full path to the binary (e.g. /path/to/engram/target/release/engram-server).

First calls over HTTP:

# Store a memory
curl -X POST localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"memory_create","arguments":{"content":"User prefers dark mode"}}}'

# Hybrid search
curl -X POST localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"memory_search","arguments":{"query":"user preferences"}}}'

For a full repository setup (repo-local databases, agent instructions, CLI, local embeddings), see Using Engram From Another Repository.

---

Why Engram

Agents forget between sessions. Context windows overflow. Important knowledge gets buried in chat logs and meeting notes. Engram turns scattered artifacts into a structured memory layer that agents query directly from the source:

Problem	Engram Solution
Knowledge is spread across meetings, docs, and chats	Structured ingestion workflows into one memory layer
Search misses exact terms or related concepts	Hybrid search: BM25 + vectors + fuzzy, fused and ranked
Context disappears between sessions	Persistent memory on SQLite + WAL
Teams need a private source of truth	Local-first with optional sync and shared workspaces
Agents need direct access to the same facts	MCP-native tools for read/write/search workflows
No project awareness	Project Context Discovery (CLAUDE.md, AGENTS.md, .cursorrules, etc.)

How it works:

1. Ingest meetings, docs, transcripts, and notes.
2. Organize — normalize, tag, and store with durable provenance.
3. Index — combine exact, fuzzy, and semantic retrieval.
4. Expose via MCP — let Claude Code and other agents query the same knowledge base.

Wondering how Engram compares to Mem0, Zep/Graphiti, Cognee, or simpler MCP memory servers? See the honest comparison in docs/COMPARISON.md.

---

Core Features

Hybrid Search

# Handles typos, semantic matches, and exact keywords in one query
engram-cli search "asynch awiat rust"
# → Returns: "Use async/await for I/O-bound work in Rust"

Multi-Workspace Support

Isolate memories by project or context through the MCP tools:

{
  "name": "memory_create",
  "arguments": {
    "content": "API keys are stored in Vault",
    "workspace": "my-project",
    "memory_type": "decision"
  }
}

Memory Tiering & Lifecycle

Two tiers for different retention needs:

• Permanent: important knowledge and decisions (never expires) — memory_create
• Daily: session context and scratch notes (auto-expire after 24h) — memory_create_daily

Salience scoring prioritizes memories by recency, frequency, importance, and feedback (salience_top, salience_boost). Salience decays over time; lifecycle transitions (Active -> Stale -> Archived) are decided by lifecycle_run.

Session Transcript Indexing

Store conversation transcripts with session_index and search them with memory_search ("include_transcripts": true).

Knowledge Graph & Identity Links

Entity extraction (memory_extract_entities) links memories through shared entities; identity_create unifies different mentions under canonical identities. Multi-hop traversal and shortest-path are available via memory_traverse and memory_find_path, and the graph can be exported:

engram-cli graph --format json --output graph.json

Context Quality

5-component quality assessment (clarity, completeness, freshness, consistency, source trust) via quality_report, plus duplicate detection (quality_find_duplicates) and conflict detection/resolution workflows for contradictions between memories.

Project Context Discovery

Ingest and query repo instruction and policy files with memory_scan_project and memory_get_project_context. Supported patterns include CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md, .aider.conf.yml, CONVENTIONS.md, and CODING_GUIDELINES.md (when present).

MCP Resources & Prompts

Resources — query-only URI templates: engram://memory/{id}, engram://workspace/{name}, engram://workspace/{name}/memories, engram://stats, engram://entities.

Prompts — guided workflows for agents: create-knowledge-base, daily-review, search-and-organize, seed-entity.

Optional Meilisearch Backend

Offload search to Meilisearch for larger-scale deployments (feature-gated). SQLite remains the source of truth; the indexer syncs changes in the background:

cargo build --features meilisearch
engram-server --meilisearch-url http://localhost:7700 --meilisearch-indexer

Dream Snapshot Review Pipeline

RFC 0007 defines an implemented reviewable pipeline for derived memory proposals. Dream output is candidate memory until reviewed and explicitly applied with confirmation; it is not canonical memory by default. See the contract and eval scaffold.

Available MCP Tools

The MCP tool reference is generated from the source of truth (src/mcp/tools/registry.rs) and tracked in docs/MCP_TOOLS.md.

• By default, tools/list exposes only the Essential profile plus discover_tools; set ENGRAM_TOOL_TIER=standard or all for broader profiles.
• Generated count, tier, group, feature requirement, and schema are in that reference (single source of truth).
• Regenerate with: ./scripts/generate-mcp-reference.sh

---

Interfaces & Integrations

• MCP over stdio and HTTP for Claude Code, Cursor, VS Code MCP clients, and other Model Context Protocol hosts.
• HTTP JSON-RPC 2.0 at POST /mcp (POST /v1/mcp as compatibility alias), with optional Bearer token auth via ENGRAM_HTTP_API_KEY — see MCP HTTP Authentication.
• WebSocket event streaming, opt-in via ENGRAM_WS_PORT.
• CLI (engram-cli) over the same memory store.
• Python and TypeScript SDKs for application code and hosted deployments.

Ecosystem	How Engram helps
Claude Code / Cursor / VS Code MCP clients	Native MCP server for durable project memory, decision search, and repo context retrieval.
CrewAI	Python SDK adapters for short-term, long-term, and entity memory.
LangChain	Python SDK chat history and vector-store-style adapters over hybrid search.
LlamaIndex	Python SDK document store, vector store, and chat store adapters.
OpenAI Assistants API / Threads	Python adapter syncs thread messages into searchable session memory.
OpenAI Agents SDK, LangGraph, FastMCP, Playwright MCP, Browser Use	No first-party adapters; integrate via MCP, HTTP JSON-RPC, or the SDKs — see the runnable examples below.

Runnable examples:

• Claude MCP — Claude Code MCP config plus a seed/search smoke test.
• OpenAI Agents SDK — function tools that call Engram over HTTP JSON-RPC.
• FastMCP server — FastMCP tools backed by Engram memory calls.
• LangGraph tool — graph nodes that search and store Engram memory.

Council Skill (SDKs + MCP)

Engram exposes the memory_council MCP tool for structured multi-perspective consensus, wrapped by both SDKs (engram_client.integrations.CouncilSkill in Python, CouncilSkill from engram-client in TypeScript). A ready-to-use Claude skill lives in skills/engram-council/ — install the folder in your agent's skills environment and keep your Engram MCP server configured as usual.

---

Configuration

Variable	Description	Default
ENGRAM_DB_PATH	SQLite database path	~/.local/share/engram/memories.db
ENGRAM_TOOL_TIER	MCP tool surface (essential, standard, all)	essential
ENGRAM_STORAGE_URI	S3/R2 URI for cloud sync	-
ENGRAM_CLOUD_ENCRYPT	AES-256-GCM encryption	false
ENGRAM_EMBEDDING_MODEL	Embedding model (tfidf, local, openai)	tfidf
ENGRAM_ONNX_MODEL_DIR	Local embedding model directory (model.onnx + tokenizer.json)	platform data dir
ENGRAM_CLEANUP_INTERVAL	Expired memory cleanup interval (seconds)	3600
ENGRAM_HTTP_PORT	HTTP transport port	3100
ENGRAM_HTTP_BIND_ADDRESS	HTTP transport bind address	127.0.0.1
ENGRAM_HTTP_API_KEY	Bearer token for the HTTP transport	-
ENGRAM_WS_PORT	WebSocket server port (0 = disabled)	0
ENGRAM_WS_BIND_ADDRESS	WebSocket server bind address	127.0.0.1
ENGRAM_WS_AUTH_KEY	Bearer token for WebSocket upgrade authentication	-
ENGRAM_GRPC_PORT	gRPC transport port (requires --features grpc)	50051
ENGRAM_GRPC_BIND_ADDRESS	gRPC transport bind address (requires --features grpc)	127.0.0.1
ENGRAM_GRPC_API_KEY	Bearer token for the gRPC transport	-
OPENAI_API_KEY	OpenAI API key (for openai embeddings)	-
MEILISEARCH_URL	Meilisearch URL (requires --features meilisearch)	-
MEILISEARCH_API_KEY	Meilisearch API key	-
MEILISEARCH_INDEXER	Enable background sync to Meilisearch	false
MEILISEARCH_SYNC_INTERVAL	Sync interval in seconds	60

Local embeddings

Local sentence-transformer embeddings are opt-in and keep the default binary small:

cargo build --features local-embeddings
./target/debug/engram-cli model download minilm-l6-v2
ENGRAM_EMBEDDING_MODEL=local ./target/debug/engram-server

This backend uses ONNX Runtime with all-MiniLM-L6-v2 (384 dimensions). The model is downloaded explicitly and is not bundled into the binary.

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Engram Server                           │
├─────────────────────────────────────────────────────────────────┤
│  MCP stdio    │  HTTP MCP     │  WebSocket* │  CLI / SDKs       │
├─────────────────────────────────────────────────────────────────┤
│                    Intelligence Layer                           │
│  • Salience scoring  • Quality assessment  • Entity extraction  │
│  • Context compression  • Lifecycle management                  │
├─────────────────────────────────────────────────────────────────┤
│                      Search Layer                               │
│  • BM25 (FTS5)  • Vectors (cosine)  • Fuzzy  • RRF fusion       │
│  • Optional Meilisearch backend for scaled deployments          │
├─────────────────────────────────────────────────────────────────┤
│                     Storage Layer                               │
│  • SQLite + WAL  • Turso/libSQL  • Connection pooling           │
│  • Optional S3/R2 sync with AES-256 encryption                  │
└─────────────────────────────────────────────────────────────────┘

* WebSocket event streaming is opt-in via ENGRAM_WS_PORT; HTTP, WebSocket, and gRPC network listeners bind 127.0.0.1 by default. Explicit public binds require the operator to configure the relevant bind-address variable and deploy the matching authentication control; public WebSocket binds require ENGRAM_WS_AUTH_KEY even behind a trusted proxy. MCP stdio remains the default agent interface.

---

Documentation

• Quickstart · Getting Started · User Guide
• Using Engram From Another Repository
• Engram vs alternatives
• MCP memory server guide
• Claude Code MCP memory guide
• Cursor MCP memory guide
• OpenAI Agents memory guide
• Architecture · MCP tool reference · Roadmap

---

Contributing

Contributions welcome! See CONTRIBUTING.md for conventions.

cargo test           # Run all tests
cargo clippy         # Lint
cargo fmt            # Format

---

License

MIT License — see LICENSE for details.