# Engram
> **Persistent Memory Cortex for AI coding agents. Gives agents session continuity, change tracking, decision logging, and multi-agent coordination across sessions.**
---
> โญ **If Engram saves you tokens and context, give it a star โ it helps other developers find it.**
---
## ๐ Table of Contents
- [Overview](#overview)
- [Why Engram?](#why-engram)
- [How Engram Works?](#how-engram-works)
- [Installation](#installation)
- [Features](#features)
- [Dashboard](#dashboard)
- [Architecture](#architecture)
- [Tools Reference](#tools-reference)
- [AI Agent Instructions](#ai-agent-instructions)
- [Multi-Agent Workflows](#multi-agent-workflows)
- [Contributing](#contributing)
- [Security](#security)
- [Author](#author)
- [License](#license)
---
## Overview
**Engram** is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI coding agents persistent memory across sessions. Instead of re-reading files, re-discovering architecture, and re-learning conventions every time a session starts, the agent calls `engram_session(action:"start")` and instantly receives everything it needs.
It operates seamlessly as a background brain for popular AI tools like **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **Trae IDE**, **Antigravity IDE**, **Android Studio**, and **GitHub Copilot** (VS Code & Visual Studio).
---
## Why Engram?
Every AI coding agent is **stateless by default**. Each new session starts from scratch:
- The agent re-reads file structures and re-discovers architecture.
- Architectural decisions made in previous sessions are forgotten.
- Conventions agreed upon are lost.
- Work-in-progress tasks have no continuity.
- **Time, tokens, and patience are wasted on repeated discovery.**
Engram solves this by providing a **persistent brain** using a native SQLite (WAL mode) database. An AI agent should only need to deeply review a file once. When you ask it to change something, it should already know where to go.
### How Engram Compares
| Tool | Approach | Local / No cloud | MCP native | Multi-agent | Works today |
|------|----------|:---:|:---:|:---:|:---:|
| **Engram** | Structured SQLite memory | โ
| โ
| โ
| โ
|
| mem0 | Cloud vector DB | โ | โ ๏ธ wrapper | โ ๏ธ | โ
|
| MemGPT / Letta | In-context manipulation | โ
| โ | โ | โ
|
| Plain `CLAUDE.md` | Static text file | โ
| โ
| โ | โ
|
Engram is the only solution that is **local-first, MCP-native, multi-agent-ready, and structured** (queryable, rankable, exportable) โ not just a text file appended to every prompt.
---
## How Engram Works?
Engram runs as a local MCP server alongside your AI tool. It maintains a **project-local SQLite database** at `.engram/memory.db` โ one per project, created automatically on first use. No cloud, no API keys, no data leaving your machine.
### The Session Lifecycle
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ AGENT SESSION LIFECYCLE โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Session โ engram_session(action:"start") โ
โ Start โ โ previous summary, open tasks, decisions, file notes, โ
โ โ conventions, triggered events โ all ranked by focus โ
โโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Active Work โ get_file_notes โ skip re-reading if notes are fresh โ
โ โ record_change โ every file edit captured with context โ
โ โ record_decision โ why you built it, persisted forever โ
โ โ add_convention โ project standards stored once, used โ โ
โ โ create_task โ work items survive session boundaries โ
โโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Context โ check_events fires at 50% / 70% / 85% fill โ
โ Pressure โ โ checkpoint to offload working memory mid-session โ
โ โ โ or end early and resume cleanly in the next session โ
โโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Session โ engram_session(action:"end", summary:"...") โ
โ End โ โ summary stored, open tasks preserved, memory locked โ
โ โ โ next session โ same agent or different โ starts fresh โ
โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### What the Agent Receives at Start
When an agent calls `engram_session(action:"start", focus:"topic")`, the response includes:
| Field | What it contains |
| -------------------------- | ------------------------------------------------------------------------- |
| `previous_session.summary` | What was done last session โ files, functions, blockers |
| `active_decisions` | Binding architectural decisions. Follow them or supersede with rationale. |
| `active_conventions` | Project standards (naming, patterns, style) โ enforced every session |
| `open_tasks` | Pending work items with priority and blocking chains |
| `abandoned_work` | Work declared via `begin_work` that was never closed โ resume or discard |
| `handoff_pending` | Structured handoff from the previous agent โ instructions, branch, tasks |
| `triggered_events` | Scheduled reminders or deferred tasks now due |
| `agent_rules` | Live-loaded behavioral rules from the README (7-day cache) |
| `tool_catalog` | Available actions, scoped to the agent's familiarity tier |
All context is **FTS5-ranked** around the `focus` topic โ the most relevant memory surfaces first. The `suggested_focus` field auto-derives the topic for the next session when none is provided.
### Token Efficiency by Mode
| Mode | Schema tokens | Works with |
| ----------------------------- | ------------- | ------------------ |
| Standard 4-dispatcher | ~1,600 | All MCP agents |
| `--mode=universal` (built-in) | ~80 | All MCP agents |
| `engram-thin-client` | ~0 (deferred) | Anthropic API only |
### Storage
All data lives in a local SQLite WAL database. There is no telemetry, no external sync, and no authentication surface. The database is a plain file โ portable via `backup`, exportable to JSON, restorable on any machine.
---
## Installation
Engram is published to the npm registry. **You do not need to download or
compile any code.** Your IDE launches it with `npx`.
> **Always install with `@latest`.** Every command below says
> `engram-mcp-server@latest`, and the `@latest` is not decoration โ see
> [Upgrading](#upgrading) for the measurement that made it mandatory. Without
> it, `npx` can silently run a version it cached months ago.
### Prerequisites
- **Node.js v20 or newer.** This is a hard floor, not a recommendation:
`better-sqlite3@12` declares `20.x || 22.x || 23.x || 24.x || 25.x` and
`open@11` declares `>=20`. On Node 18 you get `EBADENGINE` followed by a
native build failure in the dependency that *is* the database. Releases up
to and including v1.13.0 wrongly advertised v18+.
Engram stores data in **SQLite** via `better-sqlite3`, which ships a native
C++ addon. Prebuilt binaries cover most platforms. If none matches yours, npm
compiles from source, which needs:
- **Windows:** [Node.js](https://nodejs.org) v20+ and Visual C++ Build Tools +
Python โ install **"Desktop development with C++"** from the
[Visual Studio Installer](https://visualstudio.microsoft.com/downloads/).
- **Mac:** Xcode Command Line Tools (`xcode-select --install`)
- **Linux:** `build-essential` and `python3`
(`sudo apt install build-essential python3`)
### Option 1: The Magic Installer (Interactive) โ **use this one**
Detects your IDE and injects the configuration safely. Install in
**universal mode**, which is the recommended setup:
```bash
npx -y engram-mcp-server@latest --install --universal
```
Universal mode exposes Engram as a **single `engram` tool with an ~80-token
schema** instead of four dispatcher tools. Every action is still available โ
you call `engram({action:"record_decision", ...})` instead of
`engram_memory({action:"record_decision", ...})`, and a BM25 resolver forgives
near-miss action names. Nothing is given up: the universal catalogs and the
four-tool action enums were compared programmatically and match exactly, **39
of 39** memory actions and **37 of 37** admin actions reachable.
> **One naming difference worth knowing.** `action:"search"` resolves to
> *memory* search in universal mode, because the resolver checks the memory
> dispatcher before the find dispatcher. To search the **tool catalog** โ what
> `engram_find({action:"search"})` does in four-tool mode โ use its alias:
> `engram({action:"discover", query:"..."})`.
If you would rather have the four separate tools, see
[Classic four-tool mode](#classic-mode) at the end of this section.
**Non-interactive (CI/CD / scripting):**
```bash
npx -y engram-mcp-server@latest install --ide vscode --universal --yes
```
**Clean removal:**
```bash
npx -y engram-mcp-server@latest install --remove --ide claudecode
```
**Check what is installed against what npm has:**
```bash
npx -y engram-mcp-server@latest --check
```
`--check` searches **this project first** โ climbing up to four parent
directories, so it works from `src/` and not only from the repo root โ and then
the machine. For each install it prints the config file, the version stamped in
it, whether that version is behind npm, and **where that install's memory
database is**. When something is out of date it offers to update it rather than
making you retype a command per install.
```bash
npx -y engram-mcp-server@latest --check --scope local # just this project and its parents
npx -y engram-mcp-server@latest --check --scope global # just user-level IDE configs
npx -y engram-mcp-server@latest --check --walk-up 0 # do not climb at all
```
**Installing without being listed.** Every install is recorded in
`~/.engram/installs.json` so `--check` can find it again โ including installs
into a custom directory, which no config scan could rediscover. `--isolated`
skips that record:
```bash
npx -y engram-mcp-server@latest install --ide cursor --local --isolated
```
The install still happens; it simply will not appear in `--check`. The installer
prints the config path when you use it, because that path becomes the only
record โ write it down.
**Nothing is written before you have seen it.** An interactive project-local
install shows the IDE, the mode, the config file, the database location and
whether it will be findable, then offers *Install / change directory / toggle
isolation / abort*. Answer with the arrow keys or the number keys.