█████ █████ ████  █████ █████ █████ █
    ╔═══════════╗          █     █   █ █   █   █   █       █   █
    ║   ╓─╥─╖   ║          █     █   █ █   █   █   █       █   █
    ║  ╔═════╗  ║          █     █   █ █   █   █   █       █   █
    ║  ║● · ●║  ║          █████ █████ ████  █████ █████ █████ █████
    ║  ║  ▬  ║  ║
    ║  ╚══╤══╝  ║          ━━━━━━━━━━ MEMORY LEDGER ━━━━━━━━━━━━━
    ║  ███████  ║          Sessions · Facts · Confidence · MCP
    ║   ▀▀ ▀▀   ║          · Local-first — one ledger, one
    ║  Engram_  ║            confidence model, one context
    ╚═══════════╝            budget. MIT · No account · No tel.

Engram is a local-first memory and assertion ledger for AI coding agents. It persists session notes across every repo, ranks facts by confidence and corroboration, surfaces contradictions, and feeds the whole thing to Claude Code over MCP. No account. No telemetry. Local files only.

Status: Pre-1.0 (v4.0.3). Available on npm. MCP server is stable; assertion ledger is active development.

░▒▓█ TL;DR

git clone https://github.com/tinydarkforge/Engram.git
cd Engram && npm install && npm run setup
claude mcp add engram -s user -- node "$(pwd)/scripts/mcp-server.mjs"

Engram is now a tool in every Claude Code session. It remembers what you did, ranks what it knows, and injects a budget-capped slice of context on demand — stopping at the earliest retrieval layer that answers the query.

░▒▓█ What it does today

Engram captures engineering work and exposes it as structured memory:

• Session memory — Git-hook capture or manual remember. Sessions carry notes, topics, diffs, test deltas. Per-project, per-repo, across every codebase on your machine.
• Assertion ledger — SQLite-backed fact store. Every claim has confidence [0.0–1.0], status (tentative → established → fossilized), quorum count, lineage, and decay. Contradictions surface as unresolved tensions.
• Token-efficient retrieval — Four-layer stack (bloom filter → index → session detail → ledger). Stops at the earliest layer that answers the query. 80% of queries answered from a 4 KB index. Context is always token-budgeted by the caller.
• MCP-native — stdio and Streamable HTTP transport. Tools: neural_search, remember, ledger_ingest, ledger_query, ledger_select_context, cross_project_search, get_bundle, recent_sessions.
• Dashboard + HTTP API — Local web UI at :3000 for browsing sessions, inspecting ledger state, reviewing tensions.

Engram does not call any remote model by default. Semantic search runs a local ONNX embedding model (@huggingface/transformers) that loads lazily on the first semantic query. If you never invoke semantic search, no model is ever downloaded.

░▒▓█ How retrieval works

Queries traverse four layers, stopping as early as possible:

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

Facts are ranked by decay × status × quorum × tension × weight and packed into a caller-specified token budget.

░▒▓█ Assertion ledger

The ledger is where session notes become structured, queryable knowledge. Every assertion records:

• Plane — authority scope (user:alice, project:engram, session:xyz)
• Claim — terse fact text
• Confidence — [0.0–1.0], starts uncertain, grows with corroboration
• Quorum — independent sources confirming the fact
• Status — tentative → established → fossilized
• Decay model — flat, exponential, episodic, state_bound, contextual
• Lineage — which sessions contributed
• Tension — automatic negation-based contradiction detection

Tensions surface as alerts; unresolved ones downweight their claims in context selection.

░▒▓█ Positioning

Engram is not a hosted memory SaaS, a vector-DB-as-a-service, or a RAG framework. It is a local ledger and MCP server for engineering context.

| Alternative | When to pick it instead of Engram | |------------------|-----------------------------------------------------------------| | mem0 | You want hosted memory, team sync, managed upgrades. | | Letta / Zep | You want agent-framework primitives and hosted chat state. | | Plain RAG | You only need retrieval over static docs, no fact lifecycle. | | Raw SQLite | You want a schema you control and don't need MCP or ranking. |

Engram's niche: local-first, confidence-weighted, contradiction-aware, token-budgeted context for AI coding agents. Runs fully offline. If you want dashboards-as-a-service or team-wide sync, pick mem0 or Zep.

| Feature | Engram | mem0 | Letta / Zep | |--------------------------------------|:-----------:|:-----------:|:-----------:| | Local-first (no cloud required) | Yes | No | No | | Assertion ledger (confidence/quorum) | Yes | No | No | | Contradiction detection | Yes | No | No | | MCP-native (Claude Code) | Yes | No | No | | Git-hook session capture | Yes | Partial | Partial | | Token-efficient retrieval | Yes (budgeted)| No | No | | Runs fully offline | Yes | No | No |

░▒▓█ Prerequisites

• Node.js >=20
• macOS or Linux. Windows not supported (shell scripts + symlinks).
• First semantic query: downloads a ~100 MB local embedding model (@huggingface/transformers). Text search (npm run search) and keyword recall work without it.

░▒▓█ Install

npm install -g @tinydarkforge/engram
engram setup

Or from source:

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

Connect Claude Code

npm install (global):

claude mcp add engram -s user -- engram mcp

From source:

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 save
engram remember --interactive

# Git-hook capture (auto-save on commit)
./scripts/git-hook-capture.sh install   # from source clone

# Semantic search
engram semantic "authentication work"

# Keyword search
engram search "oauth"

# Status
engram status

# Launch dashboard
engram start   # http://127.0.0.1:3000/

# Ledger CLI
engram status   # includes ledger health
npm run ledger:stats   # from source clone

░▒▓█ Dashboard + API

node scripts/server.js

• Dashboard: http://127.0.0.1:3000/
• API: http://127.0.0.1:3000/api/stats
• Health: http://127.0.0.1:3000/health

The dashboard is read-only by default. Ledger mutations require the MCP or CLI path.

░▒▓█ Security

• No network calls unless you opt in. The embedding model downloads lazily on the first semantic query and is then cached locally — if you never invoke semantic search, nothing is fetched.
• No telemetry. Engram does not phone home. Ever.
• Local files only. All session data lives under the repo in summaries/ and the ledger DB in .cache/engram.db.
• Vuln disclosure: SECURITY.md.

░▒▓█ Repo layout

scripts/     runtime, CLI, servers, MCP tools, ledger
tests/       29 test files (node:test)
web/         dashboard UI (static)
schemas/     JSON schemas for sessions + ledger
migrations/  SQLite schema migrations
examples/    curated session records
summaries/   per-project session indexes + records

░▒▓█ Platform support

| Platform | Status | |----------|----------------------------------------------| | macOS | Supported | | Linux | Supported | | Windows | Not supported (shell scripts, POSIX symlinks)|