@gamaze/hicortex 0.16.8 → 0.16.9

package/README.md

@@ -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/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/nightly.js

@@ -366,6 +366,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 +391,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 +443,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.9",
   "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": {