Engram

<p align="center"> <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-10b981?style=flat-square&labelColor=18181b"></a> <img alt="Node" src="https://img.shields.io/badge/node-%E2%89%A520-10b981?style=flat-square&labelColor=18181b"> <img alt="MCP" src="https://img.shields.io/badge/MCP-native-10b981?style=flat-square&labelColor=18181b"> <img alt="Platform" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-10b981?style=flat-square&labelColor=18181b"> <a href="https://github.com/tinydarkforge/Engram/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/TinyDarkForge/Engram/actions/workflows/ci.yml/badge.svg?branch=main"></a> <a href="https://www.npmjs.com/package/@tinydarkforge/engram"><img alt="npm" src="https://img.shields.io/npm/v/@tinydarkforge/engram?style=flat-square&labelColor=18181b&color=10b981"></a> </p>

<p align="center"> <img src="web/engram-dashboard.png" alt="Engram Dashboard" width="720"> </p>

Engram is an epistemic engine for AI coding agents — not just memory. It persists facts with confidence, corroboration, and contradiction tracking across repositories, autonomously learns from outcomes, exposes everything over MCP, and replaces itself in your context window on a token budget.

Epistemic engine = contradiction detection + confidence-ranked retrieval + autonomous fact lifecycle + token-budgeted injection. Engram doesn't just store what you said — it tracks what's true, what conflicts, and what's worth remembering.

---

Quick start

npm install -g @tinydarkforge/engram
engram setup
claude mcp add engram -s user -- engram mcp

Engram is now available as a tool in every Claude Code session. It remembers what you did across every repository, ranks what it knows, and injects a budget-capped slice of context on demand.

---

How it works

Engram captures engineering work and stores it in two layers:

Session memory — Git-hook or manual engram remember saves notes, topics, diffs, and test deltas to a per-project index. Every repo on your machine gets its own namespace.

Assertion ledger — A SQLite-backed fact store. Every claim records confidence (0.0–1.0), status (tentative → established → fossilized), quorum count, decay model, lineage, and tension markers.

Autonomous Intelligence — Engram runs a background learning loop during consolidation. It automatically detects contradictions (tensions), promotes corroborated facts to established status, and fossilizes outdated knowledge without user intervention.

Retrieval

Queries traverse four layers, stopping at the earliest one that answers:

Layer	Size	Latency	Role
Bloom filter	243 B	~0.1 ms	Instant "not known" — zero tokens consumed
Session index	~4 KB	~10 ms	Compact summaries — answers ~80% of queries
Session detail	per-file	~5 ms	Full content, lazy-loaded on demand
Ledger	~2 KB/fact	5–15 ms	Ranked facts with confidence, quorum, tension

Results are packed into a caller-specified token budget using decay × status × quorum × tension × weight.

Semantic search uses a local ONNX embedding model (@huggingface/transformers) that loads lazily on the first semantic query. Text search and keyword recall work without it.

---

Install

Global (recommended)

npm install -g @tinydarkforge/engram
engram setup

From source

git clone https://github.com/tinydarkforge/Engram.git
cd Engram
npm install
npm run setup

Connect Claude Code

# Global install
claude mcp add engram -s user -- engram mcp

# Source install  
claude mcp add engram -s user -- node "$(pwd)/scripts/mcp-server.mjs"

---

Usage

# Save a session
engram remember "Implemented OAuth callback handling" --topics auth,oauth

# Interactive session capture
engram remember --interactive

# Search across all projects
engram semantic "authentication work"
engram search "oauth"

# One-shot query against the assertion ledger
engram ask "what do we know about authentication"   # new in v5

# Temporal compaction — fossilize low-signal assertions
engram compact   # new in v5

# View status and ledger health
engram status

# Launch the web dashboard
engram start   # → http://127.0.0.1:3000

Dashboard API

The dashboard exposes live metrics endpoints:

