engram

Name: engram
Author: tomcat65

本地服务

github.com/tomcat65AI 与智能体015 周前更新

代码仓库

关于 engram

Engram 是面向多个 AI 编码 Agent 的可自托管协调服务，用于共享状态、延续会话上下文并相互通信。它结合当前状态解析、分支保留的冲突处理和带跟踪状态的消息流程。

主要功能

01共享实体、观察记录与关系
02解析被后续记录替代的状态
03以分支方式呈现并发冲突
04支持直接和能力式消息
05预算受限的会话恢复与检查点

适用场景

01让多个编码 Agent 共享项目状态
02在不同会话间恢复工作上下文
03协调 Agent 间的评审与消息
04保留并发状态更新产生的冲突分支

MCP 相关

Engram 是 MCP 服务，提供供多个 AI 编码 Agent 使用的共享状态和消息工具。部署由 Docker 服务端及面向 MCP 客户端的 stdio bridge 组成。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y @tomcat65/engram-mcp

需要配置的环境变量

API_KEY密钥Shared 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)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@tomcat65/engram-mcp0.1.2stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Engram

为你的 Agent 集群提供协调总线和共享事实。 可自托管，采用双组件设置：一个 Docker 化服务，以及一个供 MCP 客户端使用的轻量 stdio 桥接程序。

Engram 是一款 MCP 服务，可让多个 AI 编码 Agent（Claude Code、Codex、Cursor、自定义执行框架）共享状态、保留跨会话上下文，并相互协调。它不是又一个记忆存储。其差异化特性包括：

取代机制 + 当前状态解析：观察结果可以相互取代（replace-current），而 get_current_observation 会在服务端解析取代链，因此读取者能获取最新的未被取代状态。冲突处理已实现：checkpoint 是保留分支的 CAS——并发写入者会创建分支，而非相互覆盖；冲突会作为头节点呈现，绝不会被静默解决（已通过契约测试；参见证据台账）。
具有可跟踪交付生命周期的 Agent 消息传递：直接发送和基于能力的发送、消息取代、作为共享信号的读取状态、原子确认 + 归档。（描述为可跟踪的生命周期，而非保证交付——这些状态如实反映服务端掌握的信息。）
自适应协调协议（ACP）：与服务共同演进、由预计完成时间（ETA）驱动的协调规范——已发布于 docs/SPEC.md，并附有一份真实的双执行框架实操教程。

文档

文档	内容
快速入门	从全新机器开始 → 约 15 分钟内启动两个协作的 Agent
概念	单一当前事实、消息生命周期、恢复/检查点、真实可信的安全模型
ACP 规范	协调协议，版本为 1.0.0
教程	Engram 上 Claude Code ↔ Codex 审查循环的真实对话记录及注释
工具兼容性映射表	v1 的 19 个工具；每个已弃用工具及其确切替代项
备份与恢复	经过测试的 SQLite 备份/恢复/压缩操作手册

状态

已发布。 @tomcat65/[email protected] 已在 npm 注册表上线，源代码公开于 github.com/tomcat65/engram。安装流程已通过契约测试，并在发布后于全新机器上完成冒烟验证：npx -y @tomcat65/engram-mcp 能解析可执行文件，首次运行向导可直接通过注册表安装启动。

约定：文档中的每项声明都必须能追溯到测试或测量结果（见下方证据台账）。无法追溯的声明都是缺陷。

证据台账

声明	证据	来源	日期
工作树干净，所有门禁均通过	lock-verify（与清单绑定的固定版本匹配）、干净的 `npm ci`、脚本完整性检查、类型检查、构建、测试（33 个文件，408 项通过 \| 2 项跳过 \| 6 项待办）、schema-docs、最终工作树冒烟测试、docker build —— 全部通过，退出代码为 0	本仓库，`internal/run-staged-proof.sh`	2026-07-16
文档所述环境变量可启动运行时	最终工作树冒烟测试门禁：服务器使用 `.env.example` 中的变量和生成的密钥启动；通过身份验证的 MCP 请求成功；数据库写入文档所述路径；桥接在相同契约上完成往返；compose 端口绑定到回环地址；未修改的占位密钥会导致启动失败	本仓库，`internal/final-tree-smoke.mjs`	2026-07-16
已实现 resume/checkpoint 和冲突处理	ENG-4 P0 契约测试套件（120 项可执行测试：CAS 分支、冲突头、幂等重放、预算覆盖闭合性、作用域绑定句柄）	`tests/contract-eng4-p0.test.ts`	2026-07-16
安装流程正常	CLI 契约测试套件（9 项测试：二进制映射、向导密钥生成与可解析配置、仅写入一次的 .env、经服务器端验证的在线演示往返、桥接委派）	`tests/contract-cli.test.ts`	2026-07-16
安全闭合的默认设置	占位密钥会导致启动失败；compose 端口绑定到回环地址；除非设置 `CORS_ORIGINS`，否则 CORS 不授予任何跨源访问权限（已测试）	`internal/final-tree-smoke.mjs`、`tests/contract-cli.test.ts`	2026-07-16
发现信息真实准确	tools/list 公布的正是处理程序所实现的冻结架构；已退役的旧版结构会被架构拒绝（对抗性审查发现偏差后添加了回归测试）	`tests/contract-eng4-p0.test.ts`	2026-07-16
已发布并可从注册表安装	在双因素身份验证（身份验证与写入、密钥）下，`npm publish` 成功；`npm view @tomcat65/engram-mcp version` → `0.1.0`；干净机器冒烟测试：使用全新的 npx 缓存，`npx -y @tomcat65/engram-mcp --help` 和 `… init` 均从注册表安装后运行	npm 注册表，发布后冒烟测试	2026-07-16

v1 功能概览（简版）

安装（双组件设置）：通过 docker compose up 启动服务，然后为每个 MCP 客户端配置 @tomcat65/engram-mcp stdio 桥接；首次运行向导会生成 API 密钥，并输出可直接粘贴到 Claude Code / Codex / Cursor / Claude Desktop 的配置；还可选择在空数据库中植入带命名空间（demo-*）的演示数据。
知识图谱：实体、观察、关系、取代、当前状态解析、冲突呈现。
Agent 消息：直接、基于能力、可取代；跟踪投递生命周期。
resume / checkpoint：通过一次调用完成带预算的会话重新水合，并进行闭合覆盖核算；通过 CAS 保护、保留分支的结构化状态捕获。
ACP：以版本化规范和真实示例呈现的协调协议。