Configuration

Core

LLM (server mode only)

LLM selection is user-controlled: init detects candidates and presents a numbered list. Nothing is silently auto-applied at runtime. If no LLM is configured, the server starts in recall-only mode — search, lessons, and context work; /distill and consolidation are disabled. Run init to configure.

Per-stage models (nested block)

The happy path is one model — set llmModel and the whole pipeline uses it. To route the four pipeline stages to different models or endpoints, add a nested models block instead of the flat keys above:

{
  "llmBackend": "ollama",
  "llmModel": "qwen3.5:4b",
  "models": {
    "distill":  { "model": "qwen3.5:35b", "baseUrl": "http://gpu-box:11434" },
    "reflect":  { "model": "qwen3.5:35b", "baseUrl": "http://gpu-box:11434" },
    "classify": { "model": "gemma3:27b",  "baseUrl": "http://gpu-box:11434" }
  }
}

The four tiers are score (importance scoring — this is the base model), distill (session distillation, 9B+ recommended), reflect (nightly reflection / lesson extraction, largest available), and classify (domain-tag classification). Each accepts model, baseUrl, apiKey, and provider. Omitting a tier inherits: distill and reflect fall back to the base (score) model; classify falls back to the reflect tier, not the base.

• Precedence is nested > flat > base. The flat keys (distillModel, reflectBaseUrl, classifyModel, …) still work; a models entry wins over the flat key of the same name. If a config has both a flat llmModel and a models.score.model, the nested value shadows the flat one — keep the model in one place.
• A tier's apiKey/provider require that tier's own baseUrl. Set on a tier without a baseUrl they are ignored with a boot warning (this prevents a bare models.reflect: { model, apiKey } silently billing to the base key). Set provider when a tier's endpoint is a different provider type than the base (e.g. an OpenAI-compatible API while the base is Ollama).
• score.provider (and score.apiKey on an Ollama base) are ignored with a warning — the base provider comes from llmBackend, and the Ollama base path sends no API key.

Nightly & Context

Recall & decay tuning (0.14)

All recall breadth and memory-decay knobs live in the server config — calibration is a config edit + server restart, never a client change or a release. See Usage: per-prompt memory recall for how the recall index behaves.

Domains

Your top-level knowledge spheres. Scaffolded by init with five editable defaults; edit freely. See Domains for the full guide.

Context layer

Hand-edited standing context ("who you are + how to work") that is injected verbatim into every session — distinct from auto-distilled memories and lessons, and never scored, decayed, or pruned. Stored as plain Markdown files on the server at ~/.hicortex/context/*.md (one file per section; the recommended starter sections are user.md and rules.md — you create them, nothing is pre-populated and a fresh install starts empty; add more by dropping in a file).

Edit via the web editor at http://localhost:8787/context/ui or the CLI: hicortex context show [name] and hicortex context edit <name>. Section names must match ^[a-z0-9][a-z0-9_-]*$ (max 64 chars). Deletion is filesystem-only — remove the file on the server (as the daemon user). See Usage.

Use contextClients (above) to choose which harnesses receive it. Since 0.13 each agent can additionally have its own context (per-section override, global, or off) — per-agent sections live at ~/.hicortex/context/agents/<id>/*.md, modes are pinned with contextAgents (above), and Claude Code machines opt in with agentName. See Usage for the full per-agent guide.

License & Telemetry

Recall-only mode (no LLM)

If no LLM is configured — or when running in client mode — the server operates in recall-only mode. All retrieval endpoints work: /search, /recent, /lessons, and all MCP tools. The /distill endpoint returns 503 (client retries next run). Consolidation is skipped.

Recall-only mode is the correct state for:

• Hermes and OC plugins running on a machine that does not host the server
• Client machines that POST sessions to a remote server
• Server machines mid-setup before an LLM is configured

To add an LLM to an existing install: edit ~/.hicortex/config.json and set llmBackend, llmBaseUrl, and llmModel. Then restart the daemon.

CC hooks

When Claude Code starts a session, the SessionStart hook runs hicortex lessons-context, which fetches current lessons and injects them into context before the agent starts. This is installed automatically by init and does not require any LLM — it is a read-only call to the server.

Since 0.14 init also installs hicortex recall-hook under UserPromptSubmit (injects the per-prompt recall index) and SessionStart (resets the session's recall dedup state). Both are fail-soft — a slow or unreachable server never blocks a prompt.

The hooks are stored in ~/.claude/settings.json. init adds each once as part of its confirmed setup; it does not overwrite an existing hook entry.

Environment variables

These override the corresponding config file keys:

Example: server mode (Ollama)

{
  "mode": "server",
  "authToken": "hctx-a3f1c2...",
  "llmBackend": "ollama",
  "llmBaseUrl": "http://localhost:11434",
  "llmModel": "qwen3.5:4b",
  "distillModel": "qwen3.5:14b",
  "reflectModel": "qwen3.5:14b",
  "distillFallback": "strict",
  "nightlyHour": 3,
  "moduleIndexTokenBudget": 500,
  "telemetry": true
}

Example: client mode

{
  "mode": "client",
  "serverUrl": "http://myserver.example.com:8787",
  "authToken": "hctx-a3f1c2...",
  "nightlyHour": 2,
  "telemetry": true
}

No LLM keys are needed in client mode. The authToken must match the server's token.