@gamaze/hicortex 0.20.4 → 0.20.5

package/README.md

@@ -253,6 +253,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. |
+| `classifyMaxTokens` | Max output tokens for the classify tier — the short JSON-verdict calls (correction/supersession verdicts, rewrite contracts, type and domain tag classification). Default 1024. A ceiling, not a target: raise it when a reasoning-style model spends the budget on internal reasoning and returns empty verdicts; `maxTokens` keeps governing the heavy phases (distill, reflect). |
 | `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). |
 | `llmTimeoutMs` | The ONE timeout ceiling on every LLM call in every phase (default 900000 = 15 min). The LLM request paths disable the HTTP client's hidden 5-minute response-header timer, so this knob is the only bound — one place to tune when the endpoint is slow, no per-phase special cases. |
@@ -303,7 +304,9 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `recallMinPromptChars` | Prompts shorter than this skip the recall index (default: 20) |
 | `recallTitleChars` | Chars of each memory's first line shown in an index entry (default: 100, range 40–400). Reverted from 150 on 2026-08-03: a full-corpus relevance eval found 100 and 150 statistically identical while 100 saves ~13% of the block's tokens |
 | `sessionIntentWeight` | Blend weight of the session-intent rolling centroid in the recall search vector: `query = (1-w)·prompt + w·centroid` (default: 0.33; set 0 to disable — pure-prompt recall, the kill-switch). The first turn of a session searches with pure prompt and seeds the centroid; subsequent turns blend so recall follows the session's intent instead of being query-literal. The EMA rate (0.4) is a shipped constant, not configurable |
-| `dedupMergeThreshold` | Minimum cosine similarity for `hicortex dedup` to cluster memories as near-duplicates (default: 0.92) |
+| `dedupAutoMergeThreshold` | The deterministic merge ceiling of the unified resolution pass: memory pairs at/above this cosine merge automatically (zero LLM) via the dedup core's clustering; pairs between `correctionMinSimilarity` and this value get the one merge/corrects/supersedes/none verdict. Also the default threshold for `hicortex dedup` (default: 0.92) |
+| `dedupMergeThreshold` | Legacy alias for `dedupAutoMergeThreshold`, still honored when the newer key is absent |
+| `dedupNightlyMaxMerges` | Pacing cap on merge operations per nightly run — deterministic-zone clusters plus verdict-confirmed pair merges count against one cap, so a large duplicate backlog drains over a few nights (default: 250; `0` disables the merge machinery) |
 | `supersessionMinSimilarity` | Minimum cosine similarity for a nightly supersession candidate pair (default: 0.80) |
 | `supersessionMaxCalls` | Max classify-tier LLM calls the nightly's supersession stage spends per run (default: 30) |
 | `supersessionPenalty` | Multiplier applied to a superseded memory's `base_strength` (default: 0.5) |

package/dist/backup.d.ts

@@ -129,19 +129,23 @@ export declare function runBackupHook(artifactPath: string, command: string | un
  */
 export declare function newestBackupArtifactMs(dir: string): number | undefined;
 /**
- * Prune a backup dir to the `retention` newest artifacts (#327). Matches ONLY
- * files named `hicortex-*.tar.gz` (the nightly/CLI artifact pattern) — anything
- * else in the dir (operator copies, notes) is never touched. Keeps the newest
- * `retention` by mtime, with the ISO filename (time-ordered by construction)
- * as a DESCENDING tie-break so equal mtimes resolve deterministically (the
- * just-written artifact is the newest and always survives); deletes the rest,
- * oldest first. `retention <= 0` keeps all.
+ * Prune a backup dir to the `retention` newest artifacts (#327). By default
+ * matches ONLY files named `hicortex-*.tar.gz` (the nightly/CLI artifact
+ * pattern); the optional `pattern` override scopes the prune to another
+ * product-owned filename family — e.g. the pre-dedup merge backups
+ * (`pre-dedup-*.db`, #392) keep their own retention count INDEPENDENT of the
+ * full-backup artifacts. Anything else in the dir (operator copies, notes) is
+ * never touched. Keeps the newest `retention` by mtime, with the ISO filename
+ * (time-ordered by construction) as a DESCENDING tie-break so equal mtimes
+ * resolve deterministically (the just-written artifact is the newest and
+ * always survives); deletes the rest, oldest first. `retention <= 0` keeps
+ * all.
  *
  * Best-effort by design: a per-file unlink failure logs and continues (a
  * stale extra artifact is cheap; failing the nightly AFTER a good backup was
  * written is not). Returns the number actually removed.
  */
-export declare function pruneBackupArtifacts(dir: string, retention: number): number;
+export declare function pruneBackupArtifacts(dir: string, retention: number, pattern?: RegExp): number;
 export interface BackupCliOptions {
     /** `--out <dir>` — output directory (the artifact is auto-named). Takes precedence over `config.backupDir`. Mutually exclusive with stdout. */
     outDir?: string;

package/dist/backup.js

@@ -282,19 +282,23 @@ function newestBackupArtifactMs(dir) {
     return newest;
 }
 /**
- * Prune a backup dir to the `retention` newest artifacts (#327). Matches ONLY
- * files named `hicortex-*.tar.gz` (the nightly/CLI artifact pattern) — anything
- * else in the dir (operator copies, notes) is never touched. Keeps the newest
- * `retention` by mtime, with the ISO filename (time-ordered by construction)
- * as a DESCENDING tie-break so equal mtimes resolve deterministically (the
- * just-written artifact is the newest and always survives); deletes the rest,
- * oldest first. `retention <= 0` keeps all.
+ * Prune a backup dir to the `retention` newest artifacts (#327). By default
+ * matches ONLY files named `hicortex-*.tar.gz` (the nightly/CLI artifact
+ * pattern); the optional `pattern` override scopes the prune to another
+ * product-owned filename family — e.g. the pre-dedup merge backups
+ * (`pre-dedup-*.db`, #392) keep their own retention count INDEPENDENT of the
+ * full-backup artifacts. Anything else in the dir (operator copies, notes) is
+ * never touched. Keeps the newest `retention` by mtime, with the ISO filename
+ * (time-ordered by construction) as a DESCENDING tie-break so equal mtimes
+ * resolve deterministically (the just-written artifact is the newest and
+ * always survives); deletes the rest, oldest first. `retention <= 0` keeps
+ * all.
  *
  * Best-effort by design: a per-file unlink failure logs and continues (a
  * stale extra artifact is cheap; failing the nightly AFTER a good backup was
  * written is not). Returns the number actually removed.
  */
-function pruneBackupArtifacts(dir, retention) {
+function pruneBackupArtifacts(dir, retention, pattern = /^hicortex-.*\.tar\.gz$/) {
     if (!Number.isFinite(retention) || retention <= 0)
         return 0;
     let names;
@@ -306,7 +310,7 @@ function pruneBackupArtifacts(dir, retention) {
         return 0;
     }
     const artifacts = names
-        .filter((n) => /^hicortex-.*\.tar\.gz$/.test(n))
+        .filter((n) => pattern.test(n))
         .map((n) => {
         const abs = (0, node_path_1.join)(dir, n);
         let mtimeMs = 0;

package/dist/claude-desktop.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Claude Desktop auto-configuration (#381) — the init-side writer for the
+ * `claude_desktop_config.json` MCP entry.
+ *
+ * Claude Desktop's ONLY stdio MCP route is this hand-edited file (no CLI, no
+ * plugin discovery), which is why Desktop never had an init step while CC
+ * (`claude mcp add`), Pi, and opencode (dropped extension files) did. The
+ * 0.20.4 `hicortex mcp` stdio bridge makes such an entry meaningful, so init
+ * now offers to write it — the same auto-detect pattern as the other
+ * harnesses, gated on the Claude Desktop config DIRECTORY existing (the
+ * config FILE may not exist yet; creating it fresh is in scope).
+ *
+ * Two properties dominate the design:
+ *
+ *   1. IT IS ANOTHER APP'S FILE. `claude_desktop_config.json` is owned by
+ *      Claude Desktop and carries the user's other servers and app settings.
+ *      The write is therefore merge-safe (preserve EVERY top-level key and
+ *      every other server; touch only `mcpServers.hicortex`), takes a
+ *      timestamped `.bak` copy of the existing file first, lands via
+ *      tmp-write + JSON-validate + rename in the same directory (atomic),
+ *      and REFUSES — touching nothing, not even a backup — when the existing
+ *      file is not valid JSON. Unlike our own config.json there is no repair
+ *      flow here (quarantening another app's config would break IT); the
+ *      user fixes the file by hand with the snippet init prints.
+ *
+ *   2. THE COMMAND MUST BE AN ABSOLUTE NPX PATH. Desktop is a GUI app and
+ *      does not inherit the shell PATH — a bare "npx" command is the #1
+ *      Desktop MCP failure mode. Resolution walks PATH plus the common
+ *      install locations and rejects npm's ephemeral `/_npx/` cache (#176: a
+ *      path that dies on the next cache GC — the entry would break silently
+ *      weeks later). Unresolvable → manual instructions, nothing written.
+ *      Windows .cmd shims cannot be spawned by Electron without a shell, so
+ *      they are wrapped in `cmd /c`.
+ *
+ * Every helper is pure/parametrised (platform/env/home/exists injected) so
+ * the suite covers darwin/win32/linux without touching a real machine. This
+ * module deliberately imports NOTHING from init.ts (init imports this — no
+ * cycle); the package spec is passed in from init's getPackageSpec().
+ */
+/**
+ * The Claude Desktop config directory for this platform, or null where no
+ * Desktop build exists (Linux → silent skip). Parametrised so tests cover
+ * the platform matrix without a real machine. Detection in init is
+ * `desktopConfigDir() !== null && existsSync(dir)` — the config FILE itself
+ * may legitimately not exist yet.
+ */
+export declare function desktopConfigDir(platform?: NodeJS.Platform, env?: Record<string, string | undefined>, home?: string): string | null;
+export interface DesktopNpxResolveOptions {
+    /** The PATH string to search (default: process.env.PATH). */
+    pathEnv?: string;
+    /** Platform under test (default: the real one). */
+    platform?: NodeJS.Platform;
+    /** Home dir for the ~-relative common locations (default: homedir()). */
+    home?: string;
+    /** Env for APPDATA on win32 (default: process.env). */
+    env?: Record<string, string | undefined>;
+    /** Existence seam (default: existsSync) — unit tests pass fixture sets. */
+    exists?: (candidatePath: string) => boolean;
+}
+/**
+ * Resolve an ABSOLUTE npx path for the Desktop entry, or null when nothing
+ * durable exists (init then prints manual instructions and writes nothing).
+ * Rejects npm's ephemeral npx cache in BOTH separator spellings — unix
+ * `/_npx/` and Windows `\_npx\` — a bare includes("/_npx/") would let the
+ * win32 form through (#176: the path dies on the next cache GC).
+ */
+export declare function resolveDesktopNpxPath(options?: DesktopNpxResolveOptions): string | null;
+/** The `mcpServers.hicortex` value — a Claude Desktop stdio server entry. */
+export interface DesktopServerEntry {
+    command: string;
+    args: string[];
+    /** Only in remote mode; absent (not empty) in local/loopback mode. */
+    env?: Record<string, string>;
+}
+/**
+ * Build the stdio entry for the `hicortex mcp` bridge. NO "type" field —
+ * stdio is implied for Desktop entries (the CC `.claude.json` writer needs
+ * `"type":"sse"`; this is the other shape). A `.cmd`/`.bat` shim is wrapped
+ * in `cmd /c` because Electron spawns without a shell and cannot exec a cmd
+ * script directly. An empty/absent env omits the key entirely — a local
+ * entry must carry no env (the bridge autostarts the daemon; loopback
+ * bypasses auth).
+ */
+export declare function buildDesktopServerEntry(npxPath: string, packageSpec: string, env?: Record<string, string>): DesktopServerEntry;
+/**
+ * Loopback check for a server URL — decides whether the Desktop entry needs
+ * an env block at all (local: none, the bridge resolves + autostarts the
+ * daemon; remote: URL + token). Mirrors mcp-stdio's isLoopbackHost (kept
+ * local rather than imported to avoid dragging the SDK into init's graph).
+ * An unparseable URL is NOT local — fail toward carrying the env, which
+ * still works everywhere the URL is real.
+ */
+export declare function isLocalServerUrl(url: string): boolean;
+export type DesktopMergeResult = {
+    ok: true;
+    config: Record<string, unknown>;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Parse the existing config text and merge our entry in, preserving every
+ * top-level key and every other server. `rawText === null` means "no file"
+ * (fresh install — a config containing only our entry is created). Malformed
+ * JSON, a non-object document, or a non-object `mcpServers` value returns
+ * `{ ok: false }` — the caller refuses to write, so the ORIGINAL file and
+ * its bytes are what the user keeps.
+ */
+export declare function mergeDesktopServerConfig(rawText: string | null, entry: DesktopServerEntry): DesktopMergeResult;
+export type DesktopWriteResult = {
+    status: "written";
+    backupPath?: string;
+} | {
+    status: "refused";
+    reason: string;
+} | {
+    status: "failed";
+    reason: string;
+};
+/**
+ * Orchestrate the merge-safe, atomic write of our entry into
+ * `claude_desktop_config.json`:
+ *
+ *   1. Read the existing file (ENOENT → fresh-install path).
+ *   2. Merge; a malformed/shape-refused file → `{ status: "refused" }` with
+ *      NOTHING touched — no backup, no tmp, no bytes changed.
+ *   3. Copy the existing file to `<path>.bak-<ISO-colons-stripped>` BEFORE
+ *      writing (the quarantineMalformedConfig naming convention).
+ *   4. Write the serialized payload to a tmp file in the SAME directory
+ *      (same filesystem → the rename is atomic), JSON-parse the exact bytes
+ *      that landed on disk, then renameSync over the target.
+ *
+ * Any unexpected I/O error returns `{ status: "failed" }` after removing the
+ * tmp file — a half-written tmp must never masquerade as a config. Never
+ * throws; the init wiring turns every non-"written" result into a printed
+ * warning and init continues.
+ */
+export declare function writeDesktopServerConfig(configPath: string, entry: DesktopServerEntry): DesktopWriteResult;

package/dist/claude-desktop.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * Claude Desktop auto-configuration (#381) — the init-side writer for the
+ * `claude_desktop_config.json` MCP entry.
+ *
+ * Claude Desktop's ONLY stdio MCP route is this hand-edited file (no CLI, no
+ * plugin discovery), which is why Desktop never had an init step while CC
+ * (`claude mcp add`), Pi, and opencode (dropped extension files) did. The
+ * 0.20.4 `hicortex mcp` stdio bridge makes such an entry meaningful, so init
+ * now offers to write it — the same auto-detect pattern as the other
+ * harnesses, gated on the Claude Desktop config DIRECTORY existing (the
+ * config FILE may not exist yet; creating it fresh is in scope).
+ *
+ * Two properties dominate the design:
+ *
+ *   1. IT IS ANOTHER APP'S FILE. `claude_desktop_config.json` is owned by
+ *      Claude Desktop and carries the user's other servers and app settings.
+ *      The write is therefore merge-safe (preserve EVERY top-level key and
+ *      every other server; touch only `mcpServers.hicortex`), takes a
+ *      timestamped `.bak` copy of the existing file first, lands via
+ *      tmp-write + JSON-validate + rename in the same directory (atomic),
+ *      and REFUSES — touching nothing, not even a backup — when the existing
+ *      file is not valid JSON. Unlike our own config.json there is no repair
+ *      flow here (quarantening another app's config would break IT); the
+ *      user fixes the file by hand with the snippet init prints.
+ *
+ *   2. THE COMMAND MUST BE AN ABSOLUTE NPX PATH. Desktop is a GUI app and
+ *      does not inherit the shell PATH — a bare "npx" command is the #1
+ *      Desktop MCP failure mode. Resolution walks PATH plus the common
+ *      install locations and rejects npm's ephemeral `/_npx/` cache (#176: a
+ *      path that dies on the next cache GC — the entry would break silently
+ *      weeks later). Unresolvable → manual instructions, nothing written.
+ *      Windows .cmd shims cannot be spawned by Electron without a shell, so
+ *      they are wrapped in `cmd /c`.
+ *
+ * Every helper is pure/parametrised (platform/env/home/exists injected) so
+ * the suite covers darwin/win32/linux without touching a real machine. This
+ * module deliberately imports NOTHING from init.ts (init imports this — no
+ * cycle); the package spec is passed in from init's getPackageSpec().
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.desktopConfigDir = desktopConfigDir;
+exports.resolveDesktopNpxPath = resolveDesktopNpxPath;
+exports.buildDesktopServerEntry = buildDesktopServerEntry;
+exports.isLocalServerUrl = isLocalServerUrl;
+exports.mergeDesktopServerConfig = mergeDesktopServerConfig;
+exports.writeDesktopServerConfig = writeDesktopServerConfig;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const node_crypto_1 = require("node:crypto");
+// ---------------------------------------------------------------------------
+// Config-dir detection
+// ---------------------------------------------------------------------------
+/**
+ * The Claude Desktop config directory for this platform, or null where no
+ * Desktop build exists (Linux → silent skip). Parametrised so tests cover
+ * the platform matrix without a real machine. Detection in init is
+ * `desktopConfigDir() !== null && existsSync(dir)` — the config FILE itself
+ * may legitimately not exist yet.
+ */
+function desktopConfigDir(platform = (0, node_os_1.platform)(), env = process.env, home = (0, node_os_1.homedir)()) {
+    if (platform === "darwin") {
+        return (0, node_path_1.join)(home, "Library", "Application Support", "Claude");
+    }
+    if (platform === "win32") {
+        // %APPDATA% is the documented location; the AppData\Roaming fallback
+        // covers shells/services where the env var is not exported.
+        return (0, node_path_1.join)(env.APPDATA ?? (0, node_path_1.join)(home, "AppData", "Roaming"), "Claude");
+    }
+    return null;
+}
+/**
+ * Candidate npx paths in resolution order: every PATH dir first, then the
+ * common install locations. On win32 each dir contributes `npx.cmd` before
+ * `npx.exe` (the cmd shim is what npm actually installs there).
+ */
+function candidateNpxPaths(platform, pathEnv, home, env) {
+    const names = platform === "win32" ? ["npx.cmd", "npx.exe"] : ["npx"];
+    const delimiter = platform === "win32" ? ";" : ":";
+    const pathDirs = pathEnv.split(delimiter).filter(Boolean);
+    const commonDirs = platform === "win32"
+        ? [
+            // The npm global bin dir (%APPDATA%\npm) and the Node installer's
+            // dir — where a GUI-launched Desktop is most likely to find npx
+            // even when PATH (a shell concept) carries nothing useful.
+            (0, node_path_1.join)(env.APPDATA ?? (0, node_path_1.join)(home, "AppData", "Roaming"), "npm"),
+            "C:\\Program Files\\nodejs",
+        ]
+        : [
+            "/opt/homebrew/bin",
+            "/usr/local/bin",
+            (0, node_path_1.join)(home, ".npm-global", "bin"),
+            (0, node_path_1.join)(home, ".volta", "bin"),
+        ];
+    return [...pathDirs, ...commonDirs].flatMap((dir) => names.map((name) => (0, node_path_1.join)(dir, name)));
+}
+/**
+ * Resolve an ABSOLUTE npx path for the Desktop entry, or null when nothing
+ * durable exists (init then prints manual instructions and writes nothing).
+ * Rejects npm's ephemeral npx cache in BOTH separator spellings — unix
+ * `/_npx/` and Windows `\_npx\` — a bare includes("/_npx/") would let the
+ * win32 form through (#176: the path dies on the next cache GC).
+ */
+function resolveDesktopNpxPath(options = {}) {
+    const platform = options.platform ?? (0, node_os_1.platform)();
+    const pathEnv = options.pathEnv ?? process.env.PATH ?? "";
+    const home = options.home ?? (0, node_os_1.homedir)();
+    const env = options.env ?? process.env;
+    const exists = options.exists ?? node_fs_1.existsSync;
+    for (const candidate of candidateNpxPaths(platform, pathEnv, home, env)) {
+        if (candidate.includes("/_npx/") || candidate.includes("\\_npx\\"))
+            continue;
+        if (exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Build the stdio entry for the `hicortex mcp` bridge. NO "type" field —
+ * stdio is implied for Desktop entries (the CC `.claude.json` writer needs
+ * `"type":"sse"`; this is the other shape). A `.cmd`/`.bat` shim is wrapped
+ * in `cmd /c` because Electron spawns without a shell and cannot exec a cmd
+ * script directly. An empty/absent env omits the key entirely — a local
+ * entry must carry no env (the bridge autostarts the daemon; loopback
+ * bypasses auth).
+ */
+function buildDesktopServerEntry(npxPath, packageSpec, env) {
+    const entry = /\.(cmd|bat)$/i.test(npxPath)
+        ? { command: "cmd", args: ["/c", npxPath, "-y", packageSpec, "mcp"] }
+        : { command: npxPath, args: ["-y", packageSpec, "mcp"] };
+    if (env && Object.keys(env).length > 0)
+        entry.env = { ...env };
+    return entry;
+}
+/**
+ * Loopback check for a server URL — decides whether the Desktop entry needs
+ * an env block at all (local: none, the bridge resolves + autostarts the
+ * daemon; remote: URL + token). Mirrors mcp-stdio's isLoopbackHost (kept
+ * local rather than imported to avoid dragging the SDK into init's graph).
+ * An unparseable URL is NOT local — fail toward carrying the env, which
+ * still works everywhere the URL is real.
+ */
+function isLocalServerUrl(url) {
+    try {
+        const hostname = new URL(url).hostname.toLowerCase();
+        return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Parse the existing config text and merge our entry in, preserving every
+ * top-level key and every other server. `rawText === null` means "no file"
+ * (fresh install — a config containing only our entry is created). Malformed
+ * JSON, a non-object document, or a non-object `mcpServers` value returns
+ * `{ ok: false }` — the caller refuses to write, so the ORIGINAL file and
+ * its bytes are what the user keeps.
+ */
+function mergeDesktopServerConfig(rawText, entry) {
+    if (rawText === null) {
+        return { ok: true, config: { mcpServers: { hicortex: entry } } };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            reason: `the file is not valid JSON (${e instanceof Error ? e.message : String(e)}) — ` +
+                `fix it by hand and re-run init`,
+        };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        const kind = parsed === null ? "null" : Array.isArray(parsed) ? "an array" : typeof parsed;
+        return { ok: false, reason: `the file parses to ${kind}, not a JSON object — fix it by hand and re-run init` };
+    }
+    const config = { ...parsed };
+    const existing = config.mcpServers;
+    if (existing !== undefined && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
+        const kind = Array.isArray(existing) ? "an array" : typeof existing;
+        return { ok: false, reason: `"mcpServers" is ${kind}, not an object — fix it by hand and re-run init` };
+    }
+    config.mcpServers = { ...existing, hicortex: entry };
+    return { ok: true, config };
+}
+/**
+ * Orchestrate the merge-safe, atomic write of our entry into
+ * `claude_desktop_config.json`:
+ *
+ *   1. Read the existing file (ENOENT → fresh-install path).
+ *   2. Merge; a malformed/shape-refused file → `{ status: "refused" }` with
+ *      NOTHING touched — no backup, no tmp, no bytes changed.
+ *   3. Copy the existing file to `<path>.bak-<ISO-colons-stripped>` BEFORE
+ *      writing (the quarantineMalformedConfig naming convention).
+ *   4. Write the serialized payload to a tmp file in the SAME directory
+ *      (same filesystem → the rename is atomic), JSON-parse the exact bytes
+ *      that landed on disk, then renameSync over the target.
+ *
+ * Any unexpected I/O error returns `{ status: "failed" }` after removing the
+ * tmp file — a half-written tmp must never masquerade as a config. Never
+ * throws; the init wiring turns every non-"written" result into a printed
+ * warning and init continues.
+ */
+function writeDesktopServerConfig(configPath, entry) {
+    // 1. Read — only a genuinely-absent file (ENOENT) is a fresh install.
+    let raw = null;
+    try {
+        raw = (0, node_fs_1.readFileSync)(configPath, "utf-8");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT") {
+            return { status: "failed", reason: `could not read ${configPath}: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
+    // 2. Merge — refusal happens BEFORE any disk mutation (step 3+).
+    const merged = mergeDesktopServerConfig(raw, entry);
+    if (!merged.ok) {
+        return { status: "refused", reason: `Refusing to write ${configPath}: ${merged.reason}` };
+    }
+    const payload = JSON.stringify(merged.config, null, 2);
+    let tmpPath;
+    try {
+        const dir = (0, node_path_1.dirname)(configPath);
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        // 3. Backup the existing file BEFORE any write of ours.
+        let backupPath;
+        if (raw !== null) {
+            backupPath = `${configPath}.bak-${new Date().toISOString().replace(/:/g, "-")}`;
+            (0, node_fs_1.copyFileSync)(configPath, backupPath);
+        }
+        // 4. tmp write → validate the exact on-disk bytes → atomic rename.
+        tmpPath = (0, node_path_1.join)(dir, `${(0, node_path_1.basename)(configPath)}.tmp-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`);
+        (0, node_fs_1.writeFileSync)(tmpPath, payload);
+        JSON.parse((0, node_fs_1.readFileSync)(tmpPath, "utf-8"));
+        (0, node_fs_1.renameSync)(tmpPath, configPath);
+        tmpPath = undefined; // committed — nothing left to clean up
+        return backupPath === undefined ? { status: "written" } : { status: "written", backupPath };
+    }
+    catch (e) {
+        if (tmpPath !== undefined) {
+            try {
+                (0, node_fs_1.rmSync)(tmpPath, { force: true });
+            }
+            catch { /* best-effort cleanup — the failure below is the real news */ }
+        }
+        return { status: "failed", reason: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/cli.d.ts

@@ -12,8 +12,12 @@
  *              nightly --evict-only       Memory-cap eviction only — pure DB, no LLM (#317)
  *              nightly --status           Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
- *   dedup      Cluster + merge near-duplicate memories (issue #100)
- *              dedup --apply           Execute the merge (default: dry run)
+ *   dedup      Cluster + merge near-duplicate memories (issues #100, #392)
+ *              dedup --apply           Execute the merge (default: dry run);
+ *                                      losers are absorbed (kept as evidence,
+ *                                      hidden from recall), not deleted
+ *   history    Show a memory's rewrite history, or roll one back (issue #384)
+ *              history --rollback <row>  Undo one rewrite + un-absorb triggers
  *   status     Show config, DB stats, adapter status
  *   uninstall  Clean removal of CC integration
  */

package/dist/cli.js

@@ -13,8 +13,12 @@
  *              nightly --evict-only       Memory-cap eviction only — pure DB, no LLM (#317)
  *              nightly --status           Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
- *   dedup      Cluster + merge near-duplicate memories (issue #100)
- *              dedup --apply           Execute the merge (default: dry run)
+ *   dedup      Cluster + merge near-duplicate memories (issues #100, #392)
+ *              dedup --apply           Execute the merge (default: dry run);
+ *                                      losers are absorbed (kept as evidence,
+ *                                      hidden from recall), not deleted
+ *   history    Show a memory's rewrite history, or roll one back (issue #384)
+ *              history --rollback <row>  Undo one rewrite + un-absorb triggers
  *   status     Show config, DB stats, adapter status
  *   uninstall  Clean removal of CC integration
  */
@@ -272,6 +276,52 @@ switch (command) {
         });
         break;
     }
+    case "history": {
+        // Rewrite history: audit + one-command rollback (#384). Listing is
+        // read-only; --rollback mutates (restores prior content/status and
+        // un-absorbs triggers). Mirrors `dedup`: flags parsed here, the runner
+        // (config load + DB open + print/rollback + close) lives in
+        // reconsolidation.ts so this switch stays thin.
+        const args = process.argv.slice(3);
+        let rollbackId;
+        try {
+            const raw = (0, cli_args_js_1.readValueFlag)(args, "--rollback");
+            if (raw !== undefined) {
+                rollbackId = parseInt(raw, 10);
+                if (isNaN(rollbackId)) {
+                    console.error("[hicortex] history: --rollback requires a numeric history row id");
+                    process.exit(1);
+                }
+            }
+        }
+        catch {
+            console.error("[hicortex] history: --rollback requires a history row id (see `hicortex history <memory-id>`)");
+            process.exit(1);
+        }
+        let dbPath;
+        try {
+            dbPath = (0, cli_args_js_1.readValueFlag)(args, "--db");
+        }
+        catch {
+            console.error("[hicortex] history: --db requires a path value");
+            process.exit(1);
+        }
+        const positional = args.filter((a) => !a.startsWith("-") && a !== dbPath);
+        const memoryId = positional[0];
+        const historyOptions = { dbPath, memoryId, rollbackId };
+        import("./reconsolidation.js").then(({ runHistoryCommand }) => {
+            runHistoryCommand(historyOptions)
+                .then((code) => process.exit(code))
+                .catch((err) => {
+                console.error(err instanceof Error ? err.message : `[hicortex] history failed: ${err}`);
+                process.exit(1);
+            });
+        }).catch((err) => {
+            console.error("[hicortex] history failed:", err);
+            process.exit(1);
+        });
+        break;
+    }
     case "identity": {
         // Standing identity layer edit surface (spec §6; renamed from context in
         // 0.18 #264): show|edit against the configured server. Secondary to the
@@ -365,6 +415,9 @@ Commands:
   nightly         Run nightly denoise + capture + consolidate
   relink          Resumable link-discovery pass over the ENTIRE corpus (server mode)
   dedup           Cluster + merge near-duplicate memories (server mode; dry run by default)
+  history         Show a memory's rewrite history, or roll one back (server mode)
+                  history <id>                List rewrite events (read-only)
+                  history --rollback <row>    Undo one rewrite + un-absorb its triggers
   backup          Snapshot the DB + identity + state to a tar.gz (online, WAL-safe)
   classify-domains  Backfill content-based domain tags over the corpus (server mode, needs config.domains)
   classify-types    Backfill episode→fact/decision type tags over the corpus (server mode)
@@ -390,8 +443,14 @@ Options:
   relink --batch <n>        Memories per batch (default: 200)
   relink --reset            Restart from the beginning (ignore saved cursor)
   dedup --apply             Execute the merge (default: dry run, report only)
-  dedup --threshold <t>     Override config dedupMergeThreshold for one run
+                            Losers are absorbed — hidden from recall, kept as
+                            evidence (fetchable by id; dedup_log audit) — not deleted
+  dedup --threshold <t>     Override the threshold for one run (default: config
+                            dedupAutoMergeThreshold, legacy dedupMergeThreshold
+                            still honored; else 0.92)
   dedup --db <path>         DB path override (defaults to the configured DB)
+  history --rollback <row>  Roll back history row <row>: restores prior content/status, un-absorbs triggers
+  history --db <path>       DB path override (defaults to the configured DB)
   backup --out <dir>        Write the artifact into <dir> as hicortex-<ISO>.tar.gz (default: <home>/backups)
   backup --stdout           Stream the tar.gz to stdout (offsite pipe: hicortex backup --stdout | rclone rcat …)
   classify-domains --all    Reclassify every memory (default: only NULL/stale-domain rows)

package/dist/consolidate.d.ts

@@ -8,6 +8,7 @@ import type { Memory, ConsolidationReport } from "./types.js";
 import type { LlmClient } from "./llm.js";
 import type { EmbedFn } from "./retrieval.js";
 import { type DomainDef } from "./domain-classify.js";
+import { type ReconsolidationOptions } from "./reconsolidation.js";
 /**
  * Default ceiling on total LLM calls across all classify-tier consolidation
  * stages (content-domain, link discovery, supersession) per run. This is a
@@ -343,7 +344,13 @@ budgetMaxCalls?: number,
 /** Soft cap on the corpus (#245). Nightly.ts reads `memorySoftCap` from
  *  config and passes it; unset → `DEFAULT_MEMORY_SOFT_CAP` (10000). `0`
  *  disables eviction (indefinite growth). */
-memorySoftCap?: number): Promise<ConsolidationReport>;
+memorySoftCap?: number, 
+/** Reconsolidation-stage knobs (#384), threaded from config by nightly.ts
+ *  (correctionMinSimilarity / correctionRewriteMinConfidence) exactly like
+ *  supersessionOptions above; unset fields → the stage's defaults.
+ *  Appended AFTER the pre-#384 params so every existing positional caller
+ *  (tests, hosted nightly) keeps its argument meaning. */
+reconsolidationOptions?: ReconsolidationOptions): Promise<ConsolidationReport>;
 /**
  * Calculate milliseconds until the next occurrence of a given hour (local time).
  */