Engram

engram

current release: 0.5.2

a cognitive memory system that actually remembers things. built because flat markdown files don't scale and every "memory" tool i tried was either too simple (just embeddings) or too complex (needs redis + neo4j + a PhD).

engram sits in the middle. it starts as one sqlite file for local use, can graduate to postgres when you want a real concurrent service, keeps hybrid retrieval that fuses five signals, memory layers that model how brains actually work, and a neural visualization that shows the whole thing firing in real time. 98.1% R@5 on LongMemEval (ICLR 2025) — highest published score, beating MemPalace (96.6%), Emergence AI (86%), and every other memory system benchmarked.

what it does

hybrid retrieval — most memory tools just do cosine similarity and call it a day. engram runs four retrieval channels in parallel (BM25 keywords, dense embeddings via HNSW approximate nearest neighbors, entity graph BFS with 1-hop traversal, Hopfield associative pattern completion), fuses them with intent-weighted reciprocal rank fusion (k=60, weights vary by query type — why/when/who/how/what), then applies temporal + importance boosting, cross-encoder reranking, deep MLP reranking, gaussian noise for beneficial variation, and a minimum score threshold gate. the full pipeline: dense (HNSW) + BM25 + graph + Hopfield → intent-weighted RRF → boost → cross-encoder → MLP reranker → noise + threshold.

memory layers — five layers modeled after atkinson-shiffrin: working (ephemeral, auto-promotes to episodic after 30 min), episodic (events, experiences), semantic (permanent knowledge), procedural (decisions, error patterns, how-to), and codebase (compressed code knowledge — file trees, function signatures, dependency graphs). memories promote upward when they prove useful and decay if nobody accesses them. 30-day half-life on episodic, infinite on semantic.

entity graph — extracts people, tools, projects, dates from every memory. builds a relationship graph with co-occurrence strength. multi-hop traversal via recursive SQL CTEs, no neo4j needed. backlinks let you trace which memories are connected to which.

dream cycle — consolidation pass that clusters similar memories (cosine > 0.8), summarizes the clusters, generates entity "peer cards" (biographical summaries), and archives the low-value old stuff. like sleep for your memory system.

semantic dedup — finds near-duplicate memories by embedding distance (default threshold 0.92), auto-merges them keeping the higher-importance version. transfers entity links, merges tags and access counts. run manually or as part of consolidation.

codebase scanning — point scan_codebase at a project directory and it extracts file trees, function/class signatures, import graphs, and config files into compressed codebase-layer memories. stores ~10x fewer tokens than raw code while keeping what you actually need to work with the project.

conversation ingest — auto-extracts memories from Claude Code JSONL session logs. parses exchanges into Q+A pairs, classifies them (decisions, corrections, errors, task completions), and stores them in the right layer with appropriate importance scores.

session handoffs — maintains a structured resumable handoff snapshot for the active MCP session. as diary entries and memory writes happen, engram refreshes the current handoff automatically. new agent sessions can call resume_context to pick up the latest decisions, open loops, recent work, and search history without reconstructing everything from raw logs.

neural visualization — force-directed graph of entities organized in concentric rings by memory layer. neurons fire with traveling impulse particles when memories get accessed. polls the database so it works across processes. fire a query from the CLI or MCP server and watch the web UI light up.

drift detection — memories reference file paths, function names, commands, and dependencies. those references go stale when the codebase changes. drift_check extracts verifiable claims from memory content and validates them against the actual filesystem — dead paths, missing functions, broken npm scripts. returns a drift score (0-100) with per-issue breakdown. zero AI cost, pure filesystem checks. drift_fix auto-invalidates dead references and flags stale memories. inspired by mex's claim verification approach.

pattern extraction — after a session, extract_patterns analyzes recent activity (diary entries, new memories, events) and distills reusable procedural knowledge. classifies work into categories (workflow, gotcha, decision, integration, debug), checks novelty against existing procedural memories via embedding distance, and only stores patterns that are genuinely new. the GROW step from mex, automated.

negative knowledge — remember_negative stores explicit "what does NOT exist" claims: no caching layer, no Redux, the /admin endpoint was removed. these prevent future hallucinated recommendations. stored in the semantic layer with a NEGATIVE KNOWLEDGE prefix so they surface when you search for the thing that doesn't exist.

enriched embeddings — at write time, an LLM generates keywords, categorical tags, and a contextual summary for each memory. the embedding is computed over the concatenation of content + keywords + tags + summary, giving the vector richer semantic signal than raw content alone. inspired by A-Mem's zettelkasten approach, where enriched embeddings nearly doubled multi-hop retrieval F1.

