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.
`contextClients`	`["cc"]`	Which harnesses inject the context layer at session start. Array of harness names — any subset of `cc`, `hermes`, `oc` — or the string `"all"`. Unknown names are dropped with a boot warning; a missing or non-array value falls back to `["cc"]`, while an array with no known names resolves to none (no harness injects). All three harnesses are wired since 0.13. The server echoes the resolved list so each harness self-gates.
`contextAgents`	(unset)	Per-agent context modes: `{ "<agent-id>": "override" \| "global" \| "off" }`. A config entry wins over the drop-in `context/agents/<id>/` directory; with no entry, a present directory means `override`, otherwise `global`. Boot-time — restart the server to apply (the drop-in directory is per-request). Invalid ids or modes are dropped with a boot warning.
`agentName`	(unset)	CC-machine config. This machine's agent identity for the context layer (Claude Code). Unset = global context (the default — all your CC machines share one context). Set with `hicortex init --agent-name <name>`; clear with `--agent-name ""`. Hermes profiles and OC agents identify themselves automatically and don't use this key.

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.

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

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