Usage

How Hicortex works day-to-day

MCP Tools

Your agent has 8 memory tools available via MCP. These are used automatically — you rarely need to invoke them directly.

Tool Description
hicortex_search Semantic search across all memories. Finds relevant context even when wording differs.
hicortex_recent Queryless recall of the latest memories by project, ranked by importance. Catch up on what happened recently. (Renamed in 0.12.)
hicortex_ingest Store a new memory. Used by the agent when it learns something worth remembering.
hicortex_lessons Retrieve distilled lessons learned. High-value patterns extracted from experience.
hicortex_index Get the knowledge domain index — what topics and projects are stored in memory.
hicortex_graph Traverse the memory knowledge graph: find neighbors, hub nodes, or paths between memories.
hicortex_update Update an existing memory with new information or corrections.
hicortex_delete Remove a memory that is no longer relevant or was stored incorrectly.

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>.

Nightly Pipeline

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

1. Capture

Reads each harness's own session store: Hermes (per-profile state.db), OpenClaw (~/.openclaw/agents/*/sessions/), Claude Code (~/.claude/projects/), and Pi (~/.pi/agent/sessions/). Only sessions since the last run watermark are processed.

2. Denoise & Distill

Sessions are denoised (tool-call plumbing stripped, bulk I/O truncated — no LLM, no value judgments) then sent to POST /distill. The server runs LLM distillation to extract memories — lessons learned, decisions made, mistakes to avoid, and context worth remembering. Lessons are extracted from both successes and failures. The raw session text is discarded after distillation.

3. Consolidate

The consolidation pipeline processes all memories:

  • Score — importance scoring based on relevance and frequency
  • Reflect — identify patterns across related memories, extract higher-order lessons
  • Link — connect related memories in the knowledge graph
  • Organize — tag each memory with the domains it touches (most memories get more than one), derive its primary domain, and recompute all domain weights from the current data
  • Prune — decay and remove outdated or low-value memories

4. Inject

Distilled lessons are fetched fresh from the server at session start and injected into your agent's context automatically — via system-prompt injection for Hermes, the before_agent_start hook for OpenClaw, and the CC SessionStart hook for Claude Code. No file writes. No manual steps.

Manual trigger: Run npx @gamaze/hicortex nightly to execute the pipeline immediately without waiting for the scheduled run.

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
Privacy: Only the denoised session text leaves the client — not the raw session. The LLM processing happens on the server. Raw sessions never transit the network.

What You Will Notice

Fewer Repetitive Questions

Your agent remembers your preferences, coding style, and context from previous sessions.

Fewer Repeated Mistakes

When your agent makes a mistake and you correct it, Hicortex captures the lesson. The same mistake will not happen again.

Better Context From Day One

Instead of re-explaining your project or preferences every session, your agent already knows.

Compound Learning

The longer you use Hicortex, the smarter your agent becomes. Not just accumulated data — actively refined and scored knowledge.

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