hythe

本地服务

github.com/hythe-devAI 与智能体08 周前更新

代码仓库

关于 hythe

HYTHE 是面向多 AI 编码 Agent 团队的可自托管 MCP 服务，支持共享状态、跨会话保留上下文和协同工作。它通过冲突可见的检查点与消息生命周期管理协调 Agent。

主要功能

01知识图谱与当前状态解析
02支持冲突分支的检查点与恢复
03直接及基于能力的 Agent 消息
04有界的相关上下文发现
05版本化自适应协调协议

适用场景

01在编码 Agent 间共享当前项目事实
02通过会话检查点恢复工作
03通过 Agent 消息协调代码审查

MCP 相关

HYTHE 通过服务端和 stdio 桥接器向 MCP 客户端提供协调工具与资源，供多个 Agent 共享状态和消息。

配置

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

mcp.json · 通用配置

{
  "mcpServers": {
    "dev-hythe-hythe": {
      "command": "npx",
      "args": [
        "-y",
        "@hythe/mcp"
      ],
      "env": {
        "HYTHE_AGENT_ID": "<HYTHE_AGENT_ID>",
        "HYTHE_AGENT_KEY_FILE": "<HYTHE_AGENT_KEY_FILE>",
        "HYTHE_AGENT_AUTH_MODE": "<HYTHE_AGENT_AUTH_MODE>",
        "API_KEY": "<API_KEY>",
        "MCP_HOST": "<MCP_HOST>",
        "MCP_PORT": "<MCP_PORT>"
      }
    }
  }
}

启动命令npx -y @hythe/mcp

需要配置的环境变量

HYTHE_AGENT_IDStable exact agent identity for this client lane; required so restarts and compaction cannot adopt another principal

HYTHE_AGENT_KEY_FILE密钥Optional path to one protected per-agent credential file: regular, non-symlink, owned by the client user, mode 0400 or 0600, containing one hya1 token. Never place the token itself in an environment variable.

HYTHE_AGENT_AUTH_MODE密钥Client authorization expectation: observe, mixed, or required (default observe). Move to mixed and then required only after this exact lane has a credential and passes /agent/whoami.

API_KEY密钥Shared API key authenticating the bridge to your self-hosted HYTHE server (create a protected .env with: npx -y @hythe/[email protected] init --write-env --agent-id <agent-id>)

MCP_HOSTHYTHE server host (default 127.0.0.1)

MCP_PORTHYTHE server port (default 6174)

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

安装包

npm@hythe/mcp0.2.0stdio

工具

还没有获取到工具列表

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

详细介绍

HYTHE

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

HYTHE 是一款 MCP 服务，可让多个 AI 编码 Agent —— Claude Code、Codex、Cursor、自定义 harness——共享状态、跨会话保留上下文并相互协调。它不是又一个记忆存储。它的差异化特性：

取代机制 + 当前状态解析：观察记录会相互取代（replace-current），而 get_current_observation 会在服务端解析取代链，因此读取者能获取最新的、尚未被取代的状态。冲突处理已实现：checkpoint 是保留分支的 CAS——并发写入者会产生分支，而不是相互覆盖；冲突会以分支头的形式显现，不会被静默解决（已通过契约测试；参见证据台账）。
具备可追踪交付生命周期的 Agent 消息传递：直接发送和基于能力的发送、消息取代、作为共享信号的读取状态、原子化确认 + 归档。（此处描述的是可追踪的生命周期，而非保证送达——这些状态如实反映了服务所知的信息。）
自适应协调协议（ACP）：一种由 ETA 驱动的协调规范，与服务共同演进——发布于 docs/SPEC.md，并附有真实的双 harness 演示教程。

文档

文档	内容
快速入门	从全新机器到两个协同工作的 Agent，约需 15 分钟
概念	一个当前事实、消息生命周期、恢复 / 检查点、诚实的安全模型
检查点 / 恢复 v3	当前分支头指针、协调、记录 / 补丁、v3 读取模型，以及为 v3 之前写入的作用域执行的一次性采用步骤
ACP 规范	协调协议，版本化（1.0.0）
教程	对原始 Engram 部署中一次真实 Claude Code ↔ Codex 审查循环的注释记录
工具兼容性映射	v1 的 20 个工具；每个已弃用工具及其确切替代项
备份与恢复	经过测试的 SQLite 备份 / 恢复 / 压缩运行手册
Agent 凭证操作指南	离线签发、证明、晋级、轮换和撤销
私有残留裁定	对含糊历史行进行哈希绑定、经所有者批准的处置
SQLite 物理清理	逻辑清理后的离线 VACUUM 验证和防覆盖晋级
Pavilion 生产环境	固定版本部署、就绪状态、关闭、金丝雀发布和回滚契约

