Configuration

Config file reference for ~/.hicortex/config.json

Created by npx @gamaze/hicortex init. You can edit the file directly; the server reads it on startup. Keys not listed here are ignored.

Core

Key	Default	Description
`mode`	`"server"`	`"server"` — owns the database, runs MCP server + REST API, runs nightly distillation and consolidation. `"client"` — no local database; connects to a remote server. Nightly denoises sessions locally (no LLM) and POSTs to the server's `/distill` endpoint.
`serverUrl`	—	Remote server URL. Required when `mode` is `"client"` (e.g. `http://bedrock:8787`).
`authToken`	generated	Bearer token for all server endpoints. Generated automatically on first `init` in server mode (`hctx-<32 hex chars>`). Never overwritten by subsequent inits. Find the active token: `npx @gamaze/hicortex status` or read `~/.hicortex/config.json`. Client machines: set this to the server's token so the client nightly can POST to `/distill`. Localhost connections bypass auth — the token is only enforced for remote calls.

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.

Key	Default	Description
`llmBackend`	—	LLM provider for importance scoring. Set by `init`. Examples: `"ollama"`, `"claude-cli"`, `"openai"`.
`llmBaseUrl`	—	Base URL for the scoring LLM endpoint (e.g. `http://localhost:11434` for Ollama).
`llmModel`	—	Model name for importance scoring. A small, fast model works well here (e.g. `qwen3.5:4b`).
`distillModel`	same as `llmModel`	Model for session distillation. Larger models produce higher-quality memories — 9B+ recommended (e.g. `qwen3.5:14b`, `claude-sonnet-4-6`).
`distillBaseUrl`	same as `llmBaseUrl`	Separate Ollama instance for distillation. Useful when routing to a more powerful machine on the same network.
`distillFallback`	`"strict"`	`"strict"` (default) — if the distill endpoint is unreachable or returns an error, abort the nightly run immediately. The watermark is not advanced; sessions are retried the next run. `"local"` — fall back to the base scoring model if the distill endpoint fails (lower quality).
`reflectModel`	same as `distillModel`	Model for nightly reflection (lesson extraction, pattern recognition). Use your largest available model for best results.
`reflectBaseUrl`	same as `distillBaseUrl`	Separate endpoint for reflection. If unreachable, reflection is skipped — scoring, linking, and decay still run.
`classifyModel`	same as `reflectModel`	Model for domain tag classification. Optional — set it when a different model classifies better than your reflection model. If the endpoint is unreachable, classification is skipped for the run and retried the next night.
`classifyBaseUrl`	same as `reflectBaseUrl`	Separate endpoint for classification.

Nightly & Recall

Key	Default	Description
`nightlyHour`	3 (server) / 2 (client)	Local hour (0–23) for the scheduled nightly job installed by `init`. Applied on fresh installs only — existing schedules are never overwritten.
`moduleIndexTokenBudget`	500	Max tokens for the knowledge domain index block injected into agent context. Reduce if the injection is consuming too much of your context window.

Domains

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

Key	Default	Description
`domains`	scaffolded by `init`	Your domain list: an array of `{ "name", "description" }` objects (server mode). The description tells Hicortex what belongs in each domain. Add `"compartment": true` to a domain for a hard boundary (work/life firewall). An existing list is never overwritten by `init`.
`weakPrimaryFloor`	0.45	How close a memory that fits no domain must be to its nearest domain to keep a weak association. Above the floor it is filed under that nearest domain with a low weight; below it, the memory is left unfiled and fades away naturally over time — unless an agent recalls it, which protects it. Raise the floor for stricter filing, lower it to keep more borderline memories.

License & Telemetry

Key	Default	Description
`licenseKey`	—	Commercial license key (`hctx-<...>`). Optional. Validated at boot for display in `hicortex status` only — no feature gates are tied to this. Personal and noncommercial use is free without a key.
`telemetry`	`true`	Anonymous usage telemetry (version, memory count, sessions distilled). Set `false` to opt out. No personal data or session content is sent. Alternatively, set the env var `HICORTEX_TELEMETRY=off`.

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, /context, /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 SessionStart hook

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.

The hook is stored in ~/.claude/settings.json under hooks.SessionStart. init adds it once with a prompt for permission; it does not overwrite an existing hook entry.

Environment variables

These override the corresponding config file keys:

Variable	Overrides
`HICORTEX_LLM_BASE_URL`	`llmBaseUrl`
`HICORTEX_LLM_API_KEY`	API key for cloud LLM providers
`HICORTEX_AUTH_TOKEN`	`authToken`
`HICORTEX_TELEMETRY`	`telemetry` (set to `off` to disable)

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://bedrock:8787",
  "authToken": "hctx-a3f1c2...",
  "nightlyHour": 2,
  "telemetry": true
}

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