@gamaze/hicortex 0.13.0 → 0.13.1

package/README.md

@@ -65,7 +65,7 @@ The plugin connects to `http://127.0.0.1:8787` by default. For a remote server,
 
 | When | What | How |
 |------|------|-----|
-| Agent start | Recent lessons fetched fresh and injected into context | CC SessionStart hook (calls `hicortex lessons-context`) / Hermes plugin prefetch / OC `before_agent_start` hook |
+| Agent start | Standing context (`## Context`) + recent lessons fetched fresh and injected | CC SessionStart hook (calls `hicortex lessons-context`) / Hermes plugin `system_prompt_block` (+ `prefetch` recall) / OC `before_agent_start` hook |
 | Nightly | Denoise sessions → POST /distill → server distills + embeds + stores → consolidate (score, reflect, link, decay) | Automatic pipeline — no manual steps |
 
 ## Memory Domains & Tags
@@ -126,7 +126,7 @@ Beyond auto-distilled memories and lessons, Hicortex holds a **hand-edited conte
 
 - **Storage:** plain files on the server at `~/.hicortex/context/*.md` — one file per section (recommended starter sections `user.md` + `rules.md`, which you create — nothing is pre-populated; add more by dropping in a file). It lives outside the memories table; consolidation never touches it.
 - **Edit:** the web editor at `http://localhost:8787/context/ui` (one tab per section, Save), or the CLI `hicortex context show [name]` / `hicortex context edit <name>`.