状态

版本 0.2.0。 此源代码树和软件包定义了经过审核的 0.2.0 版本。版本 0.2.0 保留了 0.1.7 的双重证明 Agent 授权、精确邮箱／私有负载隔离、有界相关上下文发现、延迟 SLO 恢复和离线裁定器，并新增了 checkpoint／resume resultVersion: 3：每个作用域都有明确的当前头指针；reconcile 操作可将活动头折叠为一个保留头，并因果地解决值分歧；采用仅追加的已验证事实／循环版本；读取模型只会提升经已接受的谱系证明的值；并提供针对指针所指头的 record／patch 操作。所有 v1／v2 请求和结果格式均已冻结；v3 按调用选择启用，因此 0.1.7 客户端仍可与 0.2.0 服务端配合使用。依赖树已迁移至 Express 5，解决了两个中等严重程度的 qs 安全公告问题。自 2026-09-05 起，此版本已在参考生产主机上运行。所有 0.2.0 推广配置均固定使用 @hythe/[email protected]；投入生产使用前，请确认软件包注册表返回的正是该版本。前身 @tomcat65/engram-mcp 和 io.github.tomcat65/engram 仍作为兼容性历史版本提供，且永不撤下。请参阅 CHANGELOG.md 和 v3 指南。

内部准则：本文档中的每项声明都必须能追溯到一项测试或测量结果（见下方证据台账）。无法追溯的声明都是 Bug。

证据台账

声明	证据	来源	日期
源码树和完整门禁均通过	源码和干净的已安装软件包门禁覆盖 49 个 Vitest 文件（530 项通过、2 项跳过、6 项明确标记为待办）、107 项迁移检查、43 项发布树检查、31 项 Agent Kit 检查、零生产环境 npm audit 发现、注册表验证，以及隔离的 Docker 启动/就绪状态/MCP/WebSocket/优雅关闭金丝雀测试。	`.github/workflows/ci.yml`、`tests/`、`src/migrations/`、`clients/agent-kit/tests/test-setup.sh`、`scripts/verify-hythe-release-tree.test.mjs`、`scripts/verify-packed-consumer.mjs`	2026-08-14
压缩身份验证失败时默认拒绝	启动和压缩后钩子会拒绝缺失、冲突或无效的身份；桥接程序会在发出任何 HTTP 请求之前，将执行工具和消息资源的接收方绑定到配置的精确通道。	`clients/agent-kit/tests/test-setup.sh`、`tests/contract-bridge-identity.test.ts`	2026-08-13
精确邮箱彼此隔离	Houston/Hythe、大小写变体、显示元数据、旧版身份历史、跨租户投毒、后缀句柄、生命周期变更、取代关系、HTTP 和 ENG-4 作者身份均有负向隔离测试覆盖。	`tests/contract-message-identity-isolation.test.ts`、`tests/contract-eng4-p0.test.ts`	2026-08-13
私密消息正文不会出现在共享图谱界面中	历史、超大、格式错误、别名关联、关系关联、导入、导出、搜索、绘图、记录日志和恢复等负载路径均有测试覆盖；隐藏的子项不会通过计数泄露。	`tests/contract-message-payload-isolation.test.ts`、`tests/contract-data-payload-isolation.test.ts`、`tests/contract-log-confidentiality.test.ts`	2026-08-13
清理过程离线执行，失败时默认拒绝	迁移 007、所有者批准的裁定和物理清理均采用先试运行/制定计划的方式，将执行绑定到已审核的数据库和决策证据，要求经过验证且不会覆盖已有内容的文件，拒绝未解决的保管权问题，并保留回滚状态。	`src/migrations/007-private-message-residue.mjs`、`src/migrations/private-message-residue-adjudication.mjs`、`src/migrations/vacuum-sanitized-database.mjs`、`docs/`	2026-08-14
每个 Agent 的权限由服务端推导	基础密钥证明部署/租户访问权限；独立的受保护文件 `hya1` 凭据证明精确的 Agent 身份。必需模式会拒绝被剥离的证明、身份不匹配、权限范围不足、已撤销凭据和过期的 WebSocket 会话。	`src/agent-auth/`、`tests/contract-agent-auth-foundation.test.ts`、`tests/contract-agent-auth-server.test.ts`、`tests/contract-agent-key-client.test.ts`	2026-08-14
安装和发现界面保持一致	CLI 和注册表界面要求提供精确的通道身份，并且只公开受保护的每个 Agent 专属密钥文件路径和明确的授权模式；通过 HTTP 提供的工具和资源模板与 stdio 桥接路径保持一致。	`tests/contract-cli.test.ts`、`tests/contract-agent-key-client.test.ts`、`tests/contract-mcp-resources-http.test.ts`、`scripts/verify-hythe-release-tree.test.mjs`	2026-08-14
当前头部明确指定，绝不猜测	指针只会从其指向的头部前进；过时的父项会创建分支，而不会成为当前头部；指向非活动快照的指针会默认拒绝；触发器会确保快照行不可变。33 项契约测试。	`tests/contract-eng4-h1-head-pointer.test.ts`	2026-09-03
版本和覆盖范围精确且经过验证	每个台账元组都恰有一个处置结果；启动回填要么全部完成，要么全部不做，并且具备幂等性；双向一致性验证器会在任何行缺失、多余或不匹配时默认拒绝。32 项契约测试。	`tests/contract-eng4-h2-version-foundation.test.ts`	2026-09-03
对账受 CAS 约束且具备因果性	精确的活动头部集合和指针通过比较并交换来验证；每个未保留的头部都会被停用（绝不删除）；分歧值只能通过受约束的接受、拒绝或谱系拒绝来解决；记录与负载绑定，并在重放和读取时重新验证。34 项契约测试。	`tests/contract-eng4-h3-reconcile.test.ts`	2026-09-04
v3 读取模型只提升已验证的值	`currentFacts` / `openLoops` 仅取自带有来源信息、且位于已接受谱系中的已验证版本；其他所有内容都会作为分歧或旧数据纳入统计，并确保覆盖范围完整闭合。29 项契约测试。	`tests/contract-eng4-h4-read-model.test.ts`	2026-09-04
record / patch 无法提升过时状态	只接受指针指向的头部（否则冲突）；状态根据经过哈希验证的负载生成；每次调用只读取每个负载一次；快照资源提供的字节与已验证字节完全一致。21 项契约测试，四轮审查。	`tests/contract-eng4-h5-record-patch.test.ts`	2026-09-04
Express 5 保持 HTTP 契约	无正文或内容类型错误的请求在每条已解析路由上都会像空 JSON 正文一样处理，绝不会导致框架返回 500；生产环境审计未发现任何问题。	`tests/contract-express5-body-contract.test.ts`、`.github/workflows/ci.yml` 运行 33878587010	2026-09-04
先在副本上验证生产迁移	切换之前，已在生产主机上针对生产数据库的副本执行 v3 架构和回填；线上切换耗时 17 s，行数与经过验证的冷备份完全一致。	`docs/PAVILION-PRODUCTION.md`；主机上的操作员日志 `engram-prod/releases/hythe-74a324c-cutover-20260905T005551Z.log`	2026-09-05

