{
  "markdown": "# Engram\n\n**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.\n\nEngram 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:\n\n- **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).\n- **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.)\n- **The Adaptive Coordination Protocol (ACP)**: the ETA-driven coordination discipline that co-evolved with the server — published as [docs/SPEC.md](docs/SPEC.md) with a [real two-harness worked tutorial](docs/TUTORIAL.md).\n\n## Documentation\n\n| Doc | What it covers |\n|---|---|\n| [Quickstart](docs/QUICKSTART.md) | Clean machine → two coordinating agents in ~15 minutes |\n| [Concepts](docs/CONCEPTS.md) | One current truth, messaging lifecycle, resume/checkpoint, honest security model |\n| [ACP SPEC](docs/SPEC.md) | The coordination protocol, versioned (1.0.0) |\n| [Tutorial](docs/TUTORIAL.md) | Annotated transcript of a real Claude Code ↔ Codex review loop over Engram |\n| [Tool compatibility map](TOOL-COMPATIBILITY-MAP.md) | The 19-tool v1 surface; every retired tool and its exact replacement |\n| [Backup & restore](BACKUP-AND-RESTORE.md) | Tested SQLite backup/restore/compaction runbook |\n\n## Status\n\n**Published.** `@tomcat65/engram-mcp@0.1.0` is live on the npm registry and the source is public at [github.com/tomcat65/engram](https://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.\n\nHouse 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.\n\n## Evidence ledger\n\n| Claim | Evidence | Source | Date |\n|---|---|---|---|\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n| 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 |\n\n## v1 surface (short)\n\n- **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.\n- **Knowledge graph**: entities, observations, relations, supersession, current-state resolution, conflict surfacing.\n- **Agent messaging**: direct, capability-based, superseding; tracked delivery lifecycle.\n- **`resume` / `checkpoint`**: budgeted one-call session rehydration with closed coverage accounting, and CAS-protected, branch-preserving structured state capture.\n- **ACP**: the coordination protocol as a versioned spec + real worked example.\n\n## License\n\n[Apache-2.0](LICENSE)\n",
  "bytes": 5441,
  "sha": "325a9e46174cf5bda47b711d5af4c0b550ea0ff367fec0a353b7b5df1fd5988e",
  "repo_slug": "tomcat65/engram",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tomcat65_engram_28afcec4/readme"
}