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, Python, and 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.

---

Supported Interfaces and Adapters

• MCP server over stdio and HTTP for Claude Code, Cursor, VS Code MCP clients, and other Model Context Protocol hosts.
• HTTP JSON-RPC MCP endpoints, optional WebSocket event streaming, and engram-cli over the same memory store.
• Rust single binary with SQLite + WAL local storage, optional cloud sync, and optional Meilisearch indexing.
• Python SDK and TypeScript SDK for application code and hosted deployments.
• Python adapters for CrewAI, LangChain, LlamaIndex, and OpenAI Assistants API threads.
• Project Context Discovery for CLAUDE.md, AGENTS.md, .cursorrules, GitHub Copilot instructions, and similar repo policy files.

Workflows and Ecosystems That Benefit

The native adapters above cover MCP clients, the SDKs, and the listed Python framework integrations. The same MCP/HTTP/SDK surface can also harden workflows built around OpenAI Agents SDK, LangGraph, FastMCP servers, Playwright MCP, Browser Use, and other agent runtimes, but those are integration patterns rather than first-party adapters in this repository.

Works With

Ecosystem	How this project helps
Claude Code	Native MCP server gives Claude durable project memory, decision search, and repo context retrieval.
Cursor	Native MCP configuration lets Cursor query the same memory store from .cursor/mcp.json.
VS Code MCP clients	Stdio and HTTP MCP transports expose memory tools to MCP-aware VS Code setups.
CrewAI	Python SDK includes short-term, long-term, and entity memory adapters backed by Engram.
LangChain	Python SDK includes chat history and vector-store-style adapters over Engram hybrid search.
LlamaIndex	Python SDK includes document store, vector store, and chat store adapters.
OpenAI Assistants API / Threads	Python adapter syncs thread messages into searchable Engram session memory.
OpenAI Agents SDK	No native adapter yet; use MCP, HTTP JSON-RPC, or the SDKs to persist agent state and decisions.
LangGraph	No native adapter yet; use Engram as a separate durable memory/retrieval service from graph nodes.
FastMCP servers	FastMCP projects can call Engram as an external memory server or HTTP service.
Playwright MCP	Store browser task findings, QA notes, and crawl decisions; Engram does not automate the browser.
Browser Use	Persist web task context and decisions across runs; browser control stays in Browser Use.

Searchable Guides

• MCP memory server guide
• Claude Code MCP memory guide
• Cursor MCP memory guide
• OpenAI Agents memory guide

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.

---

Choose Your Path

Internal Knowledge Server (Primary)

Use Engram when the hard part is not model access. The hard part is organizing your own context so the team can move fast without rebuilding the same mental model in every conversation.

# 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"}}}'

What you get:

• Structured ingestion workflows for notes, meetings, transcripts, and project artifacts
• Hybrid search (BM25 + vectors + fuzzy) in one call
• Memory policy layer: deterministic scoring for salience, retention, retrieval priority, reinforcement, decay, and conflict demotion over explicit memories.
• MCP / HTTP JSON-RPC / CLI / SDK access to the same organized memory
• Local-first storage with a single Rust binary and benchmarkable deployment profile

Agent Workflow Support

Capture project context and decision trails so coding agents stop repeating the same questions and stop drifting from prior decisions.

# Search decisions
engram-cli search "why did we choose postgres"

What you get:

• Project Context Discovery (CLAUDE.md, AGENTS.md, .cursorrules, etc.) via MCP tools
• Decision trails with provenance, tags, and metadata
• Local-first by default, with optional sync for shared or hosted deployments

---

Use Engram In Your Repository

See Using Engram From Another Repository for a practical setup guide covering MCP config, repo-local databases, agent instructions, CLI usage, HTTP access, and local embeddings.

What Engram Solves

Engram is built for teams that accumulate more context than a single person can keep in their head.

