@gamaze/hicortex 0.16.0 → 0.16.1

package/dist/index.js

@@ -163,10 +163,11 @@ async function buildLessonsBlock(project) {
     if (selected.length === 0)
         return null;
     const formatted = selected.map((l) => {
-        const titleMatch = l.content.match(/## Lesson: (.+)/);
         const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
         const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
-        const title = titleMatch ? titleMatch[1] : l.content.slice(0, 150);
+        // First line, with any legacy `## Lesson:` prefix stripped — new lessons
+        // are stored topic-first without the prefix (memory_type carries the type).
+        const title = l.content.replace(/^##\s*Lesson:\s*/i, "").split("\n")[0].slice(0, 150);
         const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
         return `- ${title}${meta ? ` (${meta})` : ""}`;
     });

package/dist/lessons-context.js

@@ -90,10 +90,11 @@ async function fetchLessonsBlock(cfg) {
     const project = (0, node_path_1.basename)(process.cwd()) || null;
     const selected = await (0, extensions_js_1.getLessonSelector)().select(data.lessons, { maxLessons, moduleIndex, project });
     const lessonLines = selected.map((l) => {
-        const titleMatch = l.content.match(/## Lesson: (.+)/);
         const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
         const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
-        const title = titleMatch ? titleMatch[1] : l.content.slice(0, 150);
+        // First line, with any legacy `## Lesson:` prefix stripped — new lessons
+        // are stored topic-first without the prefix (memory_type carries the type).
+        const title = l.content.replace(/^##\s*Lesson:\s*/i, "").split("\n")[0].slice(0, 150);
         const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
         return `- ${title}${meta ? ` (${meta})` : ""}`;
     });

package/dist/mcp-server.js

@@ -494,6 +494,7 @@ async function startServer(options = {}) {
         minSimilarity: savedConfig?.recallMinSimilarity,
         maxItems: savedConfig?.recallMaxItems,
         minPromptLength: savedConfig?.recallMinPromptChars,
+        titleChars: savedConfig?.recallTitleChars,
     };
     memoryInstructionsEnabled = savedConfig?.memoryInstructions !== false;
     if (resolvedAgents.dropped.length > 0) {

package/dist/prompts.js

@@ -108,25 +108,39 @@ EXTRACT into this markdown format:
 ## Classification: [pick one: PUBLIC / WORK / PERSONAL / SENSITIVE]
 
 ### Decisions Made
-- [decision]: [reasoning] (${date})
+- [SUBJECT]: [decision] — [reasoning] (${date})
 
 ### Facts Learned
-- [fact]: [context/source] (${date})
+- [SUBJECT]: [fact] — [context/source] (${date})
 
 ### Problems & Solutions
-- [problem] → [solution that worked] (${date})
+- [SUBJECT]: [problem] → [solution that worked] (${date})
 
 ### Project State Changes
-- [what changed]: [from → to] (${date})
+- [SUBJECT]: [what changed], [from → to] (${date})
 
 ### Key Entities & Relationships
 - [entity A] → [relationship] → [entity B] (${date})
 
 ### Corrections & Rejections
-- [what AI proposed] → [why rejected/corrected] → [what user wanted instead] (${date})
+- [SUBJECT]: [what AI proposed] → [why rejected/corrected] → [what user wanted instead] (${date})
   (Include: tool use denials, "no/wrong/redo", style feedback, approach rejections,
    user corrections of AI assumptions, quality complaints like "too verbose")
 
+TOPIC-FIRST RULE (critical — read carefully):
+Every item MUST begin with its [SUBJECT]: the concrete thing it is about — the
+system, file, component, decision area, or entity. The subject is what a future
+reader would search for.
+- Write:  "Electrical load calculation: don't bundle unknown loads into one figure — user rejected the estimate"
+- NOT:    "User rejected AI's bundling of unknown loads"
+- Write:  "Nightly capture (Hermes): cron sessions are excluded — source='cron' is skipped before distillation"
+- NOT:    "Discovered that cron sessions are filtered out"
+Reason: each item's first words become the memory's one-line index entry AND
+dominate its search embedding. An item that opens with a category label, a
+sentiment ("Strong Negative"), or "User rejected…" is unfindable — it matches
+every emotionally-similar prompt and no topically-relevant one. Front-load the
+subject; put reaction, intensity and reasoning AFTER it.
+
 RULES:
 - Extract MAX 20 items total (quality over quantity)
 - Each must be useful if recalled in a future session
@@ -136,7 +150,9 @@ RULES:
 - PRIORITIZE Corrections & Rejections — these are high-value signals for learning
   what the user does NOT want. Even a single "no" or style correction is worth extracting.
 - Strong language or profanity from the user is a high-intensity signal — it indicates
-  the correction matters deeply. Note the intensity in the extraction.
+  the correction matters deeply. Note the intensity AFTER the subject, never before it
+  (e.g. "Pricing tiers: strongly rejected per-agent billing — …", not
+  "[Strong Negative] User rejected per-agent billing"). The subject always comes first.
 - PRIVACY CLASSIFICATION (one of):
   - PUBLIC: general tech knowledge, open-source patterns, publicly available info
   - WORK: project-specific decisions, architecture choices, client/business context

package/dist/recall-index.d.ts

@@ -25,13 +25,31 @@ import { SessionRecallRegistry } from "./recall-registry.js";
 export interface RecallIndexOptions {
     /** Minimum measured cosine for vector-only candidates (config
      *  `recallMinSimilarity`). FTS-matched candidates pass regardless — a BM25
-     *  text match is direct evidence of relevance. Default 0.55 (the neutral
-     *  placeholder similarity is 0.5; anything at/below that is noise). */
+     *  text match is direct evidence of relevance. Default 0.62 (raised from 0.55
+     *  on 2026-08-03 per a 0.01-step floor sweep on the rewritten corpus): steady
+     *  ~3:1 noise:signal removal with no knee; 0.62 = +2.2pts precision, 10/98
+     *  prompts silent, sits below the 0.63 local pessimum. The floor is a noise
+     *  dial, NOT a silence mechanism — at 0.62 each correctly-silenced empty prompt
+     *  comes with ~1.5 wrongly-silenced (real signal); a non-cosine gate is the
+     *  real silence fix (eval #3 §4). */
     minSimilarity?: number;
-    /** Max index lines per response (config `recallMaxItems`). Default 6. */
+    /** Max index lines per response (config `recallMaxItems`). Default 5
+     *  (lowered from 6 on 2026-08-03). Per-slot decomposition at floor 0.62:
+     *  slot 6 gives NO prompt its first relevant memory — "6 is wrong" is the
+     *  robust, prompt-set-independent finding, and 5 captures it. The K-sweep
+     *  is monotone (precision@4 33.7% > @6 30.6% > @8 28.3%), so 4 is
+     *  lower-noise — but the 4-vs-5 distinction rests on 5 of 98 prompts and is
+     *  overfitting-fragile (K and the floor were tuned on the same set); 5 hedges
+     *  with coverage at modest cost. Lower to 4 if a fresh-prompt eval replicates. */
     maxItems?: number;
     /** Prompts shorter than this are skipped (continuations, "yes", "do it"). */
     minPromptLength?: number;
+    /** Max chars of the memory's first line shown in an index entry (config
+     *  `recallTitleChars`). Default 100 (reverted from 150 on 2026-08-03): the
+     *  full-corpus relevance eval (#3, §5) found 100 vs 150 statistically
+     *  identical (0.6pts apart, N=40, full CI overlap); 100 saves ~13% tokens
+     *  per block. */
+    titleChars?: number;
 }
 export interface RecallIndexResult {
     status: number;
@@ -39,7 +57,28 @@ export interface RecallIndexResult {
 }
 /** First content line, de-markdowned and truncated — the index line title. */
 export declare function memoryTitle(content: string, maxLen?: number): string;
-/** Relevance gate: real text match, or measured cosine above the floor. */
+/**
+ * Render one production index line. Exported (2026-08-02, relevance eval #v2)
+ * so the eval can measure the REAL rendered surface instead of reimplementing
+ * it — `maxLen` threads through to `memoryTitle` unchanged (default
+ * DEFAULT_TITLE_CHARS = 100, config `recallTitleChars`) so the eval's snippet-length
+ * sweep (spec §4.2) can call this SAME function at 100/150/title1sent without
+ * duplicating the date/scope/agent/type meta-line logic.
+ */
+export declare function formatIndexLine(r: MemorySearchResult & {
+    domain?: string | null;
+}, maxLen?: number): string;
+/**
+ * Relevance gate: a real BM25 text match (FTS) passes unconditionally; a
+ * vector-only candidate must clear `minSimilarity`.
+ *
+ * NOTE: FTS hits BYPASS the similarity floor, so raising the floor shifts
+ * weight toward FTS-sourced entries. In practice FTS is currently inert on
+ * real prompts — eval #3 had 0 FTS rows / 2,208 (2,203 vector + 5 graph), and
+ * a 12-prompt live bedrock sample returned 96/96 vector — so the floor change
+ * is safe as measured. But FTS quality is unmeasured; if FTS starts firing
+ * (e.g. as #205's fielded-BM25 retune beds in), give it its own eval.
+ */
 export declare function passesRelevanceGate(r: MemorySearchResult, minSimilarity: number): boolean;
 /** Recall filters a client may push per request (#193 review F1): a scoped
  *  plugin (Hermes privacy_filter / default_project) must be able to narrow

package/dist/recall-index.js

@@ -55,6 +55,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryTitle = memoryTitle;
+exports.formatIndexLine = formatIndexLine;
 exports.passesRelevanceGate = passesRelevanceGate;
 exports.parseStringListParam = parseStringListParam;
 exports.parsePrivacyParam = parsePrivacyParam;
@@ -62,13 +63,25 @@ exports.handleRecallIndex = handleRecallIndex;
 exports.handleMemoryGet = handleMemoryGet;
 exports.formatMemoryGetText = formatMemoryGetText;
 const storage = __importStar(require("./storage.js"));
-const DEFAULT_MIN_SIMILARITY = 0.55;
-const DEFAULT_MAX_ITEMS = 6;
+/** Relevance-gate floor for vector-only candidates (config `recallMinSimilarity`).
+ *  0.62 (was 0.55; raised 2026-08-03 on the fine-grain floor sweep — see the
+ *  minSimilarity doc above). */
+const DEFAULT_MIN_SIMILARITY = 0.62;
+/** Max index lines per pushed recall block (config `recallMaxItems`).
+ *  5 (was 6; lowered 2026-08-03 — slot 6 is pure padding at floor 0.62). */
+const DEFAULT_MAX_ITEMS = 5;
 const DEFAULT_MIN_PROMPT_LENGTH = 20;
-/** Retrieve more than maxItems so gating + dedup still leave a full menu. */
+/** Default index-line title length. 100 (reverted from 150 on 2026-08-03:
+ *  eval #3 §5 showed 100 vs 150 statistically identical; 100 saves ~13% tokens). */
+const DEFAULT_TITLE_CHARS = 100;
+/** Over-fetch multiplier: retrieve `maxItems × 3` candidates so gating + dedup
+ *  still leave a full menu. Kept at 3 after maxItems 6→5 and the higher floor —
+ *  permit-short is intended (returning fewer than maxItems when fewer clear the
+ *  gate is correct, not a defect); raise only if blocks are persistently
+ *  under-filled in production. */
 const CANDIDATE_MULTIPLIER = 3;
 /** First content line, de-markdowned and truncated — the index line title. */
-function memoryTitle(content, maxLen = 100) {
+function memoryTitle(content, maxLen = DEFAULT_TITLE_CHARS) {
     const firstLine = content
         .split("\n")
         .map((l) => l.trim())
@@ -88,7 +101,15 @@ function formatDate(iso) {
     const mm = String(d.getMonth() + 1).padStart(2, "0");
     return `${dd}.${mm}.${d.getFullYear()}`;
 }
-function formatIndexLine(r) {
+/**
+ * Render one production index line. Exported (2026-08-02, relevance eval #v2)
+ * so the eval can measure the REAL rendered surface instead of reimplementing
+ * it — `maxLen` threads through to `memoryTitle` unchanged (default
+ * DEFAULT_TITLE_CHARS = 100, config `recallTitleChars`) so the eval's snippet-length
+ * sweep (spec §4.2) can call this SAME function at 100/150/title1sent without
+ * duplicating the date/scope/agent/type meta-line logic.
+ */
+function formatIndexLine(r, maxLen = DEFAULT_TITLE_CHARS) {
     // Provenance (#202): date, scope (domain else project), ORIGIN AGENT, type.
     // The origin agent lets a reader calibrate trust — "from my session" vs
     // another agent/project — before fetching or acting on an entry.
@@ -100,9 +121,19 @@ function formatIndexLine(r) {
     ]
         .filter(Boolean)
         .join(", ");
-    return `- [${r.id}] ${memoryTitle(r.content)}${meta ? ` (${meta})` : ""}`;
+    return `- [${r.id}] ${memoryTitle(r.content, maxLen)}${meta ? ` (${meta})` : ""}`;
 }
-/** Relevance gate: real text match, or measured cosine above the floor. */
+/**
+ * Relevance gate: a real BM25 text match (FTS) passes unconditionally; a
+ * vector-only candidate must clear `minSimilarity`.
+ *
+ * NOTE: FTS hits BYPASS the similarity floor, so raising the floor shifts
+ * weight toward FTS-sourced entries. In practice FTS is currently inert on
+ * real prompts — eval #3 had 0 FTS rows / 2,208 (2,203 vector + 5 graph), and
+ * a 12-prompt live bedrock sample returned 96/96 vector — so the floor change
+ * is safe as measured. But FTS quality is unmeasured; if FTS starts firing
+ * (e.g. as #205's fielded-BM25 retune beds in), give it its own eval.
+ */
 function passesRelevanceGate(r, minSimilarity) {
     if (r.source === "fts" || r.source === "both")
         return true;
@@ -150,6 +181,7 @@ async function handleRecallIndex(deps, body) {
         return { status: 200, body: { block: null, skipped: "short-prompt" } };
     }
     const maxItems = clampInt(deps.options?.maxItems, DEFAULT_MAX_ITEMS, 1, 20);
+    const titleChars = clampInt(deps.options?.titleChars, DEFAULT_TITLE_CHARS, 40, 400);
     const minSimilarity = clampNumber(deps.options?.minSimilarity, DEFAULT_MIN_SIMILARITY, 0, 1);
     const turn = deps.registry.beginTurn(sessionId);
     // Optional client-side scoping (F1 + #203): project + mission_domains (soft
@@ -183,7 +215,7 @@ async function handleRecallIndex(deps, body) {
     deps.registry.markShown(sessionId, ids);
     // Exposure signal: shown_count + last_accessed refresh, NOT access_count.
     storage.touchMemoriesShown(deps.db, ids, new Date().toISOString());
-    const lines = picked.map((r) => formatIndexLine(r));
+    const lines = picked.map((r) => formatIndexLine(r, titleChars));
     const block = [
         "## Memory recall (auto)",
         // Provenance is BUILT IN (owner decision 27.07, option D; extended #202/#204):

package/dist/seed-lesson.d.ts

@@ -3,5 +3,5 @@
  * Shared between OC plugin and CC MCP server.
  */
 import type Database from "better-sqlite3";
-export declare const SEED_LESSON = "## Lesson: 1% Daily Self-Improvement\n\nSelf-improvement protocol: Review your sessions daily. Scan for mistakes, gaps, user corrections, and friction. Identify 1-2 issues maximum. Apply one targeted fix to your agent instruction files (e.g. SOUL.md / MEMORY.md for Hermes profiles, CLAUDE.md for Claude Code). Never overcorrect \u2014 feedback is guidance, not emergency. One fix per issue. Never rewrite entire systems. Before changing something, ask: is this a real pattern or am I reacting to noise?\n\nThe flywheel: Sessions \u2192 Hicortex captures \u2192 Nightly consolidation \u2192 Lessons generated \u2192 Lessons injected into your context \u2192 You apply one fix \u2192 Better sessions tomorrow.\n\nUse hicortex_lessons to check for new insights. If a lesson has high confidence, apply it. If medium, observe for one more day. If nothing needs fixing today, skip \u2014 that's fine.\n\n**Severity:** critical\n**Confidence:** high\n**Generated:** seed-lesson";
+export declare const SEED_LESSON = "1% Daily Self-Improvement\n\nSelf-improvement protocol: Review your sessions daily. Scan for mistakes, gaps, user corrections, and friction. Identify 1-2 issues maximum. Apply one targeted fix to your agent instruction files (e.g. SOUL.md / MEMORY.md for Hermes profiles, CLAUDE.md for Claude Code). Never overcorrect \u2014 feedback is guidance, not emergency. One fix per issue. Never rewrite entire systems. Before changing something, ask: is this a real pattern or am I reacting to noise?\n\nThe flywheel: Sessions \u2192 Hicortex captures \u2192 Nightly consolidation \u2192 Lessons generated \u2192 Lessons injected into your context \u2192 You apply one fix \u2192 Better sessions tomorrow.\n\nUse hicortex_lessons to check for new insights. If a lesson has high confidence, apply it. If medium, observe for one more day. If nothing needs fixing today, skip \u2014 that's fine.\n\n**Severity:** critical\n**Confidence:** high\n**Generated:** seed-lesson";
 export declare function injectSeedLesson(database: Database.Database, log?: (msg: string) => void): Promise<void>;

package/dist/seed-lesson.js

@@ -41,7 +41,7 @@ exports.SEED_LESSON = void 0;
 exports.injectSeedLesson = injectSeedLesson;
 const embedder_js_1 = require("./embedder.js");
 const storage = __importStar(require("./storage.js"));
-exports.SEED_LESSON = `## Lesson: 1% Daily Self-Improvement
+exports.SEED_LESSON = `1% Daily Self-Improvement
 
 Self-improvement protocol: Review your sessions daily. Scan for mistakes, gaps, user corrections, and friction. Identify 1-2 issues maximum. Apply one targeted fix to your agent instruction files (e.g. SOUL.md / MEMORY.md for Hermes profiles, CLAUDE.md for Claude Code). Never overcorrect — feedback is guidance, not emergency. One fix per issue. Never rewrite entire systems. Before changing something, ask: is this a real pattern or am I reacting to noise?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "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": {
@@ -39,6 +39,7 @@
     "test:watch": "vitest",
     "eval": "node dist/eval/run-eval.js",
     "eval:recall-sweep": "node dist/eval/recall-sweep.js",
+    "eval:relevance": "node dist/eval/relevance-eval.js",
     "prepack": "npm run build && rm -rf ./hermes-plugin && mkdir -p ./hermes-plugin && cp -r ../../hermes-plugin/hicortex ./hermes-plugin/ && find ./hermes-plugin -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null || true",
     "prepublishOnly": "npm run build && rm -rf ./hermes-plugin && mkdir -p ./hermes-plugin && cp -r ../../hermes-plugin/hicortex ./hermes-plugin/ && find ./hermes-plugin -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null || true"
   },