Engram

A local MCP server that gives AI coding agents persistent, semantic memory across sessions.

Install

curl -sL https://raw.githubusercontent.com/jsflax/Engram/main/scripts/install.sh | bash

This downloads the pre-built binaries and configures Claude Code. When Codex and Python 3.11+ are installed, it also registers Codex's Engram MCP and session learner.

To build from source instead:

git clone https://github.com/jsflax/Engram.git
cd Engram
./scripts/install.sh --from-source

Start a new Claude Code session — memory tools are immediately available.

Codex session learning

Codex's native Stop, PreCompact, and SessionEnd hooks queue an incremental session learner. Source installs, release downloads, and Engram app upgrades all install the same runtime. Open /hooks in the Codex CLI and review/trust the three Engram hooks before they can execute. An upgrade that changes a hook definition requires another review. Existing hooks, MCP settings, and notifications survive. The integration is tested with Codex CLI 0.153.4; older versions without native hooks and --ignore-user-config must be upgraded.

The learner uses your signed-in Codex account and selected model/reasoning effort, so automatic learning consumes Codex usage. It sends a bounded excerpt of visible user/assistant messages to that model, then calls your local Engram MCP to recall and store useful findings. It excludes hidden reasoning, tool output, and inherited fork history. Common credential patterns are redacted; this is not a general secret detector. New memories are private and include their source session ID. The current learner supports a local stdio memory MCP, not a remote HTTP MCP. Subagent compaction events use separate child cursors even when Codex supplies the parent session ID; the mapping requires explicit child metadata and a known boundary separating inherited messages.

One learner runs at a time, with a 10-minute limit, at most 12 memory calls and five writes per batch. An independent MCP gateway enforces the limits and checks write receipts. Successful transcript ranges are checkpointed so repeated hooks do not learn them again. Failures preserve the cursor and impose a five-minute backoff. A wakeup processes at most four batches (24,000 visible characters each) from one pending source; longer backlogs wait for the next source event or a manual retry. A short Stop excerpt waits for more content; compaction and session end also process short excerpts. The original Codex turn never waits for learning.

To retry installation after installing Python or Codex:

bash ~/.claude/bin/codex/install_codex_support.sh install

Inspect actual completion and pending sessions, or resume one pending source:

python3 ~/.claude/bin/codex/codex_learner.py status
python3 ~/.claude/bin/codex/codex_learner.py retry --session-id SESSION_ID

