Engram

Provable memory infrastructure for AI agents.

Engram stores, retrieves, and injects typed memory into agent prompts via a simple HTTP API or an MCP server. Memories gain confidence when reinforced, lose it when contradicted, and fade when unused. Unlike a black-box memory layer, Engram records where every belief came from, lets stale beliefs decay, can erase any subject on request, and writes every change to a tamper-evident audit trail — so you can prove what your agent knows, and why.

Architecture

Every write enters through the Provenance Firewall, flows into the cognitive core (the four memory systems plus contradiction detection, consolidation, and metacognition), stays isolated per subject, and is recorded — change by change — in a tamper-evident audit chain on top of PostgreSQL + pgvector.

Benchmarks

Engram scores 91.4% on LongMemEval — the ICLR 2025 benchmark for long-term conversational memory (500 questions over chat histories scalable past 1M tokens) — and 92.3% averaged across its six task types.

Measured with Engram as the memory store + retrieval layer, graded by LongMemEval's standard LLM judge. Full per-task breakdown, methodology, and how to read memory benchmarks: hakuya.ai/#benchmarks · docs.hakuya.ai/benchmarks.

Quick Start

# Clone and configure
git clone https://github.com/Harshitk-cp/engram.git
cd engram
cp .env.example .env

# Start with Docker
docker compose up -d

# Run migrations
docker compose exec server /engram migrate

Then open the admin console at http://localhost:8080/console to create an account, register an agent, and mint an API key — or bootstrap headlessly:

# Bootstrap a deployment (one-time): creates a tenant + its first master key
curl -X POST http://localhost:8080/v1/setup \
  -H "X-Setup-Token: $ENGRAM_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"org_name": "My App"}'   # → returns api_key (shown once)

Basic Usage

# 1. Register an agent
curl -X POST http://localhost:8080/v1/agents \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"external_id": "agent-1", "name": "My Agent"}'

# 2. Store memory
curl -X POST http://localhost:8080/v1/memories \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"agent_id": "AGENT_UUID", "content": "User prefers dark mode"}'

# 3. Recall memories
curl "http://localhost:8080/v1/memories/recall?agent_id=AGENT_UUID&query=display+preferences" \
  -H "Authorization: Bearer $API_KEY"

Use it as an MCP server

Engram ships a standalone MCP server (engram-mcp) that exposes 37 memory tools to Claude Desktop, Cursor, Windsurf, or any MCP-compatible host — remember, recall, recall_graph, get_hot_context, ingest_conversation, plus episodic, schema, anchor, metacognition, calibration, and audit tools.

{
  "mcpServers": {
    "engram": {
      "command": "engram-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "ENGRAM_API_URL": "http://localhost:8080",
        "ENGRAM_API_KEY": "mk_your_key_here",
        "ENGRAM_AGENT_ID": "your-agent-id"
      }
    }
  }
}

Full tool list and host setup: docs.hakuya.ai/guides/mcp.

Core Concepts

Memory Types

Memory Tiers

Memories are tiered by confidence for efficient retrieval:

Belief Dynamics

• Reinforcement: Similar statements increase confidence (+0.05)
• Contradiction: Conflicting beliefs decrease confidence (-0.2)
• Decay: Unused memories gradually lose confidence
• Usage Boost: Recalled memories gain small confidence (+0.02)

Every one of these changes is written to an append-only mutation log — the why-trail behind each belief.

Multi-Subject Memory (Anchors, Sessions, Canon)

One agent can act on behalf of thousands of subjects (customers, guests, patients) with full isolation. Every memory carries a server-derived binding:

# Store a fact ABOUT a subject (anchor auto-created on first use)
curl -X POST http://localhost:8080/v1/memories -H "Authorization: Bearer $API_KEY" \
  -d '{"agent_id":"AGENT","content":"Guest is vegetarian","anchor_external_id":"guest-42"}'

# Recall is isolated per subject — guest-99's data never leaks into guest-42's results
curl "http://localhost:8080/v1/memories/recall?agent_id=AGENT&query=diet&anchor_external_id=guest-42" \
  -H "Authorization: Bearer $API_KEY"

# GDPR per-subject erasure (crypto-shred — content unrecoverable, audit record retained)
curl -X DELETE "http://localhost:8080/v1/anchors/ANCHOR_ID?purge=true" -H "Authorization: Bearer $API_KEY"

