Engram
A self-hosted MCP server enabling multiple AI coding agents to share state, preserve context across sessions, and coordinate with each other.
README
Engram
A coordination bus + shared truth for your agent fleet. Self-hosted, two-component setup: a dockerized server plus a thin stdio bridge for your MCP clients.
Engram is an MCP server that lets multiple AI coding agents — Claude Code, Codex, Cursor, custom harnesses — share state, preserve context across sessions, and coordinate with each other. It is not another memory store. Its differentiators:
- Supersession + current-state resolution: observations supersede each other (
replace-current), andget_current_observationresolves the chain server-side — so readers get the newest non-superseded state. Conflict handling is implemented:checkpointis branch-preserving CAS — concurrent writers branch rather than overwrite, and conflicts surface as heads, never silently resolved (contract-tested; see the evidence ledger). - Agent messaging with a tracked delivery lifecycle: direct and capability-based sends, message supersession, read-state as a shared signal, atomic ack+archive. (Described as tracked lifecycle, not guaranteed delivery — the states are honest about what the server knows.)
- The Adaptive Coordination Protocol (ACP): the ETA-driven coordination discipline that co-evolved with the server — published as docs/SPEC.md with a real two-harness worked tutorial.
Documentation
| Doc | What it covers |
|---|---|
| Quickstart | Clean machine → two coordinating agents in ~15 minutes |
| Concepts | One current truth, messaging lifecycle, resume/checkpoint, honest security model |
| ACP SPEC | The coordination protocol, versioned (1.0.0) |
| Tutorial | Annotated transcript of a real Claude Code ↔ Codex review loop over Engram |
| Tool compatibility map | The 19-tool v1 surface; every retired tool and its exact replacement |
| Backup & restore | Tested SQLite backup/restore/compaction runbook |
Status
Published. @tomcat65/engram-mcp@0.1.0 is live on the npm registry and the source is public at github.com/tomcat65/engram. The install path is contract-tested and was smoke-verified post-publish on a clean machine: npx -y @tomcat65/engram-mcp resolves the bin, and the first-run wizard runs straight from the registry install.
House rule: every claim in these docs must trace to a test or a measurement (see the evidence ledger below). Claims that don't are bugs.
Evidence ledger
| Claim | Evidence | Source | Date |
|---|---|---|---|
| Tree green, full gates | lock-verify (manifest-bound pin matched), clean npm ci, script-integrity, typecheck, build, tests (33 files, 408 passed | 2 skipped | 6 todo), schema-docs, final-tree smoke, docker build — all PASS, exit 0 |
this repository, internal/run-staged-proof.sh |
2026-07-16 |
| Documented env boots the runtime | Final-tree smoke gate: server starts from .env.example variables with a generated key, authenticated MCP request succeeds, DB lands at the documented path, bridge round-trips on the same contract, compose ports are loopback-bound, and the untouched placeholder key fails startup |
this repository, internal/final-tree-smoke.mjs |
2026-07-16 |
| resume/checkpoint + conflict handling implemented | ENG-4 P0 contract suite (120 executable tests: CAS branching, conflict heads, idempotent replay, budget coverage closedness, scope-bound handles) | tests/contract-eng4-p0.test.ts |
2026-07-16 |
| Install path works | CLI contract suite (9 tests: bin mapping, wizard key-gen + parseable configs, .env write-once, live demo round-trip verified server-side, bridge delegation) | tests/contract-cli.test.ts |
2026-07-16 |
| Closed-safe defaults | Placeholder key fails startup; compose ports loopback-bound; CORS grants no cross-origin access unless CORS_ORIGINS is set (tested) |
internal/final-tree-smoke.mjs, tests/contract-cli.test.ts |
2026-07-16 |
| Discovery is truthful | tools/list advertises the exact frozen schemas the handlers implement; retired legacy shapes are schema-rejected (regressions added after an adversarial review caught drift) | tests/contract-eng4-p0.test.ts |
2026-07-16 |
| Published + installable from the registry | npm publish succeeded under 2FA (auth-and-writes, security key); npm view @tomcat65/engram-mcp version → 0.1.0; clean-machine smoke: fresh npx cache, npx -y @tomcat65/engram-mcp --help and … init ran from the registry install |
npm registry, post-publish smoke | 2026-07-16 |
v1 surface (short)
- Install (two-component setup): server via
docker compose up, then the@tomcat65/engram-mcpstdio bridge per MCP client; first-run wizard generates the API key and prints ready-to-paste config for Claude Code / Codex / Cursor / Claude Desktop; optional namespaced (demo-*) demo seed on an otherwise empty DB. - Knowledge graph: entities, observations, relations, supersession, current-state resolution, conflict surfacing.
- Agent messaging: direct, capability-based, superseding; tracked delivery lifecycle.
resume/checkpoint: budgeted one-call session rehydration with closed coverage accounting, and CAS-protected, branch-preserving structured state capture.- ACP: the coordination protocol as a versioned spec + real worked example.
License
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.