v1 功能概览（简短版）

安装（双组件设置）：通过 docker compose up 启动服务，然后为每个 MCP 客户端配置 @hythe/mcp stdio 桥接程序；首次运行向导会将 API 密钥存入受保护的 .env，并打印不含密钥、引用文件的 Claude Code / Codex / Cursor / Claude Desktop 配置；可选在其他为空的数据库中植入带命名空间（demo-*）的演示数据。
知识图谱：实体、观察、关系、取代、当前状态解析、冲突呈现。
相关上下文发现：精确的范围锚定，加上自动的有界向量检索和图路径重排序，并说明当前性、证据和来源；不会隐式写入。
Agent 消息传递：直接、基于能力、可取代；跟踪投递生命周期。
resume / checkpoint：通过一次调用、在预算范围内重新载入会话，并进行闭合覆盖率核算；以 CAS 保护、保留分支的方式捕获结构化状态。使用 resultVersion: 3 时：显式的当前头指针、用于合并各头并解决值分歧的 reconcile、带来源的已验证事实／循环版本，以及针对所指向头的 record / patch——参见 v3 指南。
ACP：作为带版本规范和真实示例的协调协议。

嵌入运行时约定

发布的 npm 包默认不会安装转换器引擎。没有转换器引擎时，HYTHE 仍会提供确定性的 384 维 token-hash 向量和词法排序；它不会下载模型或创建模型缓存。对于明确选择从自己的审计依赖根目录提供转换器引擎的运维人员，@xenova/[email protected] 是可选的对等依赖。

Docker 镜像通过独立且锁定的 /opt/hythe-transformers 运行时，确保语义行为稳定。服务器启动前，启动预检会加载配置的 Xenova/all-MiniLM-L6-v2 q8 模型，并要求生成一个有限值的 384 维嵌入。当 SQLITE_VEC_ALLOW_REMOTE_MODELS=false 时，配置的 SQLITE_VEC_CACHE_DIR 必须已包含该模型。对于已填充的向量索引，不要在转换器嵌入和哈希嵌入之间切换：请保留相同的提供方／模型／维度，或先重建向量索引。