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_context Get contextual memories for a specific project or topic. Combines search with linked memories.
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.

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