Usage

Per-harness capabilities

Every harness shares one server, one database, and one capture + consolidation pipeline. What differs is how each one is captured, how it recalls, and how standing identity and lessons reach the agent. Capture is always the watchdog’s job — never the plugin’s.

Identity injection is gated by identityClients (default ["cc"]; CC, Hermes, and OpenClaw all supported). Hermes and OpenClaw scope identity per profile/agent automatically; Claude Code shares one global identity across a user’s machines unless you opt a machine in with agentName. See Identity Layer below and Configuration.

MCP Tools

Your agent has 9 memory tools — via MCP for Claude Code, and in-process in the Hermes and OpenClaw plugins. These are used automatically — you rarely need to invoke them directly.

The /learn Command

Tell your agent to remember something explicitly:

/learn Always use UTC timestamps in this project

This triggers hicortex_ingest with your message. Useful for capturing preferences, decisions, or project-specific knowledge on the spot.

Identity Layer

Alongside auto-distilled memories and lessons, Hicortex holds a hand-edited identity layer — standing "who you are + how to work" Markdown that is injected into every session at start. Unlike memories, it is never distilled, scored, or decayed: what you write stays verbatim until you change it. The recommended starter sections are user (profile / facts) and rules (behavioral rules) — you create them yourself; a fresh install starts empty. Add more by dropping in another *.md file.

Edit it two ways:

• Web editor — open http://localhost:8787/identity/ui: one tab per section, edit, Save.
• CLI (headless boxes) — hicortex identity show [name] prints sections; hicortex identity edit <name> opens the section in $EDITOR and saves on change.

Which harnesses receive the identity block is controlled by identityClients in ~/.hicortex/config.json (default ["cc"]; see Configuration). All three harnesses are supported: Claude Code injects via its SessionStart hook, Hermes via the plugin's system-prompt block, OpenClaw via its agent-start hook. Files live at ~/.hicortex/identity/*.md on the server; delete a section by removing its file there.

Per-agent identity

Each agent served by the same server can have its own identity, in three modes: override (the agent's sections win per section name, the rest falls back to global), global (the shared set — the default), or off (inject nothing). Drop Markdown files into ~/.hicortex/identity/agents/<id>/ on the server and that agent is overridden — no config needed; pin modes explicitly with identityAgents in config (config wins over the drop-in dir and needs a server restart to change).

Hermes and OpenClaw scope per profile/agent automatically. Claude Code is global by default — all your CC machines share one identity; opt a box into its own identity with hicortex init --agent-name <name> (clear with --agent-name ""; hicortex status shows it). Edit any agent's scope via the selector in /identity/ui (inherited sections are dimmed — saving one makes it an override) or hicortex identity show|edit --agent <id>.

Per-prompt memory recall

Session-start injection (lessons + identity, above) covers standing knowledge. Recall is also pushed on every prompt: the server searches memory with your prompt text and injects a compact ## Memory recall (auto) index — one line per relevant memory (id, title, date, domain, type), a menu rather than the meal. The agent lazy-loads full content with hicortex_get only when a memory is actually relevant to the task.

• Turn-based dedup per session — a memory shown once rotates out of the index and may reappear after a configurable number of turns (recallReshowTurns, default 30); next-ranked memories take its place meanwhile. The dedup state resets on a new session and after compaction.
• Quiet by default — short prompts are skipped entirely (recallMinPromptChars), and a prompt with no relevant memories injects nothing. A relevance floor (recallMinSimilarity) keeps weak matches out.

Exposure vs use

Appearing in the index only marks a memory as shown — a mild, temporary strengthen (its decay clock resets while it is topically active). Fetching it with hicortex_get marks it as used — durable strengthening that hardens the memory and shields it from pruning. Memory importance is driven by what agents actually use, not by what was pushed at them. The dashboard’s headline metric — uses-per-showing — tells you whether the memories we surface are the ones agents reach for.

Product-owned memory instructions

The instructions for how agents use their memory ship with the product itself: the server injects a read-only Memory section into the standing identity of every connected harness — the recall index is a menu (hicortex_get fetches), recall before assuming, cite what you use, capture is automatic, and never touch memory infrastructure. Nothing to copy into agent personas or rules files, and the text upgrades with the server, so it can never drift. The section name memory is reserved; disable via memoryInstructions: false.

Built-in provenance

Transparency is part of the mechanism: agents are instructed to cite any memory that shapes their answer (id, date), and every memory fetched with hicortex_get carries a provenance header — id, type, project, origin agent (memories may come from another agent's session), and date. Memory influence is always visible in the transcript at three layers: the injected index block, the visible hicortex_get calls, and the inline citations in the agent's answer.

Claude Code gets all of this via hooks installed by init (UserPromptSubmit injects the index; SessionStart resets the dedup — fail-soft with a 1-second timeout, so a slow or unreachable server never blocks your prompt). The Hermes and OpenClaw plugins call the same server-side logic per turn — with their configured project scoping pushed into every recall, and a fail-soft fallback when the server is unreachable.

Memory analytics dashboard

Open http://localhost:8787/dashboard for a view-only picture of how your agents’ memory is doing. It is read-only — no edits, no approval queues, nothing leaves the server. The dashboard shows:

• Growth over time — memories, lessons, and links, with a nightly snapshot series so you can see how the bank is evolving.
• Domain composition — how your memories distribute across your domains.
• Recall adoption — the headline is uses-per-showing: of the memories Hicortex surfaces, how many do agents actually fetch? A healthy ratio means recall is on target; a low one means the wrong things are being surfaced and the recall knobs may need tuning.
• Nightly digest — the latest consolidation run: how many sessions were captured, how many memories distilled, lessons extracted, links discovered.
• Account & budget — the navigation bar shows your account identity (name, plan) when configured; installs with an LLM token cap get a used-vs-cap gauge for the current period.

The page shell is served without auth (like /viz); all data flows through the auth-gated /dashboard/data JSON endpoint. From a remote browser, paste the auth token into the in-page prompt.

How capture and consolidation work

The core of Hicortex runs on two automatic timers — no cron, no manual scheduling. Together they implement the “dreaming” model: agents experience during the day, distill and consolidate overnight, and wake up wiser.

Incremental capture

Capture tracks a per-session cursor (in ~/.hicortex/capture-cursors.json) and ships only the part of a session it has not seen yet. The delta is split into ordered segments, each POSTed with its own segment_id. The cursor advances only after the server confirms a segment was stored, so a failed segment is retried on the next run rather than lost (dup-over-loss). Multi-day sessions are captured piece by piece as they grow, not all at once.

• hicortex nightly --capture-only — runs capture without consolidation. Safe to run repeatedly; a single-flight lock prevents it colliding with the scheduled run.
• hicortex nightly --recapture-window <days> — recovery: re-discovers sessions that went quiet before you upgraded, by widening the discovery window to the last N days. Run it once after upgrading if older sessions predate the incremental-capture fix.

Backfill commands

Capture only processes what is new. Two commands apply today’s pipeline to everything you already have — useful after upgrading, or after editing your domain list. Both are resumable (safe to interrupt, they continue where they stopped) and run on the server:

• hicortex relink — re-discovers links across the entire corpus, so memories captured before your current version get connected in the knowledge graph. --dry-run previews the counts.
• hicortex classify-domains — files existing memories into your configured domains. By default only unfiled memories are processed; --all reclassifies everything (run it after changing domain names or descriptions).

Backups

Every full consolidation run ends with an automatic backup, and you can take one at any time:

npx @gamaze/hicortex backup

The command produces a single tar.gz artifact: a transactionally-consistent snapshot of everything that is hard to recreate — the memory database (copied through SQLite’s online-backup API, so it is consistent even while the server is running), the full identity layer (global and per-agent), and the capture state (cursors, watermarks). Artifacts land in ~/.hicortex/backups by default. --out <dir> writes into a directory of your choice, and --stdout streams the tarball for piping straight to offsite storage:

npx @gamaze/hicortex backup --stdout | rclone rcat remote:hicortex-backup.tar.gz

To ship artifacts offsite automatically, set backupCommand in ~/.hicortex/config.json (see Configuration) — your command runs with the artifact path as its last argument. A failing hook is logged and never breaks the nightly: the artifact is already on disk.

Restoring is manual by design: stop the server, extract the artifact, replace the files under ~/.hicortex/, start the server. Walk through the drill once on a scratch copy — the first time you restore should not be the first time you have restored.

Multi-Machine Workflow

With server + client mode, multiple machines share a single memory:

1. Server machine: npx @gamaze/hicortex init — runs the database and MCP server
2. Client machines: npx @gamaze/hicortex init --server http://server:8787
3. Each client's nightly denoises sessions locally (no LLM) and POSTs to the server's /distill
4. The server distills, embeds, and stores; raw session content never leaves the client machine
5. All machines query the same shared memory for retrieval

What You Will Notice

Monitoring

Check your server’s memory state:

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

Shows memory count, links, DB size, LLM configuration, and daemon status. For a richer view — growth over time, domain composition, recall adoption — open the analytics dashboard at http://localhost:8787/dashboard.

Next Steps

• API Reference — full REST and MCP tool documentation
• Configuration — customize LLM, auth, and more
• Upgrading — moving from an older version