engram

Name: engram
Author: tomcat65

Local

github.com/tomcat65AI & Agents0Updated 15w ago

Repository

About engram

Engram is a self-hosted coordination service for fleets of AI coding agents to share state, carry context across sessions, and communicate. It combines current-state resolution, branch-preserving conflict handling, and tracked message lifecycles.

Key features

01Share entities, observations, and relations
02Resolve superseded observations to current state
03Preserve concurrent conflicts as branches
04Send direct and capability-based messages
05Budgeted session resume and checkpoint

Use cases

01Share project state across coding agents
02Restore work context across sessions
03Coordinate reviews and messages between agents
04Retain conflict branches from concurrent updates

MCP support

Engram is an MCP server that provides shared state and messaging tools for multiple AI coding agents. It uses a Dockerized server and a stdio bridge for MCP clients.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "tomcat65-engram": {
      "command": "npx",
      "args": [
        "-y",
        "@tomcat65/engram-mcp"
      ],
      "env": {
        "API_KEY": "<API_KEY>",
        "MCP_HOST": "<MCP_HOST>",
        "MCP_PORT": "<MCP_PORT>"
      }
    }
  }
}

Run commandnpx -y @tomcat65/engram-mcp

Environment variables to set

API_KEYSecretShared API key authenticating the bridge to your self-hosted Engram server (generate with: npx -y @tomcat65/engram-mcp init)

MCP_HOSTEngram server host (default 127.0.0.1)

MCP_PORTEngram server port (default 6174)

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

npm@tomcat65/engram-mcp0.1.2stdio

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project 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), and get_current_observation resolves the chain server-side — so readers get the newest non-superseded state. Conflict handling is implemented: checkpoint is 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/[email protected] 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-mcp stdio 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

Apache-2.0

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.