Engram

Runtime continuity and interruption recovery for AI coding agents

Engram gives Claude Code, Cursor, and OpenHands resumable execution — recover agent working state after context collapse, interruption, or session termination. Agents continue from where they stopped, not from zero.

中文文档 · PyPI · Glama

The Problem

Every AI agent session is an island:

Why Engram

Most memory systems focus on conversation recall.

Engram focuses on runtime continuity:

• What the agent was doing — task state, working set, modified files
• Where execution stopped — checkpoint with goal, progress, blockers
• How to resume safely — negative memory (must_not_redo) + invariants (must_preserve)

Quick Start

pip install mcp-engram
engram-setup          # downloads embedding model + initializes DB (~500MB, one-time)

Add to your Claude Code / Cursor config:

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "env": { "HF_ENDPOINT": "https://huggingface.co" }
    }
  }
}

That's it. Engram runs fully locally — no cloud, no API keys, no telemetry.

Interruption Recovery

When a session ends unexpectedly — context overflow, process kill, IDE crash — Engram automatically captures a structured working state on shutdown:

SIGTERM / context collapse
        ↓
Engram auto-checkpoint
  goal · completed · in_progress · blocked
  modified_files (git diff) · last_tool_called · last_failure
        ↓
Agent restarts → recall_memory()
        ↓
interrupt_recovery injected into response
  → "Call restore_checkpoint(task_id=X) to resume"

No manual intervention. The next agent session picks up the hint automatically on first recall_memory call.

Generate a CLAUDE.md snippet from current state:

engram-prompt

Output (paste into your project's CLAUDE.md):

## Engram Runtime State

**Active task:** 10 — Fix the auth bug in login.py
**Checkpoint:** v3 (confidence: 0.71)

**Already completed (do not redo):**

- Reproduced the bug in test_auth.py

**In progress:**

- Tracing the JWT validation path

**Files modified in last session:**

- `src/auth/validator.py`
- `tests/test_auth.py`

## Engram Session Rules

- Session start: recall_memory(query) — interrupt state auto-pinned
- Resume task: restore_checkpoint(task_id=10)
- Context filling up: report_interruption(reason="overflow") then session_handoff(...)

How It Works

Engram is a local MCP server providing 18 tools across three areas:

Memory

Hybrid semantic search (BM25 + vector + graph) with Ebbinghaus decay so important memories stay longer.

Task Tracking

Tasks are first-class entities that survive session boundaries.

Continuity

Checkpoint-based recovery so a new agent can pick up exactly where the previous one left off.

Checkpoint Recovery Flow

Agent A (Claude Code)                  Agent B (Cursor)
  │                                        │
  ├─ create_task(name, goal)               │
  ├─ track_progress / track_failure        │
  ├─ ⚡ Interrupted (SIGTERM / overflow)   │
  ├─ [auto] interrupt checkpoint saved     │
  │        │                               │
  │   ┌────▼────────────────┐              │
  │   │  Engram Checkpoint  │              │
  │   │  goal               │              │
  │   │  completed          │              │
  │   │  must_not_redo  ────┼──────────▶   │
  │   │  must_preserve      │             ├─ recall_memory() → interrupt_recovery pinned
  │   │  modified_files     │             ├─ restore_checkpoint(task_id)
  │   │  working_set        │             ├─ continue, not from zero
  │   └─────────────────────┘             └─ session_handoff → next agent...

Continuation package fields: goal · completed · in_progress · blocked · preferred_next · must_not_redo (negative memory) · must_preserve (invariants) · working_set · continuation_confidence

Recommended CLAUDE.md Instructions

Run engram-prompt to auto-generate this from your current state, or paste manually:

## Engram Session Rules

- Task start: create_task(name, goal) → save the task_id
- Session begin: recall_memory(query) — latest handoff + interrupt state auto-pinned
- Task takeover: restore_checkpoint(task_id, memory_restore_mode="SELECTIVE")
- Progress update: track_progress(feature, status, task_id=<id>)
- On error: track_failure(error, component, root_cause, task_id=<id>)
- Context filling up: report_interruption(reason="overflow") then session_handoff(...)
- Session end: session_handoff(summary, completed, in_progress, blocked, next_steps, task_id=<id>)

Architecture

Tier 1 — Event Journal (immutable, append-only)
  source of truth · snapshot compaction · incremental replay
  → ~/.engram/events/*.jsonl  (fsync, gzip-rotated)
  → periodic snapshots for fast startup

Tier 2 — Runtime State Store (operationally durable)
  tasks · checkpoints · executions · sessions
  → SQLite WAL  ~/.engram/*.state.sqlite
  → concurrent reads, fast restore, recovery-critical
  → controlled by ENGRAM_SQLITE_TIER2=1 (fallback: DuckDB)

Tier 3 — Runtime Intelligence Cache (rebuildable)
  memories · embeddings · FTS · vector index
  future: drift vectors · recovery metrics · tool stats · continuity history
  → DuckDB (can be dropped and rebuilt without data loss)
  → rebuild with: engram-setup rebuild-cache

Two Laws:

1. The event log is the only durability primitive.
2. If it cannot be replayed, it is not critical state.

DB corruption enters readonly degraded mode — never silently resets. Recover with engram-setup recover.

Benchmark

Evaluated on LoCoMo (Snap Research long-term conversation memory benchmark):

Zero cloud dependency. Four optimization rounds: F1 +50.3%, Hit@5 +26.2pp.

Engram also tracks runtime continuity metrics via evaluate_continuity: Goal Retention · Action Consistency · Failure Recall · Working Set Stability · Replanning Rate · Redundant Exploration.

What Engram Is Not

• ❌ Guaranteed identical LLM behavior after recovery (LLM non-determinism is a physical constraint)
• ❌ Custom agent loop or prompt orchestration (handled by the MCP client)
• ❌ Multi-agent coordination or shared team memory (single-user, local-first)

Requirements

• macOS / Linux / WSL2
• Python 3.11+
• ~500MB disk for embedding model cache (one-time download)

Contributing

git clone https://github.com/hugfeature/engram.git
cd engram
pip install -e ".[dev]"
pytest tests/ -v

Issues and PRs welcome.

License

MIT · Maintained by @hugfeature

Engram restores an agent's working state, not just its memories.