hippo-memory 1.61.0 → 1.63.0

package/dist/store/summaries.js

@@ -7,17 +7,12 @@ import { audit } from './audit-event.js';
 import { syncFtsRow } from './entry-row.js';
 import { openStore } from './open.js';
 // ---------------------------------------------------------------------------
-// v0.30 / E1 of DAG live-coupling — dirty-flag helpers for the existing
-// DAG layer's level-2 summaries.
-//
-// Used by E2 (child-write propagation in invalidation.ts / writeEntry /
-// forgetMemory / archiveRawMemory) to mark a summary dirty when one of its
-// children changes, and by E3's sleep-cycle rebuildDirtySummaries phase to
-// enumerate candidates without scanning every memory row.
+// Dirty-flag helpers for DAG summaries: child writes mark a summary dirty, and the
+// sleep-cycle rebuild enumerates candidates without scanning every memory row.
 // ---------------------------------------------------------------------------
 /**
  * Load summaries flagged dirty for the given tenant. Sorted by latest_at
- * DESC (NULLS LAST) so E3's rebuild cap (HIPPO_DAG_REBUILD_CAP, default 20)
+ * DESC (NULLS LAST) so the rebuild cap (HIPPO_DAG_REBUILD_CAP, default 20)
  * takes the most-recently-changed summaries first.
  *
  * Returns full MemoryEntry shape via MEMORY_SELECT_COLUMNS + rowToEntry
@@ -46,13 +41,12 @@ export function loadDirtySummaries(hippoRoot, tenantId) {
 /**
  * Mark a summary as dirty. Idempotent (re-marking dirty is a no-op + no
  * second audit row). Tenant-scoped to prevent cross-tenant writes via
- * parent-lookup. Called by E2 from invalidation.ts / writeEntry /
+ * parent-lookup. Called from invalidation.ts / writeEntry /
  * forgetMemory / archiveRawMemory whenever a child is invalidated,
  * superseded, forgotten, or archived.
  *
- * Quietly no-ops if the target row doesn't exist or isn't a level-2
- * summary (E5 will widen the dag_level guard to IN (2, 3) when level-3
- * build path lands). Emits a 'summary_marked_dirty' audit row on actual
+ * Quietly no-ops if the target row doesn't exist or isn't a level-2/3
+ * summary. Emits a 'summary_marked_dirty' audit row on actual
  * state transitions (0 -> 1) via the audit() helper, which try/catches
  * for missing audit_log (the v27 self-heal scenario).
  */
@@ -60,8 +54,7 @@ export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli')
     assertTenantId('markSummaryDirty', tenantId);
     const db = openStore(hippoRoot);
     try {
-        // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
-        // actual level in same round trip.
+        // RETURNING dag_level reads the actual level in the same round trip.
         // SAFETY: result's shape matches the single `dag_level` column returned
         // above.
         const result = db.prepare(`
@@ -76,8 +69,7 @@ export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli')
     `).get(summaryId, tenantId);
         if (result) {
             // audit() wraps appendAuditEvent in try/catch (v27 heal scenario).
-            // metadata.source=E1 leaves a breadcrumb so E2-E5 debugging can
-            // distinguish dirty-marks across the arc's wiring layers.
+            // metadata.source tells this dirty-mark apart from the other wiring layers' marks.
             audit(db, 'summary_marked_dirty', summaryId, { dag_level: result.dag_level, source: 'E1' }, actor, tenantId);
         }
     }
@@ -86,7 +78,7 @@ export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli')
     }
 }
 // ---------------------------------------------------------------------------
-// v0.30 / E3 of DAG live-coupling — sleep-cycle rebuild surface.
+// Sleep-cycle rebuild surface.
 //
 // loadAllDirtySummaries / loadChildrenOfSummary / applyRebuildResult /
 // clearSummaryDirtyAfterBuild live HERE (not in dag.ts) because they need