• Interviews, meetings, docs, and transcripts become hard to search manually at scale.
• Not everyone attends every conversation, so information becomes unevenly distributed across the team.
• That asymmetry slows down decisions that need speed and conviction.
• Engram turns scattered artifacts into a structured memory layer that agents can query directly from the source.

How It Works

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

---

Quick Start

# Install from crates.io
cargo install engram-core

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

# Run as MCP server (Claude Code, Cursor, VS Code MCP clients, etc.)
engram-server --mcp

# Or run as HTTP MCP transport
engram-server --transport http --http-port 8080

SDK Integration Pattern: Council Skill

Engram exposes the MCP tool memory_council and both SDKs now include a reusable helper wrapper.

• Python SDK: engram_client.integrations.CouncilSkill
• TypeScript SDK: CouncilSkill from engram-client
• memory_council MCP tool: direct fallback via HTTP/MCP

Python:

from engram_client import EngramClient
from engram_client.integrations import CouncilSkill

async def run_review() -> None:
    async with EngramClient(
        base_url="https://your-engram-api.fly.dev",
        api_key="ek_...",
        tenant="my-tenant",
    ) as client:
        council = CouncilSkill(
            client,
            default_workspace="architecture",
            default_timeout_seconds=120,
            default_include_raw_stages=False,
        )
        result = await council.ask("Should we switch from Redis to Postgres?")
        print(result)

TypeScript:

import { CouncilSkill, EngramClient } from "engram-client";

const client = new EngramClient({
  baseUrl: "https://your-engram-api.fly.dev",
  apiKey: "ek_...",
  tenant: "my-tenant",
});

const council = new CouncilSkill(client, {
  defaultWorkspace: "architecture",
  defaultTimeoutSeconds: 120,
});

const result = await council.askWithPersistence(
  "Should we switch from Redis to Postgres?"
);

Use this when multiple agents need the same structured consensus process.

Reusable Agent Skill Pack

Engram includes a ready-to-use Claude skill for this workflow in:

• skills/engram-council/SKILL.md

Install the skill folder in your Claude or agent skills environment and enable it when you want consistent, low-overhead consensus prompts:

1. Open your agent's skills settings
2. Add the folder skills/engram-council/
3. Enable engram-council
4. Keep your Engram MCP server configured as usual

The skill follows this flow:

• Prefer SDK CouncilSkill wrappers
• Fallback to direct memory_council MCP call when needed
• Optionally persist decision checkpoints to project memory

Why Engram

Agents forget between sessions. Context windows overflow. Important knowledge gets buried in chat logs and meeting notes.

Engram turns that into a fast, queryable memory system that keeps the team aligned on the same facts.

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

---

Positioning

Engram's strongest fit is local-first, MCP-native memory for proprietary project context: decisions, repo policy, meetings, transcripts, and agent handoffs. For competitive and marketing planning notes, see docs/strategy/. Those notes are intentionally not public-use claims until competitor, feature, and performance statements have been independently fact-checked.

---

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:

# Create memory in a specific workspace
engram-cli create "API keys stored in Vault" --workspace my-project

# List workspaces
engram-cli workspace list

Memory Tiering

Two tiers for different retention needs:

• Permanent: Important knowledge, decisions (never expires)
• Daily: Session context, scratch notes (auto-expire after 24h)

# Create a daily memory (expires in 24h)
engram-cli create "Current debugging task" --tier daily

Session Transcript Indexing

Store and search conversation transcripts:

# Index a conversation session
engram-cli session index --session-id chat-123 --messages messages.json

# Search within transcripts
engram-cli session search "error handling"

Identity Links (Entity Unification)

Link different mentions to canonical identities:

# Create identity with aliases
engram-cli identity create user:ronaldo --alias "Ronaldo" --alias "@ronaldo"

Knowledge Graph

# Export the graph
engram-cli graph --format json --output graph.json

Entity extraction (memory_extract_entities) links memories through shared entities.
Multi-hop traversal and shortest-path are available via MCP tools:

