hippo-memory 1.53.0 → 1.53.1

package/README.md

@@ -22,6 +22,8 @@ npm install -g hippo-memory && hippo init
 
 Setting up every git repo under a folder in one go is a second step. The [Quick start](#quick-start) says what it changes, then gives the command.
 
+Package installation alone does not enable automatic preservation on every agent. Complete the documented setup and required host trust; capture and compaction coverage depend on the integration. See [automatic-save coverage](#does-installation-automatically-save-before-compaction).
+
 Having an AI agent install it? Point it at [llms-install.md](llms-install.md): it installs, wires hippo into the agents it finds, and verifies with `hippo doctor`.
 
 ```
@@ -909,7 +911,7 @@ The rows from where the data lives to the graph were checked against each tool's
 | Feature | Hippo | [MemPalace](https://github.com/milla-jovovich/mempalace) | [Mem0](https://github.com/mem0ai/mem0) | [Basic Memory](https://github.com/basicmachines-co/basic-memory) | [gbrain](https://hermesatlas.com/projects/garrytan/gbrain) | [Zep](https://www.getzep.com/) | [Letta](https://github.com/letta-ai/letta-code) | [Cognee](https://www.cognee.ai/) | [Memoria](https://github.com/matrixorigin/Memoria) | [EverMind](https://evermind.ai/) |
 |---------|-------|-----------|------|-------------|--------|-----|-------|--------|---------|----------|
 | Where your data lives | Your machine or your server (SQLite) | Your machine (ChromaDB by default) | Where you run it, or Mem0's cloud | Your machine (Markdown files); cloud optional | Your machine (PGLite) or your Postgres | Zep's cloud (your own cloud on Enterprise) | Your machine; cloud backup with /login | Your machine by default; Cognee Cloud optional | Memoria Cloud, or self-hosted (Docker or embedded) | Your machine by default; EverOS Cloud optional |
-| Managed multi-user service | No (self-hosted, with tenants and API keys; the commercial edition adds hosted SaaS) | ? | Yes (hosted platform) | Yes (Teams) | ? (self-hosted server with OAuth) | Yes (Zep Cloud) | ? (cloud backup with /login) | Yes (Cognee Cloud) | ? (Memoria Cloud) | Yes (EverOS Cloud) |
+| Managed multi-user service | No (self-hosted, with tenants and API keys; hosted SaaS is planned for the commercial edition) | ? | Yes (hosted platform) | Yes (Teams) | ? (self-hosted server with OAuth) | Yes (Zep Cloud) | ? (cloud backup with /login) | Yes (Cognee Cloud) | ? (Memoria Cloud) | Yes (EverOS Cloud) |
 | Needs an account or model key | No | No (core path) | Yes (model key; account for the platform) | No (account for the cloud) | No (keyless mode) | Yes (Zep account; Graphiti needs a model key) | Yes (your own model keys) | No (local) | ? (account for Memoria Cloud) | Yes (an LLM key, OpenRouter) |
 | License | MIT | MIT | Apache-2.0 | AGPL-3.0 | MIT | Proprietary cloud (Graphiti: Apache-2.0) | Apache-2.0 | Apache-2.0 | Apache-2.0 | Apache-2.0 (EverOS) + cloud |
 | Runtime | Node.js 22.16+, no runtime deps | Python 3.9+ (ChromaDB by default) | Python or Node.js (server: Postgres + pgvector) | Python (SQLite by default) | Bun (PGLite or Postgres + pgvector) | Managed service (Graphiti: Python + a graph database) | Node.js (npm) | Python (graph and vector stores, or Postgres) | A CLI binary + a MatrixOne database | Python (SQLite + LanceDB) |
@@ -1068,6 +1070,14 @@ Run `npm install -g hippo-memory`, then `hippo init` in the project. If the proj
 
 `hippo init` detects Claude Code, Codex, Cursor, OpenClaw, OpenCode and Pi. It installs hooks for Claude Code and OpenCode, adds 2 hooks to Codex's `hooks.json` when Codex is installed (Codex runs them once you trust them in `/hooks`), and adds instructions to an existing `AGENTS.md` for Codex, Cursor, OpenClaw and Pi. It only patches instruction files that already exist. Any MCP client can use the [MCP server](#mcp-server), and other tools can call the CLI or the HTTP API that `hippo serve` starts.
 
+### Does installation automatically save before compaction?
+
+Package installation alone does not enable automatic preservation on every agent. Complete the documented setup and required host trust; capture and compaction coverage depend on the integration.
+
+With the Claude Code hooks or native plugin configured, PreCompact saves a derivable working-state snapshot and a compaction record; PostCompact extracts the lessons listed in the compaction summary. A snapshot, a compaction record and a useful memory are different outputs, and post-compaction extraction is not a guarantee that every earlier lesson was saved before loss. Hippo's Codex hooks currently provide prompt delivery and post-compaction re-injection, with one-time trust in `/hooks`; they install no PreCompact save hook. Codex session-end capture requires the opt-in wrapper. MCP tool access and instruction files alone do not provide automatic lifecycle capture.
+
+Follow the [integration recipes](https://github.com/kitfunso/hippo-memory/tree/master/integrations) for the exact agent and mode. Automatic pre-loss preservation across all supported agents is planned under AZ4-AZ6 in the [roadmap](https://github.com/kitfunso/hippo-memory/blob/master/ROADMAP.md#current-execution-index); it is not a universal install-only capability today.
+
 ### Can I use hippo as an MCP memory server?
 
 Yes. `hippo mcp` runs the server over stdio, and `npx -y hippo-memory mcp` runs it without a global install. Add it to the MCP config of Claude Desktop, Cursor, Windsurf (now Devin Desktop), Cline or any other client (example [above](#mcp-server)); in Claude Code, run `claude mcp add hippo-memory -- hippo mcp`. The agent gets tools such as `hippo_recall`, `hippo_remember` and `hippo_outcome`.
@@ -1125,9 +1135,9 @@ The interesting problems:
 
 ## Open source and commercial
 
-Hippo is open core, and the line is drawn by who pays. Everything an individual developer or a self-hosted team needs is in this repository under MIT: the CLI, the MCP server, hooks, connectors, the dashboard, tenants, API keys, roles, per-key scope grants, the audit log and zero-touch memory. Code published here stays MIT and stays here.
+Hippo is open core. This repository provides the MIT core for individual developers and self-hosted teams: the CLI, the MCP server, supported hooks and adapters, connectors, the dashboard, tenants, API keys, admin/member roles, per-key scope grants and the audit log. Automatic capture and delivery depend on the configured integration; the all-agent low-touch acceptance work remains planned. Code published here stays MIT and stays here.
 
-A commercial edition for larger companies ships as a separate package under a commercial licence from KITFUNSO LTD. It adds SSO (OIDC and SAML sign-in), SCIM, an org admin view, the pilot report and telemetry join, SIEM export of the audit log, offline licence keys, hosted SaaS, and support with an SLA. Pull requests for those features belong there, not here; see [CONTRIBUTING.md](CONTRIBUTING.md).
+The commercial edition is planned; its private repository is a scaffold, not a released enterprise product. It is intended for larger companies as a separate package under a commercial licence from KITFUNSO LTD. Planned capabilities include SSO (OIDC and SAML sign-in), SCIM, organisation/team/project policy, an org admin view, the pilot report and telemetry join, SIEM export of the audit log, offline licence keys, hosted SaaS, and support with an SLA. Pull requests implementing those commercial features belong there; see [CONTRIBUTING.md](CONTRIBUTING.md). Release availability and independently verified benefit are separate milestones in the [roadmap](https://github.com/kitfunso/hippo-memory/blob/master/ROADMAP.md#current-execution-index).
 
 ## License
 

package/dist/api.d.ts

@@ -1195,7 +1195,7 @@ export interface SleepResult {
  * api.sleep itself will need to scope dedup / audit / delete by ctx.tenantId.
  *
  * Dedup and audit deletes each log a `forget` row with the ctx actor and a
- * `metadata.reason`. Pinned, raw and kept compaction-memory rows are never auto-deleted (canAutoDelete).
+ * `metadata.reason`. Pinned, raw, kept and object-backing rows are never auto-deleted (AUTOMATIC_DELETE_SQL).
  * dryRun previews consolidate, dedup and audit, then returns before share/ambient.
  */
 /**

package/dist/api.js

@@ -8,7 +8,7 @@
  */
 import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, } from './store.js';
+import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, memoriesBackingObjects, } from './store.js';
 import { RejectedValueError } from './rejection.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { listDormantRows, readDormantSnapshot, deleteDormantRow, hasDormantRow, } from './dormant.js';
@@ -2443,7 +2443,7 @@ export async function sleep(ctx, opts = {}) {
         // Phase 3: Quality audit (remove junk, report warnings; a dry run skips rows earlier phases would remove).
         const planned = new Set(dryRun ? [...(consolidateResult.removedIds ?? []), ...dedupResult.pairs.map((p) => p.removed)] : []);
         const allEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !planned.has(e.id));
-        const auditOut = phases.auditMemories(allEntries);
+        const auditOut = phases.auditMemories(allEntries, memoriesBackingObjects(ctx.hippoRoot));
         if (auditOut.issues.length > 0) {
             const errors = auditOut.issues.filter((i) => i.severity === 'error');
             const warnings = auditOut.issues.filter((i) => i.severity === 'warning');

package/dist/audit.d.ts

@@ -14,8 +14,9 @@ export interface AuditResult {
     clean: number;
 }
 export declare const STOP_WORDS: Set<string>;
-export declare function auditMemory(entry: MemoryEntry): AuditIssue | null;
-export declare function auditMemories(entries: MemoryEntry[]): AuditResult;
+export declare function auditMemory(entry: MemoryEntry, backsObject?: boolean): AuditIssue | null;
+/** `backing`: ids of memories that back an object (store.memoriesBackingObjects). */
+export declare function auditMemories(entries: MemoryEntry[], backing: ReadonlySet<string>): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;
 export declare const AUDIT_OPS: readonly ["remember", "recall", "promote", "supersede", "forget", "archive_raw", "auth_revoke", "auth_create", "outcome", "consolidate", "audit_prune", "summary_marked_dirty", "summary_marked_clean", "summary_rebuilt", "predict_create", "predict_close", "predict_baserate", "recall_autodebias_hint", "recall_autodebias_hint_no_class_match", "recall_autodebias_hint_tiebreak", "recall_anchor_detected_query_repeat", "recall_anchor_detected_memory_dominance", "recall_anchor_skipped_no_session", "recall_availability_detected", "decision_create", "decision_supersede", "decision_close", "incident_open", "incident_resolve", "incident_close", "process_create", "process_supersede", "process_close", "policy_create", "policy_supersede", "policy_close", "skill_create", "skill_supersede", "skill_close", "project_brief_create", "project_brief_supersede", "project_brief_close", "customer_note_create", "customer_note_supersede", "customer_note_close", "mv_rescue", "reject_value", "reject_refusal", "unreject_value", "conflict_resolve", "half_life_migrate", "dormant_restore", "auth_grant", "auth_ungrant", "quarantine", "quarantine_approve", "quarantine_reject", "agent_memory_restore", "agent_memory_set_aside"];
 export type AuditOp = (typeof AUDIT_OPS)[number];

package/dist/audit.js

@@ -109,11 +109,11 @@ function hasNoSpecificity(text) {
         return false;
     return words.length < 8 && VAGUE_ONLY.test(text);
 }
-export function auditMemory(entry) {
+export function auditMemory(entry, backsObject = false) {
     const issue = classifyMemory(entry);
-    // Error means "auto-remove"; a pinned, raw or kept-for-good row is never auto-removed, so it can only warn.
-    if (issue?.severity === 'error' && !canAutoDelete(entry)) {
-        const why = entry.pinned ? 'pinned' : entry.kind === 'raw' ? 'raw' : 'keep rule';
+    // Error means "auto-remove"; a pinned, raw, kept-for-good or object-backing row is never auto-removed, so it can only warn.
+    if (issue?.severity === 'error' && (!canAutoDelete(entry) || backsObject)) {
+        const why = entry.pinned ? 'pinned' : entry.kind === 'raw' ? 'raw' : backsObject ? 'backs an object' : 'keep rule';
         return { ...issue, severity: 'warning', reason: `${issue.reason} (${why}, kept)` };
     }
     return issue;
@@ -141,10 +141,11 @@ function classifyMemory(entry) {
     }
     return null;
 }
-export function auditMemories(entries) {
+/** `backing`: ids of memories that back an object (store.memoriesBackingObjects). */
+export function auditMemories(entries, backing) {
     const issues = [];
     for (const entry of entries) {
-        const issue = auditMemory(entry);
+        const issue = auditMemory(entry, backing.has(entry.id));
         if (issue)
             issues.push(issue);
     }

package/dist/cli.js

@@ -40,7 +40,7 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync, execSync, spawn } from 'child_process';
 import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths, detectInstalledTools, defaultSleepLogPath, ensureCodexWrapperInstalled, installCodexWrapper, detectRealCodexPath, isCodexPresent, isCodexWrapperInstalled, CODEX_TRUST_LINE, repairCodexWrapperIfInstalled, uninstallCodexWrapper, resolveCodexSessionTranscript, resolveCodexWrapperPaths, installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPath, } from './hooks.js';
 import { createMemory, createSuccessor, calculateStrength, calculateRewardFactor, deriveHalfLife, resolveConfidence, confidenceFacets, confidenceLabel, computeSchemaFit, Layer, } from './memory.js';
-import { getHippoRoot, isInitialized, initStore, writeEntry, strengthenRetrieved, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from './store.js';
+import { getHippoRoot, isInitialized, initStore, writeEntry, strengthenRetrieved, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, memoriesBackingObjects, } from './store.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { RejectedValueError } from './rejection.js';
 import { isHandoffOutcome, formatHandoffEvidenceLine } from './handoff.js';
@@ -7707,23 +7707,6 @@ function cmdDailyRunner() {
     });
     console.log(`Daily maintenance complete: ${processed} workspace${processed === 1 ? '' : 's'} processed, ${failed} command failure${failed === 1 ? '' : 's'}.`);
 }
-// JSON-hook install/uninstall lives in ./hooks.ts so tests can import it
-// without running the CLI main(). Backwards-compatible wrappers below keep
-// older call sites working.
-function installClaudeCodeSessionEndHook() {
-    const result = installJsonHooks('claude-code');
-    return {
-        installed: result.installedSessionEnd ||
-            result.installedSessionStart ||
-            result.installedUserPromptSubmit ||
-            result.installedPreCompact ||
-            result.installedCompactResume,
-        migratedFromStop: result.migratedFromStop,
-    };
-}
-function uninstallClaudeCodeSessionEndHook() {
-    return uninstallJsonHooks('claude-code');
-}
 // ---------------------------------------------------------------------------
 // Working Memory
 // ---------------------------------------------------------------------------
@@ -9611,7 +9594,7 @@ async function main(command, args, flags, hippoRoot) {
             }
             requireInit(hippoRoot);
             const entries = loadAllEntries(hippoRoot, resolveTenantId({}));
-            const result = auditMemories(entries);
+            const result = auditMemories(entries, memoriesBackingObjects(hippoRoot));
             const shouldFix = Boolean(flags['fix']);
             if (result.issues.length === 0) {
                 console.log(`All ${result.total} memories passed quality checks.`);

package/dist/compaction-record.js

@@ -8,9 +8,8 @@ import { closeHippoDb, isSqliteBusy, openHippoDb } from './db.js';
 import { gatedWrite } from './gated-write.js';
 import { COMPACTION_MEMORY_TAG, COMPACTION_SOURCE_PREFIX, Layer, createMemory, generateId } from './memory.js';
 import { deriveOriginProject, isGlobalStoreRoot } from './project-identity.js';
-import { duplicateKey } from './same-text.js';
 import { maskEmails, redactSecretsStrict } from './secret-detect.js';
-import { updateStats, writeEntryMirrors } from './store.js';
+import { strengthenRetrievedOn, updateStats, writeEntryMirrors } from './store.js';
 import { resolveTenantId } from './tenant.js';
 /** PostCompact has 10 s in all (PreCompact 30 s), so a locked store must be given up on early. */
 export const COMPACTION_DB_WAIT_MS = 2000;
@@ -133,11 +132,33 @@ function recordSummary(db, hippoRoot, tenantId, meta, text, at) {
         snapshotSaved: false, startedAt: at.toISOString(), summarisedAt: now, summary: text.summary, items: text.items, itemsWritten: 0, status: 'summarised',
     };
 }
-/** Content of live compaction rows in one tenant and origin, by SQL: a compaction repeats what an earlier one listed. */
-function liveItemKeys(db, tenantId, originProject) {
-    // SAFETY: the SELECT names the single `content` column.
-    const rows = db.prepare(`SELECT content FROM memories WHERE tenant_id = ? AND origin_project = ? AND superseded_by IS NULL AND instr(tags_json, ?) > 0`).all(tenantId, originProject, `"${COMPACTION_MEMORY_TAG}"`);
-    return new Set(rows.map((r) => duplicateKey(r.content)));
+/** Words whose loss reverses or narrows a statement: "do not", "can't", "only", "unless". */
+const PROTECTED_WORDS = new Set(['not', 'no', 'never', 'none', 'nor', 'without', 'cannot', 't', 'only', 'except', 'unless', 'until']);
+/** Below this share of the held text's words, an item is a fragment of something longer, not a restatement. */
+const RESTATE_MIN_SHARE = 0.5;
+function words(text) {
+    return text.normalize('NFC').toLowerCase().split(/[^\p{L}\p{M}\p{N}_]+/u).filter(Boolean);
+}
+/** True when `item` is `held` with words left out, in the same order, keeping every number and protected word. Spacing, case and punctuation may differ. */
+function restates(item, held) {
+    if (item.length === 0 || item.length < RESTATE_MIN_SHARE * held.length)
+        return false;
+    const kept = new Set(item);
+    let next = 0;
+    for (const w of held) {
+        if (next < item.length && w === item[next])
+            next++;
+        else if (!kept.has(w) && (PROTECTED_WORDS.has(w) || /\p{N}/u.test(w)))
+            return false;
+    }
+    return next === item.length;
+}
+/** Live rows of one tenant and origin that default recall shows: a compaction often restates what an earlier one, or the user, already saved. */
+function heldRows(db, tenantId, originProject) {
+    // SAFETY: the SELECT names the id, source_session_id and content columns.
+    const rows = db.prepare(`SELECT id, source_session_id, content FROM memories WHERE tenant_id = ? AND origin_project = ? AND superseded_by IS NULL AND kind != 'raw'
+       AND (scope IS NULL OR (scope != 'unknown:legacy' AND scope NOT LIKE '%:private:%'))`).all(tenantId, originProject);
+    return rows.map((r) => ({ id: r.id, sessionId: r.source_session_id, words: words(r.content) }));
 }
 /** Items that become rows, then the record `done`, in one transaction so two sessions cannot both insert one text. Mirrors after commit. */
 export function saveItems(db, hippoRoot, ctx, log) {
@@ -165,11 +186,15 @@ export function saveItems(db, hippoRoot, ctx, log) {
                 return current?.items_written ?? 0;
             }
         }
-        const seen = liveItemKeys(db, ctx.tenantId, ctx.originProject);
+        const held = heldRows(db, ctx.tenantId, ctx.originProject);
+        const restated = new Set();
         for (const text of rows) {
-            const key = duplicateKey(text);
-            if (seen.has(key)) {
+            const itemWords = words(text);
+            const match = held.find((h) => restates(itemWords, h.words));
+            if (match) {
                 repeats++;
+                if (match.id !== null && match.sessionId !== ctx.sessionId)
+                    restated.add(match.id);
                 continue;
             }
             // createMemory throws below 3 chars, which would sink the whole transaction.
@@ -192,12 +217,14 @@ export function saveItems(db, hippoRoot, ctx, log) {
             };
             if (gatedWrite(db, hippoRoot, entry, { actor: 'post-compact' }) === 'written') {
                 written.push(entry);
-                seen.add(key);
+                held.push({ id: null, sessionId: ctx.sessionId, words: itemWords });
             }
             else {
                 refused++;
             }
         }
+        // Said again by another session is the same signal as being recalled; the same session carrying it forward is not.
+        strengthenRetrievedOn(db, [...restated], ctx.tenantId);
         if (ctx.recordId !== null) {
             db.prepare(`UPDATE compactions SET items_written = ?, status = 'done' WHERE tenant_id = ? AND id = ?`).run(written.length, ctx.tenantId, ctx.recordId);
         }
@@ -211,7 +238,7 @@ export function saveItems(db, hippoRoot, ctx, log) {
         throw err;
     }
     if (repeats > 0)
-        log(`skipped ${repeats} item(s) an earlier compaction already saved`);
+        log(`skipped ${repeats} item(s) the store already holds`);
     if (refused > 0)
         log(`skipped ${refused} item(s) the write gate refused`);
     for (const entry of written)

package/dist/consolidate.d.ts

@@ -37,8 +37,6 @@ export interface ConsolidationResult {
     /** Ids the decay pass removes (or would remove, under dryRun). */
     removedIds?: string[];
 }
-/** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL); tests/dormant-memories.test.ts pins it to the schema. */
-export declare const MEMORY_BACKED_TABLES: readonly ["predictions", "decisions", "incidents", "processes", "policies", "skills", "project_briefs", "customer_notes"];
 /**
  * Run a full consolidation pass.
  */

package/dist/consolidate.js

@@ -8,7 +8,7 @@
  */
 import { evalNow, isRecallBoostAblated } from './ablation.js';
 import { Layer, calculateStrength, canAutoDelete, createMemory } from './memory.js';
-import { loadAllEntries, batchWriteAndDelete, appendConsolidationRun, replaceDetectedConflicts, loadSessionDecayContext, incrementSleepCount, findPromotableSessions, traceExistsForSession, listSessionEvents, } from './store.js';
+import { loadAllEntries, batchWriteAndDelete, appendConsolidationRun, replaceDetectedConflicts, loadSessionDecayContext, incrementSleepCount, findPromotableSessions, traceExistsForSession, listSessionEvents, memoriesBackingObjects, } from './store.js';
 import { textOverlap, markRetrieved, tokenize } from './search.js';
 import { compareEntryIdentity } from './compare.js';
 import { duplicateKey, mergedText } from './same-text.js';
@@ -72,39 +72,6 @@ function keptAsWritten(entry) {
 function isJsonString(value) {
     return typeof value === 'string';
 }
-/** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL); tests/dormant-memories.test.ts pins it to the schema. */
-export const MEMORY_BACKED_TABLES = ['predictions', 'decisions', 'incidents', 'processes', 'policies', 'skills', 'project_briefs', 'customer_notes'];
-/**
- * Ids of memories that back a first-class object (a decision, incident, prediction,
- * process, policy, skill, project brief or customer note). Sleep never
- * retires these: deleting or moving one to dormant storage fires the
- * object's ON DELETE SET NULL and a restore cannot repair the link. Their
- * lifecycle belongs to the object. A table missing from an older schema is
- * skipped.
- */
-function memoriesBackingObjects(hippoRoot) {
-    const ids = new Set();
-    const db = openHippoDb(hippoRoot);
-    try {
-        for (const table of MEMORY_BACKED_TABLES) {
-            try {
-                // SAFETY: SELECT of one nullable TEXT column, filtered to non-null.
-                const rows = db.prepare(`SELECT memory_id FROM ${table} WHERE memory_id IS NOT NULL`).all();
-                for (const r of rows)
-                    ids.add(r.memory_id);
-            }
-            catch (err) {
-                // A missing table is an older schema; any other error could hide a backing memory, so sleep stops.
-                if (!(err instanceof Error && err.message.includes('no such table')))
-                    throw err;
-            }
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    return ids;
-}
 /**
  * Run a full consolidation pass.
  */

package/dist/dedupe.js

@@ -21,7 +21,7 @@
  * superseded rows are not candidates at all (v1.38.1).
  */
 import { textOverlap } from './search.js';
-import { loadAllEntries, deleteEntry } from './store.js';
+import { loadAllEntries, deleteEntry, memoriesBackingObjects } from './store.js';
 import { compareEntryIdentity } from './compare.js';
 import { canAutoDelete } from './memory.js';
 import { derivationPartitionKey } from './recall-scope.js';
@@ -97,6 +97,7 @@ export function deduplicateStore(hippoRoot, options = {}) {
     // primary-key id alone.
     const removed = new Set();
     const pairs = [];
+    const backing = memoriesBackingObjects(hippoRoot);
     for (const tenantEntries of entriesByTenant.values()) {
         // The v1.26.3 survivor total order (see the file-level docstring:
         // strength bucket desc -> retrieval_count desc -> compareEntryIdentity),
@@ -116,7 +117,7 @@ export function deduplicateStore(hippoRoot, options = {}) {
             if (removed.has(tenantEntries[i].id))
                 continue;
             for (let j = i + 1; j < tenantEntries.length; j++) {
-                if (removed.has(tenantEntries[j].id) || !canAutoDelete(tenantEntries[j]))
+                if (removed.has(tenantEntries[j].id) || !canAutoDelete(tenantEntries[j]) || backing.has(tenantEntries[j].id))
                     continue;
                 if (texts[j] !== texts[i])
                     continue;

package/dist/memory.d.ts

@@ -215,7 +215,7 @@ export declare function resolveConfidence(entry: MemoryEntry, now?: Date): Confi
 export declare const DEFAULT_HALF_LIFE_DAYS = 365;
 export declare const COMPACTION_MEMORY_TAG = "compaction-memory";
 export declare const COMPACTION_SOURCE_PREFIX = "compaction:";
-/** A row with `tag` and a source starting `sourcePrefix` is kept for good. Both, since merge copies source tags onto rows whose source is 'consolidation'. */
+/** An imported agent memory (its tool's tag, and a source starting that tool's prefix) is kept for good: the agent's note file is its record. Both, since merge copies source tags onto rows whose source is 'consolidation'. */
 export interface KeepPair {
     readonly tag: string;
     readonly sourcePrefix: string;

package/dist/memory.js

@@ -317,10 +317,7 @@ export function resolveConfidence(entry, now = evalNow()) {
 export const DEFAULT_HALF_LIFE_DAYS = 365;
 export const COMPACTION_MEMORY_TAG = 'compaction-memory';
 export const COMPACTION_SOURCE_PREFIX = 'compaction:';
-export const KEEP_PAIRS = [
-    { tag: COMPACTION_MEMORY_TAG, sourcePrefix: COMPACTION_SOURCE_PREFIX },
-    ...AGENT_MEMORY_TOOLS.map((t) => ({ tag: t.tag, sourcePrefix: toolSourcePrefix(t.id) })),
-];
+export const KEEP_PAIRS = AGENT_MEMORY_TOOLS.map((t) => ({ tag: t.tag, sourcePrefix: toolSourcePrefix(t.id) }));
 const sqlText = (s) => `'${s.replace(/'/g, "''")}'`;
 // json_each matches the tag as a whole element; substr, not LIKE, keeps the prefix case-sensitive like startsWith.
 const keepPairSql = (p) => `(COALESCE(superseded_by, '') = '' AND EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(tags_json) THEN tags_json ELSE '[]' END) WHERE value = ${sqlText(p.tag)}) AND substr(source, 1, ${p.sourcePrefix.length}) = ${sqlText(p.sourcePrefix)})`;

