@gamaze/hicortex 0.16.8 → 0.16.10

package/README.md

@@ -203,7 +203,7 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `numCtx` | Context window for ollama (default 8192, one value for all phases). Scoring uses ~850 tokens, so 2048 is ample; distill/reflect/classify need more for `detectChunkSize`'s chunk sizing. |
 | `enableThinking` | Toggle the model's internal reasoning ("thinking") stream for OpenAI-compatible endpoints (default false). Only meaningful for local chat-template-aware servers (ollama, mlx-lm); leave unset for cloud OpenAI/OpenRouter/Groq endpoints (they 400 on the unknown `chat_template_kwargs` field). |
 | `maxTokens` | Max output tokens for all phases (default 8192). A ceiling, not a target — the model stops early when done. |
-| `ollamaFlushEvery` | Flush ollama's accumulated memory every N scoring calls (default 0 = off). Workaround for ollama's memory-growth bug (~171 MB/call). N=15 caps a cycle at ~2.5 GB. Scoped to the fast tier (scoring) only. |
+| `ollamaFlushEvery` | Flush ollama's accumulated memory every N scoring calls. **Off by default (0)** — opt-in only for an **ollama** install whose runner RSS growth (~171 MB/call) swap-thrashes long consolidations on a RAM-constrained box; N=15 caps a cycle at ~2.5 GB. Gated on the provider being ollama (local **or** remote) — no effect for non-ollama providers. Only you can judge whether your ollama endpoint actually suffers the growth (a managed/cloud ollama host may not), so it stays off until you set it. |
 | `ollamaFlushWaitMs` | Milliseconds to wait after an ollama flush for the runner to exit + release memory (default 180000 = 3 min). |
 | `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`. |
 | `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` and `/context/ui` pages are same-origin and need no entry. |