Endpoint	Returns
GET /api/stats	Session counts, projects, topic count
GET /api/dashboard/tensions	Unresolved contradictions with claims
GET /api/dashboard/velocity	Facts/day rate + 30-day sparkline data
GET /api/dashboard/consolidation	Last consolidation run time and tasks
GET /api/assertions	Paginated assertion browser
GET /api/assertions/:id	Full detail with outcomes, lineage, feedback

Background consolidation

Engram runs periodic consolidation (every 5 min) to close the learning loop:

ledger_scan    →  Detect new contradictions (tensions)
ledger_verify  →  Re-verify stale state_bound facts
counterfactual →  Recompute importance weights
post_hoc       →  Score assertion outcomes from sessions
auto_resolve   →  Auto-resolve tensions older than 30 days
ledger_transform → Promote/fossilize/weight assertions

Run a full cycle manually:

npm run consolidate:full   # --all including manifest + embeddings
node scripts/consolidate.js --all

MCP tools (available in Claude Code, OpenCode, Cursor, Aider, and Windsurf)

Engram exposes tools via MCP for session search, ledger ingestion, context selection, semantic recall, cross-project search, and agent handoff. Run engram mcp to start the MCP server, or configure any agent:

engram setup --agent claude       # Claude Code
engram setup --agent opencode     # OpenCode CLI
engram setup --agent cursor       # Cursor IDE
engram setup --agent aider        # Aider
engram setup --agent windsurf     # Windsurf

---

Features

	Engram	Gentleman-Programming/engram (Go)	mem0	Letta / Zep
Local-first (no cloud)	Yes	Yes	No	No
Contradiction detection + auto-resolve	Yes	No	No	No
Confidence-ranked retrieval	Yes	No	No	No
Assertion ledger (confidence, quorum, status)	Yes	No	No	No
Autonomous consolidation (learning loop)	Yes	No	No	No
Post-hoc outcome scoring	Yes	No	No	No
Counterfactual importance weighting	Yes	No	No	No
Semantic recall (by meaning, not keyword)	Yes	No	No	Yes
Temporal compaction (fossilize low-signal)	Yes	No	No	No
Event-driven confidence adjustment	Yes	No	No	No
MCP-native (7+ agents)	Yes	No	No	No
Git-hook session capture	Yes	Yes	Partial	Partial
Token-budgeted retrieval	Yes	Yes	No	No
Semantic search (local ONNX)	Yes	No	Yes	Yes
Cross-session diff	Yes	No	No	No
Agent handoff	Yes	No	Limited	Limited
MCP Resources with subscriptions	Yes	No	No	No
Live dashboard (tension radar, velocity, etc.)	Yes	No	No	No

---

Prerequisites

• Node.js >=20
• macOS or Linux (Windows not supported — shell scripts and symlinks)
• Semantic search downloads a ~100 MB ONNX embedding model on first query. Keyword search works without it.

---

Security

• No network calls unless you opt in. The embedding model is downloaded once and cached locally. If you never invoke semantic search, nothing is fetched.
• No telemetry. Engram never phones home.
• Local files only. Session data lives under ~/.engram/summaries/ and the ledger DB in ~/.engram/.cache/engram.db.
• Reporting vulnerabilities: see SECURITY.md.

---

Architecture

scripts/     Runtime, CLI, MCP servers, ledger, consolidation
web/         Dashboard UI (Express + static files)
tests/       29 test files (node:test)
schemas/     JSON schemas for sessions and ledger
migrations/  SQLite schema migrations
examples/    Curated session records

Engram runs two servers:

• HTTP API + Dashboard (port 3000) — REST endpoints and web UI
• MCP server (port 3001) — Streamable HTTP and stdio transports for Claude Code

Both can run simultaneously. The MCP server accepts optional API key authentication.

---

License

MIT — see LICENSE.

---

<p align="center"><a href="https://github.com/tinydarkforge/Engram">GitHub</a> · <a href="mailto:hello@tinydarkforge.com">Contact</a></p>