█▀▀▀▀▜▜▜▜▜▀▀█       █████ █   █ █████ ████   ███  █   █
    █           █       █     ██  █ █     █   █ █   █ ██ ██
    █    ◓  ◓   █       ████  █ █ █ █  ██ ████  █████ █ █ █
    █       ◞   █       █     █  ██ █   █ █  █  █   █ █   █
    ▜██▄▄▄▄▄▄▄██▛       █████ █   █ █████ █   █ █   █ █   █   
        ⬛ ⬛ 
                        ━━━━━━━━━━ MEMORY LEDGER ━━━━━━━━━━━━━
                        Sessions · Facts · Confidence · MCP
                            Local-first — one ledger, one
                            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)

---

Engram — because every agent deserves a ledger, not a goldfish bowl.