• memory_traverse
• memory_find_path

Multiple Interfaces

• MCP: Native Model Context Protocol for Claude Code, Cursor, VS Code MCP clients
• HTTP JSON-RPC: MCP-compatible endpoint at POST /mcp and POST /v1/mcp
• WebSocket: Optional event stream when ENGRAM_WS_PORT is enabled
• CLI: Developer-friendly commands
• SDKs: Python and TypeScript clients for application code

Salience Scoring

Dynamic memory prioritization based on recency, frequency, importance, and feedback:

# Get top memories by salience
engram-cli salience top --limit 10

# Boost a memory's salience
engram-cli salience boost 42

Salience decays over time, transitioning memories through lifecycle states: Active -> Stale -> Archived.

Context Quality

5-component quality assessment (clarity, completeness, freshness, consistency, source trust):

# Quality report for a workspace
engram-cli quality report --workspace my-project

# Find near-duplicate memories
engram-cli quality duplicates

Includes conflict detection for contradictions between memories and resolution workflows.

Optional Meilisearch Backend

Offload search to Meilisearch for larger-scale deployments (feature-gated):

# Build with Meilisearch support
cargo build --features meilisearch

# Run with Meilisearch indexer
engram-server --meilisearch-url http://localhost:7700 --meilisearch-indexer

SQLite remains the source of truth. MeilisearchIndexer syncs changes in the background.

MCP Resources & Prompts

Engram exposes MCP Resources and Prompts for richer agent integration:

Resources — Query-only URI templates:

• engram://memory/{id} — Get specific memory
• engram://workspace/{name} — Get workspace statistics
• engram://workspace/{name}/memories — List workspace memories
• engram://stats — Global statistics
• engram://entities — Extracted entities

Prompts — Guided workflows for agents:

• create-knowledge-base — Steps to build a new knowledge base
• daily-review — Daily memory review and archival workflow
• search-and-organize — Search results with suggested tags
• seed-entity — Initialize entity graph from project

Streamable HTTP Transport

Run Engram as HTTP server with JSON-RPC 2.0 support:

# HTTP-only server (port 8080)
engram-server --transport http --http-port 8080

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

# Bearer token authentication
ENGRAM_HTTP_API_KEY=secret-token-here engram-server --transport http

Clients connect via HTTP with JSON-RPC 2.0 at POST /mcp; POST /v1/mcp is also accepted as a compatibility alias. See MCP HTTP Authentication.

Project Context Discovery

Ingest and query instruction and policy files using MCP tools:

• memory_scan_project
• memory_get_project_context

Supported patterns:

• CLAUDE.md
• AGENTS.md (agora com documentação útil para agentes)
• .cursorrules
• .github/copilot-instructions.md
• .aider.conf.yml (se existir)
• CONVENTIONS.md, CODING_GUIDELINES.md (se existirem)

---

MCP Configuration

Add to your MCP config (for example: ~/.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"
      }
    }
  }
}

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

Available MCP Tools

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

• Full reference: docs/MCP_TOOLS.md
• Generated count and schema are in that reference (single source of truth).
• Regenerate with: ./scripts/generate-mcp-reference.sh

Planned Dream Snapshot Review

RFC 0007 defines a planned reviewable dream snapshot pipeline for derived memory proposals. Dream output is candidate memory until it is reviewed and explicitly applied with confirmation; it is not canonical memory by default.

• Contract: docs/rfcs/0007-dream-snapshot-review-pipeline.md
• Eval scaffold: docs/DREAM_SNAPSHOT_EVALS.md

---

Configuration

Variable	Description	Default
ENGRAM_DB_PATH	SQLite database path	~/.local/share/engram/memories.db
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_WS_PORT	WebSocket server port (0 = disabled)	0
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; the MCP stdio and HTTP JSON-RPC transports are the primary agent interfaces.

---

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.