engram

English | Русский | 中文

Engram

Persistent shared memory infrastructure for AI coding agents.

AI coding agents forget everything between sessions. Every new conversation starts from zero — past decisions, bug fixes, architectural choices, and learned patterns are lost. You waste time re-explaining context, and agents repeat the same mistakes.

Engram fixes this. It captures observations from coding sessions, stores them in PostgreSQL with vector embeddings, and automatically injects relevant memories into new sessions. One server, multiple workstations, zero context loss.

7 consolidated MCP tools replace 61 legacy tools, cutting context window usage by over 80%. Hybrid search combines full-text, vector similarity, and BM25 with cross-encoder reranking to surface exactly the memories that matter.

---

What's New in v2.4.0

Version	Highlight
v2.4.0	LLM-Driven Memory Extraction — store(action="extract") from raw content (ADR-005)
v2.3.1	Embedding Resilience Layer — 4-state circuit breaker with auto-recovery (ADR-004)
v2.3.0	Reasoning Traces / System 2 Memory — structured reasoning chains with quality scores (ADR-003)
v2.2.0	Server-side periodic summarizer — no client dependency for consolidation
v2.1.6	Knowledge graph UX — local mode, search, visual styling
v2.1.4	Config hot-reload without restart
v2.1.2	User commands — /retro, /stats, /cleanup, /export
v2.1.0	MCP tool consolidation — 61 to 7 primary tools, >80% context window reduction

See Releases for full changelog.

---

Architecture

Single server on port 37777 serves the HTTP REST API, MCP transports, Vue 3 dashboard, and background workers. Multiple workstations connect via hooks and the MCP plugin.

graph TB
    subgraph "Workstation A"
        CC_A[Claude Code]
        H_A[Hooks + MCP Plugin]
        CC_A --> H_A
    end

    subgraph "Workstation B"
        CC_B[Claude Code]
        H_B[Hooks + MCP Plugin]
        CC_B --> H_B
    end

    H_A -- "Streamable HTTP / SSE" --> Server
    H_B -- "Streamable HTTP / SSE" --> Server

    subgraph "Engram Server :37777"
        Server[Worker]
        Server --> |HTTP API| API[REST Endpoints]
        Server --> |MCP| MCP_T["SSE + Streamable HTTP"]
        Server --> |Web| Dash["Vue 3 Dashboard"]
        Server --> |Background| BG["Summarizer + Insights"]
    end

    Server --> PG[(PostgreSQL 17\n+ pgvector)]
    Server -.-> LLM["LLM API\n(extraction/summarization)"]
    Server -.-> EMB["Embedding API"]
    Server -.-> RR["Reranker API"]

Server (Docker on remote host / Unraid / NAS):

• PostgreSQL 17 with pgvector (HNSW cosine index)
• Worker — HTTP API, MCP SSE, MCP Streamable HTTP (POST /mcp), Vue 3 dashboard, consolidation scheduler, periodic summarizer

Client (each workstation):

• Hooks — capture observations from Claude Code sessions (11 lifecycle hooks)
• MCP Plugin — connects Claude Code to the remote server
• Slash commands — /retro, /stats, /cleanup, /export, /setup, /doctor, /restart

---

Features

Search and Retrieve

• Hybrid search — tsvector full-text + pgvector cosine similarity + BM25, fused with Reciprocal Rank Fusion
• Cross-encoder reranking — API-based reranker for precision
• HyDE query expansion — hypothetical document embeddings for better recall
• Knowledge graph — 17 relation types, optional FalkorDB backend, visual explorer
• Preset queries — decisions, changes, how_it_works for common lookups

Store and Organize

• LLM-driven extraction — feed raw content, get structured observations (ADR-005)
• Reasoning traces — System 2 Memory with structured chains and quality scores (ADR-003)
• Versioned documents — collections with history, comments, and semantic search
• Encrypted vault — AES-256-GCM credential storage with scoped access
• Observation merging — deduplicate and consolidate related memories