package/dist/store.d.ts

@@ -289,6 +289,8 @@ export declare function loadEntriesByIds(hippoRoot: string, ids: readonly string
 /** Strengthen what a read returned: update only the four retrieval columns on the live row, never a stale copy.
  *  Best effort: a failure logs and never fails the read. Returns the ids found in this store. */
 export declare function strengthenRetrieved(hippoRoot: string, ids: readonly string[], tenantId?: string): Set<string>;
+/** strengthenRetrieved on the caller's handle, inside the caller's transaction. Throws; the caller decides. */
+export declare function strengthenRetrievedOn(db: DatabaseSyncLike, ids: readonly string[], tenantId?: string): Set<string>;
 /**
  * All `kind='raw'` rows for a given session, tenant-scoped, returned
  * oldest-first. Used by `api.assemble` to walk a session's chronological
@@ -350,6 +352,10 @@ export declare function loadFreshRawMemories(hippoRoot: string, count: number, t
  * Used by `drillDown` (Task 3).
  */
 export declare function loadChildrenOf(hippoRoot: string, parentId: string, tenantId?: string): MemoryEntry[];
+/** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL); tests/dormant-memories.test.ts pins it to the schema. */
+export declare const MEMORY_BACKED_TABLES: readonly ["predictions", "decisions", "incidents", "processes", "policies", "skills", "project_briefs", "customer_notes"];
+/** Ids of memories that back a first-class object, for passes that plan deletes before making them. A table missing from an older schema is skipped. */
+export declare function memoriesBackingObjects(hippoRoot: string): Set<string>;
 /**
  * AT1 (plan §4, round-2 fix, designed from source): db-scoped delete core.
  * `deleteEntry` used to open+close its OWN connection, which meant it could
@@ -367,7 +373,7 @@ export declare function loadChildrenOf(hippoRoot: string, parentId: string, tena
  * Default keeps `deleteEntry` byte-identical to its pre-split behavior.
  *
  * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
- * existed or `automatic` refused it (pinned, raw or kept for good at DELETE time, so a late pin wins).
+ * existed or `automatic` refused it (pinned, raw, kept for good or backing an object at DELETE time, so a late pin wins).
  */
 export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id: string, opts?: {
     actor?: string;
@@ -400,7 +406,7 @@ export declare function deleteEntry(hippoRoot: string, id: string, opts?: {
  *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
  *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
  *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
- *  (pinned, raw or kept for good since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+ *  (pinned, raw, kept for good or backing an object since the caller decided). Returns the ids that left `memories`, deleted or moved. */
 export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEntry[], toDeleteIds: string[], opts?: {
     snapshot?: ReadonlyMap<string, MemoryEntry>;
     dormant?: DormantMove[];

package/dist/store.js

@@ -1349,20 +1349,8 @@ export function strengthenRetrieved(hippoRoot, ids, tenantId) {
     try {
         db = openHippoDb(hippoRoot);
         db.exec('BEGIN IMMEDIATE');
-        const tenantClause = tenantId !== undefined ? ' AND tenant_id = ?' : '';
-        const select = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ?${tenantClause}`);
-        const live = [];
-        for (const id of ids) {
-            // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
-            const row = (tenantId !== undefined ? select.get(id, tenantId) : select.get(id));
-            if (row)
-                live.push(rowToEntry(row));
-        }
-        const update = db.prepare('UPDATE memories SET retrieval_count = ?, last_retrieved = ?, half_life_days = ?, strength = ? WHERE id = ?');
-        for (const e of markRetrieved(live)) {
-            update.run(e.retrieval_count, e.last_retrieved, e.half_life_days, e.strength, e.id);
-            found.add(e.id);
-        }
+        for (const id of strengthenRetrievedOn(db, ids, tenantId))
+            found.add(id);
         db.exec('COMMIT');
     }
     catch (error) {
@@ -1379,6 +1367,27 @@ export function strengthenRetrieved(hippoRoot, ids, tenantId) {
     }
     return found;
 }
+/** strengthenRetrieved on the caller's handle, inside the caller's transaction. Throws; the caller decides. */
+export function strengthenRetrievedOn(db, ids, tenantId) {
+    const found = new Set();
+    if (ids.length === 0 || isRecallBoostAblated())
+        return found;
+    const tenantClause = tenantId !== undefined ? ' AND tenant_id = ?' : '';
+    const select = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id = ?${tenantClause}`);
+    const live = [];
+    for (const id of ids) {
+        // SAFETY: the SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+        const row = (tenantId !== undefined ? select.get(id, tenantId) : select.get(id));
+        if (row)
+            live.push(rowToEntry(row));
+    }
+    const update = db.prepare('UPDATE memories SET retrieval_count = ?, last_retrieved = ?, half_life_days = ?, strength = ? WHERE id = ?');
+    for (const e of markRetrieved(live)) {
+        update.run(e.retrieval_count, e.last_retrieved, e.half_life_days, e.strength, e.id);
+        found.add(e.id);
+    }
+    return found;
+}
 /**
  * All `kind='raw'` rows for a given session, tenant-scoped, returned
  * oldest-first. Used by `api.assemble` to walk a session's chronological
@@ -1538,6 +1547,34 @@ export function loadChildrenOf(hippoRoot, parentId, tenantId) {
         closeHippoDb(db);
     }
 }
+/** Tables whose rows keep a first-class object's backing memory in `memory_id` (ON DELETE SET NULL); tests/dormant-memories.test.ts pins it to the schema. */
+export const MEMORY_BACKED_TABLES = ['predictions', 'decisions', 'incidents', 'processes', 'policies', 'skills', 'project_briefs', 'customer_notes'];
+/** Deleting a memory that backs an object nulls the object's link, and no restore can repair it, so no automatic pass may. */
+const AUTOMATIC_DELETE_SQL = `${AUTO_DELETABLE_SQL}${MEMORY_BACKED_TABLES.map((t) => ` AND NOT EXISTS (SELECT 1 FROM ${t} WHERE ${t}.memory_id = memories.id)`).join('')}`;
+/** Ids of memories that back a first-class object, for passes that plan deletes before making them. A table missing from an older schema is skipped. */
+export function memoriesBackingObjects(hippoRoot) {
+    const ids = new Set();
+    const db = openHippoDb(hippoRoot);
+    try {
+        for (const table of MEMORY_BACKED_TABLES) {
+            try {
+                // SAFETY: SELECT of one nullable TEXT column, filtered to non-null.
+                const rows = db.prepare(`SELECT memory_id FROM ${table} WHERE memory_id IS NOT NULL`).all();
+                for (const r of rows)
+                    ids.add(r.memory_id);
+            }
+            catch (err) {
+                // A missing table is an older schema; any other error could hide a backing memory, so the caller stops.
+                if (!(err instanceof Error && err.message.includes('no such table')))
+                    throw err;
+            }
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return ids;
+}
 /**
  * AT1 (plan §4, round-2 fix, designed from source): db-scoped delete core.
  * `deleteEntry` used to open+close its OWN connection, which meant it could
@@ -1555,7 +1592,7 @@ export function loadChildrenOf(hippoRoot, parentId, tenantId) {
  * Default keeps `deleteEntry` byte-identical to its pre-split behavior.
  *
  * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
- * existed or `automatic` refused it (pinned, raw or kept for good at DELETE time, so a late pin wins).
+ * existed or `automatic` refused it (pinned, raw, kept for good or backing an object at DELETE time, so a late pin wins).
  */
 export function deleteEntryCore(db, id, opts) {
     // SAFETY: row's shape matches the three columns named in the SELECT above.
@@ -1564,7 +1601,7 @@ export function deleteEntryCore(db, id, opts) {
         .get(id);
     if (!row?.id)
         return null;
-    const guard = opts?.automatic ? ` AND ${AUTO_DELETABLE_SQL}` : '';
+    const guard = opts?.automatic ? ` AND ${AUTOMATIC_DELETE_SQL}` : '';
     if (Number(db.prepare(`DELETE FROM memories WHERE id = ?${guard}`).run(id).changes ?? 0) === 0)
         return null;
     deleteFtsRow(db, id);
@@ -1622,7 +1659,7 @@ function mergeOwnChanges(base, ours, live) {
  *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
  *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
  *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
- *  (pinned, raw or kept for good since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+ *  (pinned, raw, kept for good or backing an object since the caller decided). Returns the ids that left `memories`, deleted or moved. */
 export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
     const dormantMoves = opts?.dormant ?? [];
     if (toWrite.length === 0 && toDeleteIds.length === 0 && dormantMoves.length === 0)
@@ -1650,7 +1687,7 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
             const placeholders = toDeleteIds.map(() => '?').join(',');
             // A row pinned after the caller decided to delete it survives.
             // SAFETY: rows' shape matches the three columns named in the SELECT.
-            const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders}) AND ${AUTO_DELETABLE_SQL}`).all(...toDeleteIds);
+            const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders}) AND ${AUTOMATIC_DELETE_SQL}`).all(...toDeleteIds);
             for (const row of rows) {
                 deletableIds.push(row.id);
                 if (row.dag_parent_id) {
@@ -1737,7 +1774,7 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
             const byId = new Map(dormantMoves.map((m) => [m.entry.id, m]));
             const placeholders = dormantMoves.map(() => '?').join(',');
             // SAFETY: rows' shape matches the three columns named in the SELECT.
-            const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders}) AND ${AUTO_DELETABLE_SQL}`).all(...byId.keys());
+            const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders}) AND ${AUTOMATIC_DELETE_SQL}`).all(...byId.keys());
             for (const row of rows) {
                 movable.push(byId.get(row.id));
                 if (row.dag_parent_id) {

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

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.53.0",
+  "version": "1.53.1",
   "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.53.0",
+  "version": "1.53.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.53.0",
+  "version": "1.53.1",
   "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",