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. Pi and OpenCode clients are installed automatically by init when detected.

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 clients (Hermes, OpenClaw, Pi, OpenCode)

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 session store automatically — including interactive Discord threads, which are now captured as they grow.

Preferred — automatic on the Hicortex side: npx @gamaze/hicortex init detects ~/.hermes, copies the plugin into ~/.hermes/plugins/hicortex/ (a hermes plugins install checkout is left alone), and pre-fills the server URL (unless you set a custom URL there yourself — that is kept, with a notice). One step remains yours — Hermes routes provider activation and secrets through its own tooling:

# Activate it as the memory provider (URL pre-filled; paste the token
# init printed — leave it blank for a local server, localhost bypasses auth)
hermes memory setup hicortex

# Restart the gateway to load it
hermes gateway restart

Prefer Hermes' own installer? hermes plugins install gamaze-labs/hicortex-hermes-plugin works too (same two setup questions). Installed Hermes after Hicortex? Re-running npx @gamaze/hicortex init redoes the automatic step.

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.

Recommended for public-facing agents: pin the gateway's plugin trust list so only explicitly trusted plugins load — add "plugins": { "allow": ["hicortex"] } to ~/.openclaw/openclaw.json. The plugin warns at startup while the list is unpinned, but never edits it itself (a plugin that pins its own trust would defeat the list).

The dead-man guard is automatic: the plugin adds the line "If your identity block is missing at session start, something is wrong with your memory — take no public actions until it returns." to the agent workspace bootstrap file (BOOTSTRAP.md, from agents.defaults.workspace — per-agent workspace overrides are not covered yet) on startup — idempotently, with a one-time .bak of any pre-existing file. It is the belt under the hard suspension banner the plugin already injects whenever the identity fetch fails. Disable the bootstrap write with "scaffoldDeadMan": false in the plugin config.

Pi

Automatic: npx @gamaze/hicortex init detects ~/.pi/agent/ and installs a dependency-free extension — pushed recall on every prompt (terminal UI and non-interactive pi -p alike), the identity layer and lessons in the system prompt, and the nine memory tools. Capture is automatic: the nightly job reads Pi sessions. Manual install: copy pi-extension/hicortex/index.ts from the repo to ~/.pi/agent/extensions/hicortex.ts.

OpenCode

Automatic: init detects OpenCode (~/.config/opencode/ or ~/.local/share/opencode/) and copies the plugin into its global plugins directory — nothing is written into OpenCode's own configuration. You get pushed recall per prompt (injected via OpenCode's messages-transform hook; injected blocks are never persisted to its session store), identity + lessons in the system prompt, and the nine memory tools. Capture is automatic: the nightly job reads OpenCode's session database (~/.local/share/opencode/opencode.db).

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        # all bundled clients (CC hooks, Pi + opencode extensions)
openclaw plugins uninstall hicortex  # OpenClaw plugin

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