Engram MCP — Cognitive Memory for AI

An engram is a unit of cognitive information imprinted in neural tissue — the physical trace of a memory.

Engram gives Claude Code persistent, cross-session memory that learns from experience. It runs locally as an MCP server + hook processor, automatically encoding errors, decisions, and discoveries — then surfacing them when relevant.

What It Does

Remembers across sessions — knowledge encoded in session 5 surfaces automatically in session 20
Learns from mistakes — errors resolved in past sessions auto-surface their fix when the same error appears
Warns about antipatterns — known bad patterns trigger warnings before you write code
Survives compaction — after context window compression, Engram restores your full project understanding
Reduces context bloat — deliberate offloading protocol keeps the context window lean
Self-maintaining — automatic consolidation prunes noise, promotes valuable memories, optimizes storage

Quick Install

# Install
npm install -g @vedtechsolutions/engram-mcp

# Configure Claude Code
npx @vedtechsolutions/engram-mcp setup

That's it. Start a new Claude Code session and Engram activates automatically.

Manual Setup

If you prefer manual configuration, add to ~/.claude/settings.json:

MCP Server

{
  "mcpServers": {
    "engram": {
      "command": "node",
      "args": ["/path/to/node_modules/engram-mcp/dist/index.js"],
      "env": {
        "ENGRAM_DB_PATH": "~/.engram/engram.db",
        "ENGRAM_LOG_LEVEL": "info",
        "ENGRAM_AUTO_CONSOLIDATE": "true"
      }
    }
  }
}

Hooks

Add these hooks to enable automatic memory encoding:

{
  "hooks": {
    "UserPromptSubmit": [{
      "type": "command",
      "command": "node /path/to/node_modules/engram-mcp/dist/hook.js user-prompt-submit",
      "input": "stdin"
    }],
    "PreToolUse": [{
      "type": "command",
      "command": "node /path/to/node_modules/engram-mcp/dist/hook.js pre-tool-use"
    }],
    "PostToolUse": [{
      "type": "command",
      "command": "node /path/to/node_modules/engram-mcp/dist/hook.js post-tool-use"
    }],
    "SessionStart": [{
      "type": "command",
      "command": "node /path/to/node_modules/engram-mcp/dist/hook.js session-start",
      "input": "stdin"
    }],
    "SessionEnd": [{
      "type": "command",
      "command": "node /path/to/node_modules/engram-mcp/dist/hook.js session-end",
      "input": "stdin"
    }]
  }
}

See the setup script output for the complete hook list.

How It Works

Automatic Encoding

Engram hooks into Claude Code events and automatically captures:

Event	What's Captured
Bash errors	Error fingerprint + context → graduates to antipattern after recurring
Bash success after errors	Error resolution → links to original error via `caused_by`
Approach pivots	Why approach X failed, what replaced it → `contradicts` connection
Subagent completions	Discoveries, conclusions, lessons extracted from agent output
Write operations	File tracking, architecture graph updates
Session end	Session summary, Hebbian learning (co-recalled memories strengthen)

Intelligent Recall

On every prompt, Engram injects relevant memories:

[ENGRAM CONTEXT] — relevant knowledge and past experiences
[ENGRAM CAUTION] — warnings from past mistakes (cross-session)
[ENGRAM SURFACE] — top domain memories for ambient awareness
[ENGRAM REMINDER] — trigger-based prospective memories

Recall uses dual-path search:

FTS5 keyword matching — exact and stemmed keywords
TF-IDF cosine similarity — meaning-based matching (512-dim vectors, zero external APIs)

Cross-Session Error Resolution

Session 1: ParseError in views.xml
  → Encoded as error memory

Session 3: Fixed by replacing <tree> with <list>
  → Resolution linked via caused_by connection

Session 8: Same ParseError in different file
  → [ENGRAM CAUTION] Similar past error resolved: Use <list> not <tree>

Context Management

Engram actively manages context window pressure:

Context %	Behavior
> 55%	Full recall and injection
35-55%	Reduced injection, essentials prioritized
< 50%	Offload message: "your state is encoded, safe to focus"
< 40%	Summary mode: truncated content + recall pointers
< 20%	Essential antipatterns only

Tools

These tools are available in Claude Code after setup:

Tool	Usage
`engram_recall`	Search memory: `engram_recall("how to fix ParseError")`
`engram_encode`	Store knowledge: `engram_encode("In Odoo 18, use list not tree", type: "semantic")`
`engram_learn`	Record experience: `engram_learn(action, outcome, lesson)`
`engram_strengthen`	Reinforce useful memory
`engram_weaken`	Correct wrong memory
`engram_immune_check`	Check code against known antipatterns
`engram_stats`	Memory health and statistics
`engram_remind`	Create trigger-based reminder ("when X happens, do Y")
`engram_vaccinate`	Pre-register an antipattern
`engram_cleanup`	Remove noise from database (dry-run by default)
`engram_consolidate`	Trigger memory optimization cycle
`engram_self`	View/update persistent self-model
`engram_set_goal`	Set learning goals
`engram_list_goals`	Track learning progress
`engram_list_reminders`	List active reminders
`engram_experience`	Get version-specific knowledge

Architecture

Layer 6: Primary Memory Protocol    (Offloading, bridge file, cross-session learning)
Layer 5: Experience Versioning      (Framework knowledge inheritance)
Layer 4: Consolidation Engine       (9-phase: replay, prune, promote, transfer, dream)
Layer 3: Cortical Storage           (Semantic, Episodic, Procedural, Immune + TF-IDF)
Layer 2: Hippocampal Bridge         (Significance detection + encoding)
Layer 1: Sensory Buffer             (Context window / working memory)

31 cognitive engines. 14 hook handlers. 16 MCP tools. All running locally.

Data & Privacy

100% local — all data stays on your machine in ~/.engram/engram.db
No external APIs — embeddings computed locally via TF-IDF (no OpenAI, no cloud)
Your memories are yours — each installation starts with a fresh database
No telemetry — zero network calls, zero tracking

Requirements

Node.js 20+
Claude Code CLI

License

Business Source License 1.1 — free for personal and non-commercial use. Converts to Apache 2.0 on 2029-03-05. See LICENSE for details.

For commercial licensing: Contact us

Built by VedTech Solutions

Engram MCP