@@ -95,9 +87,9 @@ export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli')
 // rebuildDirtySummaries() that calls into these.
 // ---------------------------------------------------------------------------
 /**
- * v0.30 / E5 — host-wide loader for L2 topic summaries without an L3 parent.
+ * Host-wide loader for L2 topic summaries without an L3 parent.
  * Used by consolidate phase 1.9 (buildEntityProfiles) to cluster L2s into
- * L3 entity profiles. Mirrors loadAllDirtySummaries pattern (E3): SQL-level
+ * L3 entity profiles. Mirrors loadAllDirtySummaries: SQL-level
  * filter is cheaper than reusing in-memory `survivors` (which doesn't
  * contain L2s freshly created by phase 1.7 buildDag).
  *
@@ -125,7 +117,7 @@ export function loadAllL2Summaries(hippoRoot) {
     }
 }
 /**
- * v0.30 / E3 — host-wide variant of loadDirtySummaries. Iterates all tenants
+ * Host-wide variant of loadDirtySummaries. Iterates all tenants
  * in one query so consolidate.ts (host-wide per L106-109) does not need a
  * per-tenant loop. Each returned MemoryEntry carries its own tenantId (via
  * rowToEntry), so per-summary children + rebuild UPDATE stay tenant-scoped.
@@ -152,7 +144,7 @@ export function loadAllDirtySummaries(hippoRoot) {
     }
 }
 /**
- * v0.30 / E3 — load live children of a DAG summary. Used by
+ * Load live children of a DAG summary. Used by
  * rebuildDirtySummaries to regenerate content from the CURRENT child set
  * (not the children at create-time). Skips archived. Tenant-scoped
  * (defence in depth — dag_parent_id is unique-ish but tenant guard is
@@ -180,7 +172,7 @@ export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
     }
 }
 /**
- * v0.30 / E3 — apply a rebuild result to a dirty summary. Atomic: one
+ * Apply a rebuild result to a dirty summary. Atomic: one
  * prepared UPDATE statement plus syncFtsRow inside one SAVEPOINT.
  * WHERE includes `AND summary_dirty = 1` so concurrent sleep's race-loser
  * becomes a no-op (no rebuild_count bump, no audit row).
@@ -217,7 +209,6 @@ export function applyRebuildResult(hippoRoot, summary, patch) {
     }
 }
 // ONE prepared UPDATE per branch. Test #8 inspects the SQL string.
-// v0.30 / E5: widened dag_level=2 -> IN (2, 3) on both branches.
 const REBUILD_CONTENT_SQL = `UPDATE memories
               SET content = ?,
                   descendant_count = ?,
@@ -243,17 +234,8 @@ const REBUILD_METADATA_SQL = `UPDATE memories
               AND kind != 'archived'`;
 function applyRebuildInSavepoint(db, summary, patch) {
     const nowIso = new Date().toISOString();
-    // AT1 P1a fix (docs/plans/2026-08-15-at1-rejected-value-tombstone.md):
-    // applyRebuildResult's bumpRebuildCount branch wrote patch.content via
-    // a direct UPDATE, bypassing the rejection guard entirely (the guard
-    // lives in upsertEntryRow's INSERT path, which this function never
-    // calls). A rebuild that regenerates byte-identical content to an
-    // already-rejected value (e.g. deterministic summarization of an
-    // unchanged child set) would silently re-assert it every sleep cycle.
-    // Check BEFORE choosing which UPDATE to run — only the
-    // bumpRebuildCount branch ever writes content, so a miss or a
-    // zero-child call is a no-op here (one indexed point query, guarded
-    // path only).
+    // Check tombstones before choosing the UPDATE: this direct UPDATE bypasses upsertEntryRow's guard, and
+    // a deterministic rebuild would otherwise re-assert a rejected value every sleep cycle.
     const tombstone = patch.bumpRebuildCount
         ? findRejectedValue(db, summary.tenantId, rejectionDigest(patch.content))
         : null;
@@ -268,23 +250,8 @@ function applyRebuildInSavepoint(db, summary, patch) {
     const result = applyContentWrite
         ? db.prepare(REBUILD_CONTENT_SQL).run(patch.content, patch.descendant_count, patch.earliest_at, patch.latest_at, nowIso, summary.id, summary.tenantId)
         : db.prepare(REBUILD_METADATA_SQL).run(patch.descendant_count, patch.earliest_at, patch.latest_at, summary.id, summary.tenantId);
-    // Return-value semantics (v0.30/T4 split): `changed` reflects whether
-    // THIS call's UPDATE (content or metadata-only) affected a row — NOT
-    // whether patch.content specifically landed. On a refusal, metadata
-    // still applies, so changed=true even though content did not change.
-    // This preserves the pre-T4 no-infinite-retry choice: the caller
-    // (dag.ts rebuildDirtySummaries) treats changed=false as "race lost,
-    // silently retry next cycle" — returning false on a refusal would
-    // retry the same doomed LLM rebuild forever, so changed=true settles
-    // this cycle (dirty cleared) regardless of refusal.
-    // `refused` is the T4 addition: true only when a tombstone hit AND
-    // the metadata UPDATE landed (changed=true) — a refusal that loses
-    // the race to a concurrent writer reports refused=false too, since
-    // nothing from this call took effect. Before T4, a refusal also
-    // counted toward the caller's `rebuilt` stat because `changed` alone
-    // could not distinguish it; the caller now increments `refused`
-    // instead of `rebuilt` when this is true, so the stat reflects what
-    // happened without changing dirty-clearing or retry behavior.
+    // `changed` means THIS call's UPDATE hit a row, so a refusal still settles the cycle (false would retry
+    // the doomed rebuild forever); `refused` lets the caller count it as refused rather than rebuilt.
     const changed = (result.changes ?? 0) > 0;
     const refused = Boolean(tombstone) && changed;
     if (tombstone && changed)
@@ -307,13 +274,8 @@ function auditRefusedRebuild(db, summary, patch, tombstone) {
         `(digest ${tombstone.digest.slice(0, 12)}...); metadata updated, content unchanged`);
 }
 function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
-    // FTS sync — bare UPDATE on memories does NOT update memories_fts.
-    // R1 HIGH must-fix from plan-eng-r1. Construct the patched entry in
-    // memory and reuse the existing syncFtsRow helper (delete-then-insert).
-    // earliest_at/latest_at preserve null semantics (R2 must-fix).
-    // AT1: content stays summary.content (unchanged) when the write was
-    // refused — applyContentWrite is false, so patch.content was never
-    // written to the row FTS must mirror.
+    // A bare UPDATE on memories does NOT update memories_fts, so resync from the patched entry;
+    // content stays summary.content when the write was refused, since FTS must mirror the row.
     const patchedEntry = {
         ...summary,
         content: applyContentWrite ? patch.content : summary.content,
@@ -328,8 +290,7 @@ function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
     };
     syncFtsRow(db, patchedEntry);
     audit(db, 'summary_rebuilt', summary.id, {
-        // v0.30 / E5: read actual level from the summary in scope
-        // (NOT hardcoded 2). L2 -> 2, L3 -> 3.
+        // Actual level from the summary in scope, never hardcoded: L2 -> 2, L3 -> 3.
         dag_level: summary.dag_level,
         source: 'E3-rebuild',
         zero_children: patch.zeroChildren,
@@ -337,21 +298,17 @@ function syncRebuiltSummary(db, summary, patch, applyContentWrite, nowIso) {
     }, patch.actor, summary.tenantId);
 }
 /**
- * v0.30 / E3 — clear summary_dirty on a freshly-built summary. Called by
- * buildDag immediately after the child-link loop finishes. Without this,
- * each member's writeEntry call fires markSummaryDirtyInTx on the just-
- * created parent (E2 hook at store.ts:1214), and the same sleep cycle's
- * E3 rebuild phase would re-rebuild every new summary (2x LLM cost).
+ * Clear summary_dirty on a freshly-built summary. Called by buildDag right after the child-link loop:
+ * each member's writeEntry marks the new parent dirty, so the same cycle's rebuild would redo every new summary.
  *
  * Idempotent: no-op + no audit if summary isn't dirty. Audit
- * source='buildDag-clean' distinguishes from E3-rebuild source.
+ * source='buildDag-clean' distinguishes it from the rebuild's source.
  */
 export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, actor = 'cli', source = 'buildDag-clean') {
     assertTenantId('clearSummaryDirtyAfterBuild', tenantId);
     const db = openStore(hippoRoot);
     try {
-        // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
-        // actual level so audit metadata stays accurate without an extra SELECT.
+        // RETURNING dag_level reads the actual level so audit metadata stays accurate without an extra SELECT.
         // SAFETY: result's shape matches the single `dag_level` column returned
         // below.
         const result = db.prepare(`
@@ -365,8 +322,7 @@ export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, acto
       RETURNING dag_level
     `).get(summaryId, tenantId);
         if (result) {
-            // v0.30 / E5: source param distinguishes buildDag-clean (L2) from
-            // buildEntityProfiles-clean (L3) and any future build path.
+            // source tells buildDag-clean (L2) from buildEntityProfiles-clean (L3) and any future build path.
             audit(db, 'summary_marked_clean', summaryId, { dag_level: result.dag_level, source }, actor, tenantId);
         }
     }

package/dist/support-bundle.js

@@ -11,6 +11,8 @@ import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getMeta, countTabl
 import { runDoctor } from './doctor.js';
 import { loadConfig } from './config.js';
 import { redactSecretsStrict } from './secret-detect.js';
+import { isJsonString } from './json.js';
+import { escapeRegex } from './escape.js';
 const TAIL_MAX_BYTES = 256 * 1024;
 export const TAIL_MAX_LINES = 200;
 const TAIL_MAX_LINE_CHARS = 2000;
@@ -28,9 +30,6 @@ const CONFIG_SECRET_KEY_RE = /key|token|secret|passw|credential|auth|cookie|bear
 function isJsonObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
-function isJsonString(v) {
-    return typeof v === 'string';
-}
 function buildRuntime() {
     return {
         node: process.versions.node,
@@ -177,9 +176,6 @@ function buildLogsSection(opts) {
     }
     return logs;
 }
-function escapeRegExp(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 // The native realpath is the only form that exposes a short-name (8.3) or symlinked alias for what it is.
 function nativeRealPathKey(p) {
     try {
@@ -232,12 +228,12 @@ function mountedDrive(letter) {
 /** Regex source for one spelling of the home, or null when too little of it is left to swap safely. */
 function spellingPattern(spelling, deep) {
     if (process.platform !== 'win32')
-        return spelling.length >= 3 ? escapeRegExp(spelling) : null;
+        return spelling.length >= 3 ? escapeRegex(spelling) : null;
     // Each tool that mounts a drive writes it its own way, so a home two or more folders below its drive (\Users\<name>)
     // matches after any prefix, with \, / or JSON's \\ between folders. A drive written a known way goes into the swap with it.
     const drive = /^([A-Za-z])[:-]/.exec(spelling);
     const below = drive === null ? spelling : spelling.slice(2);
-    const body = below.split(/[\\/]+/).map(escapeRegExp).join('[\\\\/]+');
+    const body = below.split(/[\\/]+/).map(escapeRegex).join('[\\\\/]+');
     if (drive === null) {
         if (spelling.length < 3)
             return null;

package/dist/tenant.d.ts

@@ -1,13 +1,10 @@
 import type { DatabaseSyncLike } from './db.js';
+import type { JsonValue } from './json.js';
 export interface ResolveOpts {
     db?: DatabaseSyncLike;
     apiKey?: string;
 }
 export declare function resolveTenantId(opts: ResolveOpts): string;
-/** A value that round-trips through JSON.stringify/JSON.parse unchanged. */
-type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
 /**
  * Defensive runtime guard for tenant id arguments.
  *
@@ -25,5 +22,4 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
  * Acceptable tradeoff for catching the silent-leak class.
  */
 export declare function assertTenantId(fnName: string, value: JsonValue): asserts value is string;
-export {};
 //# sourceMappingURL=tenant.d.ts.map

package/dist/token-ledger.d.ts

@@ -2,7 +2,7 @@ import type { DatabaseSyncLike } from './db.js';
 /**
  * Where a block of memory text was sent.
  * - `hook`: the per-prompt `UserPromptSubmit` hook (`hippo context --pinned-only`).
- * - `hook_recall`: the same hook's Z1 prompt-recall section (docs/plans/2026-09-26-z1-prompt-recall.md).
+ * - `hook_recall`: the same hook's prompt-recall section.
  * - `compact_resume`: the snapshot the SessionStart(compact) hook prints (`hippo compact-resume`).
  * - `context`, `recall`: the CLI commands.
  * - `mcp_recall`, `mcp_context`: the MCP tools.

package/dist/token-ledger.js

@@ -1,5 +1,5 @@
 /**
- * Token ledger (ROADMAP Part IX, TE0): what memory text hippo hands agents,
+ * Token ledger: what memory text hippo hands agents,
  * and how many tokens it costs.
  *
  * One row per block of memory text sent to an agent, on every surface: the
@@ -11,7 +11,7 @@
  * Every later model call re-reads a sent block until the host compacts; at session end the worker counts
  * those calls from the transcript as `reread` rows for the {@link REREAD_SURFACES} blocks, dated by call day.
  *
- * It also backs TE2, inject only on change: the per-prompt hook compares the
+ * It also backs inject-only-on-change: the per-prompt hook compares the
  * hash of the block it is about to send with the last block it sent in the
  * same session and records a `skip` instead of sending it again.
  *
@@ -25,6 +25,7 @@
  */
 import { createHash } from 'node:crypto';
 import { open } from 'node:fs/promises';
+import { isJsonString } from './json.js';
 /** All surfaces, in report order. */
 export const TOKEN_SURFACES = [
     'hook', 'hook_recall', 'compact_resume', 'context', 'recall', 'mcp_recall', 'mcp_context',
@@ -144,9 +145,6 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
 export function isSyntheticMessage(message) {
     return message.model === '<synthetic>';
 }
-function isJsonString(value) {
-    return value !== undefined && value !== null && value.constructor === String;
-}
 /** JSON-value plain-object check (excludes arrays and null). */
 function isJsonObject(value) {
     return value !== undefined && value !== null && !Array.isArray(value) && value.constructor === Object;

package/dist/trace.js

@@ -5,6 +5,7 @@
  * sequence of agent actions and their final outcome. v1 stores steps as
  * markdown in `content`; `renderTraceContent` is the canonical formatter.
  */
+import { isJsonString } from './json.js';
 /**
  * Render a trace record as agent-readable markdown.
  *
@@ -32,9 +33,6 @@ export function renderTraceContent(rec) {
 function isJsonRecord(value) {
     return value !== null && !Array.isArray(value) && typeof value === 'object';
 }
-function isJsonString(value) {
-    return typeof value === 'string';
-}
 /**
  * Parse a JSON string into an array of TraceStep. Throws on invalid shape.
  */

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.61.0";
+export declare const PACKAGE_VERSION = "1.63.0";
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export declare function compareSemver(a: string, b: string): number;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.61.0';
+export const PACKAGE_VERSION = '1.63.0';
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export function compareSemver(a, b) {
     const parse = (v) => {

package/dist/working-memory.d.ts

@@ -5,8 +5,8 @@
  * importance-ranked, and automatically evicted when the buffer
  * exceeds WM_MAX_ENTRIES per scope.
  */
+import type { JsonValue } from './json.js';
 export declare const WM_MAX_ENTRIES = 20;
-export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
 export type JsonObject = {
     [key: string]: JsonValue;
 };

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Memory for AI agents that learns what is wrong and ranks it down. Injects context at session start and captures errors.",
-  "version": "1.61.0",
+  "version": "1.63.0",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.61.0",
+  "version": "1.63.0",
   "type": "module",
   "description": "Hippo Memory plugin for OpenClaw - biologically-inspired agent memory",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Memory for AI agents that learns what is wrong and ranks it down. Injects context at session start and captures errors.",
-  "version": "1.61.0",
+  "version": "1.63.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.61.0",
+  "version": "1.63.0",
   "description": "Memory for AI agents that learns what is wrong and ranks it down. MCP server, hooks for Claude Code, OpenCode and Codex, AGENTS.md instructions for Codex, Cursor, OpenClaw and Pi. SQLite, zero runtime deps.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",