Internal Engineering

System Architecture

Engram is designed from the ground up as a zero-cloud-lock-in, sub-millisecond memory engine. Below is the multi-tier architectural breakdown.

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                    AI AGENT HOSTS                                      │
│  Claude Code  │  Cursor Rules  │  Google Antigravity  │  OpenAI Agents SDK  │  CrewAI   │
└───────────────────────────────────────────┬────────────────────────────────────────────┘
                                            │ MCP Protocol / JSON-RPC / WebSocket / gRPC
┌───────────────────────────────────────────▼────────────────────────────────────────────┐
│                                ENGRAM TRANSPORT LAYER                                  │
│  • MCP stdio Server        • HTTP JSON-RPC 2.0 (/mcp)     • WebSocket Event Subscriptions │
│  • gRPC Transport          • CLI Subcommands (engram-cli) • Python & TypeScript SDKs   │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                              INTELLIGENCE & MEMORY ENGINE                              │
│  • Salience Scoring Engine (Recency, Frequency, Importance & User Feedback)            │
│  • Dynamic Knowledge Graph (Entity Extraction, Bidirectional Edges, Shortest Paths)     │
│  • Identity Alias Resolver (Unifies aliases to canonical identities)                   │
│  • Temporal Contradiction & Conflict Resolution Detector                               │
│  • 5-Component Quality Scorer (Clarity, Completeness, Freshness, Consistency, Trust)    │
│  • Dream Snapshot Review Pipeline (RFC 0007 Candidate Memory Compaction)               │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                 3-WAY HYBRID SEARCH                                    │
│  • BM25 Exact Match (SQLite FTS5)                                                      │
│  • Dense Cosine Vector Embeddings (MiniLM ONNX Runtime / OpenAI / TF-IDF)              │
│  • Fuzzy Levenshtein Matcher (Typo & Morphological Tolerance)                          │
│  • Reciprocal Rank Fusion (RRF Rank Combiner)                                          │
│  • Optional Meilisearch Sync Indexer for Massive Enterprise Catalogs                   │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                              STORAGE & PERSISTENCE LAYER                               │
│  • SQLite 3.45 + WAL (Local-first, sub-millisecond ACID writes)                        │
│  • Strict Workspace Cryptographic Partitioning                                         │
│  • Snapshot Attestation & Optional Cloud Backup Sync (S3 / Cloudflare R2 + AES-256-GCM)│
└────────────────────────────────────────────────────────────────────────────────────────┘

Layer 1: Storage & Durability

SQLite + WAL Local-First Engine

All state is written to SQLite in Write-Ahead Logging (WAL) mode, guaranteeing zero-latency reads and atomic multi-memory transactions. For distributed teams and backup durability, Engram provides optional continuous S3/R2 snapshot attestation with AES-256-GCM client-side encryption.

Property	Specification
Storage Engine	SQLite 3.45 with WAL, foreign keys, and normalized schema
Concurrency	Lock-free concurrent readers, single writer with connection pooling
Snapshot Encryption	AES-256-GCM authenticated encryption before S3/R2 upload

Layer 2: Retrieval

3-Way Hybrid Search with Reciprocal Rank Fusion

Pure vector search often misses exact symbols, variable names, or acronyms, while pure keyword search fails on semantic phrasing. Engram fuses three distinct scoring streams:

BM25 Engine (FTS5): Full-text keyword search indexed immediately on write.
Dense Vectors & HNSW Index: 384-dimensional dense vectors with Hierarchical Navigable Small World (HNSW) graph indexing and SIMD 8-lane loop unrolling.
Fuzzy Matcher: Levenshtein distance matching for typos and varied inflections.
RRF (Reciprocal Rank Fusion): Combines ordinal ranks with configurable k-constant weighting.

RFC 0005: Vector Acceleration

SIMD Vector Math & HNSW In-Memory Graph Indexing

For sub-millisecond semantic retrieval across hundreds of thousands of memories, Engram utilizes a dedicated in-memory Hierarchical Navigable Small World (HNSW) graph index:

Subsystem	Specification & Guarantees
SIMD Unrolling	8-lane unrolled vectorized loops for Cosine, Euclidean distance, Dot product, and L2 normalization
Graph Traversal	Logarithmic \(O(\log N)\) multi-layer skip-list descent with configurable \(ef_{\text{construction}}\) and \(ef_{\text{search}}\) beam search
Persistence & Checkpointing	Compact binary serialization with Adler-32 checksums, stored in SQLite `hnsw_checkpoints` (Migration v47)
Warm-Restarts	Instant \(O(1)\) snapshot restoration on server startup with automatic \(O(\Delta N)\) incremental catch-up for new memories

Layer 3: Cognitive Architecture

Knowledge Graph, Identity Resolution & Salience Decay

Engram extracts named entities upon memory creation and maps relationship edges between memories. Different terms for the same concept (e.g. auth_service, idp-gateway, AuthServer) are unified under canonical identities with alias resolution. Ephemeral memories decay over time using exponential halflife equations, while permanent decisions remain invariant.

Layer 4: Protocol & Privacy

Model Context Protocol (MCP) & Strict Boundaries

Engram implements Model Context Protocol specification over standard input/output (stdio) and HTTP JSON-RPC 2.0 (/mcp). All network listeners bind to 127.0.0.1 by default. WebSocket connections enforce origin validation and token authorization to prevent Cross-Site WebSocket Hijacking (CSWSH).