Use a Python 3.11+ interpreter for these commands. Private state and write receipts live in ~/.codex/engram-learner/ (CODEX_HOME is respected). events.jsonl records queueing separately from completion; runs/*/run.json records verified writes or the failure reason. Failed runs retain private diagnostics. Successful runs discard their provider transcript. Local budgets can be lowered in settings.json using wall_seconds, max_tool_calls, max_writes, and max_runs_per_worker.

To disable only Codex learning, untrust its Engram hooks in /hooks, or run bash ~/.claude/bin/codex/install_codex_support.sh uninstall. Uninstall removes only unchanged Engram-owned registrations and keeps memories, cursors, and backups.

Engram Visualizer

swift run -c release EngramVisualizer

Why not MEMORY.md?

Claude Code has built-in memory via MEMORY.md files. Here's why Engram is better:

	MEMORY.md	Engram
Retrieval	Dumps entire file into system prompt	Semantic vector search — only relevant memories surfaced
Capacity	Truncated at 200 lines	Unlimited — stores thousands, retrieves the best matches
Search	Position-based (top of file = seen first)	Hybrid FTS5 + vector similarity (most relevant = seen first)
Cross-project	Per-project files, no sharing	Project scoping + global scope — preferences follow you everywhere
Maintenance	Append-only text that gets stale	update, merge, forget, auto-expiring memories, conflict detection
Structure	Flat text, no relationships	Knowledge graph — connect memories with typed edges, traverse on recall
Continuity	No session awareness	Episodic memory, task checkpoints, clustering + consolidation
Privacy	Plain text files	Local SQLite + on-device embeddings (MiniLM-L6); optional Codex learning sends visible excerpts to the selected model

The one-liner: MEMORY.md is 200 lines of flat text that gets stale. Engram is a vector database that scales, searches semantically, and self-maintains.

Tools

Core

Tool	Description
remember	Store a memory with semantic embedding. Conflict detection blocks near-duplicates (force: true to override). Optional importance: 1-5
recall	Hybrid FTS5 + vector search with project boosting, reinforcement scoring (frequency + importance + recency), temporal filters (since/before), and optional graph traversal (depth: 1-3)
forget	Delete by ID, topic, or project. Cascades edge cleanup
update	Edit by ID or similarity — full replace, append, prepend, find+replace, or metadata-only (topic, source, expires_in_days, importance)
merge	Consolidate multiple memories into one. Cleans up source edges
stats	Database overview with per-project and per-topic breakdowns
list_topics	List all topics with counts
timeline	Chronological memory view grouped by day/week/month with project, topic, and temporal filters

Knowledge Graph

Tool	Description
connect	Create a directed edge between memories (relates_to, contradicts, supersedes, derived_from, part_of, summarized_by)
disconnect	Remove edges by edge ID or by (from, to) pair
graph	View a memory's neighborhood — shows connections up to a given depth

Task Continuity

Tool	Description
checkpoint	Save work-in-progress state (plan, progress, context) for cross-session resume
resume	Load a task checkpoint and mark it active
list_tasks	List tasks filtered by project and/or status (active, paused, completed)

Episodic Memory

Tool	Description
begin_episode	Start a named session episode. Auto-closes any active episode
end_episode	End an episode with optional summary
recall_episode	Replay an episode's memories in chronological order
list_episodes	List episodes filtered by project and/or status

Organization & Clustering

Tool	Description
organize	Batch re-topic memories, create a hub memory, and link members via part_of edges
detect_communities	Label propagation on the knowledge graph to discover natural memory groups
find_clusters	Discover groups of semantically similar memories by cosine distance
consolidate	Create a summary memory from a cluster, deprioritize originals with summarized_by edges

Engram Visualizer

An interactive force-directed graph visualization of your memory database, built with SwiftUI. Point it at a specific database with CLAUDE_MEMORY_DB=~/path/to/memory.sqlite swift run -c release EngramVisualizer.

Features:

• Force-directed graph layout with project-colored nodes and inter-project repulsion
• Floating PiP panel — drag to detach, resize from corners, snaps to screen edges
• FTS5-backed search with prefix matching — highlights matches, dims the rest
• Edge type filtering with color-coded relations (part_of, contradicts, supersedes, etc.)
• Time slider with play button to animate graph growth over time
• Project filtering toggles in the stats overlay
• Semantic cluster hulls drawn as translucent project-colored regions
• Activity log with real-time memory updates and click-to-navigate
• Minimap with click-to-navigate
• Detail panel with typewriter effect for selected memories
• Drag nodes with instant local repulsion, pan, zoom-to-cursor (scroll wheel + pinch)
• Keyboard shortcuts: Esc (deselect), Tab (cycle connections), Cmd+F (search), +/- (zoom), Cmd+Shift+E (export PNG)

Uninstall

curl -sL https://raw.githubusercontent.com/jsflax/Engram/main/scripts/uninstall.sh | bash

Removes the binary and MCP registration. Database is preserved at ~/.claude/memory.sqlite (delete manually if desired).

How it works

• Embedding model: paraphrase-MiniLM-L6-v2 runs locally via CoreML. 384-dimensional vectors.
• Storage: SQLite via Lattice ORM with sqlite-vec for vector search and FTS5 for full-text search.
• Transport: stdio MCP — server starts with each Claude Code session, loads embedding model once, stays alive for the session duration.
• Hybrid search: Recall combines FTS5 full-text search (any matching term qualifies) with vector cosine similarity. Falls back to FTS5-only if the embedding model is unavailable.
• Scoping: Memories have project and topic fields. Project is a soft ranking signal — same-project and global memories rank higher, but cross-project results still surface if semantically relevant.
• Knowledge graph: Connect memories with typed directed edges. Recall with depth > 0 follows edges via BFS to surface connected knowledge. Edges auto-cleanup on forget/merge.
• Reinforcement scoring: Recall ranking blends cosine similarity with three reinforcement signals — frequency (log-scaled access count, up to 15% boost), importance (explicit 1-5 rating, up to 20% boost), and recency (exponential decay from last access, up to 10% boost). Cosine similarity still dominates; reinforcement fine-tunes ordering among close matches.
• Conflict detection: remember checks for near-duplicates (cosine distance < 0.12 same-project, < 0.05 cross-scope). Blocks storage with a warning; use force: true to override.
• Expiration: Set expires_in_days for temporal context ("currently working on X"). Expired memories are filtered from recall automatically.
• Episodic memory: Opt-in session grouping via begin_episode/end_episode. Episodes are hub memories (topic: "episode") linked to member memories via part_of edges. Stale episodes auto-end after a 30-minute gap.
• Task continuity: checkpoint saves plan/progress/context state. resume restores it in a new session. Tasks persist across conversations.
• Clustering: find_clusters uses greedy cosine-distance clustering to find related memory groups. consolidate creates a summary, deprioritizes originals (importance -> 0), and links them with summarized_by edges. organize batch re-topics memories with automatic hub creation.
• Cross-project linking: remember auto-detects mentions of other project names in content and creates relates_to edges to those projects' hub memories.
• Hooks: Optional memory-hooks binary for Claude Code hooks integration — auto-injects recalled context before each message (advise), blocks session end to capture insights when significant work is detected (stop), and triggers maintenance when memory operations accumulate.

Configuration

Environment variable	Default	Description
CLAUDE_MEMORY_DB	~/.claude/memory.sqlite	Database path
CLAUDE_MEMORY_MODEL	Bundled MiniLM-L6	Custom embedding model path

Requirements

• macOS (CoreML for embeddings)
• Swift 6.2+
• Claude Code CLI