memory evolution — memories aren't write-once. when a new memory arrives and near-neighbors are detected (via the surprise gate), the system asks an LLM whether existing memories should be updated with the new context. old memories get smarter over time instead of going stale. from A-Mem — removing evolution dropped multi-hop F1 from 45.85% to 31.24% in ablation.

intent-aware retrieval — queries are classified by intent (why/when/who/how/what) and retrieval signals are dynamically weighted. "why" queries boost graph traversal for causal reasoning. "when" queries boost BM25 for date matching. "who" queries boost entity graph lookup. from MAGMA's adaptive policy (+9% over static weighting).

trust-weighted decay — different sources decay at different rates. human-authored memories get full 30-day half-life. auto-extracted observations decay 3x faster. formula: λ_eff = λ · (1 + κ·(1 - trust)), κ=2.0. from SuperLocalMemory V3.3. also: confirmation count — memories corroborated by multiple independent sources get importance boost.

write-path CRUD — instead of always appending then deduplicating later, new memories are classified at write time as ADD/UPDATE/NOOP by comparing against existing neighbors. updates merge content in-place. noops skip storage entirely. from Mem0's production pipeline.

adversarial belief probing — during the dream cycle, randomly sample old semantic/procedural memories and challenge them: "is this still true?" beliefs that fail the probe get importance reduced. prevents fossilized false beliefs. from the March 2026 survey on autonomous agent memory.

memory types — memories are now typed: fact (structured knowledge, statuses, states), procedure (how-to, playbooks, rules), narrative (session logs, raw context). types are indexed and filterable. the recall tool accepts a mode parameter: facts_only (just structured knowledge), facts_plus_rules (+ procedures), full_context (everything). no more narrative dumps when you just want a status. existing memories auto-backfill from metadata on migration.

status tracking — memories have lifecycle states: active, challenged, invalidated, merged, superseded. every transition is recorded in a status_history audit table with timestamp and reason. non-active memories are filtered from retrieval results. use update_status to transition, status_history to audit. designed for the "which status is current?" problem — one canonical state per memory, no conflicting duplicates.

83 MCP tools — plugs into claude code (or any MCP client) as a tool server. docker-ready. recall, remember, entity lookup, codebase scanning, conversation extraction, semantic dedup, drift detection, pattern extraction, negative knowledge, quality metrics, embedding compression, community detection, timeline queries, similarity search, backlinks, briefing, query comparison, hotspot surfacing, consolidation, batch operations, export, health checks, the works.

the retrieval pipeline

eight stages — four parallel channels, intent-weighted fusion, boosted, reranked, gated:

query
  │
  ├── intent classification (why/when/who/how/what)
  │         → dynamic signal weights per intent type
  │
  ├── dense HNSW search (bge-small-en-v1.5, 384-dim, hnswlib)  → top 3k candidates
  ├── BM25 via sqlite FTS5 (content + hypothetical queries)     → top 3k candidates
  ├── entity graph BFS (1-hop traversal, strength-weighted)     → top k candidates
  └── Hopfield associative (pattern completion, β=8.0)          → top k candidates
           │
           ▼
     intent-weighted reciprocal rank fusion (k=60)
     score = Σ w_intent · 1/(60 + rank) across 4 channels
           │
           ▼
     temporal + importance boosting
     retention regularization, access frequency, date matching
           │
           ▼
     cross-encoder reranking (ms-marco-MiniLM-L-6-v2)
     joint (query, document) scoring — optional, adds ~200ms
           │
           ▼
     deep MLP reranker (optional, if trained)
     learned relevance from historical access patterns, = 0.7 and access count >= 5 get promoted to semantic (permanent). working memories auto-promote to episodic after 30 minutes or 2 accesses. the sweep runs on every `recall` call so it's basically free.

**pinning** — pin any memory with the `pin` tool or the pin button in the web UI. pinned memories are immune to the dream cycle's forgetting pass. useful for memories that are important but accessed infrequently — the kind ebbinghaus would normally archive.