-- **Delivery:** injected into the harnesses listed in `contextClients` (default `["cc"]` — Claude Code only in v1; `"all"` or any subset of `cc`/`hermes`/`oc`).
+- **Delivery:** injected into the harnesses listed in `contextClients` (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc` — all three are supported since 0.13).
 - **Deletion** is filesystem-only — remove the file on the server (as the daemon user).
 
 ### Per-agent context (0.13)
@@ -191,12 +191,9 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 |-------|-------------|
 | `mode` | `"server"` (default) or `"client"` |
 | `serverUrl` | Remote server URL (client mode) |
-| `llmModel` | Model for importance scoring (server mode) |
-| `distillModel` | Model for session distillation — 9b+ recommended (server mode) |
-| `distillBaseUrl` | Separate Ollama instance for distillation (server mode) |
+| `llmModel` | The one model the whole pipeline uses (server mode). One model is the happy path; route individual stages with `models` — see [Advanced: per-stage models](#advanced-per-stage-models) |
+| `models` | Optional nested per-stage model overrides (`score`/`distill`/`reflect`/`classify`) — see [Advanced: per-stage models](#advanced-per-stage-models) |
 | `distillFallback` | `"strict"` (default) — abort on remote distill failure, retry next run; `"local"` — fall back to base model (lower quality, 0.9.0 behaviour) |
-| `reflectModel` | Model for nightly reflection — largest available (server mode) |
-| `reflectBaseUrl` | Separate Ollama instance for reflection (server mode) |
 | `authToken` | Bearer token for endpoint auth. Generated on first `init` in server mode. Find the active token with `hicortex status` or in `~/.hicortex/config.json`. |
 | `licenseKey` | Commercial license key (optional; for display in `hicortex status`) |
 | `domains` | Your memory domain list (`[{name, description}]`). Scaffolded by `init`; edit freely — see [Memory Domains & Tags](#memory-domains--tags) |
@@ -263,6 +260,30 @@ LLM selection is **user-controlled**: `npx @gamaze/hicortex init` detects candid
 
 If no LLM is configured, the server starts in **recall-only mode**: search, lessons, and context work; `/distill` and consolidation are disabled. Run `npx @gamaze/hicortex init` to configure.
 
+### Advanced: per-stage models
+
+The happy path is **one model** (`llmModel`) for the whole pipeline. If you want to route the four pipeline stages to different models or endpoints, add a nested `models` block to `~/.hicortex/config.json`:
+
+```json
+{
+  "llmBackend": "ollama",
+  "llmModel": "qwen3.5:4b",
+  "models": {
+    "score":    { "model": "qwen3.5:4b" },
+    "distill":  { "model": "qwen3.5:35b-a3b", "baseUrl": "http://gpu-box:11434" },
+    "reflect":  { "model": "qwen3.5:35b-a3b", "baseUrl": "http://gpu-box:11434" },
+    "classify": { "model": "gemma4-31b",      "baseUrl": "http://gpu-box:11434" }
+  }
+}
+```
+
+The four tiers: `score` (importance scoring — this **is** the base model), `distill` (session distillation, 9b+ recommended), `reflect` (nightly reflection, largest available), `classify` (memory-domain tagging). 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 — `classify` delegates to the reflect path when unset).
+
+- **Flat keys still work.** `distillModel`/`distillBaseUrl`/`reflectModel`/`reflectBaseUrl`/`classifyModel`/`classifyBaseUrl` remain supported at **lower precedence** — a `models` entry wins over the flat key of the same name.
+- **A tier's `apiKey`/`provider` require the tier's own `baseUrl`.** They only take effect when the tier sets `baseUrl`; set on a tier without a `baseUrl` they are **ignored with a warning** (a bare `models.reflect: { model, apiKey }` would otherwise silently bill to the base key). Set `provider` when a tier's `baseUrl` points at a different provider type than the base (e.g. an OpenAI-compatible API while the base is Ollama); set `apiKey` for an API-provider tier over an Ollama base, whose base key is empty (`""`).
+- **`init` writes a flat `llmModel`.** The already-configured guard now recognizes a nested-only config (`models.score`), so re-running `init` on one is a no-op. But if a config has **both** a flat `llmModel` and a `models.score.model`, the nested value **shadows** the flat one (nested > flat) — keep the model in one place.
+- **`score.provider` (and `score.apiKey` on an Ollama base) are ignored** (a warning is logged): the base provider comes from `llmBackend` (or is auto-detected from the base endpoint), and the Ollama base path sends no api key.
+
 ## Database
 
 Canonical location: `~/.hicortex/hicortex.db`. The OC plugin no longer owns its own database — it is a thin client to the server. Previously, OC installations at `~/.openclaw/data/hicortex.db` were migrated automatically on upgrade; this migration path remains in the server's `resolveDbPath` for any pre-0.10.0 installations.

package/dist/distiller.d.ts

@@ -26,5 +26,31 @@ export declare function extractConversationText(messages: unknown[], redactionCo
  * Send filtered conversation to LLM for knowledge extraction.
  * For large transcripts, chunks into segments to avoid overwhelming small models.
  * Returns an array of memory entries to ingest, or empty array if nothing worth extracting.
+ *
+ * `droppedOut`, when provided, is filled with every entry the substance gate
+ * discarded (full text). Callers use it to build a durable audit trail (#156);
+ * omitting it leaves gate behaviour unchanged.
+ */
+export declare function distillSession(llm: LlmClient, conversation: string, projectName: string, date: string, chunkSizeChars?: number, droppedOut?: string[]): Promise<string[]>;
+/**
+ * Reject ONLY structurally-empty distiller fragments before they become
+ * memories (#156). The distiller occasionally emits leftovers that parse into
+ * entries but carry no recallable content:
+ *   - bare section prefixes:        "[Specific AI Content:]", "[Facts Learned]"
+ *   - echoed template placeholders: "[decision]: [reasoning] (2026-07-05)"
+ *   - pseudo-header bullets:        "**Facts Learned:**"
+ *   - metadata-only lines:          "(2026-07-05)"
+ *
+ * PRECISION OVER RECALL — deliberate trade: the gate rejects only shapes that
+ * are structurally empty of content, never on a length or word-count threshold.
+ * A kept artifact ("Classification: WORK" style) is cheaply pruned later by the
+ * no-fit decay path; a wrongly-dropped genuine memory is unrecoverable. So when
+ * in doubt, keep. Consequence documented for the reviewer: metadata lines like
+ * "Classification: WORK" now PASS the gate — that is intended.
+ *
+ * Stripping is scoped and anchored (one leading section prefix, one trailing
+ * date stamp), never global, so bracketed payloads ("use [ollama] not
+ * [claude-cli]") and content-bearing dates ("deadline moved (2026-08-01)")
+ * survive. Stripping affects only this gate's decision, never stored text.
  */
-export declare function distillSession(llm: LlmClient, conversation: string, projectName: string, date: string, chunkSizeChars?: number): Promise<string[]>;
+export declare function hasMinimalSubstance(entry: string): boolean;

package/dist/distiller.js

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectChunkSize = detectChunkSize;
 exports.extractConversationText = extractConversationText;
 exports.distillSession = distillSession;
+exports.hasMinimalSubstance = hasMinimalSubstance;
 const prompts_js_1 = require("./prompts.js");
 const redact_js_1 = require("./redact.js");
 const MAX_TRANSCRIPT_CHARS = 80_000;
@@ -215,8 +216,12 @@ function extractConversationText(messages, redactionConfig) {
  * Send filtered conversation to LLM for knowledge extraction.
  * For large transcripts, chunks into segments to avoid overwhelming small models.
  * Returns an array of memory entries to ingest, or empty array if nothing worth extracting.
+ *
+ * `droppedOut`, when provided, is filled with every entry the substance gate
+ * discarded (full text). Callers use it to build a durable audit trail (#156);
+ * omitting it leaves gate behaviour unchanged.
  */
-async function distillSession(llm, conversation, projectName, date, chunkSizeChars) {
+async function distillSession(llm, conversation, projectName, date, chunkSizeChars, droppedOut) {
     if (conversation.length < MIN_CONVERSATION_CHARS) {
         return [];
     }
@@ -229,7 +234,10 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
     const chunkSize = chunkSizeChars ?? MAX_TRANSCRIPT_CHARS;
     // If transcript fits in one chunk, distill directly (errors propagate)
     if (transcript.length <= chunkSize) {
-        return distillChunk(llm, transcript, projectName, date);
+        const { entries, dropped } = await distillChunk(llm, transcript, projectName, date);
+        if (droppedOut)
+            droppedOut.push(...dropped);
+        return entries;
     }
     // Chunk large transcripts and distill each segment.
     //
@@ -248,7 +256,9 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
     for (let i = 0; i < chunks.length; i++) {
         console.log(`[hicortex]     Chunk ${i + 1}/${chunks.length} (${chunks[i].length} chars)`);
         try {
-            const entries = await distillChunk(llm, chunks[i], projectName, date);
+            const { entries, dropped } = await distillChunk(llm, chunks[i], projectName, date);
+            if (droppedOut)
+                droppedOut.push(...dropped);
             for (const entry of entries) {
                 // Deduplicate by normalized content
                 const key = entry.toLowerCase().replace(/\s+/g, " ").slice(0, 100);
@@ -279,13 +289,17 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
  * Distill a single chunk of conversation text.
  *
  * Behaviour contract:
- *   - Returns `[]` for legitimate empty results (NO_EXTRACT, empty LLM response,
- *     transcript produced no entries). These are terminal states — the chunk was
- *     processed successfully, there's just nothing worth keeping.
+ *   - Returns `{entries: [], dropped: []}` for legitimate empty results
+ *     (NO_EXTRACT, empty LLM response, transcript produced no entries). These are
+ *     terminal states — the chunk was processed successfully, there's just
+ *     nothing worth keeping.
  *   - Throws for transient errors (LLM unreachable, HTTP 4xx/5xx, timeout, model
  *     not found, rate limit). These MUST propagate so the nightly pipeline can
  *     distinguish "nothing to extract" from "try again later" and avoid
  *     advancing the last-run watermark past sessions it never actually processed.
+ *
+ * `dropped` carries entries the substance gate rejected (full text) so the
+ * caller can surface them in a durable audit trail (#156).
  */
 async function distillChunk(llm, transcript, projectName, date) {
     const prompt = (0, prompts_js_1.distillation)(projectName, date, transcript);
@@ -295,11 +309,24 @@ async function distillChunk(llm, transcript, projectName, date) {
     // "processed successfully with zero extractions".
     const result = await llm.completeDistill(prompt);
     if (!result)
-        return [];
+        return { entries: [], dropped: [] };
     if (result === "NO_EXTRACT" || result.slice(0, 20).includes("NO_EXTRACT")) {
-        return [];
+        return { entries: [], dropped: [] };
     }
-    return parseDistilledEntries(result);
+    const parsed = parseDistilledEntries(result);
+    const entries = [];
+    const dropped = [];
+    for (const entry of parsed) {
+        (hasMinimalSubstance(entry) ? entries : dropped).push(entry);
+    }
+    if (dropped.length > 0) {
+        for (const d of dropped) {
+            const preview = d.length > 120 ? `${d.slice(0, 120)}…` : d;
+            console.log(`[hicortex]     Substance gate: dropped "${preview}"`);
+        }
+        console.log(`[hicortex]     Substance gate: dropped ${dropped.length}/${parsed.length} content-free fragment(s)`);
+    }
+    return { entries, dropped };
 }
 /**
  * Split transcript text into chunks at natural boundaries (double newlines).
@@ -330,6 +357,51 @@ function splitIntoChunks(text, maxChars) {
     }
     return chunks.filter((c) => c.length >= MIN_CONVERSATION_CHARS);
 }
+// Entries longer than this trivially carry substance; the cap short-circuits
+// the checks below and bounds every regex to a small input, so no pathological
+// input can make the gate expensive (#156).
+const MAX_GATE_LENGTH = 2000;
+/**
+ * Reject ONLY structurally-empty distiller fragments before they become
+ * memories (#156). The distiller occasionally emits leftovers that parse into
+ * entries but carry no recallable content:
+ *   - bare section prefixes:        "[Specific AI Content:]", "[Facts Learned]"
+ *   - echoed template placeholders: "[decision]: [reasoning] (2026-07-05)"
+ *   - pseudo-header bullets:        "**Facts Learned:**"
+ *   - metadata-only lines:          "(2026-07-05)"
+ *
+ * PRECISION OVER RECALL — deliberate trade: the gate rejects only shapes that
+ * are structurally empty of content, never on a length or word-count threshold.
+ * A kept artifact ("Classification: WORK" style) is cheaply pruned later by the
+ * no-fit decay path; a wrongly-dropped genuine memory is unrecoverable. So when
+ * in doubt, keep. Consequence documented for the reviewer: metadata lines like
+ * "Classification: WORK" now PASS the gate — that is intended.
+ *
+ * Stripping is scoped and anchored (one leading section prefix, one trailing
+ * date stamp), never global, so bracketed payloads ("use [ollama] not
+ * [claude-cli]") and content-bearing dates ("deadline moved (2026-08-01)")
+ * survive. Stripping affects only this gate's decision, never stored text.
+ */
+function hasMinimalSubstance(entry) {
+    const raw = entry.trim();
+    if (raw.length > MAX_GATE_LENGTH)
+        return true;
+    // Strip ONE leading section prefix (anchored + length-bounded, never global).
+    let body = raw.replace(/^\[[^\]]{0,80}\]\s*/, "");
+    // Strip ONE trailing date stamp (anchored to end).
+    body = body.replace(/\(\s*\d{4}-\d{2}-\d{2}\s*\)\s*$/, "");
+    // Markdown decoration.
+    body = body.replace(/[*_`#>]/g, " ").trim();
+    if (!body)
+        return false; // metadata-only line or bare section prefix
+    if (/:$/.test(body))
+        return false; // pseudo-header: "Facts Learned:"
+    // Pure placeholder echo — nothing but bracketed tokens and separators,
+    // e.g. "[decision]: [reasoning]".
+    if (/^(?:\[[^\]]{0,80}\]|[\s:.,;–-])+$/.test(body))
+        return false;
+    return true;
+}
 /**
  * Parse distilled markdown into individual memory entry strings.
  * Each section item becomes a separate memory.

package/dist/init.d.ts

@@ -29,6 +29,14 @@ export declare function parseMcpListStatus(mcpListOutput: string): "connected" |
  * Exported for testability.
  */
 export declare function parseEnvFile(content: string): Record<string, string>;
