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

Related MCP server: samskriti-project

Status

Version 0.1.7. This source tree and package define the reviewed 0.1.7 release. Version 0.1.7 preserves 0.1.6's dual-proof agent authorization, exact-mailbox/private-payload containment, bounded related-context discovery, and latency-SLO recovery. It extends the offline adjudicator with an explicit, hash-bound quarantine_backing_observation disposition for a uniquely proven private-shaped observation that backs an otherwise unresolved vector; ambiguous, cross-tenant, stale, or multiply owned evidence still fails closed. The earlier 0.1.4 candidate is superseded and is not a publish target. All 0.1.7 rollout configurations pin @hythe/mcp@0.1.7; 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.

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.

• 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