zanfiel/engram

---

What is Engram?

Engram gives your AI agents long-term memory. Instead of losing context between sessions, agents store what they learn and recall it when relevant, automatically.

bash
# Store what the agent learns
curl -X POST http://localhost:4200/store \
  -H "Authorization: Bearer eg_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode and uses Vim keybindings", "category": "decision", "importance": 8}'

# Later, in a new session - recall relevant context
curl -X POST http://localhost:4200/recall \
  -H "Authorization: Bearer eg_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "setting up the user editor"}'
# → Returns the dark mode + Vim preference automatically

Key features:

• 🧠 FSRS-6 spaced repetition - cognitive science-backed memory decay using power-law forgetting curves (ported from https://github.com/open-spaced-repetition/fsrs4anki)
• 💪 Dual-strength memory model - Bjork & Bjork (1992) storage strength (never decays) + retrieval strength (decays via power law)
• 🧬 Reciprocal Rank Fusion search - four-channel RRF scoring across vector similarity, FTS5 full-text, personality signals, and graph relationships
• 🔗 Auto-linking - memories automatically connect via cosine similarity, forming a knowledge graph
• 🧹 SimHash deduplication - 64-bit locality-sensitive hashing detects near-duplicates before embedding, saving compute
• 🕐 Bi-temporal fact tracking - structured facts carry temporal validity windows with automatic contradiction-based invalidation
• 🧩 Entity cooccurrence graph - entities that appear together build weighted relationships automatically
• 🏘️ Community detection - label propagation groups related memories into discoverable clusters, auto-runs on store
• 📈 PageRank - iterative weighted PageRank ranks memories by structural importance, not just connection count
• 📊 Graph timeline - GET /graph/timeline shows how your knowledge graph grew week by week
• 🔬 Cross-encoder reranker - BGE-reranker-base (quantized INT8) reranks search results for semantic precision
• 🎭 Personality engine - extracts preferences, values, motivations, decisions, emotions, and identity signals from memories
• 📊 Graph visualization - explore your memory space in a WebGL galaxy
• 🔄 Versioning - update memories without losing history
• ⏰ Implicit spaced repetition - every access is an FSRS review, building stability over time
• 🔍 Fact extraction & auto-tagging - LLM extracts facts, classifies, tags (optional, requires LLM)
• 💬 Conversation extraction - feed chat logs, get structured memories
• ⚡ Contradiction detection - find and resolve conflicting memories
• ⏪ Time-travel queries - query what you knew at any point in time
• 🎯 Smart context builder - token-budget-aware RAG context assembly with progressive depth (1/2/3-hop)
• 💭 Reflections - periodic meta-analysis that becomes searchable memory
• 🧬 Derived memories - inference engine finds patterns across memories
• 🗜️ Auto-consolidation - summarize large memory clusters automatically
• 👥 Multi-tenant - isolated memory per user with API keys
• 📖 Episodic memory - store conversation episodes as embedded, searchable narratives with temporal + semantic search. Facts link to source episodes.
• 🚫 Abstention - search returns abstained: true when confidence is below threshold. The system knows when it doesn't know.
• 🤖 Assistant recall - extracts what the AI said/did, not just user facts. LLM + regex patterns for assistant actions.
• ⏳ Temporal search - temporal_sort orders results chronologically. Episode search by date range.
• 🔗 2-hop graph traversal - relationship expansion reaches 2 levels deep for multi-hop reasoning
• 🧩 Implicit connection inference - LLM post-processing in /context finds unstated relationships between memories
• 🛡️ Guardrails - POST /guard checks proposed actions against stored rules before execution. Returns allow/warn/block. Prevents repeated deployment mistakes, outdated references, and policy violations.
• 📦 Spaces, tags, episodes - organize memories into named collections
• 🧩 Entities & projects - track people, servers, tools, projects
• 📬 Webhooks & digests - event hooks + scheduled HMAC-signed summaries
• 🔄 Sync & import - cross-instance sync, import from Mem0 / Supermemory
• 📥 URL ingest - extract facts from web pages or text blobs
• 🛠️ MCP server - JSON-RPC 2.0 stdio transport for Claude Desktop, Cursor, Windsurf
• ⌨️ CLI - full-featured command-line interface (engram-cli store, engram-cli search, etc.)
• 📥 Review queue / inbox - auto-detected memories land in review; explicit stores bypass
• 🔒 Security hardening - auth required by default, body/content limits, IP allowlists, timing-safe auth
• 📋 Audit trail - every mutation logged (who, what, when, from where)
• 📊 Structured JSON logging - configurable log levels, request IDs, zero raw console output
• 💾 Backup & checkpoint - download SQLite DB via API, manual WAL checkpoint, graceful shutdown
• 🐳 One-command deploy - docker compose up

---

What's New

Syntheos Service Consolidation (v5.11.0)

Six standalone microservices absorbed into the Engram monolith as native modules. No new dependencies, no new processes. Same database, same auth.

Thymus (quality evaluation) - Rubric-based scoring engine for agent output quality. Define evaluation criteria with weighted scales, run evaluations, track agent scores over time. Stores quality metrics alongside memories.

• POST /thymus/rubrics - Create evaluation rubrics with weighted criteria
• GET /thymus/rubrics - List rubrics
• POST /thymus/evaluations - Score agent output against a rubric
• GET /thymus/evaluations - List evaluations with agent/rubric filtering
• GET /thymus/agents/:agent/scores - Aggregate scores per agent
• POST /thymus/metrics - Record arbitrary quality metrics
• GET /thymus/metrics - Query metrics with time range and agent filtering
• GET /thymus/stats - Rubric, evaluation, and metric counts

Soma (agent registry) - Agent lifecycle management. Register agents with capabilities, track heartbeats, organize into groups, collect structured logs.

• POST /soma/agents - Register an agent
• GET /soma/agents - List agents with type/status/capability filtering
• PATCH /soma/agents/:id - Update agent metadata
• DELETE /soma/agents/:id - Deregister (atomic cascade delete)
• POST /soma/agents/:id/heartbeat - Heartbeat with optional status update
• GET /soma/agents/stale - Find agents that missed heartbeats
• POST /soma/agents/:id/logs - Submit structured log entries
• GET /soma/agents/:id/logs - Read agent logs
• POST /soma/groups - Create agent groups
• GET /soma/groups - List groups
• POST /soma/groups/:id/members - Add agent to group
• DELETE /soma/groups/:id/members/:agentId - Remove from group
• GET /soma/agents/capability/:name - Find agents by capability
• GET /soma/stats - Registry statistics

Chiasm (task tracking) - Lightweight task coordination for multi-agent systems. Agents create tasks, update status, and read each other's active work via a feed endpoint.

• POST /tasks - Create a task
• GET /tasks - List tasks with status/agent/project filtering
• GET /tasks/:id - Get task with full audit trail
• PATCH /tasks/:id - Update status/summary (creates audit entry)
• DELETE /tasks/:id - Delete task
• GET /tasks/stats - Task counts by status
• GET /feed - Activity feed of recent task updates

Axon (event bus) - Real-time pub/sub event bus with SSE streaming, webhook fan-out, and cursor-based polling. Agents publish events to named channels, subscribe for real-time delivery or poll at their own pace.

• POST /axon/publish - Publish an event to a channel
• GET /axon/events - Query events with channel/type/source filtering
• GET /axon/channels - List channels with event and subscriber counts
• POST /axon/channels - Create a new channel
• POST /axon/subscribe - Subscribe agent to channel (optional webhook URL)
• POST /axon/unsubscribe - Remove subscription
• GET /axon/subscriptions - List subscriptions
• GET /axon/poll - Cursor-based event consumption
• GET /axon/stream - SSE real-time event stream
• GET /axon/stats - Bus statistics

Loom (workflow orchestration) - Multi-step pipeline engine with dependency-based execution. Define reusable workflows with webhook, LLM, and transform step types. Runs track progress, retry failed steps, and collect outputs.

• POST /loom/workflows - Create a workflow definition
• GET /loom/workflows - List workflows
• POST /loom/runs - Start a workflow run with input
• GET /loom/runs - List runs with status filtering
• GET /loom/runs/:id - Get run with full state
• POST /loom/runs/:id/cancel - Cancel a running workflow
• GET /loom/runs/:id/steps - Get step states for a run
• GET /loom/runs/:id/logs - Get execution logs
• POST /loom/steps/:id/complete - External callback to complete a step
• POST /loom/steps/:id/fail - External callback to fail a step
• GET /loom/stats - Workflow and run statistics

Broca (action log and narrator) - Agent action logger with template-based narration and natural language query. Logs what agents do, translates actions into plain English, and answers questions about system activity.

• POST /broca/actions - Log an action with auto-narration
• GET /broca/actions - Query actions with filtering
• GET /broca/actions/:id - Get single action
• GET /broca/actions/:id/narrate - Generate narrative for action
• GET /broca/feed - Activity feed with narratives
• POST /broca/narrate - Bulk narrate actions
• POST /broca/ask - Natural language query over the system
• GET /broca/stats - Action statistics

All six services share the main Engram database, reuse auth middleware, and publish events via the Axon event bus.

v5.9.x

PageRank for Memory Graphs - Full iterative PageRank algorithm with type-aware edge weighting. Memories linked to by important memories score higher, not just memories with lots of connections. Scores are normalized 0-1 and stored per memory. Runs automatically every 25th store alongside community detection.

Search Ranking from Graph Structure - Search results now get a 0-15% boost based on their PageRank score. Structurally important memories surface higher in /search and /context results. This works on top of the existing RRF scoring, decay, and temporal signals.

Auto Graph Analysis on Store - Every 25th memory stored triggers background community detection and PageRank recomputation via the durable job queue. No impact on store latency.

Temporal Graph Evolution - New GET /graph/timeline endpoint returns weekly aggregates of graph growth.

Enriched Graph Endpoint - /graph now returns pagerank_score per node. Node sizes are boosted by PageRank.

v5.8.3

Server-Side Source Filtering - /search, /context, and /recall accept a source parameter. Filter propagates into hybrid search at both vector and FTS5 stages.

Worker Thread Embeddings - ONNX inference moved to a dedicated Worker thread. No more event loop blocking.

Batch Link Queries - Relationship expansion uses single batch query instead of N+1.

TypeScript Zero Errors - Clean compilation with zero TS errors.

Previous releases

v5.8.2 - Blended Retrieval, Memory Health, Feedback Loop

Blended Multi-Strategy Retrieval - classifyQuestionMixed detects mixed-intent queries and blends multiple question types with normalized weights. blendStrategies produces a weighted combination of SearchStrategy configs.

Memory Health Endpoint - GET /memory-health returns four diagnostic categories: stale, duplicates, high-value unlinked, and contradiction hints.

Retrieval Feedback - POST /feedback accepts signals (used, ignored, corrected, irrelevant, helpful). Auto-adjusts importance. GET /feedback/stats returns analytics.

Search Explainability - Per-channel score breakdowns (vector, FTS, graph, personality, reranker, decay) in search results.

Freshness-Weighted Structured Facts - Facts sorted by freshness with linear decay. Old facts tagged [possibly outdated].

Contradiction Ranking Penalty - Non-latest-version memories with contradiction keywords receive 0.65x score penalty.

v5.8.1 - Durable Jobs, Security Hardening, Scheduler Leases

Durable Job Queue - DB-backed jobs table with retry, exponential backoff, and crash recovery.

Scheduler Leases - DB-backed leases prevent duplicate background work in multi-instance deployments.

Security - Atomic memory ownership, bootstrap hardening, cross-tenant scratchpad fix, SSRF redirect blocking, passport tenant binding.

Readiness Probes - GET /live and GET /ready with 503 when degraded.

v5.8.0 - Intelligence Pipeline Overhaul

Reciprocal Rank Fusion - 4-channel RRF scoring (vector, FTS5, personality, graph). Question-type-aware strategies.

SimHash Deduplication - 64-bit locality-sensitive hashing detects near-duplicates before embedding.

Bi-Temporal Fact Tracking - Structured facts with valid_at/invalid_at windows. Contradiction-based invalidation.

Entity Cooccurrence Graph - Composite scoring (name similarity, frequency, temporal proximity).

Community Detection - Label propagation on memory_links graph.

Cross-Encoder Reranker - BGE-reranker-base (INT8, sub-100ms). Optional.

Personality Engine - Six signal types: preference, value, motivation, decision, emotion, identity.

Progressive Disclosure - /context depth=1/2/3 for token budget control.

v5.7.0 - BGE-large, Episodic Memory, Multi-Tenant Isolation

BGE-large-en-v1.5 (1024-dim), episodic memory, complete multi-tenant security audit, guardrails, abstention, assistant recall, 2-hop graph traversal, implicit connection inference.

v5.6.0 - Node.js 22, Graph Intelligence

Node.js 22+, optimized MCP server, vitest, Graphology knowledge graph.

v5.5.0 - Intelligence Layer

LLM fact extraction, auto-tagging, conversation extraction, URL ingest, reflections, derived memories, auto-consolidation.

v5.4.0 - Security Hardening

7 security fixes (S1-S7), RBAC, timing-safe auth, rate limiting, HSTS, CSP.

v5.3.0 - FSRS-6 Spaced Repetition

FSRS-6 with 21 trained weights, dual-strength model, time travel, smart context, reflections, digests, derived memories, auto-consolidation.

v5.0.0 - Multi-Tenant

Users, API keys, spaces, FTS5+vector hybrid search, auto-linking, version chains, libsql.

v4.0.0 - SQLite + Local Embeddings

SQLite + FTS5, MiniLM-L6-v2 embeddings, basic CRUD, conversations.

v3.0.0 - Initial Release

In-memory storage, basic embedding search.

---

Quick Start (10 minutes)

1. Start the server

bash
git clone https://github.com/zanfiel/engram.git && cd engram
npm install
cp .env.example .env    # Edit .env: set ENGRAM_GUI_PASSWORD
npm start               # Or: docker compose up -d

2. Bootstrap your admin key

bash
curl -X POST http://localhost:4200/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"name": "my-admin-key"}'
# Save the returned eg_... key

3. Store your first memories

bash
export KEY="eg_your_key_here"

curl -X POST http://localhost:4200/store \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"content": "Production database is PostgreSQL 16 on db.example.com:5432", "category": "reference", "importance": 8}'

curl -X POST http://localhost:4200/store \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"content": "Never deploy on Fridays - outage on 2026-01-15 was caused by Friday deploy", "category": "decision", "importance": 9}'

curl -X POST http://localhost:4200/store \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"content": "Migrated auth service from JWT to opaque sessions for compliance", "category": "decision", "importance": 7}'

4. Recall what matters

bash
# Semantic search
curl -X POST http://localhost:4200/search \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query": "database connection details"}'

# Decision-focused search
curl -X POST http://localhost:4200/search \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query": "deployment policy", "mode": "decision"}'

# Budget-aware context for RAG injection
curl -X POST http://localhost:4200/context \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query": "setting up a new deploy pipeline", "mode": "fast"}'

5. Check the guardrails

bash
# Before deploying, check against stored rules
curl -X POST http://localhost:4200/guard \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"action": "deploy to production on Friday"}'
# Returns: { "verdict": "warn", "reasons": ["Never deploy on Fridays..."] }

---

Decision Memory

Engram is especially strong as a decision memory system. It tracks not just what you know, but what you decided, why, and what changed.

• Versioning: update a memory and the full version chain is preserved
• Contradictions: when new information conflicts with old, both are flagged with a contradicts link
• Corrections: POST /correct stores a correction that supersedes the original, with corrects relationship
• Guardrails: POST /guard checks proposed actions against stored decision rules before execution
• Temporal queries: "what did we know last Tuesday?" via mode=timeline or time-travel queries
• Structured facts: subject/verb/object decomposition with temporal validity windows

This makes Engram ideal for:

• Agent memory: agents that learn from mistakes and don't repeat them
• Ops runbooks: infrastructure decisions with context ("we chose X because Y")
• Project continuity: decisions survive team turnover

---

Review Inbox

Memories extracted by LLM (fact extraction, personality signals) land in the review inbox instead of being immediately trusted. This gives you control over what enters long-term memory.

bash
# List pending memories
curl http://localhost:4200/inbox -H "Authorization: Bearer $KEY"

# Approve a memory
curl -X POST http://localhost:4200/inbox/42/approve -H "Authorization: Bearer $KEY"

# Reject a memory
curl -X POST http://localhost:4200/inbox/42/reject -H "Authorization: Bearer $KEY"

Memories you store directly via /store bypass the inbox and are approved immediately.

---

SDK

TypeScript SDK

typescript
import { Engram } from "@zanfiel/engram/sdk";

const engram = new Engram({ url: "http://localhost:4200", apiKey: "eg_..." });

// Store
await engram.store("User prefers dark mode", { category: "decision", importance: 8 });

// Search with presets
const results = await engram.search("dark mode", { mode: "preference" });

// Budget-aware context for RAG
const ctx = await engram.context("setting up the editor", { mode: "fast" });

// Guardrails
const check = await engram.guard("deploy to production on Friday");
if (check.verdict === "block") console.log("Blocked:", check.reasons);

// Inbox review
const pending = await engram.inbox();
for (const mem of pending.pending) {
  await engram.approve(mem.id);  // or: engram.reject(mem.id)
}

cURL

bash
# Store
curl -X POST http://localhost:4200/store \
  -H "Authorization: Bearer eg_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Server migrated to new IP", "category": "state", "importance": 7}'

