@gamaze/hicortex 0.17.4 → 0.17.6

package/README.md

@@ -1,5 +1,7 @@
 # @gamaze/hicortex — Self-Learning Memory for AI Agents
 
+<img src="https://raw.githubusercontent.com/gamaze-labs/hicortex/main/docs/dashboard-composition.png" alt="Hicortex dashboard — live screenshot: memory-type composition (episodes / lessons / facts / decisions)" width="800">
+
 Your agents learn from every session — successes and mistakes. Hicortex captures experiences, distills lessons, and applies them automatically. Connect multiple agents to shared memory and they improve together, overnight.
 
 Works with **Hermes**, **OpenClaw**, **Claude Code**, **Pi**, and any MCP-compatible agent.
@@ -104,6 +106,12 @@ npx @gamaze/hicortex classify-domains              # classify unfiled/stale memo
 npx @gamaze/hicortex classify-domains --all        # reclassify every memory
 npx @gamaze/hicortex classify-domains --batch 100  # memories per batch (default: 200)
 npx @gamaze/hicortex classify-domains --reset      # restart from the beginning (ignore saved cursor)
+
+# Reclassify memory types (episode/fact/decision) — fixes the 98%-episode default
+npx @gamaze/hicortex classify-types                # reclassify all episodes (default scope)
+npx @gamaze/hicortex classify-types --all          # reclassify every memory
+npx @gamaze/hicortex classify-types --batch 100    # memories per batch (default: 200)
+npx @gamaze/hicortex classify-types --reset        # restart from the beginning
 ```
 
 The run is resumable — interrupt it any time and it continues where it stopped. New memories are classified automatically by the nightly; the backfill is only needed once for a pre-existing corpus or after you reshape your domain list.
@@ -157,6 +165,7 @@ npx @gamaze/hicortex nightly                   # Run distill + consolidate (full
 npx @gamaze/hicortex nightly --capture-only    # Capture only, skip consolidation (safe for sub-daily runs)
 npx @gamaze/hicortex nightly --dry-run         # Preview without changes
 npx @gamaze/hicortex classify-domains          # Backfill domain tags over the corpus (see Memory Domains & Tags)
+npx @gamaze/hicortex classify-types            # Reclassify memory types (episode/fact/decision)
 npx @gamaze/hicortex dedup                     # Preview near-duplicate memory clusters (dry run, no changes)
 npx @gamaze/hicortex dedup --apply             # Merge near-duplicate clusters (backs up the DB first)
 npx @gamaze/hicortex context show [name]       # Print the standing context layer (see Context Layer)

package/assets/dashboard.html

@@ -77,7 +77,7 @@
   .bar-row { display: flex; align-items: center; gap: 8px; margin: 4px 0; font-size: 13px; }
   .bar-row .k { width: 140px; color: var(--text-dim); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
   .bar-row .track { flex: 1; height: 14px; background: rgba(128,128,128,0.12); border-radius: 3px; overflow: hidden; }
-  .bar-row .fill { height: 100%; background: var(--accent); }
+  .bar-row .fill { display: block; height: 100%; background: var(--accent); }
   .bar-row .n { width: 50px; text-align: right; color: var(--text-dim); font-variant-numeric: tabular-nums; }
   .line { font: 12px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; color: var(--text); white-space: pre-wrap; word-break: break-word; }
   .line a { color: var(--accent); text-decoration: none; }

package/dist/consolidate.d.ts

@@ -196,8 +196,17 @@ export declare function classifyLinkCandidates(candidates: LinkCandidate[], _llm
 export declare function classifyRelationship(source: Memory, target: Memory, similarity: number): string;
 /** Default minimum COSINE similarity for a supersession candidate pair. */
 export declare const DEFAULT_SUPERSESSION_MIN_SIMILARITY = 0.8;
-/** Default max classify-tier LLM calls (pairs evaluated) spent per nightly run. */
-export declare const DEFAULT_SUPERSESSION_MAX_CALLS = 30;
+/**
+ * Default max classify-tier LLM calls (pairs evaluated) spent per nightly run.
+ * 0 = no separate cap — supersession shares the consolidation budget
+ * (CONSOLIDATE_MAX_LLM_CALLS, default 5000) like every other stage. The old
+ * default of 30 was set when the corpus had 14 decisions; with the distiller
+ * now classifying types correctly (#216), decisions are common and the cap
+ * was throttling supersession to a crawl. On a local free model there is no
+ * per-call cost to defend against — the binding constraint is the wall-clock
+ * timeout (TimeoutStartSec), not call count.
+ */
+export declare const DEFAULT_SUPERSESSION_MAX_CALLS = 0;
 export interface SupersessionOptions {
     minSimilarity?: number;
     maxCalls?: number;

package/dist/consolidate.js

@@ -941,8 +941,17 @@ function stageHubBoost(db, dryRun) {
 // note below); it never mis-links.
 /** Default minimum COSINE similarity for a supersession candidate pair. */
 exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = 0.8;
-/** Default max classify-tier LLM calls (pairs evaluated) spent per nightly run. */
-exports.DEFAULT_SUPERSESSION_MAX_CALLS = 30;
+/**
+ * Default max classify-tier LLM calls (pairs evaluated) spent per nightly run.
+ * 0 = no separate cap — supersession shares the consolidation budget
+ * (CONSOLIDATE_MAX_LLM_CALLS, default 5000) like every other stage. The old
+ * default of 30 was set when the corpus had 14 decisions; with the distiller
+ * now classifying types correctly (#216), decisions are common and the cap
+ * was throttling supersession to a crawl. On a local free model there is no
+ * per-call cost to defend against — the binding constraint is the wall-clock
+ * timeout (TimeoutStartSec), not call count.
+ */
+exports.DEFAULT_SUPERSESSION_MAX_CALLS = 0;
 /** Default multiplier applied to a superseded memory's base_strength. */
 /** Floor under which a superseded memory's base_strength never drops. */
 /** Neighbor pool size before shape/older/similarity filtering narrows to top 5. */
@@ -1096,7 +1105,7 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
     let callsUsed = 0;
     let cursor = startCursor;
     for (const candidate of rows) {
-        if (!dryRun && (callsUsed >= maxCalls || budget.exhausted))
+        if (!dryRun && ((maxCalls > 0 && callsUsed >= maxCalls) || budget.exhausted))
             break;
         scanned++;
         let neighbors;
@@ -1115,7 +1124,7 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
             }
             if (dryRun)
                 continue; // preview only — no LLM call, no write
-            if (callsUsed >= maxCalls || !budget.use("supersession"))
+            if ((maxCalls > 0 && callsUsed >= maxCalls) || !budget.use("supersession"))
                 break;
             callsUsed++;
             const { verdict, usage } = await classifySupersession(llm, neighbor.content, candidate.content);

package/dist/type-classify.d.ts

@@ -15,16 +15,20 @@
  * ------------
  * Walks memories ordered by rowid in batches (default 200). Default scope =
  * episodes only (`memory_type = 'episode'`); `--all` reclassifies every memory
- * regardless of current type. For each memory, ONE constrained LLM call asks
- * the model to classify the content as episode / fact / decision. The reply is
- * parsed + validated, and `UPDATE memories SET memory_type = ? WHERE id = ?`
- * runs inside a per-batch transaction. The cursor (`typeCursor` in state.json)
- * advances to the last committed rowid after each batch — crash-safe and
- * infra-abort-safe (same discipline as classify-domains).
+ * regardless of current type **except lessons** (see below). For each memory,
+ * ONE constrained LLM call asks the model to classify the content as
+ * episode / fact / decision. The reply is parsed + validated, and
+ * `UPDATE memories SET memory_type = ? WHERE id = ?` runs inside a per-batch
+ * transaction. The cursor (`typeCursor` in state.json) advances to the last
+ * committed rowid after each batch — crash-safe and infra-abort-safe (same
+ * discipline as classify-domains).
  *
- * Lessons are NEVER produced here: the reflection stage owns them. A model that
- * replies "lesson" is treated as unparseable (the memory keeps its current type
- * and is retried next run via the cursor).
+ * Lessons are NEVER touched here: the reflection stage owns them. The `--all`
+ * scope explicitly excludes `memory_type = 'lesson'` — this is the primary
+ * defence. (The prompt asks only for episode/fact/decision, so a lesson that
+ * DID enter scope would be overwritten to E/F/D — the model never replies
+ * "lesson". `parseTypeReply`'s rejection of a "lesson" reply is a backstop, not
+ * the main guard.)
  *
  * This command does NOT use the consolidation budget — it is a standalone CLI,
  * not a nightly stage.
@@ -81,13 +85,19 @@ export declare function buildTypeClassifyPrompt(content: string): string;
  * Returns null on anything unparseable or out-of-vocabulary so the caller can
  * retry once (matching classify-domains' two-attempt discipline).
  */
-export declare function parseTypeReply(reply: string): "episode" | "fact" | "decision" | null;
+export declare function parseTypeReply(reply: string): {
+    type: "episode" | "fact" | "decision";
+    score: number;
+} | null;
 /**
  * Classify one memory's type. Two attempts (one call, one retry on a throw OR
  * an unparseable reply). Returns the validated type, or null on infra error
  * (caller leaves the memory untouched and retries via the cursor next run).
  */
-export declare function classifyMemoryType(content: string, llm: LlmClient): Promise<"episode" | "fact" | "decision" | null>;
+export declare function classifyMemoryType(content: string, llm: LlmClient): Promise<{
+    type: "episode" | "fact" | "decision";
+    score: number;
+} | null>;
 /**
  * Run the classify-types pass. Returns a structured report.
  * Throws on unrecoverable setup errors (client mode, no LLM) — the cursor

package/dist/type-classify.js

@@ -16,16 +16,20 @@
  * ------------
  * Walks memories ordered by rowid in batches (default 200). Default scope =
  * episodes only (`memory_type = 'episode'`); `--all` reclassifies every memory
- * regardless of current type. For each memory, ONE constrained LLM call asks
- * the model to classify the content as episode / fact / decision. The reply is
- * parsed + validated, and `UPDATE memories SET memory_type = ? WHERE id = ?`
- * runs inside a per-batch transaction. The cursor (`typeCursor` in state.json)
- * advances to the last committed rowid after each batch — crash-safe and
- * infra-abort-safe (same discipline as classify-domains).
+ * regardless of current type **except lessons** (see below). For each memory,
+ * ONE constrained LLM call asks the model to classify the content as
+ * episode / fact / decision. The reply is parsed + validated, and
+ * `UPDATE memories SET memory_type = ? WHERE id = ?` runs inside a per-batch
+ * transaction. The cursor (`typeCursor` in state.json) advances to the last
+ * committed rowid after each batch — crash-safe and infra-abort-safe (same
+ * discipline as classify-domains).
  *
- * Lessons are NEVER produced here: the reflection stage owns them. A model that
- * replies "lesson" is treated as unparseable (the memory keeps its current type
- * and is retried next run via the cursor).
+ * Lessons are NEVER touched here: the reflection stage owns them. The `--all`
+ * scope explicitly excludes `memory_type = 'lesson'` — this is the primary
+ * defence. (The prompt asks only for episode/fact/decision, so a lesson that
+ * DID enter scope would be overwritten to E/F/D — the model never replies
+ * "lesson". `parseTypeReply`'s rejection of a "lesson" reply is a backstop, not
+ * the main guard.)
  *
  * This command does NOT use the consolidation budget — it is a standalone CLI,
  * not a nightly stage.
@@ -64,7 +68,7 @@ function buildTypeClassifyPrompt(content) {
     const truncated = content.length > CLASSIFY_CONTENT_MAX_CHARS
         ? content.slice(0, CLASSIFY_CONTENT_MAX_CHARS) + "…"
         : content;
-    return (`You are classifying a single memory by its TYPE.\n\n` +
+    return (`You are classifying a single memory by its TYPE and IMPORTANCE.\n\n` +
         `TYPES:\n` +
         `- episode: a specific event, interaction, or narrative — a one-time ` +
         `occurrence ("tried X, failed because Y", a correction, a debugging session).\n` +
@@ -73,8 +77,14 @@ function buildTypeClassifyPrompt(content) {
         `- decision: a choice made that future work builds on and a later decision ` +
         `can supersede ("switched from gemma4 to qwen3.5", "adopted the graded-schema ` +
         `tag model"). Not a fact (it can change) and not an episode (it persists).\n\n` +
+        `IMPORTANCE (0.0–1.0):\n` +
+        `- 0.8–1.0: load-bearing — a core fact or decision the agent must know.\n` +
+        `- 0.5–0.8: useful context — relevant to current and future work.\n` +
+        `- 0.2–0.5: marginal — situational, likely to fade.\n` +
+        `- 0.0–0.2: noise — low value, safe to forget.\n` +
+        `Facts and decisions tend to score higher than episodes (they persist).\n\n` +
         `MEMORY:\n${truncated}\n\n` +
-        `Reply with ONLY one word: episode, fact, or decision. No prose, no punctuation.`);
+        `Reply with ONLY: type importance (e.g. "fact 0.8"). No prose, no explanation.`);
 }
 /**
  * Parse the model's reply into a validated type. Accepts the bare word
@@ -99,11 +109,23 @@ function parseTypeReply(reply) {
     // Strip markdown emphasis, surrounding quotes/backticks, trailing punctuation.
     cleaned = cleaned
         .replace(/^[*_`"'\s]+/, "")
-        .replace(/[*_`"'.\s]+$/, "")
-        .trim()
-        .toLowerCase();
-    if (VALID_TYPES.has(cleaned)) {
-        return cleaned;
+        .replace(/[*_`"']+$/, "")
+        .trim();
+    // Expected format: "type score" (e.g. "fact 0.8"). Parse both.
+    const match = cleaned.toLowerCase().match(/^(episode|fact|decision)\s+([0-9]*\.?[0-9]+)/);
+    if (match) {
+        const type = match[1];
+        let score = parseFloat(match[2]);
+        if (isNaN(score) || score < 0)
+            score = 0.5;
+        if (score > 1)
+            score = 1;
+        return { type, score };
+    }
+    // Backward compat: bare type word with no score (old prompt output).
+    const bare = cleaned.toLowerCase().replace(/[.\s]+$/, "");
+    if (VALID_TYPES.has(bare)) {
+        return { type: bare, score: 0.5 };
     }
     return null;
 }
@@ -117,8 +139,8 @@ async function classifyMemoryType(content, llm) {
     for (let attempt = 0; attempt < 2; attempt++) {
         let raw;
         try {
-            // ~8 tokens covers a single word + a little headroom.
-            const r = await llm.completeClassify(prompt, 8);
+            // ~20 tokens covers "type score" + headroom for models that add labels.
+            const r = await llm.completeClassify(prompt, 20);
             raw = r.text;
         }
         catch (err) {
@@ -187,8 +209,15 @@ async function runClassifyTypes(options = {}) {
         report.cursor = cursor;
         console.log(`[hicortex] classify-types starting: scope ${all ? "ALL" : "episodes only"}, ` +
             `batch ${batchSize}, cursor ${cursor}${options.reset ? " (reset)" : ""}`);
-        // Scope filter: default = episodes only; --all = everything.
-        const scopeSql = all ? "rowid > ?" : "rowid > ? AND memory_type = 'episode'";
+        // Scope filter: default = episodes only; --all = everything EXCEPT lessons.
+        // Lessons are owned by the reflection stage — they must never be
+        // reclassified here. (The prompt asks only for episode/fact/decision, so a
+        // lesson row in scope gets overwritten: the model never replies "lesson".
+        // The scope exclusion is therefore the real guard; parseTypeReply's
+        // "lesson" rejection is a backstop, not the primary defence.)
+        const scopeSql = all
+            ? "rowid > ? AND (memory_type IS NULL OR memory_type != 'lesson')"
+            : "rowid > ? AND memory_type = 'episode'";
         const batchStmt = db.prepare(`SELECT rowid AS __rowid, id, content, memory_type FROM memories
        WHERE ${scopeSql} ORDER BY rowid ASC LIMIT ?`);
         // Set true when the classifier returns null (infra error): finish the
@@ -210,8 +239,8 @@ async function runClassifyTypes(options = {}) {
             // Classify (network) OUTSIDE the write transaction; collect results.
             const writes = [];
             for (const row of rows) {
-                const type = await classifyMemoryType(row.content, llm);
-                if (type === null) {
+                const result = await classifyMemoryType(row.content, llm);
+                if (result === null) {
                     // Infra error OR two unparseable replies — stop scanning; leave this
                     // row untouched for retry. (Two unparseable replies is rare; treating
                     // it as an abort rather than a skip means the cursor does not advance
@@ -222,21 +251,21 @@ async function runClassifyTypes(options = {}) {
                     break;
                 }
                 scannedInBatch++;
-                if (type === row.memory_type) {
+                if (result.type === row.memory_type) {
                     batchUnchanged++;
                 }
                 else {
                     batchReclassified++;
                 }
-                writes.push({ id: row.id, type });
+                writes.push({ id: row.id, type: result.type, score: result.score });
                 committedRowid = row.__rowid;
             }
             // Commit the resolved writes, then persist the cursor at the last fully
             // resolved rowid (crash-safe + infra-abort-safe: a re-run resumes there).
-            const updateStmt = db.prepare("UPDATE memories SET memory_type = ? WHERE id = ?");
+            const updateStmt = db.prepare("UPDATE memories SET memory_type = ?, base_strength = ? WHERE id = ?");
             const tx = db.transaction(() => {
                 for (const w of writes)
-                    updateStmt.run(w.type, w.id);
+                    updateStmt.run(w.type, w.score, w.id);
             });
             tx();
             (0, state_js_1.updateState)((s) => { s.typeCursor = committedRowid; }, stateDir);

package/hermes-plugin/hicortex/plugin.yaml

@@ -1,5 +1,5 @@
 name: hicortex
-version: 0.7.2
+version: 0.7.3
 description: "Self-learning memory for Hermes agents — every session is distilled into lessons overnight, and your agent wakes up wiser. Pushes a compact per-turn recall index (lazy-loaded with hicortex_get), injects fresh lessons plus a per-agent standing context block, and exposes the full 9-tool memory surface (search, get, recent, ingest, lessons, index, graph, update, delete) via a shared Hicortex server. Stdlib-only."
 pip_dependencies: []
 hooks: []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.17.4",
+  "version": "0.17.6",
   "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": {