Upgrading

Moving to 0.17 from an older install

The short version

Re-run init with the latest package:

npx @gamaze/hicortex init

Your memories, lessons, links, capture cursors, domain list, auth token, and daemon settings are preserved. Database schema migrations run automatically on startup. The command re-runs LLM detection and the daemon install and takes under a minute.

For OpenClaw plugins:

openclaw plugins install @gamaze/hicortex
openclaw gateway restart

For the Hermes plugin: hermes plugins install gamaze-labs/hicortex-hermes-plugin and restart the gateway.

Upgrading to 0.17

0.17 is the biggest release since launch — a capture watchdog that heals itself, one-model simplification, a memory analytics dashboard, sharper lessons, and Hermes open-thread discovery. Your data is preserved. Three things to know:

1. One model for everything

0.16.8 collapsed the LLM config from a four-tier split (distill / reflect / classify / score) to a single model used by every phase. If you are coming from 0.16.7 or earlier and had routed the heavy phases (distill/reflect/classify) to a larger model, that model must become llmModel — otherwise every phase quietly drops to the smaller base model.

The obsolete per-stage keys — distillModel / distillBaseUrl / distillApiKey / distillProvider, the reflect* and classify* variants, the nested models block, and distillFallback — are no longer read. On boot the server prints a one-time warning naming every ignored key and the corrective action. Consolidate the model into llmModel / llmBaseUrl / llmProvider and remove the old keys to clear the warning.

maxTokens, numCtx, and enableThinking are now single values applying to every phase — no per-tier overrides. A model that doesn’t answer fails soft and is retried on the next scheduled run.

2. Scheduling rework

The old single nightly job is replaced by two timers:

  • Capture watchdog (every machine) — polls ~every 20 min, captures when the machine is awake and the server is reachable, throttled by a success cooldown (default 6 h, ~4 captures per day). A transient network miss now retries in minutes instead of skipping a whole day.
  • Consolidation (server only) — the full “dreaming” pass on fixed local-hour slots, default [10, 22].

Re-running init rewrites the timers to the resolved standard. The legacy nightlyHour is honored as a single-slot fallback only when consolidationHours is absent — new installs use the two-slot default. captureHours (briefly introduced in a pre-release) is renamed captureCooldownHours.

No data loss. Per-session capture cursors are preserved across the upgrade, so nothing is re-captured or skipped. Existing memories, lessons, links, and domain assignments are unchanged.

3. Hermes open-thread discovery

If you run Hermes, interactive Discord threads (open-ended live conversations) are now captured — they were silently dropped before. You do not need to do anything beyond upgrading; the watchdog picks them up automatically on the next capture.

What happens automatically on upgrade

  • Database schema migrations run on daemon start — no manual steps. New migrations in 0.17 add the dashboard_snapshots series for the analytics dashboard.
  • Existing memories, links, domain weights, and capture cursors are preserved.
  • Your config file is never modified destructively. The server adds new defaults at read time; init only adds new keys on a fresh config.
  • The old POST /ingest endpoint still works — POST /distill is additive.
  • Nightly log lines are now ISO-timestamped for diagnosability.

Upgrading from 0.7.1 or earlier

0.10.0 included two changes that affect very old installs.

License change (PolyForm Noncommercial)

From 0.10.0, Hicortex is licensed under the PolyForm Noncommercial License 1.0.0 instead of MIT. Versions ≤ 0.7.1 published to npm remain MIT-licensed — the license change only applies to 0.10.0 and later.

  • Personal and noncommercial use — free, no key needed, no feature limits.
  • Commercial use (for-profit business, client work, product that generates revenue) — requires a per-seat license. Contact hicortex.gamaze.com.

Per-install auth token

Earlier versions used a shared default token. From 0.10.0, each install generates a unique token at init. Re-running init handles this automatically: a custom authToken is left unchanged; the shared default is replaced with a new unique token. After upgrading, run hicortex status to see your token and update any client machines.

New since 0.7.1: two more agent harnesses

  • Hermes (Nous Research) — a recall-only plugin injects lessons and memory search into your Hermes agents, and capture is handled by the watchdog reading each profile’s state.db. See Installation.
  • OpenClaw — the plugin is a thin client (no local database or LLM inside the gateway). It requires a running Hicortex server. See Installation.

Capture architecture change (0.9.0)

If you upgraded from a 0.4.x–0.7.x client mode (which ran local LLM distillation before POSTing to the server), the client no longer needs a local LLM. It denoises locally and POSTs to /distill — the server handles all LLM work. Remove llmBackend, llmModel, and related keys from your client ~/.hicortex/config.json if you no longer want a local LLM. The server must be running 0.9.0+ to handle /distill requests.

Commercial licensing

If you are using Hicortex commercially and need a license key, contact us at hicortex.gamaze.com. Commercial license keys start with hctx- and are added to your config:

{
  "licenseKey": "hctx-<your-key>"
}

The key is validated at boot for display in hicortex status only — it does not enable or disable any features.

FAQ

What happens to my existing memories?

Nothing changes — all memories, lessons, links, and capture cursors are preserved. Schema migrations are additive (new columns, new indexes, new tables).

Do I need to reconfigure my LLM?

If you were already on the single-model setup, no — your existing llmModel is used as-is. If you were on 0.16.7 or earlier and had separate per-stage model keys, consolidate your heavy-phase model into llmModel / llmBaseUrl / llmProvider and remove the obsolete keys. The startup warning names them.

Will my nightly schedule change?

Re-running init installs the watchdog + consolidation timers. If you had consolidationHours set, it is preserved. If you had only nightlyHour, it is honored as a single daily consolidation slot until you switch to consolidationHours.

My recall went silent after upgrade — is it broken?

Probably not. Returning nothing when nothing is relevant is the correct behavior — a silent recall block is better than a noisy one. If it persists across many genuinely-relevant prompts, check the recall knobs (recallMinSimilarity, recallMaxItems) and the dashboard’s recall-adoption panel.

I had a Pro or Team license key — does it still work?

Yes. License keys are still accepted in the config and displayed by hicortex status. Feature gates no longer exist, so the key only affects the status display.

Questions?

Reply to your license email or open an issue at github.com/gamaze-labs/hicortex.