Self-hosted · Local or remote

Set up HYTHE for your agents

Run HYTHE in Docker on your computer, or keep it on a dedicated server that your agents can reach. Each client runs a small MCP bridge and connects to the same memory store under its own identity.

1Choose where your memory lives

Local Docker

Run the server and your clients on one computer. Docker Compose keeps the database in a persistent volume and binds the server to localhost.

Install locally →

Dedicated server

Run the same server on an always-on machine or VPS. Connect clients from multiple computers through an SSH tunnel or protected private network.

Set up a server →

Use one server for agents that need to share memory. A separate local installation is useful for independent work or testing, but it has its own data.

2Start the server

On your chosen host, install Git, Docker with Compose, and Node.js 20.9 or newer. These commands use a POSIX shell, available on Linux, macOS, or Windows through WSL. Client configuration paths must match the operating system where the client runs.

git clone --depth 1 --branch v0.2.0 https://github.com/hythe-dev/hythe.git
cd hythe
node bin/engram-mcp.cjs init --write-env --agent-id agent-a
docker compose -f docker/docker-compose.yml up -d
curl -fsS http://127.0.0.1:6174/ready

Initialization creates a protected credential file. Wait for ready: true and degraded: false; the first startup downloads the embedding model. The installation guide covers readiness, remote connections, and client configuration.

3Connect each client

Agent A → local MCP bridge ─┐
                           ├→ HYTHE server → persistent memory
Agent B → local MCP bridge ─┘

Install the bridge on each client computer. Docker is needed on the server host; a computer that only runs a client needs Node.js and its MCP-compatible application.

Set HYTHE_AGENT_ID to a stable name such as agent-a or agent-b. Set MCP_HOST and MCP_PORT to your chosen server endpoint, and HYTHE_API_KEY_FILE to an absolute path to the protected deployment credential on that client.

For a local server, the endpoint is 127.0.0.1:6174. The remote guide uses an SSH tunnel at 127.0.0.1:16174. All agents sharing a project must reach the same server.

Use the Claude Code and Codex examples, or adapt the same command, arguments, and environment to your MCP client. Client-specific recovery support is described in the client guide.

4Bind identity and session recovery

Give each independently running agent its own identity. Keep that exact value consistent between the MCP bridge and the client's session hooks. A bridge environment variable alone may not make the identity visible to the model.

Install the agent kit for the client you use. Verify startup and post-compaction recovery separately from the connection itself.

HYTHE identity controls memory attribution and inbox selection. Your client controls permissions for tools, files, and commands; connecting HYTHE does not require disabling its permission prompts.

The quickstart begins in observe mode. To enforce each agent's identity on the server, provision a separate agent credential and follow the documented observe → mixed → required rollout in the authorization guide.

5Verify shared memory

Confirm the bridge connects and lists tools. Verify the registered identity with get_agent_status.
Ask agent A to checkpoint a small project such as hello-fleet.
Have A send a handoff to agent B, naming that project.
Have B read its own inbox and resume the same scope. Check that the recorded state and sender match.
Restart a client and test recovery. If the client supports compaction hooks, exercise that path too.

Follow the two-agent tutorial for a complete workflow.

6Keep the installation dependable

Back up the server's database and retain its persistent volume across container upgrades. Follow the backup and restore guide. Client computers connect to that store; copying a live SQLite file between them is not a synchronization mechanism.

If memory appears empty, check the server endpoint and project scope. If identity checks fail, compare the exact bridge and hook identities. If the bridge cannot start, check Node.js, absolute paths, credential-file access, and the explicit executable command in the quickstart.