+/**
+ * True when an LLM is already persisted and `init` must NOT re-run provider
+ * selection: a named/flat backend, a flat baseUrl+apiKey pair, OR a nested-only
+ * `models.score` (model or baseUrl). The last clause (0.13.1) stops init from
+ * walking a nested-only config back through selection and writing flat keys that
+ * a `models.score` would then silently shadow (nested > flat).
+ */
+export declare function isLlmConfigured(config: Record<string, unknown>): boolean;
 /**
  * Generate a random auth token in the format hctx-<32 hex chars>.
  * Exported for testability.

package/dist/init.js

@@ -20,6 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GENERIC_DEFAULT_DOMAINS = void 0;
 exports.parseMcpListStatus = parseMcpListStatus;
 exports.parseEnvFile = parseEnvFile;
+exports.isLlmConfigured = isLlmConfigured;
 exports.generateAuthToken = generateAuthToken;
 exports.persistAuthToken = persistAuthToken;
 exports.decideAgentName = decideAgentName;
@@ -493,6 +494,18 @@ function mergeByKey(candidates) {
     }
     return [...seen.values()];
 }
+/**
+ * True when an LLM is already persisted and `init` must NOT re-run provider
+ * selection: a named/flat backend, a flat baseUrl+apiKey pair, OR a nested-only
+ * `models.score` (model or baseUrl). The last clause (0.13.1) stops init from
+ * walking a nested-only config back through selection and writing flat keys that
+ * a `models.score` would then silently shadow (nested > flat).
+ */
+function isLlmConfigured(config) {
+    const modelsScore = config.models?.score;
+    const hasModelsScore = Boolean(modelsScore?.model || modelsScore?.baseUrl);
+    return Boolean(config.llmBackend || (config.llmApiKey && config.llmBaseUrl) || hasModelsScore);
+}
 /**
  * Detect or ask for LLM config and persist to ~/.hicortex/config.json.
  * The daemon can't inherit shell env vars, so we persist here.
@@ -508,8 +521,8 @@ async function persistLlmConfig() {
         config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
     }
     catch { /* new file */ }
