Website · Quickstart · How It Works · Connect · Full Reference · Dashboard
Engram is fully-local, long-term episode memory for AI agents — and it provably works. On the real 8.9k-episode dogfood brain, deep recall reaches the gold memory in 42/42 gate queries and the organic continuity gate passes live at ~440ms (evidence). Conversations are stored as episodes with deterministic cues, recalled through hybrid semantic search, and cleaned up by an offline cold-brain process. A capture→recall loop with echo-guarded usage learning ships conservatively behind flip gates. A temporal knowledge graph is available as a research/depth tier — validation-gated, not the headline (measured net-neutral for answer accuracy so far; its proven win is surfacing connected episodes).
|
Session-start injection, auto-observe hooks, offline queue replay. Routine turns stay in the harness; no agent tokens spent on capture. |
|
Triage, projection, 15-phase consolidation, dream associations. Runs as a separate cold-brain process on a schedule — not while you work. |
| Stage | What happens |
|---|---|
| Capture | observe, harness auto:*, or remember: fast store, optional cue trace |
| Cue | Deterministic latent memory; recallable before projection (agent proposals or the narrow rung) |
| Project | Entity resolution, embedding, graph write (background or immediate) |
| Recall | Compact memory packets from hybrid search instead of raw chat history |
| Consolidate | Merge, infer, prune, dream (offline) |
The harness handles capture and session injection. The agent spends tokens on recall and explicit remember calls. Consolidation runs out-of-band in a separate cold-brain process, not during your session.
| Tier | Trigger | Action | Budget |
|---|---|---|---|
| Hot | Session start, project open | AXI home, bootstrap, session prime | < 3s |
| Warm | Read tools, proper nouns | auto_recall lite, packet cache | < 350ms |
| Cold | Identity query, deep prior work | recall, get_context |
< 2s |
| Background | Scheduled (~2h), off-battery | Cold-brain consolidation, separate process | async |
Runtime split: a hot shell (engram serve, role shell) serves the golden loop with no in-process consolidation. A separate cold brain (engram brain run, a LaunchAgent every ~2h) does the heavy consolidation — it briefly pauses the shell and skips on battery or when there is no actionable work. Consolidation does not run while you work.
Identity-core entities are promoted to the semantic tier, which decays more slowly in scoring. Semantic memories and identity-core entities are pruned on longer horizons than fresh episodic entries.
curl -sSL https://raw.githubusercontent.com/Moshik21/engram/main/scripts/install.sh | bashInstalls native Helix (recommended), runs engramctl quickstart, and verifies the runtime.
engramctl start
engramctl status
engramctl doctor# MCP + priming (Cursor, Windsurf, Grok Build)
engramctl connect cursor --project "$PWD"
# Claude Code / Codex: read-only session injection
engramctl connect claude-code --project "$PWD" --axi
# Passive transcript capture (Claude AutoCapture hooks)
engramctl connect claude-code --project "$PWD" --capture-transcript
# Bootstrap project docs into memory (idempotent)
engramctl bootstrap "$PWD"Developer / source install
git clone https://github.com/Moshik21/engram.git ~/engram
cd ~/engram/server && uv sync
uv run engram setup --mode helix
make mcp-native # MCP with native HelixDB (no Docker)Modes: Helix native (best quality, no Docker) · Lite (SQLite, zero infra) · Helix HTTP (Docker) · Full (FalkorDB + Redis, legacy)
See docs/install/ and docs/REFERENCE.md for full install paths.
Replay a bundled lite demo brain with no API keys:
cd server && uv run engram showcase run
Three scripted beats: Liam continuity ("He had a great game today"), a correction (soccer to baseball), and a cross-session get_context briefing. Runs copy the bundled demo.db to ~/.engram/showcase/demo-run.db so the packaged brain stays pristine.
# Export static beats for the website theater
cd server && uv run engram showcase export --out ../website/public/showcase-export.json
# Reseed the bundled demo.db from source
cd server && uv run engram showcase seed
cd server && uv run python scripts/simulate.py --showcase-seed engram/data/demo.dbRegenerate the recording anytime:
cd server && uv run python ../scripts/record_showcase.pyOutputs docs/assets/showcase/showcase-demo.mp4 and .gif (also copied to website/public/ for the site).
Step through the same beats in the website scenario theater. It reads website/public/showcase-export.json.
| Client | MCP | Priming rules | AXI inject | Transcript capture |
|---|---|---|---|---|
| Claude Code | yes | - | default | --capture-transcript |
| Codex | - | - | default | future |
| Cursor | yes | yes | - | - |
| Windsurf | yes | yes | - | - |
| Grok Build | yes | yes | - | - |
| OpenClaw | yes | skill | - | - |
Agent protocol (harness-first):
claim_authority, then followrequired_tools_before_answerget_contextonce per session (or on project switch / adoption debt)recallwhen people, projects, or prior work appear in the questionrememberfor preferences, corrections, identity, durable decisions- Skip per-turn
observewhen harness capture is active
Validate adoption:
engram adoption --authority claim.json --calls trace.jsonl --expect-harness-captureDesign doc: docs/harness-memory-adoption-plan.md
| Capability | Summary |
|---|---|
| Deep episode recall | Hybrid vector + BM25 search with a circuit breaker; 42/42 gate reach on the real brain |
| Usage-based recency/frequency | Bounded tiebreaker u = f·r' over behavioral usage events, echo-guarded; ships gated (default off until organic usage yield exists) |
| ACT-R hygiene | Recency/frequency activation retained for forgetting, prune floors, and tier-aware decay — not as a ranking signal (refuted by measurement; see below) |
| Temporal graph (depth tier) | People, orgs, concepts, relationships with valid-from / valid-to; research tier, validation-gated |
| 15-phase consolidation | Triage, merge, infer, dream, prune (offline cycle) |
| Memory packets | Compact recall output with provenance for the current turn |
| Prospective memory | intend: graph-embedded intentions triggered by related topics |
| Atlas | Multi-scale graph exploration from region clusters to neighborhoods |
| 3D dashboard | Graph visualization, consolidation monitor, evaluation gates |
| Topological immunity | Prunes low-connectivity noise and weak edges |
Evidence ledger (what is measured, not marketed): deep recall 42/42 and organic continuity PASS at ~440ms on the real 8.9k-episode brain (M2.6 rerun); usage-ranking flip armed but held until organic used-tier yield is nonzero (M2.6 gate); activation-from-access-history as a ranker was measured and refuted (reach collapse 23→2/36 when populated), replaced by the bounded usage tiebreaker (RF goal, design); graph channel's proven contribution is episode surfacing (oracle-surface 2→22/36), not answer-accuracy lift.
The public MCP surface is frozen to a 9-tool golden loop (ENGRAM_MCP_SURFACE=public, the default). Stdio or streamable HTTP.
| Tool | Purpose |
|---|---|
observe / remember |
Capture (fast queue vs immediate extraction) |
recall / get_context |
Hybrid retrieval and durable-first briefing |
intend |
Prospective memory (topic-triggered intentions) |
forget |
Retract or correct a memory |
claim_authority |
Memory ownership and tool protocol for the turn |
bootstrap_project |
Ingest project docs on first run |
get_runtime_state |
Report brain readiness and adoption debt |
Operator and evaluation tools (consolidation triggers, artifact search, timeline, question routing, Loop Steward) live on the operator and full surfaces via ENGRAM_MCP_SURFACE — they are not part of the public agent loop. See docs/GOLDEN_LOOP.md.
Full tool list: docs/REFERENCE.md#mcp-integration
| Mode | Backend | Docker | Best for |
|---|---|---|---|
| Helix native | PyO3 in-process | None | Recommended (~97ms search, nDCG@10 0.448) |
| Lite | SQLite + FTS5 | None | Zero setup, demos |
| Helix HTTP | HelixDB container | 1 | Production multi-service |
| Full | FalkorDB + Redis | 2 | Legacy throughput |
HelixDB combines graph, HNSW vector search, and field-level BM25 in one engine (171 compiled HelixQL queries).
Details: docs/install/helix.md · Benchmarks
Everything runs and stays local by default.
- No API key is required to operate. Embeddings are local FastEmbed (nomic) (local FastEmbed is the only embedding provider and no key is read;
noopdisables vectors); extraction is the resident agent proposing entities and relationships throughremember/observe, with a deterministic narrow adapter as the internal rung (regex-level entities and relationships, markedextractedBy: narrow, that the agent can re-propose withremember(episode_id=...)). Engram never calls an external model. - The offline capture queue at
~/.engram/capture-queue.jsonlholds verbatim prompts until they are replayed into the graph on the next session start. - The graph store is plaintext on disk. An encryption config exists (
ENGRAM_ENCRYPTION__ENABLED) but is off by default. - The REST API binds
127.0.0.1and is unauthenticated by default. Only pass--host 0.0.0.0if you understand the exposure. - Use
engram backup createfor snapshots (andengram backup verify/engram backup restoreto check and roll back).
3D graph view plus Atlas, Timeline, Feed, Activation, Consolidation, Evaluate, and Knowledge chat (the chat route answers 501: Engram runs no external model; use the resident agent through MCP).
cd dashboard && pnpm install && pnpm dev # http://localhost:5173With the full stack, the dashboard updates over WebSocket when episodes are stored.
| Doc | Contents |
|---|---|
| REFERENCE.md | Installation, architecture, MCP, API, benchmarks, config, dev, troubleshooting |
| harness-memory-adoption-plan.md | Harness-first adoption design |
| axi-interface-plan.md | AXI session-start injection |
| install/ | Lite, Helix, Docker, OpenClaw guides |
| vision/ | Product narrative and science |
server/engram/
activation/ ACT-R engine, BFS, PPR
consolidation/ 15-phase engine + scheduler
ingestion/ CQRS: store_episode / project_episode
mcp/ 9-tool golden loop + operator surface
retrieval/ Hybrid search, packets, auto_recall
storage/ Helix native, SQLite, FalkorDB
dashboard/src/ React 19 + Three.js brain + Zustand
cd server && uv run pytest -m "not requires_helix" -v # Backend tests
cd server && uv run ruff check . # Lint
cd server && uv run engram mcp # MCP stdio
make up-native # Full stack, native HelixFull commands: docs/REFERENCE.md#development
Engram is Apache 2.0. See LICENSE.
HelixDB note: HTTP/gRPC transport (default Docker) has no license impact on Engram. Native PyO3 links AGPL-3.0 in-process; review terms for proprietary network services. Lite and Full backends have no AGPL concerns.