Installation

Get your agents learning in five minutes

Hicortex gives your agents a shared long-term memory. They capture what happens during the day, distill it into memories and lessons overnight, and recall the right thing at the right moment — automatically. This page walks you through the setup that fits your situation.

Requirements: Node.js 20+ (22 recommended). Server mode also needs an LLM — Ollama with a 9B+ model is recommended (private, runs locally); a Claude CLI or any OpenAI-compatible API key works too. Client mode needs nothing but network access to your server.

Choose your setup

Most users start with single-machine mode on one computer. If you want multiple machines (a desktop and a laptop, or a fleet of agents) to share one brain, use multi-machine mode. If you run Hermes or OpenClaw, add the matching plugin.

Single machine

One command does everything: detects the LLMs available on your machine (Ollama models, the Claude CLI, API keys in your environment), shows you a numbered list, and asks you to pick. Then it installs the memory server, registers the memory tools with your agent, and schedules automatic capture and consolidation.

npx @gamaze/hicortex init

What init does for you:

  • Creates ~/.hicortex/config.json with your LLM choice and a generated auth token
  • Scaffolds five editable default memory domains (Work, Personal, People, Health, Finance) — a starting point, edit them to match your world; an existing list is never overwritten
  • Installs and starts the memory server (launchd on macOS, systemd on Linux) on port 8787
  • Registers the memory tools with Claude Code and verifies the connection (claude mcp list)
  • Installs a Claude Code SessionStart hook so fresh lessons reach the agent at the start of every session
  • Schedules the capture watchdog and the consolidation timer (see below) — no cron setup, no manual scheduling

Verify the server is running:

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

After restarting Claude Code, confirm the memory tools are connected:

claude mcp list        # hicortex should show ✓ Connected

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

Multi-machine (one shared brain)

One machine runs the server and owns the shared memory database. Every other machine is a client: it denoises its own sessions locally (no LLM needed) and ships only the cleaned conversation text to the server, which does the heavy lifting — distillation, embedding, scoring. Raw session content never leaves the machine it was created on.

1. Set up the server machine

Run init on the machine that will host the shared database:

npx @gamaze/hicortex init

Then grab the auth token clients will need:

npx @gamaze/hicortex status

Note the Auth token shown in the output.

2. Connect each client machine

On every other machine:

npx @gamaze/hicortex init --server https://your-server.example.com:8787

init prompts for the server’s auth token and registers the memory tools against the remote server. No local database, LLM, or embedding model is installed on clients — the client is set up entirely via npx.

All machines now query the same shared memory. The MCP tools work transparently; your agents cannot tell the difference between local and remote.

What runs automatically (no cron)

Hicortex works in the background without any scheduling on your part. init installs two timers that handle everything:

Capture watchdog (every machine)

A short timer fires roughly every 20 minutes and asks: is there anything new to capture, and can I reach the server? When both are true and enough time has passed since the last capture (default 6 hours — about 4 captures per day), it denoises the new sessions and ships them to the server. If the server is briefly unreachable (a laptop that just woke and whose network has not reconnected yet), it retries in minutes instead of skipping a whole day. Tunable via captureCooldownHours.

Consolidation (server only)

Twice a day, at fixed local-hour slots (default [10, 22]), the server runs the full “dreaming” pass: it distills captured sessions into memories, scores importance, extracts lessons, links related memories, files everything into your domains, and prunes what has faded. Clients do not run this — only the machine that owns the database. Tunable via consolidationHours.

Prefer a single daily slot? If consolidationHours is absent, Hicortex honors the legacy nightlyHour as one daily consolidation slot. New installs use the two-slot default.

Harness plugins (Hermes and OpenClaw)

The memory server and capture pipeline are harness-agnostic. The harness-specific plugins connect a particular agent to the running server for recall — per-prompt memory injection, lessons at session start, and the full memory toolset. Capture is always handled by the capture watchdog reading each harness’s own session store, never by the plugin.

Hermes

The Hermes plugin injects a compact memory index into every turn, fresh lessons into the system prompt, and exposes the full memory tool surface in-process. The capture watchdog reads each Hermes profile’s state.db automatically — including interactive Discord threads, which are now captured as they grow.

# Install the plugin (prompts for server URL + auth token; leave empty for a local server)
hermes plugins install gamaze-labs/hicortex-hermes-plugin

# Activate it as the memory provider
hermes memory setup hicortex

# Restart the gateway to load it
hermes gateway restart

OpenClaw

OpenClaw requires a running Hicortex server on the same machine (or reachable over the network). The plugin is a recall-only adapter. The capture watchdog reads OpenClaw session files (~/.openclaw/agents/*/sessions/) alongside any Claude Code or Hermes sessions on the same box.

# 1. Start the Hicortex server (once, on the machine running OpenClaw)
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 memory tools and installs hooks that inject lessons at session start and a memory index on every prompt. 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

Next steps

  • Configuration — LLM, scheduling, recall tuning, and the full config reference
  • Usage — how recall, capture, and the dashboard work day to day
  • Domains — define the knowledge spheres Hicortex files into