-    // Don't overwrite if LLM config already persisted
-    if (config.llmBackend || (config.llmApiKey && config.llmBaseUrl)) {
+    // Don't overwrite if LLM config already persisted (incl. a nested-only config).
+    if (isLlmConfigured(config)) {
         console.log(`  ✓ LLM config already configured`);
         return;
     }

package/dist/llm.d.ts

@@ -68,6 +68,25 @@ export declare function resolveExplicitLlmConfig(overrides?: {
  * the transition for any lingering call sites — remove after 0.10.0 ships.
  */
 export declare const resolveLlmConfigForCC: typeof resolveExplicitLlmConfig;
+export type { ModelTierOverride } from "./types.js";
+/**
+ * Normalize a nested `models: { <tier>: {model,baseUrl,apiKey,provider} }` block
+ * onto the flat `llm*` / `distill*` / `reflect*` / `classify*` keys the resolver
+ * already consumes. Nested overrides WIN over any flat key of the same name; every
+ * non-mapped key (llmBackend, licenseKey, distillFallback, contextClients, …)
+ * is preserved via spread. Pure: returns the SAME reference when there is no
+ * `models` key, so this is a provable no-op for every existing install.
+ *
+ * Robust to a malformed config.json: a config that parses to a scalar, array,
+ * or null is returned untouched (matching the pre-0.13.1 optional-chaining
+ * tolerance — this function must never throw at server/nightly boot).
+ *
+ * Fail-explicit (warn + skip, never throw): an invalid `models` value, an
+ * unknown tier name, a non-object tier value, a non-string field value, a tier
+ * apiKey/provider set without a baseUrl (they are baseUrl-gated downstream), and
+ * a dead score apiKey/provider under an ollama base.
+ */
+export declare function applyModelsBlock(saved: Record<string, unknown> | null): Record<string, unknown> | null;
 /**
  * Resolve an LlmConfig from a saved ~/.hicortex/config.json object.
  *
@@ -79,8 +98,12 @@ export declare const resolveLlmConfigForCC: typeof resolveExplicitLlmConfig;
  *
  * Returns `reason: "claude_binary_missing"` when claude-cli is configured but
  * the binary can't be found, so callers can log a context-specific message.
+ *
+ * `findBinary` is injectable (defaults to the real `findClaudeBinary`) so the
+ * claude-cli branch — including the missing-binary passthrough — can be pinned
+ * deterministically in tests without depending on the host filesystem.
  */
-export declare function resolveSavedLlmConfig(savedConfig: Record<string, unknown> | null): {
+export declare function resolveSavedLlmConfig(savedConfig: Record<string, unknown> | null, findBinary?: () => string | null): {
     config: LlmConfig | null;
     reason?: "claude_binary_missing";
 };

package/dist/llm.js

@@ -17,6 +17,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LlmClient = exports.RateLimitError = exports.resolveLlmConfigForCC = void 0;
 exports.resolveExplicitLlmConfig = resolveExplicitLlmConfig;
+exports.applyModelsBlock = applyModelsBlock;
 exports.resolveSavedLlmConfig = resolveSavedLlmConfig;
 exports.resolveClassifyProbeTarget = resolveClassifyProbeTarget;
 exports.findClaudeBinary = findClaudeBinary;
@@ -70,6 +71,117 @@ function resolveExplicitLlmConfig(overrides) {
  * the transition for any lingering call sites — remove after 0.10.0 ships.
  */
 exports.resolveLlmConfigForCC = resolveExplicitLlmConfig;
+/**
+ * Map from a `models.<tier>` name to the flat config keys it feeds. The base
+ * tier is `score` — score IS the base model today (completeFast reads
+ * config.model), so it lands on the llm* keys and its `provider` is ignored
+ * (the base provider comes from llmBackend / detectProvider, not config).
+ * Tiers with a `provider` key (distill/reflect/classify) apply their apiKey +
+ * provider through a baseUrl-gated overlay downstream; `score` (no provider
+ * key) rides the base resolution.
+ */
+const MODELS_TIER_KEYS = {
+    score: { model: "llmModel", baseUrl: "llmBaseUrl", apiKey: "llmApiKey" },
+    distill: { model: "distillModel", baseUrl: "distillBaseUrl", apiKey: "distillApiKey", provider: "distillProvider" },
+    reflect: { model: "reflectModel", baseUrl: "reflectBaseUrl", apiKey: "reflectApiKey", provider: "reflectProvider" },
+    classify: { model: "classifyModel", baseUrl: "classifyBaseUrl", apiKey: "classifyApiKey", provider: "classifyProvider" },
+};
+/**
+ * Normalize a nested `models: { <tier>: {model,baseUrl,apiKey,provider} }` block
+ * onto the flat `llm*` / `distill*` / `reflect*` / `classify*` keys the resolver
+ * already consumes. Nested overrides WIN over any flat key of the same name; every
+ * non-mapped key (llmBackend, licenseKey, distillFallback, contextClients, …)
+ * is preserved via spread. Pure: returns the SAME reference when there is no
+ * `models` key, so this is a provable no-op for every existing install.
+ *
+ * Robust to a malformed config.json: a config that parses to a scalar, array,
+ * or null is returned untouched (matching the pre-0.13.1 optional-chaining
+ * tolerance — this function must never throw at server/nightly boot).
+ *
+ * Fail-explicit (warn + skip, never throw): an invalid `models` value, an
+ * unknown tier name, a non-object tier value, a non-string field value, a tier
+ * apiKey/provider set without a baseUrl (they are baseUrl-gated downstream), and
+ * a dead score apiKey/provider under an ollama base.
+ */
+function applyModelsBlock(saved) {
+    // Guard the container itself first — `"models" in saved` throws a TypeError on
+    // a truthy non-object (config.json = `true`/`5`/`"x"`); such configs must pass
+    // through so the boot path degrades to recall-only exactly as before.
+    if (typeof saved !== "object" || saved === null || Array.isArray(saved))
+        return saved;
+    if (!("models" in saved))
+        return saved;
+    const models = saved.models;
+    if (typeof models !== "object" || models === null || Array.isArray(models)) {
+        console.warn(`[hicortex] Ignoring invalid "models" config: expected an object of per-tier overrides, got ${Array.isArray(models) ? "array" : models === null ? "null" : typeof models}`);
+        return saved;
+    }
+    const ollamaBase = saved.llmBackend === "ollama";
+    const mapped = {};
+    for (const [tier, value] of Object.entries(models)) {
+        const keys = MODELS_TIER_KEYS[tier];
+        if (!keys) {
+            console.warn(`[hicortex] Ignoring unknown "models" tier "${tier}" (expected: score, distill, reflect, classify)`);
+            continue;
+        }
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            console.warn(`[hicortex] Ignoring invalid "models.${tier}" override: expected an object with model/baseUrl/apiKey/provider`);
+            continue;
+        }
+        const o = value;
+        // Per-field string validation: a non-string value would map verbatim and
+        // fail opaquely downstream (e.g. baseUrl: 11434), so drop it with a warning.
+        const strField = (name) => {
+            const v = o[name];
+            if (v === undefined)
+                return undefined;
+            if (typeof v !== "string") {
+                console.warn(`[hicortex] Ignoring non-string "models.${tier}.${name}" (expected a string)`);
+                return undefined;
+            }
+            return v;
+        };
+        const model = strField("model");
+        const baseUrl = strField("baseUrl");
+        const apiKey = strField("apiKey");
+        const provider = strField("provider");
+        if (model !== undefined)
+            mapped[keys.model] = model;
+        if (baseUrl !== undefined)
+            mapped[keys.baseUrl] = baseUrl;
+        if (keys.provider) {
+            // Overlay tier (distill/reflect/classify): the downstream overlay only
+            // consumes apiKey/provider when the tier ALSO sets its own baseUrl.
+            // Without one, they would silently bill to the base key — so warn + drop.
+            if ((apiKey !== undefined || provider !== undefined) && baseUrl === undefined) {
+                console.warn(`[hicortex] Ignoring "models.${tier}" apiKey/provider without a baseUrl: they only take effect when the tier sets its own baseUrl`);
+            }
+            else {
+                if (apiKey !== undefined)
+                    mapped[keys.apiKey] = apiKey;
+                if (provider !== undefined)
+                    mapped[keys.provider] = provider;
+            }
+        }
+        else {
+            // score = base tier: no separate provider key, and apiKey rides llmApiKey.
+            if (provider !== undefined) {
+                console.warn(`[hicortex] Ignoring "models.score.provider": the base provider comes from llmBackend (or is auto-detected from the endpoint)`);
+            }
+            if (apiKey !== undefined) {
+                if (ollamaBase) {
+                    // The ollama base path hardcodes an empty api key and never reads
+                    // llmApiKey, so score.apiKey is dead there.
+                    console.warn(`[hicortex] Ignoring "models.score.apiKey": the base ollama path sends no api key`);
+                }
+                else {
+                    mapped[keys.apiKey] = apiKey;
+                }
+            }
+        }
+    }
+    return { ...saved, ...mapped };
+}
 /**
  * Resolve an LlmConfig from a saved ~/.hicortex/config.json object.
  *
@@ -81,11 +193,16 @@ exports.resolveLlmConfigForCC = resolveExplicitLlmConfig;
  *
  * Returns `reason: "claude_binary_missing"` when claude-cli is configured but
  * the binary can't be found, so callers can log a context-specific message.
+ *
+ * `findBinary` is injectable (defaults to the real `findClaudeBinary`) so the
+ * claude-cli branch — including the missing-binary passthrough — can be pinned
+ * deterministically in tests without depending on the host filesystem.
  */
-function resolveSavedLlmConfig(savedConfig) {
+function resolveSavedLlmConfig(savedConfig, findBinary = findClaudeBinary) {
+    savedConfig = applyModelsBlock(savedConfig);
     let llmConfig = null;
     if (savedConfig?.llmBackend === "claude-cli") {
-        const claudePath = findClaudeBinary();
+        const claudePath = findBinary();
         if (claudePath) {
             llmConfig = claudeCliConfig(claudePath);
         }

package/dist/mcp-server.js

@@ -332,7 +332,7 @@ async function startServer(options = {}) {
     // Named backends (claude-cli, ollama) → immediate config; everything else
     // goes through resolveExplicitLlmConfig which requires a user-chosen provider.
     // If nothing is configured: start recall-only with an unmissable warning.
-    const savedConfig = readConfigFile(stateDir);
+    const savedConfig = (0, llm_js_1.applyModelsBlock)(readConfigFile(stateDir));
     if (savedConfig?.llmBackend === "claude-cli") {
         const claudePath = (0, llm_js_1.findClaudeBinary)();
         if (claudePath) {
@@ -717,7 +717,11 @@ async function startServer(options = {}) {
             ? `${session_id}${segment_id ? `#${segment_id}` : ""}`
             : undefined;
         try {
-            const entries = await (0, distiller_js_1.distillSession)(llm, conversationText, project ?? "unknown", date, chunkSize);
+            // Collect gate-dropped entries so they can ride back in the response and
+            // land in the caller's file-persisted nightly log (#156 audit trail); the
+            // server-side per-entry console.log in distillChunk stays as well.
+            const dropped = [];
+            const entries = await (0, distiller_js_1.distillSession)(llm, conversationText, project ?? "unknown", date, chunkSize, dropped);
             const ids = [];
             for (let i = 0; i < entries.length; i++) {
                 const entry = entries[i];
@@ -736,7 +740,11 @@ async function startServer(options = {}) {
                 });
                 ids.push(id);
             }
-            res.status(201).json({ ids, distilled: ids.length });
+            res.status(201).json({
+                ids,
+                distilled: ids.length,
+                dropped: dropped.map((d) => (d.length > 120 ? `${d.slice(0, 120)}…` : d)),
+            });
         }
         catch (err) {
             res.status(500).json({ error: "Distillation failed", message: err instanceof Error ? err.message : String(err) });

package/dist/nightly-status.js

@@ -18,6 +18,7 @@ const node_os_1 = require("node:os");
 const node_child_process_1 = require("node:child_process");
 const db_js_1 = require("./db.js");
 const state_js_1 = require("./state.js");
+const llm_js_1 = require("./llm.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CONFIG_PATH = (0, node_path_1.join)(HICORTEX_HOME, "config.json");
 async function showNightlyStatus() {
@@ -36,7 +37,9 @@ async function showNightlyStatus() {
     }
     // LLM config
     try {
-        const config = JSON.parse((0, node_fs_1.readFileSync)(CONFIG_PATH, "utf-8"));
+        // No `?? {}` coercion: a null/invalid parse must fall through to the catch
+        // below (as it did pre-0.13.1) rather than print a fabricated-healthy status.
+        const config = (0, llm_js_1.applyModelsBlock)(JSON.parse((0, node_fs_1.readFileSync)(CONFIG_PATH, "utf-8")));
         const backend = config.llmBackend ?? "auto-detect";
         const model = config.llmModel ?? "default";
         const mode = config.mode === "client" ? "client → " + (config.serverUrl ?? "?") : "server (local)";

package/dist/nightly.js

@@ -228,6 +228,10 @@ async function runNightly(options = {}) {
                     const data = await resp.json();
                     memoriesIngested += data.distilled ?? 0;
                     console.log(`[hicortex]     → ${data.distilled ?? 0} memories extracted`);
+                    // Durable audit trail (#156): the server truncates each dropped entry.
+                    for (const d of data.dropped ?? []) {
+                        console.log(`[hicortex]     Substance gate: dropped "${d}"`);
+                    }
                 }
                 else if (resp.status === 429) {
                     const data = await resp.json();
@@ -444,6 +448,10 @@ async function runClientNightly(config, dryRun) {
                 memoriesIngested += count;
                 sessionsSent++;
                 console.log(`[hicortex]     → ${count} memories sent to server`);
+                // Durable audit trail (#156): the server truncates each dropped entry.
+                for (const d of data.dropped ?? []) {
+                    console.log(`[hicortex]     Substance gate: dropped "${d}"`);
+                }
             }
             else if (resp.status === 401) {
                 console.error(`[hicortex]     Auth failed. Check authToken in ~/.hicortex/config.json`);

package/dist/types.d.ts

@@ -115,6 +115,16 @@ export interface ConsolidationReport {
         calls_by_stage: Record<string, number>;
     };
 }
+/**
+ * A single per-stage override inside the nested `models` server-config block.
+ * Consumed by `applyModelsBlock` (llm.ts), which re-exports this type.
+ */
+export interface ModelTierOverride {
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    provider?: string;
+}
 /** Plugin configuration from openclaw.plugin.json configSchema. */
 export interface HicortexConfig {
     licenseKey?: string;
@@ -145,6 +155,16 @@ export interface HicortexConfig {
     classifyApiKey?: string;
     /** Optional provider for the classify endpoint (defaults to the base provider). */
     classifyProvider?: string;
+    /**
+     * Server config (NOT an OC-plugin key): nested per-stage model overrides.
+     * `{ score|distill|reflect|classify: { model?, baseUrl?, apiKey?, provider? } }`.
+     * Normalized onto the flat `llm*` / `distill*` / `reflect*` / `classify*`
+     * keys at read time (see applyModelsBlock in llm.ts); nested wins, and the
+     * flat keys remain supported at lower precedence. Happy path is a single model via
+     * `llmModel`; use this block only for per-stage routing. `score.provider` is
+     * ignored (base provider comes from llmBackend).
+     */
+    models?: Record<string, ModelTierOverride>;
     /** @deprecated Consolidation is owned by the server nightly. */
     consolidateHour?: number;
     /** @deprecated The OC plugin no longer opens its own database. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Self-learning memory for AI agents \u2014 experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {