Hythe

HYTHE

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.

HYTHE 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

Status

Version 0.2.0. This source tree and package define the reviewed 0.2.0 release. Version 0.2.0 preserves 0.1.7's dual-proof agent authorization, exact-mailbox/private-payload containment, bounded related-context discovery, latency-SLO recovery and the offline adjudicator, and adds checkpoint / resume resultVersion: 3: an explicit current-head pointer per scope, a reconcile operation that folds live heads into one survivor and resolves divergent values causally, append-only verified fact/loop versions, a read model that only promotes values proven on the accepted lineage, and record / patch operations on the pointed head. Every v1 / v2 request and result shape is frozen; v3 is opt-in per call, so a 0.1.7 client keeps working against a 0.2.0 server. The dependency tree moved to Express 5, clearing two moderate qs advisories. This release runs on the reference production host since 2026-09-05. All 0.2.0 rollout configurations pin @hythe/mcp@0.2.0; verify that the registry returns that exact version before production use. The predecessor @tomcat65/engram-mcp and io.github.tomcat65/engram remain available as compatibility history and are never unpublished. See CHANGELOG.md and the v3 guide.

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

v1 surface (short)

• Install (two-component setup): server via docker compose up, then the @hythe/mcp stdio bridge per MCP client; first-run wizard stores the API key in a protected .env and prints secret-free file-referencing 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.
• Related-context discovery: exact scope anchoring plus automatic bounded vector retrieval and graph-path reranking, with currentness/evidence/provenance explanations and no implicit writes.
• 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. With resultVersion: 3: an explicit current-head pointer, reconcile to fold heads and resolve divergent values, verified fact/loop versions with provenance, and record / patch on the pointed head — see the v3 guide.
• ACP: the coordination protocol as a versioned spec + real worked example.

Embedding runtime contract

The published npm package does not install a transformer engine by default. Without one, HYTHE still provides deterministic 384-dimension token-hash vectors plus lexical ranking; it does not download a model or create a model cache. @xenova/transformers@2.17.2 is an optional peer for operators who deliberately provide it from their own audited dependency root.

The Docker image keeps semantic behavior stable through a separate, locked /opt/hythe-transformers runtime. Its startup preflight loads the configured Xenova/all-MiniLM-L6-v2 q8 model and requires one finite 384-dimension embedding before the server starts. When SQLITE_VEC_ALLOW_REMOTE_MODELS=false, the configured SQLITE_VEC_CACHE_DIR must already contain that model. Do not switch between transformer and hash embeddings on a populated vector index: retain the same provider/model/dimensions or rebuild the vector index first.

License

Apache-2.0