Installation

Single machine

One command sets everything up: detects available LLM candidates (Ollama models, Claude CLI, API keys), presents a numbered list, asks you to choose, then installs the daemon and registers with Claude Code.

npx @gamaze/hicortex init

What init does:

• Creates ~/.hicortex/config.json with your LLM choice and a generated auth token
• Scaffolds five editable default memory domains (Work, Personal, People, Health, Finance) — edit them to match your world, see Domains. An existing domain list is never overwritten
• Installs and starts the MCP server daemon (launchd on macOS, systemd on Linux) on port 8787
• Registers the MCP server with Claude Code
• Installs a CC SessionStart hook that injects lessons into context at session start
• Schedules the nightly pipeline (capture → distill → consolidate → inject)

Verify the server is running:

npx @gamaze/hicortex status
curl http://localhost:8787/health

Your auth token is printed once during init and shown by hicortex status. Keep it — you will need it if you later connect additional machines.

Team (self-hosted server)

One machine runs the server with the shared database. All other machines are clients — they denoise sessions locally (no LLM needed) and POST to the server, which handles distillation, embedding, and consolidation.

1. Set up the server machine

Run init as above on the machine that will host the database. After setup, get the auth token:

npx @gamaze/hicortex status

Note the Auth token shown in the output — you will enter it on each client.

2. Connect client machines

On every other machine:

npx @gamaze/hicortex init --server http://<server-host>:8787

init will prompt for the server's auth token. No local LLM, database, or embedding model is needed on clients. The client nightly denoises sessions locally (strip tool noise, truncate bulk output — no LLM) and POSTs the denoised text to POST /distill on the server. Raw session content never leaves the machine.

All machines query the same shared memory for retrieval. The MCP tools work transparently.

Harness plugins

The core server and nightly pipeline are harness-independent. The harness-specific setup connects the agent to the running server for recall (search + lesson injection). Capture is always handled by the nightly pipeline reading each harness's own session store — not the plugin.

Hermes

Hermes uses a Python recall-only plugin. The plugin injects lessons into the system prompt at session start and exposes the full Hicortex tool set in-process (search, context, lessons, index, graph and more). Capture is handled by the nightly pipeline reading each profile's state.db.

# Install the plugin
hermes plugins install gamaze-labs/hicortex-hermes-plugin

# Activate it for a profile — select "hicortex" when prompted
hermes memory setup

# Restart the gateway to load it
hermes gateway restart

OpenClaw

OpenClaw requires a running Hicortex server on the same machine (or accessible via network). The OC plugin is a recall-only adapter — it does not capture sessions itself. Capture is handled by the nightly pipeline reading OpenClaw session files (~/.openclaw/agents/*/sessions/) alongside Hermes and CC sessions.

# 1. Set up the Hicortex server (once, on the machine running OC)
npx @gamaze/hicortex init

# 2. Install the plugin
openclaw plugins install @gamaze/hicortex
openclaw gateway restart

The plugin connects to http://127.0.0.1:8787 by default. For a remote server, add serverUrl and authToken to the plugin entry in ~/.openclaw/openclaw.json. Find the auth token with hicortex status on the server machine.

Claude Code

Handled automatically by npx @gamaze/hicortex init. The installer registers the MCP server and installs a SessionStart hook that fetches fresh lessons from the server at session start. Nothing else to configure.

Uninstall

npx @gamaze/hicortex uninstall        # Claude Code
openclaw plugins uninstall hicortex  # OpenClaw

Database and config are preserved by default. To remove all data:

rm -rf ~/.hicortex