@gamaze/hicortex 0.20.4 → 0.20.6

package/dist/retrieval.d.ts

@@ -147,6 +147,20 @@ export declare function recallQueryVector(registry: CentroidStore, sessionId: st
  * old → new). One query, not per-candidate.
  */
 export declare function findSupersededIds(db: Database.Database, candidateIds: string[]): Set<string>;
+/**
+ * The full ranking-demotion set among `candidateIds` (#384): the UNION of
+ * (a) sources of a `superseded_by` link (legacy + stageSupersession — link
+ * driven, works on pre-v14 rows with NULL status) and (b) rows whose
+ * `memories.status` is 'superseded' or 'retracted' (reconsolidation marks +
+ * explicit ingest marks). `corrected` is deliberately NOT demoting — a
+ * rewritten memory carries the CORRECTION, and demoting it would bury the
+ * fix (the exact failure reconsolidation exists to repair). `absorbed` needs
+ * no entry here: absorbed rows have no vector/FTS row and are filtered at
+ * candidacy. One batched query, both call sites (retrieve + searchRecent).
+ * Byte-identical behavior for memories with no correction relationship
+ * (NULL status, no link) — they never match either arm.
+ */
+export declare function findDemotedIds(db: Database.Database, candidateIds: string[]): Set<string>;
 /**
  * Convert an L2 distance (as returned by sqlite-vec's vec0 `distance`) to
  * cosine similarity. Valid because our embeddings are L2-normalized

package/dist/retrieval.js

@@ -63,6 +63,7 @@ exports.getSessionIntent = getSessionIntent;
 exports.blendQueryVector = blendQueryVector;
 exports.recallQueryVector = recallQueryVector;
 exports.findSupersededIds = findSupersededIds;
+exports.findDemotedIds = findDemotedIds;
 exports.l2ToCosine = l2ToCosine;
 exports.effectiveStrength = effectiveStrength;
 exports.computeScore = computeScore;
@@ -276,6 +277,34 @@ function findSupersededIds(db, candidateIds) {
         .all(...candidateIds);
     return new Set(rows.map((r) => r.source_id));
 }
+/**
+ * The full ranking-demotion set among `candidateIds` (#384): the UNION of
+ * (a) sources of a `superseded_by` link (legacy + stageSupersession — link
+ * driven, works on pre-v14 rows with NULL status) and (b) rows whose
+ * `memories.status` is 'superseded' or 'retracted' (reconsolidation marks +
+ * explicit ingest marks). `corrected` is deliberately NOT demoting — a
+ * rewritten memory carries the CORRECTION, and demoting it would bury the
+ * fix (the exact failure reconsolidation exists to repair). `absorbed` needs
+ * no entry here: absorbed rows have no vector/FTS row and are filtered at
+ * candidacy. One batched query, both call sites (retrieve + searchRecent).
+ * Byte-identical behavior for memories with no correction relationship
+ * (NULL status, no link) — they never match either arm.
+ */
+function findDemotedIds(db, candidateIds) {
+    if (candidateIds.length === 0)
+        return new Set();
+    const placeholders = candidateIds.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT DISTINCT id FROM (
+         SELECT source_id AS id FROM memory_links
+          WHERE relationship = 'superseded_by' AND source_id IN (${placeholders})
+         UNION
+         SELECT id FROM memories
+          WHERE status IN ('superseded', 'retracted') AND id IN (${placeholders})
+       )`)
+        .all(...candidateIds, ...candidateIds);
+    return new Set(rows.map((r) => r.id));
+}
 /**
  * Placeholder L2 distance for candidates that have no measured vector
  * distance (FTS-only hits and graph-discovered neighbors). Chosen so that
@@ -608,6 +637,11 @@ async function retrieve(db, embedFn, query, options) {
         const mem = storage.getMemory(db, gid);
         if (!mem)
             continue;
+        // #384: absorbed memories never enter via the graph either — they keep
+        // their link rows (evidence + rollback reference), so graph traversal can
+        // reach them, but they are invisible to recall by contract.
+        if (mem.status === "absorbed")
+            continue;
         // #203: project check removed — project is a soft affinity in computeScore,
         // not a filter. 0.16.x: privacy check removed — the column is vestigial,
         // never filtered. sourceAgent stays a hard filter.
@@ -622,8 +656,10 @@ async function retrieve(db, embedFn, query, options) {
     const scored = [];
     const maxRrf = Math.max(...([...rrfScores.values()].length > 0 ? [...rrfScores.values()] : [1]));
     // One query for the whole candidate set (#191 Phase B): superseded memories
-    // are demoted in computeScore rather than strength-penalized.
-    const supersededIds = findSupersededIds(db, [...candidateMap.keys()]);
+    // are demoted in computeScore rather than strength-penalized. #384: the set
+    // is the full demotion set — link-driven supersessions UNION status-marked
+    // superseded/retracted rows (see findDemotedIds).
+    const supersededIds = findDemotedIds(db, [...candidateMap.keys()]);
     // #203: ONE batched load of every candidate's graded domain tags — fed to
     // computeScore for domain affinity. Only needed when the scope carries
     // missionDomains; absent otherwise (skips the query entirely on /search and
@@ -714,7 +750,9 @@ function searchRecent(db, options) {
         ? [...connectionCounts.values()]
         : [0]));
     const scored = [];
-    const supersededRecent = findSupersededIds(db, candidates.map((c) => c.id));
+    // #384: same full demotion set as retrieve() — link-driven supersessions
+    // UNION status-marked superseded/retracted rows (findDemotedIds).
+    const supersededRecent = findDemotedIds(db, candidates.map((c) => c.id));
     for (const mem of candidates) {
         const connCount = connectionCounts.get(mem.id) ?? 0;
         const score = computeScore(mem, DEFAULT_GRAPH_DISTANCE, connCount, maxConnections, now, {

package/dist/state.d.ts

@@ -16,7 +16,7 @@
  * Note: ~/.hicortex/config.json is intentionally NOT merged here. Config is
  * user-edited and tracked separately from machine state.
  */
-import type { LicenseInfo, ModuleIndex } from "./types.js";
+import type { LicenseInfo, ModuleIndex, ResolutionBandStat } from "./types.js";
 /** Persisted tier information — reflects the last successful validation. */
 export interface PersistedTier {
     /** Tier name from the validation API response. */
@@ -60,6 +60,17 @@ export interface HicortexState {
      * gradually over many nights.
      */
     supersessionCursor?: number;
+    /**
+     * Resume cursor for the nightly's reconsolidation stage (#384) — highest
+     * memories.rowid whose candidates have been evaluated (or infra-skipped)
+     * this run. Absent/0 = never run. Same advance-past-considered-candidates
+     * discipline as supersessionCursor, with one addition: when a rewrite group
+     * could not be applied (budget exhausted / rewrite-call infra error), the
+     * cursor holds BELOW the earliest candidate contributing to an un-applied
+     * group so those pairs are re-detected next run — a confirmed correction is
+     * never silently dropped by the cursor passing it.
+     */
+    reconsolidationCursor?: number;
     /**
      * Resume cursor for `hicortex classify-types` (#216) — highest memories.rowid
      * whose batch has been fully committed. Absent/0 = never run (or reset).
@@ -89,6 +100,17 @@ export interface HicortexState {
      * which means the first run is never throttled (correct: no baseline yet).
      */
     llmTokensLastRun?: number;
+    /**
+     * Cumulative per-band verdict statistics for the unified resolution pass
+     * (#392), keyed by cosine band label ("0.75-0.8", …, ">=0.92" — labels
+     * derive from the live floor/ceiling at write time). Accumulated across
+     * runs, never reset: labeled calibration evidence for moving the
+     * floor/ceiling boundaries later. The deterministic zone persists its own
+     * band; the reconsolidation stage persists the judged bands. Never written
+     * on dry runs. The per-run snapshot lives in the stage report
+     * (`stages.reconsolidation.band_stats`).
+     */
+    resolutionBandStats?: Record<string, ResolutionBandStat>;
 }
 /**
  * Load the state file. Returns an empty state if the file is missing

package/dist/storage.d.ts

@@ -46,6 +46,27 @@ export declare function touchMemoriesShown(db: Database.Database, memoryIds: str
  * Delete a memory, its vector, its tags, and all its links.
  */
 export declare function deleteMemory(db: Database.Database, memoryId: string): void;
+/**
+ * A memory's rowid in `memories` (the FTS table's rowid), or null when the
+ * row does not exist. Shared by the absorb primitive below and the
+ * reconsolidation stage's FTS bookkeeping (#384/#392).
+ */
+export declare function memoryRowid(db: Database.Database, memoryId: string): number | null;
+/**
+ * Drop a memory's retrieval candidacy: status `absorbed`, vector row deleted,
+ * FTS row deleted (direct DELETE — the AFTER UPDATE trigger's `UPDATE … WHERE
+ * rowid` is a silent no-op on the missing row, so later column edits cannot
+ * resurrect it). The plain row + links are KEPT (evidence, session lineage,
+ * rollback reference). Must run inside a transaction.
+ *
+ * The shared absorb primitive (#392): the reconsolidation stage's rewrite
+ * path (via the `absorbTrigger` re-export) AND dedup merge losers both fold a
+ * row into invisible-evidence state through this ONE function, so the
+ * "absorbed" vocabulary can never drift between them. Tags/domain are the
+ * CALLER's concern (the rewrite path clears the target's; a dedup merge
+ * clears the loser's before absorbing).
+ */
+export declare function absorbMemory(db: Database.Database, memoryId: string): void;
 /** Options for setMemoryTags (graded-schema spec 2026-07-07). */
 export interface SetMemoryTagsOptions {
     /**
@@ -223,6 +244,8 @@ export declare function insertMemoriesBatch(db: Database.Database, memories: Arr
 export declare function countMemories(db: Database.Database): number;
 /**
  * Get memories created in the last N days, newest first.
+ * Absorbed memories are excluded (#384): they are invisible to recall — the
+ * plain row is evidence only, never a recent-recall candidate.
  */
 export declare function getRecentMemories(db: Database.Database, days?: number, limit?: number): Memory[];
 /**
@@ -245,5 +268,7 @@ export declare function getPruneCandidates(db: Database.Database, cutoffIso: str
 export declare function getAllLinkCounts(db: Database.Database): Map<string, number>;
 /**
  * Get all memories with default base_strength (never scored).
+ * Absorbed memories are excluded (#384): they are invisible to recall, so
+ * importance-scoring one would spend an LLM call on dead evidence.
  */
 export declare function getUnscoredMemories(db: Database.Database): Memory[];

package/dist/storage.js

@@ -13,6 +13,8 @@ exports.updateMemory = updateMemory;
 exports.strengthenMemory = strengthenMemory;
 exports.touchMemoriesShown = touchMemoriesShown;
 exports.deleteMemory = deleteMemory;
+exports.memoryRowid = memoryRowid;
+exports.absorbMemory = absorbMemory;
 exports.setMemoryTags = setMemoryTags;
 exports.getMemoryTags = getMemoryTags;
 exports.getMemoryTagsWeighted = getMemoryTagsWeighted;
@@ -132,6 +134,10 @@ const ALLOWED_UPDATE_FIELDS = new Set([
     "privacy",
     "memory_type",
     "updated_at",
+    // Reconsolidation state (#384, migration v14): written by the
+    // reconsolidation stage, explicit ingest marks, and history rollback.
+    // Code-defined vocabulary — see Memory.status.
+    "status",
 ]);
 /**
  * Update specific fields on a memory.
@@ -185,6 +191,36 @@ function deleteMemory(db, memoryId) {
     db.prepare("DELETE FROM memory_vectors WHERE id = ?").run(memoryId);
     db.prepare("DELETE FROM memories WHERE id = ?").run(memoryId);
 }
+/**
+ * A memory's rowid in `memories` (the FTS table's rowid), or null when the
+ * row does not exist. Shared by the absorb primitive below and the
+ * reconsolidation stage's FTS bookkeeping (#384/#392).
+ */
+function memoryRowid(db, memoryId) {
+    const row = db.prepare("SELECT rowid AS rid FROM memories WHERE id = ?").get(memoryId);
+    return row?.rid ?? null;
+}
+/**
+ * Drop a memory's retrieval candidacy: status `absorbed`, vector row deleted,
+ * FTS row deleted (direct DELETE — the AFTER UPDATE trigger's `UPDATE … WHERE
+ * rowid` is a silent no-op on the missing row, so later column edits cannot
+ * resurrect it). The plain row + links are KEPT (evidence, session lineage,
+ * rollback reference). Must run inside a transaction.
+ *
+ * The shared absorb primitive (#392): the reconsolidation stage's rewrite
+ * path (via the `absorbTrigger` re-export) AND dedup merge losers both fold a
+ * row into invisible-evidence state through this ONE function, so the
+ * "absorbed" vocabulary can never drift between them. Tags/domain are the
+ * CALLER's concern (the rewrite path clears the target's; a dedup merge
+ * clears the loser's before absorbing).
+ */
+function absorbMemory(db, memoryId) {
+    const rid = memoryRowid(db, memoryId);
+    updateMemory(db, memoryId, { status: "absorbed" });
+    db.prepare("DELETE FROM memory_vectors WHERE id = ?").run(memoryId);
+    if (rid !== null)
+        db.prepare("DELETE FROM memories_fts WHERE rowid = ?").run(rid);
+}
 /**
  * Set a memory's classification tags (graded schema model).
  *
@@ -451,12 +487,14 @@ function searchFts(db, query, limit = 10, sourceAgent) {
  * Create a link between two memories.
  */
 function addLink(db, sourceId, targetId, relationship, strength = 0.5) {
-    // Guard: superseded_by is the sole ranking-demotion signal, so never let a
-    // different relationship clobber an existing superseded_by link for the same
-    // pair — INSERT OR REPLACE would otherwise silently remove the demotion.
-    if (relationship !== "superseded_by") {
+    // Guard: superseded_by and corrected_by are the ranking-demotion /
+    // correction-resolution signals, so never let a different relationship
+    // clobber an existing one for the same pair — INSERT OR REPLACE would
+    // otherwise silently remove the resolution (corrected_by is protected
+    // exactly like superseded_by, #384 AC9).
+    if (relationship !== "superseded_by" && relationship !== "corrected_by") {
         const protectedLink = db
-            .prepare("SELECT 1 FROM memory_links WHERE source_id = ? AND target_id = ? AND relationship = 'superseded_by' LIMIT 1")
+            .prepare("SELECT 1 FROM memory_links WHERE source_id = ? AND target_id = ? AND relationship IN ('superseded_by', 'corrected_by') LIMIT 1")
             .get(sourceId, targetId);
         if (protectedLink)
             return;
@@ -530,11 +568,13 @@ function countMemories(db) {
 }
 /**
  * Get memories created in the last N days, newest first.
+ * Absorbed memories are excluded (#384): they are invisible to recall — the
+ * plain row is evidence only, never a recent-recall candidate.
  */
 function getRecentMemories(db, days = 7, limit = 50) {
     const rows = db
         .prepare(`SELECT * FROM memories
-       WHERE created_at >= datetime('now', ?)
+       WHERE created_at >= datetime('now', ?) AND COALESCE(status, '') != 'absorbed'
        ORDER BY created_at DESC LIMIT ?`)
         .all(`-${days} days`, limit);
     return rows.map(rowToMemory);
@@ -602,11 +642,13 @@ function getAllLinkCounts(db) {
 }
 /**
  * Get all memories with default base_strength (never scored).
+ * Absorbed memories are excluded (#384): they are invisible to recall, so
+ * importance-scoring one would spend an LLM call on dead evidence.
  */
 function getUnscoredMemories(db) {
     const rows = db
         .prepare(`SELECT * FROM memories
-       WHERE base_strength = 0.5
+       WHERE base_strength = 0.5 AND COALESCE(status, '') != 'absorbed'
        ORDER BY ingested_at ASC`)
         .all();
     return rows.map(rowToMemory);

package/dist/type-classify.js

@@ -151,8 +151,10 @@ async function classifyMemoryType(content, llm) {
     for (let attempt = 0; attempt < 2; attempt++) {
         let raw;
         try {
-            // ~20 tokens covers "type score" + headroom for models that add labels.
-            const r = await llm.completeClassify(prompt, 20);
+            // No per-call cap (#391): the classify-tier ceiling (classifyMaxTokens,
+            // default 1024) resolves inside completeClassify — a hardcoded 20
+            // starved reasoning models whose thinking ate the whole output budget.
+            const r = await llm.completeClassify(prompt);
             raw = r.text;
         }
         catch (err) {

package/dist/types.d.ts

@@ -32,6 +32,16 @@ export interface Memory {
     privacy: ("PUBLIC" | "WORK" | "PERSONAL" | "SENSITIVE") | null;
     memory_type: "experience" | "learnings" | "knowledge" | "decisions";
     updated_at: string | null;
+    /**
+     * Reconsolidation state (#384, migration v14). Code-defined vocabulary,
+     * never config: NULL/absent = active (the default, and every pre-v14 row);
+     * 'superseded'/'retracted' = marked stale or wrong (demoted in ranking);
+     * 'corrected' = rewritten in place (does NOT demote — demoting it would
+     * bury the correction); 'absorbed' = invisible to recall (trigger memory
+     * folded into a corrected target — no vector/FTS row, plain row + link
+     * kept as evidence and rollback reference).
+     */
+    status?: string | null;
 }
 /** A link between two memories. */
 export interface MemoryLink {
@@ -67,6 +77,68 @@ export interface MemorySearchResult {
      *  both, or graph traversal). Used by the /recall-index relevance gate. */
     source?: "vector" | "fts" | "both" | "graph";
 }
+/**
+ * Per-cosine-band verdict statistics for the unified resolution pass (#392).
+ * Bands are labeled from the live floor/ceiling ("0.75-0.8", …, ">=0.92").
+ * The stage report carries the per-run snapshot; state.json
+ * `resolutionBandStats` carries the cumulative series — calibration evidence
+ * for moving the floor/ceiling boundaries later, with data.
+ */
+export interface ResolutionBandStat {
+    /** Candidate pairs judged (or deterministically merged) in this band. */
+    pairs: number;
+    /** Verdict/action counts. `merge` counts gated merges (applied or applicable). */
+    merge: number;
+    corrects: number;
+    supersedes: number;
+    none: number;
+    /** Merge verdicts below the confidence gate — both memories kept. */
+    merge_below_gate: number;
+    /** Sum of verdict confidences (divide by `pairs` for the mean). Deterministic merges count 1.0 each. */
+    conf_sum: number;
+    /** Deterministic band only: clusters refused by the metadata rails. */
+    metadata_skipped?: number;
+}
+/**
+ * Report of the deterministic merge zone (#392) — the >= dedupAutoMergeThreshold
+ * band, merged by the dedup core's union-find clustering with ZERO LLM calls.
+ * Computed in dedup.ts (runDeterministicMergeZone); surfaced verbatim as
+ * `stages.reconsolidation.merges`.
+ */
+export interface DeterministicMergeZoneReport {
+    /** The cosine ceiling in force (config dedupAutoMergeThreshold; default 0.92). */
+    threshold: number;
+    /** The pacing cap in force (dedupNightlyMaxMerges; 0 = machinery disabled). */
+    max_merges: number;
+    /** Every cluster found at the threshold (mergeable + mismatch-skipped). */
+    clusters_found: number;
+    /** Clusters that passed the metadata rails (would merge). */
+    mergeable_clusters: number;
+    /** Clusters actually merged this run (apply only; 0 on dry-run). */
+    merged_clusters: number;
+    /** Loser rows absorbed (hidden from recall, kept as evidence) this run. */
+    losers_merged: number;
+    /** Loser links re-pointed onto canonicals this run. */
+    links_repointed: number;
+    /** Clusters skipped — members disagree on project / source_agent. */
+    skipped_metadata_mismatch: number;
+    /** Mergeable clusters NOT attempted because the pacing cap was exhausted. */
+    capped: number;
+    /** Clusters whose merge transaction failed (rolled back; retried next run). */
+    failed: number;
+    /** Apply only: the capture lock was busy — zero merges, fail-soft. */
+    lock_busy?: boolean;
+    /** Apply only: the pre-merge backup failed — zero merges, fail-soft. */
+    backup_failed?: boolean;
+    /** Apply only: path of the pre-merge DB backup. */
+    backup_path?: string;
+    /** Dry-run only: bounded preview of the first 10 mergeable clusters. */
+    preview?: Array<{
+        size: number;
+        canonical_id: string;
+        loser_ids: string[];
+    }>;
+}
 /** Report returned by the consolidation pipeline. */
 export interface ConsolidationReport {
     started_at: string;
@@ -141,6 +213,81 @@ export interface ConsolidationReport {
             /** supersessionCursor after this run (unchanged in dry-run). */
             cursor: number;
         };
+        /**
+         * Reconsolidation (#384) — runs after supersession, before decay/prune.
+         * Since #392 this is THE unified resolution stage: its verdict also carries
+         * a `merge` disposition, and the deterministic merge zone (pairs at/above
+         * `dedupAutoMergeThreshold`) runs inside it, LLM-free, before the scan.
+         */
+        reconsolidation?: {
+            /** Candidates examined this run (rowid > cursor; no shape filter). */
+            scanned: number;
+            /** Pairs actually sent to the verdict LLM (detection + explicit-mark verification). */
+            pairs_evaluated: number;
+            /**
+             * #394: pairs the similarity floor discovered this run (KNN neighbors
+             * at/above correctionMinSimilarity), counted before any skip or
+             * judgment — the only sizing number a dry-run can show, where
+             * pairs_evaluated is always 0.
+             */
+            pairs_discovered: number;
+            /** #394: discovered pairs with no resolution link yet — the actionable
+             * candidates (deterministic-zone work + would-be verdict calls). */
+            pairs_discovered_unlinked: number;
+            /** Targets rewritten in place this run (one history row each). */
+            rewritten: number;
+            /** Triggers absorbed (invisible to recall: vector + FTS dropped). */
+            absorbed: number;
+            /** Triggers kept live by their disposition (standalone substance). */
+            kept_linked: number;
+            /** Memories marked status 'superseded' (mark-only path). */
+            marked_superseded: number;
+            /** Memories marked status 'retracted' (mark-only: below gate / non-fact / failed contract). */
+            marked_retracted: number;
+            /** Verdicts that were `corrects` but below correctionRewriteMinConfidence. */
+            below_gate: number;
+            /** Rewrite groups degraded to mark-only on a failed rewrite contract. */
+            contract_failed: number;
+            /** Verdict/rewrite calls skipped on a parse/infra error (retried naturally). */
+            skipped_infra: number;
+            /** Pairs skipped because a resolution link already existed (either direction). */
+            skipped_idempotent: number;
+            /** Explicit ingest marks verified and upgraded into a rewrite group. */
+            explicit_verified: number;
+            /** Explicit marks whose verification diverged (mark retained untouched). */
+            explicit_divergent: number;
+            /** reconsolidationCursor after this run (unchanged in dry-run). */
+            cursor: number;
+            /**
+             * #392: the deterministic merge zone's own report (pairs >= the
+             * ceiling, union-find merged, zero LLM). Present on every run —
+             * including quiet-night skips (a stock install with a pre-upgrade
+             * backlog still drains it, LLM-free).
+             */
+            merges: DeterministicMergeZoneReport;
+            /** #392: judged-zone pair merges applied this run (merge verdicts at/above the confidence gate). */
+            merge_pairs_applied: number;
+            /** #392: merge verdicts below correctionRewriteMinConfidence — both memories kept. */
+            merge_below_gate: number;
+            /**
+             * #392: pairs the scan saw at/above the ceiling — owned by the
+             * deterministic zone (or waiting for its cap), never LLM-judged.
+             */
+            skipped_above_ceiling: number;
+            /**
+             * #392: judged merge pairs refused by the metadata rails (project /
+             * source_agent disagreement). Both memories kept; the cursor advances —
+             * the verdict was rendered, this is not an infra failure.
+             */
+            skipped_metadata_mismatch: number;
+            /**
+             * #392: per-run verdict statistics by cosine band ("0.75-0.8" …
+             * ">=0.92"; labels derive from the live floor/ceiling). Calibration
+             * evidence for moving the boundaries later; the cumulative series lives
+             * in state.json `resolutionBandStats`.
+             */
+            band_stats: Record<string, ResolutionBandStat>;
+        };
         decay_prune?: {
             candidates: number;
             pruned: number;
@@ -345,6 +492,18 @@ export interface HicortexConfig {
      * when it finishes early. Read in llm.ts; see #220.
      */
     maxTokens?: number;
+    /**
+     * Max output tokens for the classify tier ONLY — the short JSON-verdict
+     * calls: correction/supersession verdicts, rewrite contracts, and type +
+     * domain tag classification. Default 1024. A ceiling, not a target
+     * (generation stops at the model's natural end) — raise it when a
+     * reasoning-style model spends the budget on internal reasoning and returns
+     * empty verdicts (the pre-#391 hardcoded per-call caps starved exactly that
+     * shape; a local non-reasoning model is unaffected by the raise).
+     * `maxTokens` continues to govern the heavy phases (distill/reflect).
+     * Read in llm.ts; see #391.
+     */
+    classifyMaxTokens?: number;
     /**
      * Toggle the model's internal reasoning ("thinking") stream on the openai-compat
      * path — applies to ALL phases (distill / reflect / classify / scoring) since one
@@ -547,6 +706,45 @@ export interface HicortexConfig {
     orgName?: string;
     /** Plan/tier label rendered as a small badge (e.g. "Cloud · Early bird"). */
     planLabel?: string;
+    /**
+     * Minimum cosine similarity for a reconsolidation candidate pair (#384):
+     * each new-since-cursor memory is paired with up to 5 older KNN neighbors
+     * at/above this bar before the verdict call. Default 0.75 — a touch wider
+     * than the supersession stage's 0.80 because a retraction often rides inside
+     * an otherwise unrelated memory; the verdict + confidence gate carry the
+     * precision. Number in (0, 1]; invalid/absent keeps the default.
+     */
+    correctionMinSimilarity?: number;
+    /**
+     * Minimum verdict confidence for the REWRITE fork of reconsolidation (#384):
+     * a `corrects` verdict at/above this bar on a fact-shaped target is rewritten
+     * in place; below it the pair degrades to mark-only (a weak mark is
+     * recoverable, a weak rewrite is corruption). Default 0.80. Number in
+     * (0, 1]; invalid/absent keeps the default. Since #392 this same gate also
+     * decides whether a `merge` verdict is applied (analogous reasoning: a weak
+     * merge keeps both memories, a confirmed merge hides one).
+     */
+    correctionRewriteMinConfidence?: number;
+    /**
+     * Deterministic merge ceiling for the unified resolution pass (#392): memory
+     * pairs at/above this cosine are merged by the dedup core's union-find
+     * clustering with ZERO LLM calls; pairs in [correctionMinSimilarity, this
+     * value) get the one unified verdict call (merge/corrects/supersedes/none).
+     * Default 0.92 (the #100/#191 calibration). The legacy `dedupMergeThreshold`
+     * key is honored as a fallback when this key is absent. Number in (0, 1];
+     * invalid/absent keeps the default. Also read by the manual `hicortex dedup`
+     * CLI (same precedence: --threshold > this key > legacy key > 0.92).
+     */
+    dedupAutoMergeThreshold?: number;
+    /**
+     * Pacing cap on merge OPERATIONS per nightly run (#392): deterministic-zone
+     * clusters plus judged pair merges count against ONE cap, so a
+     * misbehaving-distiller burst is bounded and a large pre-existing backlog
+     * drains over a few nights rather than in one run. Default 250. `0` disables
+     * the merge machinery entirely (the deterministic zone is skipped; a
+     * confirmed merge verdict keeps both memories). Non-negative integer.
+     */
+    dedupNightlyMaxMerges?: number;
 }
 /** A config-owned life-sphere domain (see HicortexConfig.domains). */
 export interface DomainDef {

package/hermes-plugin/hicortex/provider.py

@@ -484,8 +484,12 @@ class HicortexProvider(MemoryProvider):
             {
                 "name": "hicortex_search",
                 "description": (
-                    "Search long-term memory using semantic similarity. Returns the most "
-                    "relevant memories from past sessions."
+                    "Search shared long-term memory (all agents, all sessions). "
+                    "CALL THIS BEFORE assuming, guessing, or asking the user about "
+                    "anything that may have come up before: prior decisions, "
+                    "preferences, project facts, people, hardware, past incidents. "
+                    "If you are about to write 'I don't have information about…', "
+                    "search first."
                 ),
                 "parameters": {
                     "type": "object",
@@ -504,13 +508,13 @@ class HicortexProvider(MemoryProvider):
                 "name": "hicortex_get",
                 "description": (
                     "Fetch ONE memory's full content by id — use this to lazy-load "
-                    "entries from the recall index or from search results whose "
-                    "snippet was not enough. Fetching a memory marks it as used "
-                    "(strengthens it), so fetch entries that could change your "
-                    "action — not every shown one. When the memory shapes your "
-                    "answer, cite it as given in the response — mark a fetched "
-                    "memory FETCHED and a one-line entry cited unread SNIPPET; "
-                    "don't pass SNIPPET off as established."
+                    "entries from the '## Memory recall (auto)' index or from search "
+                    "results whose snippet was not enough. Fetching a memory marks "
+                    "it as used (strengthens it), so fetch entries that could "
+                    "change your action — not every shown one. When the memory "
+                    "shapes your answer, cite it to the user (id + date + origin "
+                    "agent) — mark a fetched memory `FETCHED` and a one-line entry "
+                    "cited unread `SNIPPET`; don't pass SNIPPET off as established."
                 ),
                 "parameters": {
                     "type": "object",
@@ -526,9 +530,9 @@ class HicortexProvider(MemoryProvider):
             {
                 "name": "hicortex_recent",
                 "description": (
-                    "Get recent memories, optionally filtered by project. Queryless recall "
-                    "of the latest memories by project, ranked by importance. Useful to "
-                    "catch up on what happened recently."
+                    "Get recent memories, optionally filtered by project. CALL THIS "
+                    "AT THE START of substantive work on a project to catch up on "
+                    "its latest state — cheaper than asking the user what happened."
                 ),
                 "parameters": {
                     "type": "object",
@@ -542,7 +546,9 @@ class HicortexProvider(MemoryProvider):
                 "name": "hicortex_ingest",
                 "description": (
                     "Store a new memory in long-term storage. "
-                    "Use for Knowledge, Decisions, or Learnings."
+                    "Use for Knowledge, Decisions, or Learnings. Capture is "
+                    "automatic (nightly) — use this ONLY for explicitly requested "
+                    "learnings, never routine content."
                 ),
                 "parameters": {
                     "type": "object",
@@ -561,8 +567,10 @@ class HicortexProvider(MemoryProvider):
             {
                 "name": "hicortex_lessons",
                 "description": (
-                    "Get actionable Learnings distilled from past sessions. "
-                    "Auto-generated insights about mistakes to avoid."
+                    "Get actionable Learnings — auto-generated insights about "
+                    "mistakes to avoid. CALL THIS before retrying an approach that "
+                    "failed before, or when picking up work where past problems may "
+                    "have been recorded."
                 ),
                 "parameters": {
                     "type": "object",
@@ -575,7 +583,9 @@ class HicortexProvider(MemoryProvider):
                 "name": "hicortex_index",
                 "description": (
                     "Get the knowledge domain index — shows what topics and projects "
-                    "are stored in memory, grouped by domain."
+                    "are stored in memory, grouped by domain. Call before a broad "
+                    "search to see which knowledge domains exist, or when unsure "
+                    "what the memory covers."
                 ),
                 "parameters": {
                     "type": "object",
@@ -586,7 +596,9 @@ class HicortexProvider(MemoryProvider):
                 "name": "hicortex_graph",
                 "description": (
                     "Query the memory knowledge graph — find connected memories, "
-                    "hub nodes, or paths between memories."
+                    "hub nodes, or paths between memories. Use it to explore "
+                    "memories connected to one you just fetched, or to find hub "
+                    "memories in a domain."
                 ),
                 "parameters": {
                     "type": "object",