@gamaze/hicortex 0.19.3 → 0.19.4

package/dist/storage.js

@@ -4,6 +4,7 @@
  * Ported from hicortex/storage.py. All functions are synchronous (better-sqlite3).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FTS_MATCH_MAX_TOKENS = void 0;
 exports.embedToBlob = embedToBlob;
 exports.insertMemory = insertMemory;
 exports.resolveMemoryId = resolveMemoryId;
@@ -20,6 +21,7 @@ exports.getStoredEmbedding = getStoredEmbedding;
 exports.vectorSearch = vectorSearch;
 exports.configureBm25Fts = configureBm25Fts;
 exports.getBm25Weights = getBm25Weights;
+exports.buildFtsMatchExpression = buildFtsMatchExpression;
 exports.searchFts = searchFts;
 exports.addLink = addLink;
 exports.getLinks = getLinks;
@@ -345,6 +347,44 @@ function configureBm25Fts(config) {
 function getBm25Weights() {
     return { ...bm25Weights };
 }
+/**
+ * Cap on tokens fed to an FTS5 MATCH expression (#329 CR finding 1a).
+ * Quoting made pasted term lists LEGAL queries — and an all-common-tokens AND
+ * is expensive: measured at 100K rows, a 50-token AND runs ~518ms and a
+ * 200-token one 6.3s, and the /recall-index hot path would pay it twice per
+ * prompt. Beyond ~24 tokens the implicit AND is semantic noise anyway (a
+ * memory matching 24+ ANDed prompt tokens is either the exact text or
+ * nothing), so the FIRST 24 tokens are used. 24 is a shipped bound, not a
+ * config knob — change it deliberately, with a perf measurement.
+ */
+exports.FTS_MATCH_MAX_TOKENS = 24;
+/**
+ * FTS5 MATCH-safety quoting (#329 item 1). The raw prompt is NOT valid FTS5
+ * query syntax: ordinary prompt punctuation (?, -, (, :, URLs, apostrophes, a
+ * leading AND/OR) crashes the FTS5 parser, and retrieval.retrieve's catch then
+ * silently drops the ENTIRE FTS candidate list — the perf sweep measured 8/12
+ * realistic prompts affected, and it is why relevance eval #3 saw 0 FTS rows
+ * in 2,208 candidates. Fix: tokenize on whitespace, strip embedded double
+ * quotes (a raw `"` would terminate our own quoting), and wrap each token in
+ * double quotes — a quoted token is a phrase of LITERAL strings, immune to
+ * FTS5 query syntax (`"what" "is" "the" "deployment" "status"`). Punctuation
+ * INSIDE a token is kept: the tokenizer strips it identically on both sides,
+ * so `"status?"` still matches content containing "status". Joined with spaces
+ * (implicit AND — the same semantics clean prompts always had; a PROSE prompt
+ * whose content holds only most of the tokens matches nothing, which is why
+ * FTS fires on short keyword prompts, not prose recall). Capped at the first
+ * FTS_MATCH_MAX_TOKENS tokens. A query that quotes away to nothing yields ""
+ * and the caller skips the SQL entirely.
+ */
+function buildFtsMatchExpression(query) {
+    return query
+        .split(/\s+/)
+        .map((token) => token.replace(/"/g, ""))
+        .filter((token) => token.length > 0)
+        .slice(0, exports.FTS_MATCH_MAX_TOKENS)
+        .map((token) => `"${token}"`)
+        .join(" ");
+}
 /**
  * Full-text search using FTS5 fielded BM25 (BM25F) ranking.
  * Returns memories with a rank field (lower is better — see sign note below).
@@ -366,8 +406,13 @@ function getBm25Weights() {
  * caching is unaffected and the config path is the only editor.
  */
 function searchFts(db, query, limit = 10, sourceAgent) {
+    // #329: quote the query into literal phrases — a raw prompt crashes the
+    // FTS5 parser on punctuation and the caller's catch drops the whole list.
+    const matchExpr = buildFtsMatchExpression(query);
+    if (!matchExpr)
+        return [];
     const conditions = ["memories_fts MATCH ?"];
-    const params = [query];
+    const params = [matchExpr];
     if (sourceAgent) {
         conditions.push("m.source_agent = ?");
         params.push(sourceAgent);

package/dist/type-classify.js

@@ -84,7 +84,9 @@ function buildTypeClassifyPrompt(content) {
         `"adopted the graded-schema tag model"). Not knowledge (it can change) and ` +
         `not an experience (it persists). A bare AI recommendation or proposal is ` +
         `NEVER a decision — "AI proposed X → user declined/held" is experience ` +
-        `(#290).\n\n` +
+        `(#290). Even if carried out by the user, a version bump, merge, or count ` +
+        `is never a decision — only the durable user-confirmed standardization it ` +
+        `embodies is (#329).\n\n` +
         `IMPORTANCE (0.0–1.0):\n` +
         `- 0.8–1.0: load-bearing — a core piece of knowledge or a decision the ` +
         `agent must know.\n` +

package/dist/types.d.ts

@@ -413,6 +413,15 @@ export interface HicortexConfig {
      * accepts no client limit.
      */
     recallLimit?: number;
+    /**
+     * OC plugin (#326): auto-scaffold the dead-man guard line into the agent
+     * workspace bootstrap file (BOOTSTRAP.md) at service start — the #313
+     * SECONDARY layer under the injected IDENTITY UNAVAILABLE banner (which is
+     * the primary, plugin-side mechanism). Idempotent: a bootstrap already
+     * carrying the line is never rewritten. Default true; `false` disables both
+     * the write and any file creation entirely.
+     */
+    scaffoldDeadMan?: boolean;
     /**
      * Soft cap on the memory corpus (default 10000). When the corpus exceeds this,
      * the nightly's capacity-eviction stage (#245) removes the lowest-
@@ -465,6 +474,14 @@ export interface HicortexConfig {
      * Operator-owned: point at a mounted backup volume, a tmpfs, etc.
      */
     backupDir?: string;
+    /**
+     * Backup retention (#327): how many of the newest `hicortex-*.tar.gz`
+     * artifacts the backup dir keeps after each successful write. Default 7;
+     * 0 keeps everything. Without it every full nightly (and `hicortex backup`)
+     * adds an artifact forever — unbounded growth, per hosted tenant too. Only
+     * artifacts matching the product's own name pattern are ever pruned.
+     */
+    backupRetention?: number;
     /**
      * Post-backup offsite hook (#6). When set, `hicortex backup` and the nightly
      * backup stage invoke this command with the artifact path appended as the LAST

package/dist/uninstall.d.ts

@@ -14,4 +14,37 @@
 export declare const SESSION_START_HOOK_COMMAND_RE: RegExp;
 /** True when a CC hook `command` string runs the Hicortex SessionStart hook. */
 export declare function isHicortexSessionStartHook(command: string): boolean;
+/**
+ * Matches a CC hook `command` that runs the Hicortex recall hook — the
+ * `recall-hook` subcommand (#192). Same word-boundary discipline as the
+ * learnings matcher: an unrelated command that merely CONTAINS the substring
+ * ("my-recall-hook", "recall-hooks-old") is never swept up. Used for BOTH
+ * event arrays the installer writes (UserPromptSubmit + SessionStart).
+ */
+export declare const RECALL_HOOK_COMMAND_RE: RegExp;
+/** True when a CC hook `command` string runs the Hicortex recall hook. */
+export declare function isHicortexRecallHook(command: string): boolean;
+/** One hook group removed from settings.json (for per-group logging). */
+export interface RemovedHookGroup {
+    /** CC event array the entries were removed from ("SessionStart", "UserPromptSubmit"). */
+    event: string;
+    /** Which Hicortex hook set: "learnings" (learnings-identity/lessons-context) or "recall". */
+    kind: "learnings" | "recall";
+    /** Number of matcher entries removed. */
+    count: number;
+}
+/**
+ * Remove every Hicortex hook entry from a PARSED ~/.claude/settings.json
+ * (#327): the SessionStart learnings hook (canonical + legacy alias) AND the
+ * recall-hook pair (UserPromptSubmit + SessionStart, installed together by
+ * installRecallHooks — leaving either behind is a silent npx spawn per prompt
+ * forever). Mutates `settings` in place; returns what was removed (empty when
+ * nothing matched — a clean no-op). Exact-match discipline throughout: only
+ * entries whose `hooks[].command` matches a Hicortex subcommand are removed;
+ * foreign hooks (and prefix-colliding names) stay untouched.
+ *
+ * Pure on the parsed object so the uninstall behavior is unit-testable
+ * without spinning up CC; runUninstall owns the file I/O.
+ */
+export declare function removeHicortexCcHooks(settings: Record<string, unknown>): RemovedHookGroup[];
 export declare function runUninstall(): Promise<void>;

package/dist/uninstall.js

@@ -4,8 +4,10 @@
  * Preserves the database (user data).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_START_HOOK_COMMAND_RE = void 0;
+exports.RECALL_HOOK_COMMAND_RE = exports.SESSION_START_HOOK_COMMAND_RE = void 0;
 exports.isHicortexSessionStartHook = isHicortexSessionStartHook;
+exports.isHicortexRecallHook = isHicortexRecallHook;
+exports.removeHicortexCcHooks = removeHicortexCcHooks;
 exports.runUninstall = runUninstall;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
@@ -33,6 +35,69 @@ exports.SESSION_START_HOOK_COMMAND_RE = /(^|\s)(?:learnings-identity|lessons-con
 function isHicortexSessionStartHook(command) {
     return typeof command === "string" && exports.SESSION_START_HOOK_COMMAND_RE.test(command);
 }
+/**
+ * Matches a CC hook `command` that runs the Hicortex recall hook — the
+ * `recall-hook` subcommand (#192). Same word-boundary discipline as the
+ * learnings matcher: an unrelated command that merely CONTAINS the substring
+ * ("my-recall-hook", "recall-hooks-old") is never swept up. Used for BOTH
+ * event arrays the installer writes (UserPromptSubmit + SessionStart).
+ */
+exports.RECALL_HOOK_COMMAND_RE = /(^|\s)recall-hook(\s|$)/;
+/** True when a CC hook `command` string runs the Hicortex recall hook. */
+function isHicortexRecallHook(command) {
+    return typeof command === "string" && exports.RECALL_HOOK_COMMAND_RE.test(command);
+}
+/**
+ * Remove every Hicortex hook entry from a PARSED ~/.claude/settings.json
+ * (#327): the SessionStart learnings hook (canonical + legacy alias) AND the
+ * recall-hook pair (UserPromptSubmit + SessionStart, installed together by
+ * installRecallHooks — leaving either behind is a silent npx spawn per prompt
+ * forever). Mutates `settings` in place; returns what was removed (empty when
+ * nothing matched — a clean no-op). Exact-match discipline throughout: only
+ * entries whose `hooks[].command` matches a Hicortex subcommand are removed;
+ * foreign hooks (and prefix-colliding names) stay untouched.
+ *
+ * Pure on the parsed object so the uninstall behavior is unit-testable
+ * without spinning up CC; runUninstall owns the file I/O.
+ */
+function removeHicortexCcHooks(settings) {
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return [];
+    const groups = [
+        { event: "SessionStart", kind: "learnings", match: isHicortexSessionStartHook },
+        { event: "SessionStart", kind: "recall", match: isHicortexRecallHook },
+        { event: "UserPromptSubmit", kind: "recall", match: isHicortexRecallHook },
+    ];
+    const removed = [];
+    for (const g of groups) {
+        const arr = hooks[g.event];
+        if (!Array.isArray(arr))
+            continue;
+        const filtered = arr.filter((entry) => {
+            if (typeof entry !== "object" || entry === null)
+                return true;
+            const e = entry;
+            if (Array.isArray(e.hooks)) {
+                return !e.hooks.some((h) => typeof h === "object" &&
+                    h !== null &&
+                    typeof h.command === "string" &&
+                    g.match(h.command));
+            }
+            return true;
+        });
+        if (filtered.length < arr.length) {
+            // Drop the event key entirely when the filter emptied it — no
+            // `"UserPromptSubmit": []` husk left in the settings file.
+            if (filtered.length > 0)
+                hooks[g.event] = filtered;
+            else
+                delete hooks[g.event];
+            removed.push({ event: g.event, kind: g.kind, count: arr.length - filtered.length });
+        }
+    }
+    return removed;
+}
 async function ask(question) {
     const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stdout });
     return new Promise((resolve) => {
@@ -146,34 +211,21 @@ async function runUninstall() {
     }
     if (removedCmds > 0)
         console.log(`  ✓ Removed ${removedCmds} legacy CC command${removedCmds > 1 ? "s" : ""} (/learn, /hicortex-activate)`);
-    // 4. Remove SessionStart hook (JSON merge — filter out entries containing
-    //    EITHER the canonical "learnings-identity" OR the legacy "lessons-context"
-    //    alias, #264 backcompat: an install may have written either name.)
+    // 4. Remove ALL Hicortex CC hooks (#327): the SessionStart learnings hook
+    //    (canonical `learnings-identity` OR the legacy `lessons-context` alias,
+    //    #264 backcompat) AND BOTH `recall-hook` entries (UserPromptSubmit +
+    //    SessionStart — installed as a pair by installRecallHooks; leaving
+    //    either behind keeps a silent npx spawn per prompt forever).
+    //    Fail-soft when absent; word-boundary matchers never touch foreign hooks.
     try {
         const raw = (0, node_fs_1.readFileSync)(CC_SETTINGS, "utf-8");
         const settings = JSON.parse(raw);
-        const hooks = settings.hooks;
-        const sessionStart = hooks && Array.isArray(hooks.SessionStart) ? hooks.SessionStart : null;
-        if (hooks && sessionStart) {
-            const before = sessionStart.length;
-            const filtered = sessionStart.filter((entry) => {
-                if (typeof entry !== "object" || entry === null)
-                    return true;
-                const e = entry;
-                if (Array.isArray(e.hooks)) {
-                    return !e.hooks.some((h) => {
-                        if (typeof h !== "object" || h === null)
-                            return false;
-                        const hook = h;
-                        return typeof hook.command === "string" && isHicortexSessionStartHook(hook.command);
-                    });
-                }
-                return true;
-            });
-            if (filtered.length < before) {
-                hooks.SessionStart = filtered;
-                (0, node_fs_1.writeFileSync)(CC_SETTINGS, JSON.stringify(settings, null, 2));
-                console.log("  ✓ Removed SessionStart learnings-identity hook");
+        const removed = removeHicortexCcHooks(settings);
+        if (removed.length > 0) {
+            (0, node_fs_1.writeFileSync)(CC_SETTINGS, JSON.stringify(settings, null, 2));
+            for (const r of removed) {
+                const name = r.kind === "learnings" ? "learnings-identity" : "recall-hook";
+                console.log(`  ✓ Removed ${r.event} ${name} hook${r.count > 1 ? "s" : ""}`);
             }
         }
     }

package/dist/viz.d.ts

@@ -54,7 +54,7 @@ export declare const VIZ_VENDOR_FILES: ReadonlySet<string>;
  * this — a hosted tenant dir is fail-closed by default. mcp-server.ts captures
  * the marker state once at boot and passes it in (no per-request stat).
  */
-export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string, allowLocalhostBypass?: boolean): express.RequestHandler;
+export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string, allowLocalhostBypass?: boolean, bodyLimitBytes?: number): express.RequestHandler;
 /**
  * Resolve the on-disk path of the viz page. Throws (fail explicitly) when the
  * asset is missing — a broken install should surface, not degrade silently.

package/dist/viz.js

@@ -101,10 +101,37 @@ function safeBearerMatch(headerValue, expectedToken) {
  * this — a hosted tenant dir is fail-closed by default. mcp-server.ts captures
  * the marker state once at boot and passes it in (no per-request stat).
  */
-function createAuthMiddleware(authToken, authTokenPrevious, allowLocalhostBypass) {
+function createAuthMiddleware(authToken, authTokenPrevious, allowLocalhostBypass, bodyLimitBytes) {
     const previous = authTokenPrevious && authTokenPrevious.length > 0 ? authTokenPrevious : undefined;
     const bypassEnabled = allowLocalhostBypass === true;
+    const contentLengthCap = Number.isFinite(bodyLimitBytes) && bodyLimitBytes > 0
+        ? bodyLimitBytes
+        : null;
     return (req, res, next) => {
+        // #328 item 4 (package-server half) — BELT. The PRIMARY gate is
+        // makeContentLengthGate (mcp-server.ts), registered BEFORE express.json:
+        // this middleware sits AFTER the parser, so by the time it runs the body
+        // has already been buffered (up to the parser's limit) — its Content-Length
+        // check can only catch what a caller wires WITHOUT the front gate. Kept
+        // for standalone/reuse callers of createAuthMiddleware and as
+        // defense-in-depth; 413 mirrors express.json's own oversize status.
+        //
+        // RESIDUAL RISK (unchanged by either check): chunked transfer-encoding
+        // sends no Content-Length, so neither gate sees it — those requests still
+        // buffer up to the parser limit inside express.json before the 413
+        // (bounded per request, no pre-auth rejection), and there is no
+        // concurrency cap here. Full pre-auth bounding lives in the hosted
+        // router's webhook path (stripe.ts, #328 item 4) — the tenant data plane
+        // trusts its bearer (self-hosted threat model) or sits behind the
+        // provider's edge (hosted).
+        if (contentLengthCap !== null) {
+            const declared = req.headers["content-length"];
+            const declaredNum = typeof declared === "string" ? Number(declared) : NaN;
+            if (Number.isFinite(declaredNum) && declaredNum > contentLengthCap) {
+                res.status(413).json({ error: "request body too large" });
+                return;
+            }
+        }
         if (req.path === "/health")
             return next();
         // The /viz page SHELL is public like /health — it contains no data and no

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hicortex",
   "name": "Hicortex — Long-term Memory That Learns",
   "description": "Your agents remember past decisions, avoid repeated mistakes, and get smarter every day. Nightly reflection generates actionable lessons that automatically update agent behavior.",
-  "version": "0.19.3",
+  "version": "0.19.4",
   "kind": "lifecycle",
   "skills": ["./skills/hicortex-memory"],
   "configSchema": {
@@ -25,6 +25,11 @@
         "type": "number",
         "default": 8,
         "description": "Max memories per recall on the pre-0.14 /search fallback (default 8). The pushed recall index is sized by SERVER config (recallMaxItems) — the server accepts no client limit."
+      },
+      "scaffoldDeadMan": {
+        "type": "boolean",
+        "default": true,
+        "description": "Auto-scaffold the dead-man identity-guard line into the agent workspace bootstrap (BOOTSTRAP.md) at startup — the secondary defense under the identity-unavailable banner the plugin injects when the identity fetch fails. Idempotent: the .bak backup is written once and never touched again. Set false to keep the plugin from writing any bootstrap file."
       }
     },
     "required": []
@@ -46,6 +51,10 @@
     "recallLimit": {
       "label": "Recall Limit",
       "placeholder": "8"
+    },
+    "scaffoldDeadMan": {
+      "label": "Scaffold Dead-Man Guard",
+      "placeholder": "true"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.19.3",
+  "version": "0.19.4",
   "description": "Persistent agent identity for AI agents \u2014 a hand-edited identity layer, nightly-distilled experience, and lessons injected every session, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {