Usage

Per-harness capabilities

Every harness shares one server, one database, and one nightly pipeline. What differs is how each one is captured, how it recalls, and how standing context and lessons reach the agent. Capture is always the nightly reader's job — never the plugin's.

Context injection is gated by contextClients (default ["cc"]; all three of CC/Hermes/OpenClaw supported since 0.13). Hermes and OpenClaw scope context per profile/agent automatically; Claude Code shares one global context across a user's machines unless you opt a machine in with agentName. See Context Layer below and Configuration.

MCP Tools

Your agent has 9 memory tools — via MCP for Claude Code, and in-process in the plugins (Hermes 0.7.0; OpenClaw since package 0.14.3). 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.

Context Layer

Alongside auto-distilled memories and lessons, Hicortex holds a hand-edited context 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/context/ui: one tab per section, edit, Save.
• CLI (headless boxes) — hicortex context show [name] prints sections; hicortex context edit <name> opens the section in $EDITOR and saves on change.

Which harnesses receive the context block is controlled by contextClients in ~/.hicortex/config.json (default ["cc"]; see Configuration). Since 0.13 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/context/*.md on the server; delete a section by removing its file there.

Per-agent context (0.13)

Each agent served by the same server can have its own context, 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/context/agents/<id>/ on the server and that agent is overridden — no config needed; pin modes explicitly with contextAgents 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 context; 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 /context/ui (inherited sections are dimmed — saving one makes it an override) or hicortex context show|edit --agent <id>.

Per-prompt memory recall (0.14)

Session-start injection (lessons + context, above) covers standing knowledge. Since 0.14 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.

Product-owned memory instructions (0.14.4)

The instructions for how agents use their memory ship with the product itself: the server injects a read-only Memory section into the standing context 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 (0.14.1)

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 plugin (0.7.0) and the OpenClaw plugin (package 0.14.3) call the same server-side logic per turn — with their configured privacy/project scoping pushed into every recall, and a fail-soft fallback when the server predates 0.14.

Nightly Pipeline

The core of Hicortex. Every night (3 AM by default on the server), the daemon runs an automated pipeline:

Incremental capture

Since 0.13.2, capture tracks a per-session cursor (in ~/.hicortex/capture-cursors.json) and each night 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). This fixes the earlier behavior where a long-running session was captured whole on night one and everything added later was silently dropped — multi-day sessions are now captured night by night.

• hicortex nightly --capture-only — runs capture without consolidation. Safe to run repeatedly through the day (a single-flight lock prevents it from colliding with the scheduled nightly); the once-a-day consolidation still runs via the full nightly timer.
• 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. It only widens the window, never narrows it. Run it once after upgrading if older sessions predate the incremental-capture fix.

This fix takes effect when the capturing machine upgrades — it is driven by the client that reads the sessions. A server still on ≤0.13.1 accepts the segmented POSTs; a client still on ≤0.13.1 keeps sending whole-session POSTs, which the server continues to dedup as before.

Backfill commands

The nightly 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).

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.

Next Steps

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