# Search with mode preset
curl -X POST http://localhost:4200/search \
  -H "Authorization: Bearer eg_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "server migration", "mode": "timeline", "limit": 5}'

# Recall
curl -X POST http://localhost:4200/recall \
  -H "Authorization: Bearer eg_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "infrastructure changes"}'

# FSRS state
curl http://localhost:4200/fsrs/state?id=42 \
  -H "Authorization: Bearer eg_your_key"

---

MCP Server

Engram includes a real https://modelcontextprotocol.io/ server for integration with Claude Desktop, Cursor, Windsurf, and other MCP-compatible tools.

Transport: JSON-RPC 2.0 over stdio

Setup (Claude Desktop)

Add to claude_desktop_config.json:

json
{
  "mcpServers": {
    "engram": {
      "command": "node",
      "args": ["--experimental-strip-types", "path/to/engram/mcp-server.ts"],
      "env": {
        "ENGRAM_URL": "http://localhost:4200",
        "ENGRAM_API_KEY": "eg_your_key"
      }
    }
  }
}

Available Tools

Note: The MCP server connects to a running Engram instance via HTTP. All tools support signed tool manifests for integrity verification when ENGRAM_SIGNING_SECRET is set.

---

CLI

Engram ships a full CLI that wraps the HTTP API. Zero external dependencies -- uses Node.js 22 built-in util.parseArgs.

bash
# Install globally (or use npx)
npm install -g @zanfiel/engram

# Configure
export ENGRAM_URL=http://localhost:4200
export ENGRAM_API_KEY=eg_your_key

# Store
engram-cli store "Deployed auth migration to production" --category state --importance 9

# Search
engram-cli search "deployment history" --limit 5 --explain

# Context (RAG)
engram-cli context "current infrastructure state" --budget 4000

# Recall
engram-cli recall --context "what changed recently"

# Other commands
engram-cli list --limit 20
engram-cli forget 42 --reason "outdated"
engram-cli delete 42
engram-cli health
engram-cli stats

All commands support --json for raw API output and --quiet for minimal output (IDs and counts only). Config can also be set in ~/.engram/config.json.

---

API Reference

Authentication

All endpoints