@@ -211,6 +211,7 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `domains` | Your memory domain list (`[{name, description}]`). Scaffolded by `init`; edit freely — see [Memory Domains & Tags](#memory-domains--tags) |
 | `weakPrimaryFloor` | Minimum similarity for a no-fit memory to keep a weak domain association (default: 0.45) |
 | `moduleIndexTokenBudget` | Max tokens for domain index in lessons context (default: 500) |
+| `lessonsLimit` | Max lessons injected into an agent's session-start context (default: 10). Lessons are ranked per session by project/domain affinity + recency + strength + access, so each session sees its most-relevant slice. Lower = leaner system prompts. |
 | `contextClients` | Which harnesses inject the [context layer](#context-layer) at session start (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc`) |
 | `contextAgents` | Per-agent context modes (0.13): `{ "<id>": "override" \| "global" \| "off" }`. Absent + no `agents/<id>/` dir → every agent gets the global set. Boot-time (restart to apply) — see [Per-agent context](#per-agent-context-013) |
 | `agentName` | This install's per-agent context id sent as `?agent=`. **Unset by default** (CC shares the global context — no `?agent=` sent). Explicit opt-in via `init --agent-name <name>`; `init --agent-name ""` clears it. An empty/whitespace value equals unset |

package/dist/config-read.d.ts

@@ -29,3 +29,10 @@ export declare function readStrictBoolean(config: Record<string, unknown>, key:
  * value (e.g. ollamaFlushEvery).
  */
 export declare function readNonNegativeConfig(config: Record<string, unknown>, key: string, def: number): number;
+/**
+ * Warn if the saved config carries keys that 0.16.8+ ignores. Call at every
+ * config read (daemon boot + nightly). The warning clears once the keys are
+ * removed and (for the model keys) the model is consolidated into
+ * llmModel/llmBaseUrl/llmProvider.
+ */
+export declare function warnIgnoredConfigKeys(savedConfig: Record<string, unknown> | null | undefined): void;

package/dist/config-read.js

@@ -16,6 +16,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readPositiveConfig = readPositiveConfig;
 exports.readStrictBoolean = readStrictBoolean;
 exports.readNonNegativeConfig = readNonNegativeConfig;
+exports.warnIgnoredConfigKeys = warnIgnoredConfigKeys;
 /**
  * Read a positive finite number from a config object. Returns `def` when the
  * key is absent OR present-but-invalid (with a warn in the latter case).
@@ -58,3 +59,49 @@ function readNonNegativeConfig(config, key, def) {
     console.warn(`[hicortex] config "${key}" = ${String(v)} is not a non-negative finite number — using default ${def}.`);
     return def;
 }
+/**
+ * Config keys that ≤0.16.7 accepted and 0.16.8+ IGNORES. Two groups:
+ *  - per-stage model keys + the nested `models` block (#231): one model now
+ *    serves all phases, so distillation/reflection/classification silently run
+ *    on `llmModel` — a quality downgrade if a larger model was on a distill/
+ *    reflect tier.
+ *  - `distillFallback` (#232): removed; strict mode is default. A `"local"`
+ *    value no longer falls back — failures retry next run.
+ * Both were public (documented in the README config table). Warn loudly at the
+ * config boundary so neither change is silent.
+ *
+ * NOTE: this list is deliberately WIDER than the `HicortexConfig` type. In
+ * ≤0.16.7 most of these keys (the flat `distill*`/`reflect*` set and
+ * `distillFallback`) were NEVER declared in the interface — they were
+ * accepted-but-untyped, read loosely off the config object, with the README
+ * config table as their only public contract. So deriving this list from the
+ * type would miss them. The list is the README's documented keys; don't trim it
+ * to match the interface (a future audit that did so would silently re-introduce
+ * the ignored-key gap this warning exists to close).
+ */
+const IGNORED_CONFIG_KEYS = [
+    "distillModel", "distillBaseUrl", "distillApiKey", "distillProvider",
+    "reflectModel", "reflectBaseUrl", "reflectApiKey", "reflectProvider",
+    "classifyModel", "classifyBaseUrl", "classifyApiKey", "classifyProvider",
+    "distillFallback",
+];
+/**
+ * Warn if the saved config carries keys that 0.16.8+ ignores. Call at every
+ * config read (daemon boot + nightly). The warning clears once the keys are
+ * removed and (for the model keys) the model is consolidated into
+ * llmModel/llmBaseUrl/llmProvider.
+ */
+function warnIgnoredConfigKeys(savedConfig) {
+    if (!savedConfig)
+        return;
+    const present = IGNORED_CONFIG_KEYS.filter((k) => savedConfig[k] !== undefined);
+    const hasModelsBlock = savedConfig.models !== undefined;
+    if (present.length === 0 && !hasModelsBlock)
+        return;
+    const detail = [...present, ...(hasModelsBlock ? ["models"] : [])].join(", ");
+    console.warn(`[hicortex] config has keys IGNORED since 0.16.8 (${detail}). They have no effect now. ` +
+        `Per-stage model keys / the \`models\` block: one model serves all phases — set ` +
+        `llmModel/llmBaseUrl/llmProvider (+ llmApiKey) to your intended model. ` +
+        `distillFallback: removed (strict mode is default — a failed distill retries next run). ` +
+        `Remove these keys to clear this warning. See the 0.16.8 changelog.`);
+}

package/dist/features.d.ts

@@ -25,8 +25,18 @@ export declare function isPro(): boolean;
 export declare function maxMemoriesAllowed(): number;
 /** Always false — no cap is ever reached. */
 export declare function memoryCapReached(_currentCount: number): boolean;
-/** Always 20. */
-export declare function lessonsLimit(): number;
+/**
+ * Max lessons injected into an agent's session-start context. Configurable via
+ * `config.lessonsLimit` (a positive integer); defaults to 10. Reuses
+ * `readPositiveConfig` so a present-but-invalid value (0, negative, NaN, wrong
+ * type) is rejected AT THE BOUNDARY with a warn — never silently. 0 is NOT
+ * honoured as "off" (use a real config switch if that's ever needed); it is
+ * invalid and falls back to 10 with a warning, so an operator can't
+ * accidentally silence lesson injection by typing 0.
+ */
+export declare function lessonsLimit(config?: {
+    lessonsLimit?: unknown;
+} | null): number;
 /** Always true — remote ingest is always allowed. */
 export declare function remoteIngestAllowed(): boolean;
 /** Direct read of the underlying features record. */

package/dist/features.js

@@ -24,6 +24,7 @@ exports.getCurrentFeatures = getCurrentFeatures;
 const paths_js_1 = require("./paths.js");
 const license_js_1 = require("./license.js");
 const state_js_1 = require("./state.js");
+const config_read_js_1 = require("./config-read.js");
 const DEFAULT_STATE_DIR = (0, paths_js_1.hicortexHome)();
 // A single canonical "full" feature set — no tiers.
 const FULL_FEATURES = {
@@ -90,9 +91,19 @@ function maxMemoriesAllowed() {
 function memoryCapReached(_currentCount) {
     return false;
 }
-/** Always 20. */
-function lessonsLimit() {
-    return 20;
+/**
+ * Max lessons injected into an agent's session-start context. Configurable via
+ * `config.lessonsLimit` (a positive integer); defaults to 10. Reuses
+ * `readPositiveConfig` so a present-but-invalid value (0, negative, NaN, wrong
+ * type) is rejected AT THE BOUNDARY with a warn — never silently. 0 is NOT
+ * honoured as "off" (use a real config switch if that's ever needed); it is
+ * invalid and falls back to 10 with a warning, so an operator can't
+ * accidentally silence lesson injection by typing 0.
+ */
+function lessonsLimit(config) {
+    if (!config)
+        return 10;
+    return Math.floor((0, config_read_js_1.readPositiveConfig)({ lessonsLimit: config.lessonsLimit }, "lessonsLimit", 10));
 }
 /** Always true — remote ingest is always allowed. */
 function remoteIngestAllowed() {

package/dist/index.js

@@ -50,6 +50,9 @@ const THIS_HARNESS = "oc";
 let serverUrl = DEFAULT_SERVER_URL;
 let authToken;
 let hicortexHome = HICORTEX_HOME;
+/** Resolved plugin config captured at service start — used for tunable knobs
+ *  (e.g. lessonsLimit) that injected context blocks read at hook time. */
+let pluginConfig = null;
 /** Old-server guard (F2): 0 = not latched; otherwise the Date.now() epoch-ms
  *  until which /recall-index is skipped after a 404 (pre-0.14 server). The
  *  latch EXPIRES so a client-first rollout heals itself once the server is
@@ -152,7 +155,7 @@ async function buildLessonsBlock(project) {
     const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
     if (!data || !data.lessons || data.lessons.length === 0)
         return null;
-    const maxLessons = (0, features_js_1.lessonsLimit)();
+    const maxLessons = (0, features_js_1.lessonsLimit)(pluginConfig);
     const state = (0, state_js_1.loadState)(hicortexHome);
     const moduleIndex = data.moduleIndex ?? state.moduleIndex;
     const selected = await (0, extensions_js_1.getLessonSelector)().select(data.lessons, {
@@ -264,6 +267,7 @@ exports.default = {
             id: "hicortex-service",
             async start(ctx) {
                 const config = (ctx.config ?? {});
+                pluginConfig = config;
                 const log = ctx.logger
                     ? (msg) => ctx.logger.info(msg)
                     : console.log;

package/dist/lessons-context.d.ts

@@ -39,6 +39,8 @@ export interface ResolvedConfig {
     home: string;
     /** Per-agent context id sent as ?agent= (0.13); null → global (no param). */
     agentName: string | null;
+    /** Max lessons to inject (config.lessonsLimit, default 10). */
+    lessonsLimit?: number;
 }
 /**
  * Read ~/.hicortex/config.json and resolve the server URL + auth token, or

package/dist/lessons-context.js

@@ -64,7 +64,13 @@ function resolveConfig() {
     // context. A configured agentName that sanitizes to null → agentId null too
     // (NO ?agent=), never a 400 that the fail-soft hook would silently swallow.
     const agentName = (0, context_store_js_1.resolveAgentIdentity)(config).agentId;
-    return { serverUrl, authToken: config.authToken, home, agentName };
+    return {
+        serverUrl,
+        authToken: config.authToken,
+        home,
+        agentName,
+        lessonsLimit: typeof config.lessonsLimit === "number" ? config.lessonsLimit : undefined,
+    };
 }
 function authHeaders(authToken) {
     return authToken ? { "Authorization": `Bearer ${authToken}` } : {};
@@ -81,7 +87,7 @@ async function fetchLessonsBlock(cfg) {
     if (!resp.ok)
         return null;
     const data = await resp.json();
-    const maxLessons = (0, features_js_1.lessonsLimit)();
+    const maxLessons = (0, features_js_1.lessonsLimit)(cfg);
     const moduleIndex = data.moduleIndex ?? (0, state_js_1.loadState)(cfg.home).moduleIndex;
     // The SessionStart hook runs in the session's working directory, whose last
     // path component matches the capture-side CC project name convention

package/dist/mcp-server.js

@@ -57,6 +57,7 @@ const zod_1 = require("zod");
 const db_js_1 = require("./db.js");
 const llm_js_1 = require("./llm.js");
 const features_js_1 = require("./features.js");
+const config_read_js_1 = require("./config-read.js");
 const state_js_1 = require("./state.js");
 const embedder_js_1 = require("./embedder.js");
 const storage = __importStar(require("./storage.js"));
@@ -373,6 +374,9 @@ async function startServer(options = {}) {
     // If nothing is configured: start recall-only with an unmissable warning.
     // One model serves all phases (#231) — no per-tier overlay here.
     const savedConfig = readConfigFile(stateDir);
+    // 0.16.8 upgrade guard: per-stage keys are silently ignored now. Warn loudly
+    // so a carried-over distill/reflect model doesn't silently downgrade quality.
+    (0, config_read_js_1.warnIgnoredConfigKeys)(savedConfig);
     // 0.16.2 activation gap: self-heal the agentId provenance field for
     // pre-0.16.2 server installs on first boot after upgrade. The server's own
     // nightly captures its sessions to localhost:8787/distill and needs this id;

package/dist/nightly.js

@@ -219,6 +219,8 @@ async function runNightly(options = {}) {
     (0, state_js_1.migrateLegacyState)(stateDir);
     // Check mode: client or server
     const savedConfig = readNightlyConfig(stateDir);
+    // 0.16.8 upgrade guard: warn if ignored per-stage keys are still present.
+    (0, config_read_js_1.warnIgnoredConfigKeys)(savedConfig);
     // 0.16.2 activation gap: pre-0.16.2 installs never re-run init, so their
     // config has no agentId → capture sent source_agent_id: null forever (the
     // provenance feature was inert for the whole existing fleet). Self-heal on
@@ -366,6 +368,7 @@ async function runNightly(options = {}) {
         // Runs even if capture had transient failures (opens DB directly, independent
         // of the HTTP capture path). Full nightly only — capture-only runs are
         // intended to run more frequently than once daily.
+        let lessonsGenerated; // hoisted for telemetry; undefined when reflection didn't run (skipped) — bucketed apart from a real 0
         if (!dryRun && !captureOnly) {
             if (!llm || !llmConfig) {
                 console.error("[hicortex] consolidation skipped: no LLM configured — run npx @gamaze/hicortex init");
@@ -390,6 +393,14 @@ async function runNightly(options = {}) {
                 });
                 console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s` +
                     (report.stages.reflection ? ` (${report.stages.reflection.lessons_generated} lessons)` : ""));
+                // Only set when reflection actually RAN (not skipped). A skipped stage
+                // (e.g. endpoint offline, #232 fail-soft) must NOT collapse to 0 — that
+                // would make "endpoint down" indistinguishable from "prompt too tight"
+                // in the fleet aggregate. Leave undefined so the optional field is
+                // omitted and the aggregate buckets skipped runs separately.
+                const refl = report.stages.reflection;
+                if (refl && !refl.skipped)
+                    lessonsGenerated = refl.lessons_generated;
             }
         }
         // Step 4: Update last-run timestamp.
@@ -434,6 +445,7 @@ async function runNightly(options = {}) {
                 agent: agentType,
                 mem: storage.countMemories(db),
                 lessons: storage.getLessons(db, 365).length,
+                lessonsGenerated,
                 sessions: batches.length,
                 ok: !hadTransientFailure,
                 shown: adoption.shown,

package/dist/prompts.d.ts

@@ -1,6 +1,12 @@
 /**
  * LLM prompt templates for memory consolidation and distillation.
  * Copied EXACTLY from the Python codebase (proven working prompts).
+ *
+ * SHIPPED SOURCE: this file is compiled into dist/ and published to npm + the
+ * public mirror (it is NOT in .publicignore). Any example, name, or detail in
+ * these prompts is therefore public. Use generic, anonymous examples — never
+ * real internal project/tool/host names or real incident specifics. The
+ * infra-name denylist cannot catch conceptual leaks, only known names.
  */
 /**
  * Importance scoring prompt. Takes a {memories_block} with indexed memories.

package/dist/prompts.js

@@ -2,6 +2,12 @@
 /**
  * LLM prompt templates for memory consolidation and distillation.
  * Copied EXACTLY from the Python codebase (proven working prompts).
+ *
+ * SHIPPED SOURCE: this file is compiled into dist/ and published to npm + the
+ * public mirror (it is NOT in .publicignore). Any example, name, or detail in
+ * these prompts is therefore public. Use generic, anonymous examples — never
+ * real internal project/tool/host names or real incident specifics. The
+ * infra-name denylist cannot catch conceptual leaks, only known names.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.importanceScoring = importanceScoring;
@@ -41,6 +47,9 @@ function reflection(memoriesBlock, recentLessons) {
 
 Like human learning: we grow fastest when we reinforce what works AND correct what doesn't. A system that only learns from mistakes becomes overly cautious. A system that only learns from successes never improves. The combination multiplies.
 
+GENERALITY BAR (read carefully — the most important rule):
+Every lesson MUST be a generalizable operating principle that transfers across contexts, agents, and projects. It is NOT: an incident report, a changelog entry, a one-event fact, a tool-specific recipe, or a note about a named entity. If a memory is only interesting as "what happened today", it is an EPISODE — do not emit a lesson for it. Abstract away specific tool names, hostnames, and incident details from the lesson text; state the transferable rule.
+
 Quality over quantity. 1-3 lessons is typical. An empty array [] is the CORRECT response when memories show routine competent work without noteworthy patterns, surprises, or friction. Do not manufacture lessons from nothing.
 
 LESSON TYPES:
@@ -56,15 +65,19 @@ Good reinforce: "Bundling related changes into a single PR with clear narrative
 Good reinforce: "When presenting multi-scenario analysis, show assumptions side-by-side so stakeholders evaluate trade-offs rather than reacting to isolated worst-cases"
 Good correct: "Always verify ALL substitution targets by diffing output — partial fixes cause silent failures"
 Good principle: "Gather evidence from logs before forming hypotheses — evidence-first debugging resolved issues 3x faster today"
+Good principle: "When a long-running background agent survives a system migration as an orphan, explicitly unregister it before declaring the migration clean — orphans cause silent crash-loops"
 Bad lesson: "The deploy script had a bug" (restatement, not actionable)
+Bad (incident note / changelog entry): "The graph resolver was fixed by adding a computed-at marker column" — that is a changelog entry, not a lesson
+Bad (tool-specific decision): "Tool X is banned because it broke Tool Y's settings" — a one-tool decision, not transferable
+Bad (single-event): "The chat client crashed after a system restore because a background agent was left orphaned" — an incident report, not a principle
 
 For each lesson, output a JSON object:
-- "lesson": Concise, actionable rule in imperative voice
+- "lesson": Concise, actionable rule in imperative voice. State the transferable rule — abstract away specific tool names, hostnames, and incident details.
 - "type": "reinforce" | "correct" | "principle"
 - "project": "global" unless genuinely project-specific (project-specific lessons are still valuable)
 - "severity": "critical" | "important" | "minor"
 - "confidence": "high" | "medium" | "low"
-- "source_pattern": What triggered this (1 sentence, no personal data)
+- "source_pattern": What triggered this (1 sentence, no personal data; may name the specific incident/tool here — but the \`lesson\` field itself stays generic)
 
 Severity guide:
 - "critical": Near-misses that could have caused data loss or security breach, even if caught in time. Also: recurring patterns that keep appearing despite prior corrections.
@@ -87,7 +100,7 @@ Focus on:
 
 Privacy: Never include personal data (names, health, finances, credentials) in lesson text. Abstract to the process level.
 
-Skip: isolated trivial actions, already-documented rules. However, if multiple small successes form a consistent pattern of quality, extract that pattern as a reinforcement.
+Skip: isolated trivial actions, already-documented rules, incident notes, changelog entries, and tool-specific recipes. However, if multiple small successes form a consistent pattern of quality, extract that pattern as a reinforcement.
 
 Respond with a JSON array. Empty array [] is a valid response.`;
 }

package/dist/telemetry.d.ts

@@ -13,6 +13,9 @@
  *              client is never miscounted as "cc".
  *   mem      — total memory count
  *   lessons  — total lesson count
+ *   lessonsGenerated — lessons created THIS run (server mode only; the per-run
+ *              delta, distinct from `lessons` which is the corpus total). Lets a
+ *              silent decline in reflection output be seen in the fleet aggregate.
  *   sessions — sessions distilled this run
  *   ok       — nightly succeeded (true/false)
  *   shown    — sum of shown_count (server mode only)
@@ -76,6 +79,12 @@ export interface TelemetryPayload {
     shown?: number;
     uses?: number;
     cold?: number;
+    /**
+     * Lessons generated THIS run (server mode only). The per-run delta —
+     * `lessons` above is the corpus total, which drifts slowly via decay/prune
+     * and can't reveal a sudden drop in reflection output. 0.16.9+.
+     */
+    lessonsGenerated?: number;
 }
 /**
  * Check if telemetry is enabled. Disabled by:

package/dist/telemetry.js

@@ -14,6 +14,9 @@
  *              client is never miscounted as "cc".
  *   mem      — total memory count
  *   lessons  — total lesson count
+ *   lessonsGenerated — lessons created THIS run (server mode only; the per-run
+ *              delta, distinct from `lessons` which is the corpus total). Lets a
+ *              silent decline in reflection output be seen in the fleet aggregate.
  *   sessions — sessions distilled this run
  *   ok       — nightly succeeded (true/false)
  *   shown    — sum of shown_count (server mode only)

package/dist/types.d.ts

@@ -300,6 +300,13 @@ export interface HicortexConfig {
      * doubled for margin). Only relevant when `ollamaFlushEvery` > 0.
      */
     ollamaFlushWaitMs?: number;
+    /**
+     * Max lessons injected into an agent's session-start context (default 10).
+     * Lessons are ranked per-session by project/domain affinity + recency +
+     * strength + access, so each session sees its most-relevant slice. Lower =
+     * leaner system prompts.
+     */
+    lessonsLimit?: number;
 }
 /** A config-owned life-sphere domain (see HicortexConfig.domains). */
 export interface DomainDef {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.16.8",
+  "version": "0.16.10",
   "description": "Self-learning memory for AI agents — 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": {