🧠 Engram

Give your AI agents persistent memory. Zero cloud. Zero API keys. Two-minute setup.

Engram is a local-first memory server that lets AI agents like Claude, Cursor, Cline, and Windsurf remember things across sessions. It runs entirely on your machine — no external services, no data leaving your device, no monthly bills.

npm install -g @hbarefoot/engram
engram start

That's it. Your AI agent now has long-term memory.

---

Why Engram?

Most AI memory solutions require cloud infrastructure, API keys, and external vector databases. Engram takes a different approach:

	Engram	Mem0	Zep
Setup time	2 minutes	Requires API keys + cloud setup	Requires Docker + API keys
Dependencies	None — SQLite + local embeddings	OpenAI API, vector DB (Qdrant/Pinecone)	PostgreSQL, OpenAI API
Data location	Your machine only	Cloud (or self-hosted with infra)	Cloud (or self-hosted with infra)
Cost	Free forever	Pay per API call	Pay per API call
Privacy	Complete — nothing leaves your device	Data sent to external APIs	Data sent to external APIs
MCP native	✅ First-class	❌ REST only	❌ REST only

Engram is built for developers who want AI memory without the overhead.

---

Features

• 🔒 Fully Local — SQLite database + local embeddings (all-MiniLM-L6-v2, 23 MB). No network calls, ever
• 🤖 MCP Native — First-class Model Context Protocol integration. Works with Claude Desktop, Claude Code, Cline, Cursor, Windsurf, and any MCP client
• 🔍 Hybrid Search — Combines vector similarity with full-text search (FTS5) for accurate recall
• 🧹 Smart Deduplication — Automatically detects and merges similar memories (>0.92 similarity threshold)
• 📊 Feedback Loop — Rate memory usefulness to improve future recall accuracy
• 🔐 Secret Detection — Automatically blocks API keys, passwords, and tokens from being stored
• ⏰ Temporal Queries — Filter memories by time: "last week", "3 days ago", or exact dates
• 📦 Namespace Isolation — Organize memories by project, client, or any scope you need
• 🌐 REST API — Full HTTP API with CORS support for custom integrations
• 🖥️ Web Dashboard — React-based UI for browsing, searching, and managing memories
• 💾 Export — Export memories to Markdown, JSON, or plain text for documentation

---

Quick Start

1. Install

npm install -g @hbarefoot/engram

2. Start the server

engram start

3. Connect to your AI agent

Add Engram to your MCP client config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["start", "--mcp-only"]
    }
  }
}

Claude Code:

claude mcp add engram -- engram start --mcp-only

Cline / Cursor / Windsurf: Add the same MCP config to your editor's settings. Engram's built-in Integration Wizard can auto-detect your setup:

engram connect

4. Use it

Once connected, your AI agent can store and recall memories naturally:

You: "Remember that our API uses JWT tokens with 24-hour expiry"

Claude: stores the memory via engram_remember

You: (next day) "What authentication approach are we using?"

Claude: recalls via engram_recall — "Your API uses JWT tokens with 24-hour expiry."

Memories persist across sessions, restarts, and even different AI clients sharing the same Engram instance.

---

MCP Tools

Engram exposes 6 tools to AI agents via the Model Context Protocol:

Tool	Description
engram_remember	Store a memory with category, entity, confidence, namespace, and tags
engram_recall	Retrieve relevant memories by semantic query with optional filters
engram_forget	Delete a specific memory by ID
engram_feedback	Rate a memory as helpful or unhelpful to improve future recall
engram_context	Generate a pre-formatted context block (markdown/xml/json) with token budget
engram_status	Health check with memory count, model status, and configuration info

Memory Categories

Memories are organized by type for better retrieval:

• fact — Objective truths about setup, architecture, or configuration
• preference — User likes, dislikes, and style choices
• pattern — Recurring workflows and habits
• decision — Choices made and the reasoning behind them
• outcome — Results of actions taken

---

CLI Reference

engram start                    # Start MCP + REST server
engram start --mcp-only         # MCP server only (for agent integration)
engram start --port 3838        # Custom port for REST API

engram remember "content"       # Store a memory from the command line
engram recall "query"           # Search memories
engram forget <id>              # Delete a memory
engram list                     # List all memories
engram status                   # Health check and stats

engram export                   # Export memories to JSON
engram import <file>            # Import memories from file
engram consolidate              # Run deduplication and cleanup

engram agents                   # List detected AI agents on your system
engram connect                  # Interactive setup wizard for MCP clients

---

REST API

The REST API runs on http://localhost:3838 by default.

Endpoint	Method	Description
/health	GET	Health check
/api/status	GET	System status with stats
/api/memories	POST	Create a memory
/api/memories	GET	List memories (with pagination, category/namespace filters)
/api/memories/search	POST	Semantic search
/api/memories/:id	GET	Get a single memory
/api/memories/:id	DELETE	Delete a memory
/api/consolidate	POST	Run deduplication and cleanup
/api/conflicts	GET	Get detected memory conflicts

---

Web Dashboard

Engram includes a built-in web dashboard at http://localhost:3838 when running the full server:

• Dashboard — Overview of memory stats and recent activity
• Memory Browser — Browse, filter, and manage all stored memories
• Search — Semantic search with similarity scores
• Statistics — Charts and breakdowns by category, namespace, and time
• Agents — Integration hub with a setup wizard for connecting MCP clients

---

How It Works

1. Store: When an AI agent calls engram_remember, the memory text is embedded locally using all-MiniLM-L6-v2 (a 23 MB model that runs on CPU). The embedding and metadata are stored in a local SQLite database at ~/.engram/memory.db.

2. Recall: When engram_recall is called, the query is embedded with the same model and matched against stored memories using cosine similarity. FTS5 keyword matching runs in parallel, and results are merged using a hybrid scoring algorithm.

3. Deduplicate: Before storing, Engram checks existing memories for similarity. Exact duplicates (>0.95) are rejected. Near-duplicates (0.92–0.95) are merged intelligently.

4. Learn: The engram_feedback tool lets agents mark memories as helpful or unhelpful. This adjusts confidence scores and influences future recall ranking.

5. Protect: Every memory passes through secret detection before storage. API keys, passwords, tokens, and other sensitive data are automatically blocked.

---

Configuration

Engram stores its data and config in ~/.engram/:

~/.engram/
├── memory.db          # SQLite database (memories + embeddings)
├── config.json        # Server configuration
└── models/            # Cached embedding model (~23 MB)

Default settings work out of the box. To customize:

// ~/.engram/config.json
{
  "port": 3838,
  "defaultNamespace": "default",
  "recallLimit": 5,
  "confidenceThreshold": 0.3,
  "secretDetection": true
}

---

Advanced Usage

Namespace Isolation

Organize memories by project or client:

# Store memories in different namespaces
engram remember "Uses Next.js 14 with app router" --namespace my-saas
engram remember "WordPress multisite with Redis cache" --namespace client-site

# Recall searches within a namespace
engram recall "what framework?" --namespace my-saas

AI agents can use namespaces automatically — just include the namespace parameter in engram_remember and engram_recall calls.

Temporal Queries

Filter memories by time:

engram recall "deployment changes" --after "last week"
engram recall "API decisions" --after "2025-01-01" --before "2025-06-01"

Export for Documentation

Export your project's memory as documentation:

engram export --format markdown --namespace my-project > PROJECT_CONTEXT.md
engram export --format json > memories-backup.json

---

Contributing

See CONTRIBUTING.md for development setup and guidelines.

git clone https://github.com/HBarefoot/engram.git
cd engram
npm install
npm run dev

---

License

MIT © 2026 HBarefoot