hippo-memory 1.58.0 → 1.60.0

package/dist/store.js

@@ -27,6 +27,7 @@ import { checkRejectionGuard, RejectedValueError, rejectionDigest, normalizeValu
 // is the standard safe mutual-function-reference shape under NodeNext ESM.
 import { archiveRawMemory } from './raw-archive.js';
 import { insertDormantRow } from './dormant.js';
+import { log } from './log.js';
 /**
  * Emit an audit event for a mutation against `db`. Wrapped so a broken audit
  * log can never crash the surrounding mutation — the SQLite store is still the
@@ -58,7 +59,7 @@ export function auditRejectionRefusal(db, err, actor) {
     audit(db, 'reject_refusal', err.entryId, { digest: err.digest, reason: err.reason }, actor, err.tenantId);
 }
 const INDEX_VERSION = 3;
-const MEMORY_SELECT_COLUMNS = `id, created, last_retrieved, retrieval_count, strength, half_life_days, layer, tags_json, emotional_valence, schema_fit, source, outcome_score, outcome_positive, outcome_negative, conflicts_with_json, pinned, confidence, content, parents_json, starred, trace_outcome, source_session_id, valid_from, superseded_by, extracted_from, dag_level, dag_parent_id, kind, scope, owner, artifact_ref, tenant_id, origin_project, descendant_count, earliest_at, latest_at, summary_dirty, last_rebuilt_at, rebuild_count, dag_level_3_built_at`;
+export const MEMORY_SELECT_COLUMNS = `id, created, last_retrieved, retrieval_count, strength, half_life_days, layer, tags_json, emotional_valence, schema_fit, source, outcome_score, outcome_positive, outcome_negative, conflicts_with_json, pinned, confidence, content, parents_json, starred, trace_outcome, source_session_id, valid_from, superseded_by, extracted_from, dag_level, dag_parent_id, kind, scope, owner, artifact_ref, tenant_id, origin_project, descendant_count, earliest_at, latest_at, summary_dirty, last_rebuilt_at, rebuild_count, dag_level_3_built_at`;
 // F1 (v1.7.0): qualified-and-aliased columns for the FTS join in
 // loadSearchRows. Every column is `m.<col> AS <col>` so rowToEntry's
 // unqualified field reads keep working unchanged. The trailing
@@ -180,9 +181,9 @@ export function serializeEntry(entry) {
     if (tenantId !== 'default') {
         frontmatter['tenant_id'] = tenantId;
     }
-    // v39: origin_project '' (user-global) is meaningful and must round-trip;
-    // only undefined/null (legacy/unstamped) is omitted.
-    if (entry.origin_project !== undefined && entry.origin_project !== null) {
+    // v39: '' (user-global) and null (unknown, hidden by default) must both round-trip;
+    // only undefined (unstamped) is omitted, so a rebuild stamps nothing it can read.
+    if (entry.origin_project !== undefined) {
         frontmatter['origin_project'] = entry.origin_project;
     }
     // Spread into a fresh object literal: dumpFrontmatter's Record<string,
@@ -241,7 +242,7 @@ export function deserializeEntry(raw) {
         owner: data['owner'] === null || data['owner'] === undefined ? null : String(data['owner']),
         artifact_ref: data['artifact_ref'] === null || data['artifact_ref'] === undefined ? null : String(data['artifact_ref']),
         tenantId: data['tenant_id'] === null || data['tenant_id'] === undefined ? 'default' : String(data['tenant_id']),
-        origin_project: data['origin_project'] === null || data['origin_project'] === undefined ? null : String(data['origin_project']),
+        origin_project: !('origin_project' in data) ? undefined : data['origin_project'] === null ? null : String(data['origin_project']),
     };
 }
 function normalizeStringArray(value) {
@@ -312,7 +313,8 @@ function parseJsonArray(raw) {
         const parsed = JSON.parse(raw);
         return Array.isArray(parsed) ? parsed.map((item) => String(item)) : [];
     }
-    catch {
+    catch (err) {
+        log.debug(`store: corrupt JSON array column read as empty: ${err instanceof Error ? err.message : String(err)}`);
         return [];
     }
 }
@@ -346,7 +348,8 @@ function parseJsonObject(raw) {
         }
         return {};
     }
-    catch {
+    catch (err) {
+        log.debug(`store: corrupt JSON object column read as empty: ${err instanceof Error ? err.message : String(err)}`);
         return {};
     }
 }
@@ -748,12 +751,12 @@ export function purgeMirrorBestEffort(hippoRoot, id, isRaw, logPrefix) {
         catch (secondErr) {
             const msg = secondErr instanceof Error ? secondErr.message : String(secondErr);
             if (isRaw) {
-                console.error(`${logPrefix}: mirror cleanup failed for ${id} (will retry via reaper on next open): ${msg}`);
+                log.error(`${logPrefix}: mirror cleanup failed for ${id} (will retry via reaper on next open): ${msg}`);
             }
             else {
                 const leftover = getExistingEntryMirrorPaths(hippoRoot, id);
                 const pathsNote = leftover.length > 0 ? leftover.join(', ') : `${id}.md (path unresolved)`;
-                console.error(`${logPrefix}: mirror cleanup failed for ${id} - no automatic retry exists for this file, ` +
+                log.error(`${logPrefix}: mirror cleanup failed for ${id} - no automatic retry exists for this file, ` +
                     `delete it manually: ${pathsNote} (${msg})`);
             }
             return false;
@@ -809,7 +812,7 @@ function bootstrapLegacyStore(db, hippoRoot) {
             }
         }
         if (rejectedCount > 0) {
-            console.error(`bootstrapLegacyStore: skipped ${rejectedCount} rejected value(s) found in legacy mirrors`);
+            log.warn(`bootstrapLegacyStore: skipped ${rejectedCount} rejected value(s) found in legacy mirrors`);
         }
         const legacyIndex = loadLegacyIndexFile(hippoRoot);
         setMeta(db, 'last_retrieval_ids', JSON.stringify(legacyIndex.last_retrieval_ids ?? []));
@@ -874,7 +877,8 @@ function loadLegacyIndexFile(hippoRoot) {
         // that violates the shape falls through to the catch block's fallback.
         return JSON.parse(fs.readFileSync(indexPath, 'utf8'));
     }
-    catch {
+    catch (err) {
+        log.debug(`store: unreadable index.json read as empty: ${err instanceof Error ? err.message : String(err)}`);
         return { version: 1, entries: {}, last_retrieval_ids: [], last_trace_id: null };
     }
 }
@@ -895,7 +899,8 @@ function loadLegacyStatsFile(hippoRoot) {
         // hand-edited or corrupted file even if this optimistic cast is wrong.
         return JSON.parse(fs.readFileSync(statsPath, 'utf8'));
     }
-    catch {
+    catch (err) {
+        log.debug(`store: unreadable stats.json read as zero: ${err instanceof Error ? err.message : String(err)}`);
         return {
             total_remembered: 0,
             total_recalled: 0,
@@ -1077,7 +1082,7 @@ function mirrorBestEffort(what, write) {
         write();
     }
     catch (err) {
-        console.error(`hippo: ${what} not refreshed (${err instanceof Error ? err.message : String(err)}); the database write succeeded`);
+        log.warn(`${what} not refreshed (${err instanceof Error ? err.message : String(err)}); the database write succeeded`);
     }
 }
 function syncMirrorFiles(hippoRoot, db) {
@@ -1174,7 +1179,7 @@ export function stampOriginProject(hippoRoot, entry) {
     return { ...entry, origin_project: deriveOriginProject(path.dirname(hippoRoot)) };
 }
 /**
- * Import-time variant that ALSO stamps null: used only where evidence exists
+ * Import-time variant for a mirror with no origin field (an explicit null stays null): used only where evidence exists
  * for rows that predate the origin column - the legacy-markdown bootstrap and
  * rebuildIndex import, which are the markdown-store equivalent of the v39 SQL
  * backfill. Same evidence order as the migration: the provenance source
@@ -1183,7 +1188,7 @@ export function stampOriginProject(hippoRoot, entry) {
  * owning project instead of becoming user-global (codex gating round 3 P1).
  */
 function stampOriginProjectForImport(hippoRoot, entry) {
-    if (entry.origin_project !== undefined && entry.origin_project !== null)
+    if (entry.origin_project !== undefined)
         return entry;
     const fromSource = originFromSource(entry.source);
     return {
@@ -1332,7 +1337,7 @@ export function strengthenRetrieved(hippoRoot, ids, tenantId) {
             db?.exec('ROLLBACK');
         }
         catch { /* already rolled back; keep the original error */ }
-        console.error(`hippo: retrieval stats not saved (${error instanceof Error ? error.message : String(error)})`);
+        log.warn(`retrieval stats not saved (${error instanceof Error ? error.message : String(error)})`);
         found.clear();
     }
     finally {
@@ -1772,7 +1777,7 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
         }
         db.exec('COMMIT');
         if (batchRejectedSkips > 0) {
-            console.error(`batchWriteAndDelete: skipped ${batchRejectedSkips} write(s) whose content matches a rejected value (tombstone hit during the batch transaction)`);
+            log.warn(`batchWriteAndDelete: skipped ${batchRejectedSkips} write(s) whose content matches a rejected value (tombstone hit during the batch transaction)`);
         }
         // Sync mirrors once after all DB writes. Entries skipped above were
         // never inserted — writing their markdown mirror would resurrect the
@@ -1853,6 +1858,11 @@ export function loadContentsWithTag(hippoRoot, tenantId, tag) {
         closeHippoDb(db);
     }
 }
+const AMBIENT_SCOPED = 'superseded_by IS NULL AND tenant_id = ?';
+/** Exported so the plan test runs the exact SQL; idx_memories_pinned (db.ts v51) serves it. */
+export const AMBIENT_PINNED_WHERE = `pinned = 1 AND ${AMBIENT_SCOPED} ORDER BY created ASC, id ASC`;
+/** Exported so the plan test runs the exact SQL; idx_memories_created_drift (db.ts v51) serves it. */
+export const AMBIENT_DRIFT_SQL = `SELECT 1 FROM memories WHERE ${AMBIENT_SCOPED} AND (length(created) <> 24 OR created NOT LIKE '%Z') LIMIT 1`;
 // The pins plus the `recentNeeded` newest rows that pass `admit`, for ambient
 // injection. One connection; `recall` piggybacks the Z1 FTS query on it too.
 export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit, recall) {
@@ -1864,14 +1874,14 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
         // SAFETY: every `where` below starts from MEMORY_SELECT_COLUMNS' table.
         const run = (where, params) => db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE ${where}`).all(...params).map(rowToEntry);
         const byId = new Map();
-        const scoped = 'superseded_by IS NULL AND tenant_id = ?';
-        for (const e of run(`pinned = 1 AND ${scoped} ORDER BY created ASC, id ASC`, [tenantId])) {
+        const scoped = AMBIENT_SCOPED;
+        for (const e of run(AMBIENT_PINNED_WHERE, [tenantId])) {
             if (admit(e))
                 byId.set(e.id, e);
         }
         if (needed > 0) {
             // Text order is chronological only for canonical UTC ISO (memory.ts).
-            const drifted = db.prepare(`SELECT 1 FROM memories WHERE ${scoped} AND (length(created) <> 24 OR created NOT LIKE '%Z') LIMIT 1`).get(tenantId) !== undefined;
+            const drifted = db.prepare(AMBIENT_DRIFT_SQL).get(tenantId) !== undefined;
             // `id DESC` mirrors getContext's comparator, not loadFreshRawMemories'
             // cross-ingest-stable order: that would change what the hook injects.
             const window = Math.max(needed * 4, 32);
@@ -1903,6 +1913,97 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit,
         closeHippoDb(db);
     }
 }
+// calculateStrength's decay exponent with its reward factor, pins first: the strongest rows, without scoring each one in JS.
+const DECAY_RANK_SQL = `pinned DESC,
+  CASE WHEN half_life_days > 0 THEN (julianday(?) - julianday(last_retrieved))
+    / (half_life_days * (1.0 + 0.5 * (COALESCE(outcome_positive, 0) - COALESCE(outcome_negative, 0))
+      / (COALESCE(outcome_positive, 0) + COALESCE(outcome_negative, 0) + 1.0))) END ASC NULLS LAST,
+  id ASC`;
+/** Live tenant rows passing `filter`, at most `filter.cap`, in loadAllEntries' order; below the cap, every such row. */
+export function loadContextCandidates(hippoRoot, tenantId, filter) {
+    const where = ['tenant_id = ?', `COALESCE(superseded_by, '') = ''`];
+    const params = [tenantId];
+    if (filter.exactScope) {
+        where.push('scope = ?');
+        params.push(filter.exactScope);
+    }
+    else {
+        // isRestrictedScope's rule; NOT LIKE folds ASCII case as its /:private:/i does.
+        where.push(`(scope IS NULL OR (scope NOT IN (${RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ')}) AND scope NOT LIKE '%:private:%'))`);
+        params.push(...RECALL_DEFAULT_DENY_SCOPES);
+    }
+    if (filter.project !== undefined) {
+        where.push(`(origin_project = '' OR origin_project = ?)`);
+        params.push(filter.project);
+    }
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: the outer SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set; the rank sort carries ids only.
+        const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (
+        SELECT id FROM memories WHERE ${where.join(' AND ')} ORDER BY ${DECAY_RANK_SQL} LIMIT ?
+      ) ORDER BY created ASC, id ASC`).all(...params, filter.now.toISOString(), Math.max(0, Math.trunc(filter.cap)));
+        return rows.map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Every tenant row as a StrengthRow, for whole-store health numbers; defaults match rowToEntry's. */
+export function loadStrengthRows(hippoRoot, tenantId) {
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: rows' shape matches the columns named in the SELECT below.
+        const rows = db.prepare(`SELECT pinned, created, last_retrieved, half_life_days, retrieval_count, emotional_valence, outcome_positive, outcome_negative, tags_json
+       FROM memories WHERE tenant_id = ?`).all(tenantId);
+        return rows.map((row) => ({
+            pinned: Boolean(row.pinned),
+            created: row.created,
+            last_retrieved: row.last_retrieved,
+            half_life_days: Number(row.half_life_days ?? 7),
+            retrieval_count: Number(row.retrieval_count ?? 0),
+            emotional_valence: row.emotional_valence ?? 'neutral',
+            outcome_positive: Number(row.outcome_positive ?? 0),
+            outcome_negative: Number(row.outcome_negative ?? 0),
+            tags: parseJsonArray(row.tags_json),
+        }));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Text and source of tenant rows holding any of `words`; a row equal to a text apart from spacing holds its every word. */
+export function loadTextsHoldingWords(hippoRoot, tenantId, words) {
+    const unique = [...new Set(words)];
+    const out = [];
+    const db = openStore(hippoRoot);
+    try {
+        // Chunked so one statement stays far under SQLite's bound-parameter limit.
+        for (let i = 0; i < unique.length; i += 200) {
+            const chunk = unique.slice(i, i + 200);
+            // SAFETY: rows' shape matches the two columns named in the SELECT below.
+            const rows = db.prepare(`SELECT content, source FROM memories WHERE tenant_id = ? AND (${chunk.map(() => 'instr(content, ?) > 0').join(' OR ')})`).all(tenantId, ...chunk);
+            for (const row of rows)
+                out.push({ content: row.content, source: row.source ?? 'cli' });
+        }
+        return out;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Row count and newest `created` per source, for peer listings that need no row; all tenants when `tenantId` is absent. */
+export function tallySources(hippoRoot, tenantId) {
+    const db = openStore(hippoRoot);
+    try {
+        const where = tenantId !== undefined ? 'WHERE tenant_id = ?' : '';
+        // SAFETY: rows' shape matches the four aliased columns in the SELECT below.
+        return db.prepare(`SELECT COALESCE(source, 'cli') AS source, COUNT(*) AS count, MAX(created) AS latest, MIN(created || char(31) || id) AS first
+       FROM memories ${where} GROUP BY COALESCE(source, 'cli')`).all(...(tenantId !== undefined ? [tenantId] : []));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 /**
  * Load likely search candidates directly from SQLite.
  * Uses FTS5 when available, falls back to LIKE matching, then full-store fallback.
@@ -2019,7 +2120,7 @@ export function rebuildIndex(hippoRoot) {
                     }
                 }
                 if (rejectedCount > 0) {
-                    console.error(`rebuildIndex: skipped ${rejectedCount} rejected value(s) found in legacy mirrors`);
+                    log.warn(`rebuildIndex: skipped ${rejectedCount} rejected value(s) found in legacy mirrors`);
                 }
                 db.exec('COMMIT');
             }
@@ -3279,7 +3380,7 @@ export function applyRebuildResult(hippoRoot, summary, patch) {
                 // tool) is the wrong one here; a direct audit() call is correct and
                 // commits with the rest of this savepoint.
                 audit(db, 'reject_refusal', summary.id, { digest: tombstone.digest, reason: tombstone.reason }, patch.actor, summary.tenantId);
-                console.error(`applyRebuildResult: refused rebuild content for ${summary.id} — matches a rejected value ` +
+                log.warn(`applyRebuildResult: refused rebuild content for ${summary.id} — matches a rejected value ` +
                     `(digest ${tombstone.digest.slice(0, 12)}...); metadata updated, content unchanged`);
             }
             if (changed) {

package/dist/token-ledger.js

@@ -161,6 +161,7 @@ function parseHookPayload(stdinText) {
         return isJsonObject(payload) ? payload : null;
     }
     catch {
+        // Malformed is one of the null cases the docblock names.
         return null;
     }
 }

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.58.0";
+export declare const PACKAGE_VERSION = "1.60.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.58.0';
+export const PACKAGE_VERSION = '1.60.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/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.58.0",
+  "version": "1.60.0",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.58.0",
+  "version": "1.60.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.58.0",
+  "version": "1.60.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.58.0",
+  "version": "1.60.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",
@@ -30,10 +30,12 @@
   "scripts": {
     "baseline": "npm run build && npm test",
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc && tsc -p tsconfig.benchmarks.json && tsc -p tsconfig.extensions.json",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
     "dev": "tsc --watch",
     "pretest": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "test:delivery-ledger": "vitest run tests/delivery-ledger",
     "lint": "oxlint",
     "sbom": "node scripts/sbom.mjs",
@@ -90,9 +92,11 @@
   "devDependencies": {
     "@oxlint/plugins": "^1.78.0",
     "@types/node": "^22.16.0",
+    "@vitest/coverage-v8": "^5.0.3",
     "oxlint": "^1.78.0",
     "typescript": "^5.4.0",
-    "vitest": "^3.2.6"
+    "vite": "^8.3.2",
+    "vitest": "^5.0.3"
   },
   "peerDependenciesMeta": {
     "@xenova/transformers": {