foreigndmitryi/engram repository overview

⁠Engram — Persistent Knowledge Base MCP Server

Engram is a self-hosted Model Context Protocol⁠ server that gives AI agents persistent memory across sessions and projects. Markdown files as source of truth, hybrid keyword + semantic search, typed graph relations.

GitHub: veronchenko/engram-memory⁠ · Website: veronchenko.github.io/engram-memory⁠

⁠Concept

Agent conversations end and take their context with them. Engram is the piece that survives: a knowledge base an agent searches before acting and writes to after resolving something non-obvious, so the next session — same project or a different one — starts with what was already learned instead of re-deriving it.

It deliberately stores zero discoverable information. If a fact can be pulled from code, git history, config files, or existing docs, it does not belong in Engram. What belongs is the kind of knowledge a conversation would otherwise lose: a decision and the alternatives it ruled out, a bug's root cause and fix, a procedure learned the hard way, a preference stated once that should hold from then on.

⁠Features

• Hybrid search — SQLite FTS5 (BM25, Porter stemming) fused with cosine similarity over local Model2Vec embeddings via Reciprocal Rank Fusion; finds entries by meaning or by literal proper noun, zero cloud dependency
• Typed graph relations — kb://uuid#type links between entries, resolved both directions (outgoing + backlinks) on every recall
• Schema-enforced entry types — hub, decision, diagnostic, feature, procedure, integration, pattern, snippet, preference, idea — declared in schema.json, exposed to the client as an enum
• doctor integrity pass — schema-driven check over the Markdown files for dangling links, undeclared types, missing template fields
• Bi-temporal versioning — remember(..., supersede=True) creates a new version instead of overwriting; old versions stay in history
• Duplicate detection & link suggestions — remember matches near-identical titles and returns embedding-similarity suggested_links
• Web dashboard — force-directed graph view, hybrid search, and a CRUD panel over the same knowledge base
• Three transports — stdio (agent-managed), SSE, streamable-http — one local agent or a shared multi-agent deployment
• Markdown as source of truth — the SQLite index is a rebuildable cache; delete it and rebuild, no data is ever lost

⁠Quick Start

⁠stdio

Your agent manages the server. Recommended for Claude Code, ChatGPT Desktop, Cursor.

claude mcp add --transport stdio engram -- \
  docker run -i --rm -v ./knowledge:/knowledge foreigndmitryi/engram

⁠SSE

Persistent server on the network. Share knowledge across multiple agents.

docker run -d --name engram \
  -p 8192 \
  -v ./knowledge:/knowledge \
  foreigndmitryi/engram --transport sse

docker port engram 8192   # host port Docker assigned
claude mcp add --transport sse engram http://your-host:<port>/sse

⁠HTTP

Stateless, load-balanceable.

docker run -d --name engram \
  -p 8192 \
  -v ./knowledge:/knowledge \
  foreigndmitryi/engram --transport streamable-http

docker port engram 8192
claude mcp add --transport http engram http://your-host:<port>/mcp

⁠Tools

⁠Configuration

All options have ENGRAM_* environment variable fallbacks. CLI args take priority.

See the full README⁠ for multi-tenant setup, the dashboard, benchmark results against a plain Markdown wiki, and comparison with Mem0/Zep-Graphiti/LangMem.

⁠License

MIT⁠