# Engram — Provable Memory Infrastructure for AI Agents (Full Context)

> Expanded reference for LLMs and AI assistants. Engram is open-source, self-hostable memory infrastructure for AI agents whose differentiator is trust: write-provenance on every belief, a tamper-evident SHA-256 audit trail over every mutation, verified per-subject cryptographic erasure, and self-cleaning memory lifecycle (decay, contradiction handling, consolidation). Apache-2.0, Go + PostgreSQL/pgvector. Website: https://engram.to · Docs: https://docs.hakuya.ai · GitHub: https://github.com/Harshitk-cp/engram

## One-paragraph summary

Every other memory layer asks you to trust a black box: facts go in, context comes out, and nobody can say where a belief came from, whether it is stale, or whether the store has been tampered with. Engram records provenance and confidence on every memory, decays beliefs that go unused, detects contradictions between beliefs, seals every change into a per-tenant SHA-256 hash chain that can be verified in one API call, and can cryptographically erase everything about one subject while keeping a provable record of the erasure. It is the memory layer designed for production agents whose mistakes cost money and for regulated industries that must answer auditors.

## The problem it solves

1. Agents forget everything between sessions → Engram persists typed memory across sessions.
2. Memory stores rot: a public 2026 production audit of a leading memory layer found 97.8% of entries were junk after 32 days (duplicates, hallucinated profiles, leaked secrets/PII). Engram's decay, deduplication-by-competition, and contradiction handling keep the store clean automatically.
3. Stored facts go stale but stay confident: "Customer is on the Basic plan" stored a year ago is still served at full strength by other systems. In Engram confidence decays with disuse, the memory is flagged stale below a threshold, and the agent can verify before trusting it.
4. Memory poisoning (OWASP Agentic Top 10, ASI06): query-only injection attacks achieve >95% success against auto-extracting memory systems. Engram's evidence-typed write-provenance and tamper-evident mutation log are the audit substrate for detecting and investigating poisoning.
5. Compliance: the EU AI Act (fully applicable August 2026) and GDPR Article 17 require explainability and erasure. Engram answers "what did the agent believe on date X and why" and "prove you deleted subject Y."

## Trust & governance (the differentiators)

### Tamper-evident audit trail
Every memory mutation — created, reinforced, decayed, contradicted, redacted, deleted — appends a row to a mutation log with old/new confidence, a reason, the source of the change, and a content snapshot for deletions. Rows are hash-chained per tenant: each row's SHA-256 includes the previous row's hash, append-only is enforced by database triggers, and `GET /v1/audit/verify` recomputes the chain — any edit, insertion, deletion, or reordering breaks verification. `GET /v1/audit/export` streams the log as NDJSON with an HMAC-SHA256 signed trailer for handing to auditors (SOC 2 / HIPAA workflows). The chain is tamper-EVIDENT (detection), which is the honest claim; it is not marketed as tamper-proof.

### Write-provenance
Each memory stores its provenance (e.g., user statement, behavioral inference, system import) and the evidence type sets the initial confidence (a direct user statement starts higher than an inference). Recall responses can therefore explain why an agent holds a belief and how strongly.