**retention regularization** — forgetting is reframed as retention regularization, inspired by [Miras](https://arxiv.org/abs/2504.13173) (Behrouz et al., Google). three modes, configurable via `retention_mode` in config:
- `l2` (classic ebbinghaus): smooth exponential decay, 50% at half-life. everything fades gradually.
- `huber` (default): matches L2 near-term, transitions to linear for old memories. robust to burst-then-quiet access patterns — old-but-once-hot memories get a gentler transition instead of an infinite long tail. `huber_delta` controls the transition point.
- `elastic` (L1+L2): sparse retention. strongly-held memories stay near full strength, weakly-held ones decay faster. produces cleaner separation between keepers and forgettables. `elastic_l1_ratio` controls the L1/L2 blend.

all modes include access reinforcement — each recall strengthens retention (spaced repetition effect, log-scaled, capped at +0.3). **trust-weighted**: low-trust sources (auto-extracted, dream-generated) decay up to 3x faster than human-authored memories (`λ_eff = λ · (1 + κ·(1 - trust))`, κ=2.0, from [SuperLocalMemory V3.3](https://arxiv.org/abs/2604.04514)). after 90 days, if retention 0.8) = 32-bit float, warm = 8-bit (3.9x compression, 0.9999 cosine fidelity), cold = 4-bit (7.6x, 0.97 fidelity), archive = 2-bit (14.6x, 0.59 fidelity). uses Fisher-Rao Quantization-Aware Distance (FRQAD) for mixed-precision comparison — inflates variance proportional to quantization loss to prevent false similarity. run with `compress_embeddings`.

**consolidation** (dream cycle) — 7-step pipeline: (1) apply forgetting curve with trust-weighted retention, (2) cluster similar memories by embedding distance and merge clusters of 5+, (3) generate peer cards for entities with enough data, (4) cross-domain synthesis — find entity pairs in different contexts with moderate embedding similarity (0.75-0.90), LLM-confirm genuine connections, create SYNTHESIZED_WITH bridges, (5) adversarial belief probing — randomly sample old semantic/procedural memories and challenge them ("is this still true?"), reduce importance on invalidated beliefs, (6) drift detection — validate memory claims against filesystem, auto-invalidate dead references, (7) prune old access logs and events. run manually with `engram consolidate` or the MCP `consolidate` tool.

## entity graph

every memory gets scanned for entities — people, tools, projects, dates, URLs, file paths. these go into an entity registry with canonical names, aliases, and types.

relationships form automatically through co-occurrence (entities mentioned in the same sentence get a CO_OCCURS link) and through pattern matching ("X uses Y" → USES, "X built Y" → CREATED, etc.). relationship strength increases with evidence count.

traversal uses recursive SQL CTEs for multi-hop queries — "show me everything connected to Ari within 2 hops" runs in a single SQL query, no graph database needed. the `recall_related` tool does this.

you can also manually link entities (`link_memories`), merge duplicates (`merge_entities`), add aliases (`update_entity`), find backlinks (`backlinks`), and fuzzy-search for entities by partial name (`search_entities`).

## editing and annotating

memories aren't write-once. you can:

- **edit content** — `edit_memory` changes the text and automatically re-embeds and rebuilds the FTS index. the memory keeps its ID, access history, and entity links.
- **annotate** — `annotate` attaches timestamped notes to a memory without touching its content. useful for adding context later ("this turned out to be wrong" or "confirmed by Ari on april 8").
- **invalidate** — `invalidate` marks a fact as no longer true with a reason. the memory stays in the database (useful for audit) but gets flagged and shown with a strikethrough in the web UI.
- **tag** — `tag` adds or removes freeform tags. `batch_tag` applies tags to all memories matching a search query.

## examples

the `examples/` directory has ready-to-use setup guides:

**setup guides:**

| file | what it covers |
|------|---------------|
| [`claude-code-setup.md`](examples/claude-code-setup.md) | full walkthrough: install, wire into claude code, add CLAUDE.md instructions, seed memories |
| [`hooks-setup.md`](examples/hooks-setup.md) | auto-extract memories from conversations via claude code hooks |
| [`agent-patterns.md`](examples/agent-patterns.md) | common patterns: session orientation, learning from corrections, check-before-store, cognitive scaffolding, multi-agent setup |

**skills:**

| file | what it covers |
|------|---------------|
| [`session-continuity/SKILL.md`](examples/skills/session-continuity/SKILL.md) | agent skill for loading `resume_context`, writing important state during work, and leaving a structured `session_handoff` behind |

**python examples:**

| file | what it does |
|------|-------------|
| [`python-client.py`](examples/python-client.py) | standalone usage without MCP — store, search, surprise scoring, reranker training |
| [`custom-agent.py`](examples/custom-agent.py) | conversational agent with engram memory using the Anthropic SDK |
| [`openai-compatible.py`](examples/openai-compatible.py) | same pattern for any OpenAI-compatible API (OpenAI, Ollama, vLLM, llama.cpp) |
| [`multi-agent.py`](examples/multi-agent.py) | 3 specialized agents sharing one database — cross-domain recall, surprise, dream cycle |
| [`api-embeddings.py`](examples/api-embeddings.py) | switch between local and cloud embedding backends (Voyage, OpenAI, Gemini) |
| [`entity-graph.py`](ex

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [raya-ac](https://github.com/raya-ac)
- **Source:** [raya-ac/engram](https://github.com/raya-ac/engram)
- **License:** MIT
- **Homepage:** https://engram-memory.dev

Install and usage instructions live in the source repository linked above.