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. Most users never need most of these knobs — the defaults are sensible. Keys not listed here are ignored.
Core
| Key | Default | Description |
|---|---|---|
mode |
"server" |
"server" — owns the database, runs the memory server, distills and consolidates."client" — no local database; denoises sessions locally and POSTs to a remote server.
|
serverUrl |
— | Remote server URL. Required when mode is "client" (e.g. https://myserver.example.com: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 can POST to /distill.Localhost connections bypass auth — the token is only enforced for remote callers. |
LLM (server mode)
Hicortex uses one model for everything: distilling sessions into memories, scoring importance, classifying domains, and extracting lessons. Pick it once during init and the whole pipeline uses it.
If no LLM is configured, the server starts in recall-only mode — search, lessons, and identity work; /distill and consolidation are disabled. Run init to configure.
| Key | Default | Description |
|---|---|---|
llmBackend / llmProvider |
set by init |
LLM provider. Set by init based on your choice. Examples: "ollama", "claude-cli", "openai", "anthropic", "openrouter". |
llmBaseUrl |
— | Base URL for the LLM endpoint (e.g. http://localhost:11434 for a local Ollama, or your provider’s API URL). |
llmModel |
— | The single model used by all phases: distill, score, classify, reflect. A 9B+ model is recommended (e.g. qwen3.5:14b, claude-sonnet-4-6). Set during init. |
llmApiKey |
— | API key for cloud providers. Not needed for Ollama or the Claude CLI. |
maxTokens |
8192 | Maximum output tokens for all phases. A ceiling, not a target — the model stops early when done, so a higher cap costs no latency when the work is small. |
numCtx |
8192 | Context window for the Ollama provider (one value for all phases). Also drives chunk sizing during distillation, so the chunker and the request agree by construction. |
enableThinking |
false | Toggle the model’s internal “thinking” stream for OpenAI-compatible endpoints. Only meaningful for local chat-template-aware servers (Ollama, mlx-lm); leave unset for cloud endpoints, which reject the unknown field. A reasoning model with thinking on can spend its whole budget on internal reasoning and emit nothing. |
distillModel, reflectModel, classifyModel, their baseUrl/apiKey/provider variants, the nested models block) and distillFallback are no longer read. On boot the server prints a one-time warning naming every ignored key. Consolidate your heavy-phase model into llmModel/llmBaseUrl/llmProvider and remove the old keys to clear the warning. See Upgrading.
Capture & consolidation scheduling
Two timers handle everything automatically (installed by init — no cron setup). See Installation · Scheduling for what each does.
| Key | Default | Description |
|---|---|---|
captureCooldownHours |
6 | Success cooldown (hours) for the capture watchdog. The watchdog polls roughly every 20 minutes and captures only if more than this has elapsed since the last successful capture. Default 6 h — about 4 captures per day. A failed reachability check retries in minutes, not hours. |
consolidationHours |
[10, 22] (server only) | Hours (0–23, local) for the consolidation timer — the full “dreaming” pass (capture + distill + score + reflect + link). Installed on server/co-located machines only; clients have no local DB. The default evening slot runs after the day’s capture waves; the morning slot runs after wake-up capture. |
consolidateMaxLlmCalls |
5000 | Ceiling on total LLM calls across all consolidation stages per run (content-domain, link discovery, supersession). A runaway backstop, not a throttle — on a free local model the real constraint is the run’s wall-clock budget, not the call count. |
memorySoftCap |
10000 | Maximum number of memories in the corpus. When exceeded, the lowest-value memories (by decay-weighted strength) are evicted — the least-useful make room for new ones. 0 disables eviction (indefinite growth). Shown on the dashboard as a capacity gauge. |
llmTokensPerMonth |
0 | Monthly LLM token fair-use cap. The usage meter always records real token counts parsed from every LLM API response — distill and consolidation both, even when no cap is set; the cap only gates enforcement. At or over it, consolidation is throttled (skipped + logged) and /distill answers 429 until the period resets (monthly). 0 = unlimited. The dashboard shows a used-vs-cap gauge when a cap is set. |
nightlyHour |
deprecated | Deprecated. Local hour (0–23) honored only when consolidationHours is absent — yields one daily consolidation slot at that hour (preserves the pre-0.17 “one daily job” intent). New installs should use consolidationHours. |
preflightTimeoutMs |
20000 | Client mode only. Per-attempt timeout for the reachability check before capture starts. Default 20 s — absorbs a slow link re-establishing after the client wakes. |
preflightAttempts |
3 | Client mode only. Reachability-check retries before the run aborts (floored at 1). |
preflightRetryGapMs |
60000 | Client mode only. Delay between reachability retries. Timers do not advance while the machine is asleep, so on a sleeping laptop this counts awake-time, not wall-clock. |
Backups
Every full consolidation run ends with an automatic backup (see Usage: Backups). Two knobs control where artifacts land and how they leave the machine:
| Key | Default | Description |
|---|---|---|
backupDir |
~/.hicortex/backups |
Directory where backup artifacts are written. Point it at a mounted backup volume if you have one. |
backupCommand |
(unset) | Offsite hook. When set, hicortex backup and the nightly backup stage run this command with the artifact path appended as its last argument (e.g. "rclone copyto" → rclone copyto <artifact> remote:bucket/). Split on whitespace, no shell — use a wrapper script for commands with quoted arguments. A failing or timed-out hook (5-minute ceiling) is logged and never breaks the nightly: the artifact is already on disk, only the offsite copy is missing. |
Release channel
| Key | Default | Description |
|---|---|---|
updateChannel |
auto | Release channel pinned into the generated daemon/timer for npx-thin installs (machines that run Hicortex via npx rather than a global binary). A dist-tag ("rc", "next") or an exact version ("0.17.1"). For example "rc" makes the timer run npx -y @gamaze/hicortex@rc nightly, so the host tracks the rc dist-tag — useful if you want to ride a pre-release channel across a fleet before promotion. Absent → auto-detect (bare on latest, else @next). Validated as [\w.\-]+. (0.17.1) |
Lessons & identity
| Key | Default | Description |
|---|---|---|
lessonsLimit |
10 | Max lessons injected into an agent’s session-start context. Lessons are ranked per session by project/domain affinity + recency + strength + access, so each session sees its most-relevant slice. Lower → leaner system prompts. |
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. |
identityClients |
["cc"] |
Which harnesses inject the identity layer at session start. Any subset of cc, hermes, oc, or the string "all". Unknown names are dropped with a boot warning. All three harnesses are wired since 0.13. (The legacy key contextClients still works as a backcompat alias.) |
identityAgents |
(unset) | Per-agent identity modes: { "<agent-id>": "override" | "global" | "off" }. A config entry wins over the drop-in identity/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). |
agentName |
(unset) | Claude Code machines only. This machine’s agent identity for the identity layer. Unset = global identity (the default — all your CC machines share one identity). Set with hicortex init --agent-name <name>; clear with --agent-name "". Hermes profiles and OpenClaw agents identify themselves automatically and don’t use this key. |
Recall & decay tuning
All recall breadth and memory-decay knobs live in the server config — calibration is a config edit + server restart, never a release. See Usage: per-prompt memory recall for how the recall index behaves.
| Key | Default | Description |
|---|---|---|
decayHalfLifeDays |
365 | Memory decay half-life in days at reference importance. Larger = slower forgetting; a memory’s importance, access history, and links slow it further. |
searchLimit |
8 | Default result count for semantic search when no explicit limit is given. |
recentLimit |
12 | Default result count for queryless recent recall. |
recentWindowDays |
180 | Candidate window for recent recall — how far back /recent looks. |
coldExposureSlots |
2 | Top-k result slots reservable for never-accessed memories, so the long tail gets exposure instead of the same well-worn memories always winning. |
recallMaxItems |
6 | Max lines in the per-prompt recall index. |
recallMinSimilarity |
0.55 | Relevance floor for recall-index entries; text-search matches always pass. |
recallReshowTurns |
30 | Turns before an already-shown memory may reappear in the recall index within the same session. |
recallMinPromptChars |
20 | Prompts shorter than this skip the recall index entirely. |
recallTitleChars |
150 | Chars of each memory’s first line shown in an index entry (range 40–400). Default 100 — enough for a topic-first title to carry its subject and its claim. |
sessionIntentWeight |
0.33 | Blend weight of the rolling session-intent centroid in the recall search vector: query = (1-w)·prompt + w·centroid. Set 0 to disable (pure-prompt recall — the kill-switch). |
memoryInstructions |
true | Inject the product-owned memory instructions (a read-only memory section in the identity layer) — how agents should use recall, citing, and capture. The section name is reserved; set false to disable. |
Ranking weights
Score weights are config keys, rebalanced so similarity leads. Defaults ship tuned; adjust only if you have a reason.
| Key | Default | Description |
|---|---|---|
scoreSimilarityWeight | 0.50 | Weight of semantic similarity in the ranking score. |
scoreStrengthWeight | 0.20 | Weight of effective strength — importance/use/recency of access. |
scoreConnectionsWeight | 0.15 | Weight of graph centrality. |
scoreRecencyWeight | 0.15 | Weight of the slow recency curve. |
freshnessBoostDays | 7 | Fresh-memory window: new memories rank higher for this many days. |
freshnessBoostWeight | 0.15 | Size of the fresh-memory bonus at age 0, fading linearly to 0 at the window edge (set 0 to disable). |
supersededDemotion | 0.50 | Score multiplier for a memory a later decision reversed. |
Dedup & supersession
| Key | Default | Description |
|---|---|---|
dedupMergeThreshold | 0.92 | Minimum cosine similarity for hicortex dedup to cluster memories as near-duplicates. |
supersessionMinSimilarity | 0.80 | Minimum cosine similarity for a nightly supersession candidate pair. |
supersessionMaxCalls | 30 | Max consolidation-LLM calls the supersession stage spends per run. |
supersessionPenalty | 0.5 | Multiplier applied to a superseded memory’s base_strength. |
Ollama tuning
Two opt-in knobs for Ollama-only installs whose runner RSS grows over a long consolidation and swap-thrashes a RAM-constrained box. Leave both at default (off) unless you have evidence your Ollama endpoint actually suffers the growth.
| Key | Default | Description |
|---|---|---|
ollamaFlushEvery |
0 (off) | When greater than 0, every Nth Ollama scoring call triggers a keep_alive:0 unload + an ollamaFlushWaitMs pause for the runner to release its accumulated memory, then the next call reloads fresh. Gated on the provider being Ollama (local or remote) — no effect for non-Ollama providers. |
ollamaFlushWaitMs |
180000 | Milliseconds to wait after an Ollama flush for the runner to exit + release memory (the runner takes >90 s to exit after keep_alive:0; 3 min allows margin). |
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. 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 for stricter filing, lower to keep more borderline memories. |
Agent identity & provenance
Every install gets a stable agent id — a UUID generated automatically and stored in config. Each memory a client captures is stamped with it, so you can always tell which agent produced a memory, even after renames. The id is created for you on first run (you don’t set it).
| Key | Default | Description |
|---|---|---|
agentId |
auto-generated UUID | Stable per-install identity (generated once, never rotated). Sent with captured memories for attribution. Set automatically — leave it alone. |
sourceDomain |
— | Optional. Declare this agent’s topic (e.g. "Work", "Marine"); every memory it captures is stamped with it as provenance. This is distinct from domains (the vocabulary above) — it’s one client saying “I work on X”, not the server’s content classification. |
Identity layer
Hand-edited standing identity (“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/identity/*.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).
~/.hicortex/context/ directory is automatically renamed to ~/.hicortex/identity/ on the next server boot or nightly run. If both directories exist, they merge additively — no data is lost. Old config keys (contextClients/contextAgents) and the /context endpoint continue to work as aliases.Edit via the web editor at http://localhost:8787/identity/ui or the CLI: hicortex identity show [name] and hicortex identity 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. See Usage.
Use identityClients (above) to choose which harnesses receive it. Since 0.13 each agent can additionally have its own identity (per-section override, global, or off) — per-agent sections live at ~/.hicortex/identity/agents/<id>/*.md, modes are pinned with identityAgents (above), and Claude Code machines opt in with agentName. See Usage for the full per-agent guide.
Account identity
Optional display identity for the server console (dashboard, graph, and editor pages): a name — and optionally an organization and a plan label — shown in the navigation bar. Purely cosmetic; no behavior keys off it. Typically you set at most a display name.
| Key | Default | Description |
|---|---|---|
displayName / orgName / planLabel |
(unset) | Display name, organization (rendered as “Name · Org”), and a small plan badge. All optional; served via GET /account (see the API Reference). When all three are unset the console renders no account element. |
HTTP & security
| Key | Default | Description |
|---|---|---|
corsAllowedOrigins |
[] |
Browser origins allowed to read cross-origin responses (e.g. ["https://ui.example.com"]). Empty by default — the server sends no Access-Control-Allow-Origin and never Allow-Credentials, so no external web page can read its data. The bundled /viz, /identity/ui, and /dashboard pages are same-origin and need no entry. |
distillBodyLimitMb |
25 | Maximum request body size (MB) accepted by the REST/MCP server. An oversized body gets 413; the capturing client holds its cursor and retries on the next run, so nothing is lost. A backstop against misbehaving clients — legitimate capture never approaches it. |
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, mode, agent type, memory/lesson counts, sessions distilled, success flag). On by default and not written into config by init — add "telemetry": false yourself (or set HICORTEX_TELEMETRY=off) to opt out. Inspect exactly what is sent with hicortex 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 (the client retries on the next capture). Consolidation is skipped.
Recall-only mode is the correct state for:
- Hermes and OpenClaw 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.
Claude Code hooks
When Claude Code starts a session, the SessionStart hook runs hicortex learnings-identity (lessons-context kept as an alias for existing installs), which fetches the current identity + lessons and injects them before the agent starts. This is installed automatically by init and requires no LLM — it is a read-only call to the server.
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:
| 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:14b",
"maxTokens": 8192,
"captureCooldownHours": 6,
"consolidationHours": [10, 22],
"moduleIndexTokenBudget": 500,
"lessonsLimit": 10,
"telemetry": true
}Example: client mode
{
"mode": "client",
"serverUrl": "https://myserver.example.com:8787",
"authToken": "hctx-a3f1c2...",
"captureCooldownHours": 6,
"preflightTimeoutMs": 20000,
"telemetry": true
}No LLM keys are needed in client mode. The authToken must match the server’s token.