### Verified per-subject erasure (anchors)
Memory is scoped with a binding model: `private` (the agent's own), `anchored` (about one subject — a customer, patient, guest), `session` (ephemeral, auto-expiring), and `canon` (tenant-wide shared truth). One agent can serve thousands of isolated subjects; recall composes scopes with per-binding budgets and per-binding decay rates. `DELETE /v1/anchors/{id}?purge=true` erases a subject; the crypto-shred admin operation makes content unrecoverable while writing redaction rows to the audit chain — provable right-to-be-forgotten that coexists with an append-only log.

### Self-cleaning lifecycle
- Exponential confidence decay for unused memories (distance-to-floor model, hourly background worker).
- Competition-aware decay: similar memories of the same type suppress each other — only higher-confidence near-duplicates suppress weaker ones — so redundant beliefs die out instead of accumulating.
- Reinforcement resistance: frequently reinforced memories resist decay (log-scaled bonus).
- Memories below an archive threshold are archived (soft-deleted), not silently kept.
- Contradiction detection: new memories are checked against existing beliefs; hard contradictions demote the old belief, temporal updates archive it as superseded, contextual variants coexist. Every resolution is logged to the audit chain.
- 5-stage consolidation pipeline: episodes → semantic beliefs → procedures → schemas → forgetting, run by a background scheduler.

## Cognitive memory model

- **Semantic**: facts, preferences, constraints, decisions; typed and confidence-scored.
- **Episodic**: experiences with context, entities, causal links, and recorded outcomes.
- **Procedural**: learned trigger→action skills extracted from successful episodes, matched to new situations.
- **Schema**: higher-order patterns clustered from related memories.
- **Working memory**: 7-slot active context for current goals and reasoning state.
- **Belief dynamics**: confidence updates use log-odds arithmetic (logit → delta → sigmoid). Reinforcement raises confidence, contradiction lowers it, decay erodes it. Confidence drives tiering: hot memories auto-inject into agent context; cold ones surface only on explicit recall.
- **Hybrid retrieval**: pgvector similarity + knowledge-graph traversal (entities/relationships, up to 2 hops), fused ranking by relevance × recency × confidence; sub-10ms p95 recall latency. Conversation ingestion extracts and classifies memories from transcripts automatically.

## Benchmark (reproducible)

LongMemEval (ICLR 2025, 500 questions), public reproducible harness: **91.4% overall**.
Per task: knowledge update 100% (72/72), abstention 100% (30/30), single-session user facts 98.4% (63/64), single-session preference 93.3% (28/30), multi-session 90.2% (109/121), single-session assistant 89.3% (50/56), temporal reasoning 82.3% (102/124).

## API & integration surface

- REST API (~70 endpoints): memories CRUD + recall + extract + mutations history, agents (mind, policies, tier-stats, hot-memories, dashboard, review-queue, snapshot, conversations/ingest), episodes, procedures, schemas, working memory, graph (entities/relationships/traverse), cognitive ops (decay/consolidate/health), anchors/sessions/canon, audit (verify/export), billing.
- Auth: Bearer API keys (scoped), per-tenant isolation; console with OAuth (Google/GitHub) and WorkOS SSO.
- Python SDK: `pip install engram.to` — sync + async clients, Pydantic v2 models.
- LangChain: `pip install langchain-engram` — EngramRetriever.
- MCP server (stdio for Claude Desktop/Claude Code; SSE and streamable HTTP transports): tools `remember`, `recall`, `recall_graph`, `forget`, `get_hot_context`, `list_agents`.
- Self-host: single Go binary or Docker Compose (`docker compose up -d`); only dependency is PostgreSQL with pgvector. LLM providers pluggable: OpenAI, Anthropic, Gemini, Cerebras (embeddings: OpenAI).
- Managed cloud: Developer $29/mo and Team $149/mo tiers (waitlist); self-hosted is free forever under Apache-2.0.

## Honest comparison (public documentation, June 2026)

**vs Mem0**: Mem0 leads on adoption and integrations breadth. It has no confidence model, no decay/lifecycle (memories persist at full weight), an operation log without integrity guarantees, and row-delete without per-subject scope or erasure proof. Engram adds belief dynamics, self-cleaning decay, a tamper-evident chain, and per-subject erasure.
**vs Zep/Graphiti**: Zep's strength is bi-temporal knowledge graphs (fact validity windows) and enterprise compliance certifications. It deprecated its self-hosted Community Edition (April 2025) and is annual-contract cloud. Engram is fully self-hostable (Apache-2.0), adds confidence/decay (Zep tracks when facts changed, not how certain they are), and tamper-evidence Zep does not offer.
**vs vector DBs / DIY RAG**: those are storage and similarity search; Engram is the cognitive + governance layer above them (it does not replace Postgres/Pinecone for general workloads).

## FAQ

**Q: What makes Engram different from Mem0 or Zep?**
A: Trust and governance. Engram is the only agent-memory layer with a tamper-evident audit trail (per-tenant SHA-256 hash chain with one-call verification and signed export), write-provenance on every belief, verified per-subject cryptographic erasure, and self-cleaning decay. Others solve retrieval; Engram solves whether memory can be trusted, audited, and provably deleted.

**Q: Is "tamper-evident" the same as tamper-proof?**
A: No, and Engram is explicit about this. The hash chain detects any modification of the audit history (edit, insert, delete, reorder breaks verification). Detection is what auditors require.

**Q: How does Engram handle GDPR right-to-be-forgotten?**
A: Memories about one subject are isolated under an anchor. Purging the anchor erases its memories; the crypto-shred operation makes content unrecoverable while the append-only audit chain retains a provable record that data existed and was erased.

**Q: Does memory decay mean my agent forgets things it needs?**
A: Reinforced (used) memories resist decay; only unused, low-value beliefs fade, get flagged stale, and archive. Decay is what prevents the months-old "Basic plan" fact from being served at full confidence after the customer upgraded.

**Q: Can I self-host?**
A: Yes — a single Go binary (or Docker Compose) plus PostgreSQL with pgvector, Apache-2.0 licensed, full functionality without the managed cloud.

**Q: Does it work with Claude / OpenAI / Gemini?**
A: Yes. The extraction/consolidation LLM is pluggable (OpenAI, Anthropic, Gemini, Cerebras), and the MCP server lets Claude Desktop, Claude Code, Cursor, and Windsurf read/write Engram memory directly.

## Links

- Website: https://engram.to
- Docs: https://docs.hakuya.ai
- GitHub: https://github.com/Harshitk-cp/engram
- Python SDK: https://pypi.org/project/engram.to/
- LangChain: https://pypi.org/project/langchain-engram/
- Concise version: https://engram.to/llms.txt