Passing only agent_id preserves today's exact behavior. Endpoints: /v1/anchors, /v1/sessions, /v1/canon. See the Subjects, Sessions & Canon guide.

Provenance & Trust

Engram is built so you can prove what an agent knows and how it changed:

• Provenance on every belief — source (user/agent/tool/derived), evidence type, and confidence are attached at write time.
• Tamper-evident audit trail — every memory mutation (create / reinforce / decay / contradict / redact / release) is appended to a per-tenant SHA-256 hash chain. GET /v1/audit/verify recomputes the chain and detects any edit, insertion, deletion, or reordering. GET /v1/audit/export produces a signed NDJSON trail for compliance.
• Provenance Firewall — untrusted memories (e.g. extracted from third-party content) are held in a quarantine queue, kept out of recall and belief logic until an admin reviews them. Release/reject decisions are themselves recorded in the audit chain.
• Verified per-subject erasure — forget_subject / crypto-shred destroys a subject's content irrecoverably while preserving the immutable audit record that the erasure happened (GDPR Article 17, EU AI Act).

# Verify the tamper-evident chain is intact
curl http://localhost:8080/v1/audit/verify -H "Authorization: Bearer $ADMIN_KEY"

# Review the Provenance Firewall queue, then release or reject
curl http://localhost:8080/v1/agents/AGENT_ID/quarantine -H "Authorization: Bearer $ADMIN_KEY"
curl -X POST http://localhost:8080/v1/quarantine/MEM_ID/release -H "Authorization: Bearer $ADMIN_KEY"

Admin Console

A React admin console is embedded in the server binary at /console. It provides:

• Agent dashboard — knowledge health, tier distribution, learning velocity, stability
• Memories browser — filter by tier, type, source, and binding; inspect provenance
• Contradictions & Review Queue — resolve conflicting beliefs with audited reasons
• Quarantine — the Provenance Firewall review surface (release / reject)
• Audit — verify the hash chain and export the signed trail
• Subjects — manage anchors and per-subject erasure
• Canon — tenant-wide authoritative knowledge
• Time Machine — replay how a memory evolved over time
• Keys, Billing, Settings — API keys, plan/usage, and per-tenant engine tuning

Memory Systems

Engram implements four memory types inspired by cognitive science:

Plus Schemas for higher-order mental models (user archetypes, situation templates): /v1/schemas.

Key Features

Hybrid Retrieval (Vector + Graph)

All recall uses hybrid retrieval by default, combining semantic similarity with graph relationship traversal:

curl "http://localhost:8080/v1/memories/recall?agent_id=...&query=...&graph_weight=0.4&max_hops=2" \
  -H "Authorization: Bearer $API_KEY"

Response includes both vector and graph scores for transparency.

Conversation Extraction

Automatically extract memories from conversations:

curl -X POST http://localhost:8080/v1/memories/extract \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "agent_id": "...",
    "conversation": [
      {"role": "user", "content": "I only use open source tools"},
      {"role": "assistant", "content": "Noted, I will suggest open source alternatives."}
    ],
    "auto_store": true
  }'

Metacognition & Calibration

Self-assessment of memory quality, plus a measured calibration score (ECE / MCE / Brier):

# Reflect on memory state
curl -X POST http://localhost:8080/v1/cognitive/reflect \
  -H "Authorization: Bearer $API_KEY" -d '{"agent_id": "..."}'

# Measure how well-calibrated the agent's confidence is
curl "http://localhost:8080/v1/cognitive/calibration?agent_id=..." \
  -H "Authorization: Bearer $API_KEY"

Confidence Lifecycle

Explicit confidence management:

# Reinforce a memory
curl -X POST http://localhost:8080/v1/cognitive/confidence/reinforce \
  -d '{"memory_id": "...", "boost": 0.1}'

# Penalize a memory
curl -X POST http://localhost:8080/v1/cognitive/confidence/penalize \
  -d '{"memory_id": "...", "penalty": 0.15}'

API Reference

The full, browsable reference lives at docs.hakuya.ai/api-reference. Key families:

Auth & Keys

Agents & Memories

Multi-Subject (Anchors, Sessions, Canon)

Provenance, Audit & Admin

Cognitive, Graph & Learning

Billing & Settings