hippo-memory 1.63.0 → 1.63.1

package/README.md

@@ -1,6 +1,6 @@
-# 🦛 Hippo: memory for AI agents that learns what is wrong
+# 🦛 Hippo
 
-**Hippo learns what is wrong and ranks it down.** Good memory is knowing what to forget: what turned out wrong, what got replaced, what nobody used.
+**Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.**
 
 [![npm](https://img.shields.io/npm/v/hippo-memory)](https://npmjs.com/package/hippo-memory)
 [![npm downloads](https://img.shields.io/npm/dm/hippo-memory)](https://npmjs.com/package/hippo-memory)

package/dist/cli/usage.d.ts

@@ -1,7 +1,7 @@
 export declare function printAuditPruneUsage(): void;
 export declare function printSlackBackfillUsage(): void;
 export declare function printSlackWorkspacesUsage(): void;
-export declare const USAGE_HEADER = "\nHippo - memory for AI agents that learns what is wrong and ranks it down\n\nUsage: hippo <command> [options]\n\nCommands:";
+export declare const USAGE_HEADER = "\nHippo - Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.\n\nUsage: hippo <command> [options]\n\nCommands:";
 export declare const USAGE_EXAMPLES = "\n\nExamples:\n  hippo init\n  hippo remember \"FRED cache can silently drop series\" --tag error\n  hippo recall \"data pipeline issues\" --budget 2000\n  hippo context --auto --budget 1500\n  hippo conflicts\n  hippo reject mem_abc123 --reason \"leaked credential\"\n  hippo reject --value \"never store my key again\" --reason \"secret\"\n  hippo rejections\n  hippo unreject a1b2c3d4e5f6\n  hippo dormant \"staging hostname\"\n  hippo dormant restore mem_abc123\n  hippo tokens --days 7\n  hippo session log --id sess_123 --task \"Ship feature\" --type progress --content \"Build is green, next step is docs\"\n  hippo session latest --json\n  hippo session resume\n  hippo snapshot save --task \"Ship feature\" --summary \"Tests are green\" --next-step \"Open the PR\" --session sess_123\n  hippo handoff create --summary \"PR is open, tests green\" --next \"Merge after review\" --session sess_123 --artifact src/foo.ts\n  hippo handoff create --summary s --constraint a --constraint b --outcome partial --target-runtime codex --card-id c1 --tests pass\n  hippo card create --title \"Add cards table\" --repo hippo --depends-on card_abc\n  hippo card claim card_abc --runtime codex\n  hippo card complete card_abc --outcome success\n  hippo card heartbeat card_abc --run 7\n  hippo card reclaim\n  hippo embed --status\n  hippo watch \"npm run build\"\n  hippo learn --git --days 30\n  hippo promote mem_abc123\n  hippo sync\n  hippo setup\n  hippo hook install claude-code\n  hippo decide \"Use PostgreSQL for new services\" --context \"JSONB support\"\n  hippo incident \"Prod outage: DB connection pool exhausted\" --context \"spike at 14:00\"\n  hippo process new \"Release\" --step \"run tests\" --step \"bump version\" --step \"publish\"\n  hippo policy new \"Data retention\" --text \"Delete logs after 90 days\" --from 2026-01-01\n  hippo policy asof 2026-03-01 --name \"Data retention\"\n  hippo skill new \"Run tests\" --instructions \"npm test before every commit\" --trigger \"before commit\"\n  hippo skill export\n  hippo brief new \"hippo\" --summary \"Agent-memory library; E2 first-class objects in progress\"\n  hippo brief refresh \"hippo\"\n  hippo note new \"Acme Corp\" --text \"Renewal call: wants SSO before Q3; champion is the VP Eng\"\n  hippo note list --customer \"Acme Corp\" --status active\n  hippo graph extract\n  hippo invalidate \"REST API\" --dry-run\n  hippo invalidate \"REST API\" --reason \"migrated to GraphQL\"\n  hippo invalidate --id mem_a1b2c3d4e5f6 --reason \"superseded by new policy\"\n  hippo invalidate --churn --dry-run\n  hippo export memories.json\n  hippo export --format markdown memories.md\n  hippo sleep --dry-run\n  hippo outcome --good\n  hippo status\n";
 /** Each verb's help blocks for the command table, keyed like COMMANDS; a block opens with a newline. */
 export declare const VERB_USAGE: {

package/dist/cli/usage.js

@@ -21,7 +21,7 @@ export function printSlackWorkspacesUsage() {
     console.log('  remove --team <T>             Remove a workspace registration');
 }
 export const USAGE_HEADER = `
-Hippo - memory for AI agents that learns what is wrong and ranks it down
+Hippo - Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.
 
 Usage: hippo <command> [options]
 

package/dist/consolidate/run.d.ts

@@ -41,6 +41,8 @@ interface LazyDb {
     close: () => void;
 }
 export declare function lazyConsolidateDb(hippoRoot: string, dryRun: boolean): LazyDb;
+/** Re-syncs the full-text index with `memories`; a store open that is already current no longer counts the two. */
+export declare function syncFtsIndex(hippoRoot: string, dryRun: boolean, result: ConsolidationResult): void;
 /** State every sleep stage reads or appends to; the pending lists are flushed in one transaction at the end. */
 export interface SleepRun {
     hippoRoot: string;

package/dist/consolidate/run.js

@@ -1,4 +1,4 @@
-import { openHippoDb, closeHippoDb } from '../db.js';
+import { openHippoDb, closeHippoDb, ftsRowCounts, isFtsAvailable, repairFtsDrift } from '../db.js';
 import { NO_MERGE_TAGS } from '../shared.js';
 export const REPLAY_COUNT_DEFAULT = 5;
 export function keptAsWritten(entry) {
@@ -25,6 +25,23 @@ export function lazyConsolidateDb(hippoRoot, dryRun) {
     };
     return { get, close };
 }
+/** Re-syncs the full-text index with `memories`; a store open that is already current no longer counts the two. */
+export function syncFtsIndex(hippoRoot, dryRun, result) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        if (!isFtsAvailable(db))
+            return;
+        const counts = ftsRowCounts(db);
+        if (counts === null || counts.memories === counts.fts)
+            return;
+        if (!dryRun)
+            repairFtsDrift(db);
+        result.details.push(`  🔎 ${dryRun ? 'would re-sync' : 're-synced'} the full-text index (${counts.fts} indexed rows for ${counts.memories} memories)`);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 export function newConsolidationResult(dryRun) {
     return {
         decayed: 0,

package/dist/consolidate/sleep.js

@@ -21,7 +21,7 @@ import { log } from '../log.js';
 import { decayPass } from './decay.js';
 import { retireHeldTexts, mergePass } from './merge.js';
 import { detectConflicts } from './conflicts.js';
-import { lazyConsolidateDb, newConsolidationResult } from './run.js';
+import { lazyConsolidateDb, newConsolidationResult, syncFtsIndex } from './run.js';
 import { promoteSessionTraces, replayPass } from './traces.js';
 import { llmPasses } from './llm-passes.js';
 import { physicsPass } from './physics-pass.js';
@@ -33,6 +33,7 @@ export async function consolidate(hippoRoot, options = {}) {
     const dryRun = options.dryRun ?? false;
     const result = newConsolidationResult(dryRun);
     const halfLife = migrateHalfLives(hippoRoot, dryRun, result);
+    syncFtsIndex(hippoRoot, dryRun, result);
     // Host-wide by design: per-tenant filtering would mean N runs per host and no cross-tenant dedup.
     // The api.sleep audit row tags this with the admin synthetic actor.
     const all = loadAllEntries(hippoRoot);

package/dist/db/continuity.d.ts

@@ -1,5 +1,10 @@
 import type { DatabaseSyncLike } from './sqlite.js';
 export declare const MEMORY_QUARANTINE_DDL = "\n    CREATE TABLE IF NOT EXISTS memory_quarantine (\n      tenant_id      TEXT NOT NULL DEFAULT 'default',\n      memory_id      TEXT NOT NULL,\n      original_scope TEXT,\n      reason         TEXT NOT NULL,\n      status         TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','approved','rejected')),\n      quarantined_at TEXT NOT NULL,\n      decided_at     TEXT,\n      decided_by     TEXT,\n      PRIMARY KEY (tenant_id, memory_id)\n    ) WITHOUT ROWID;\n    CREATE INDEX IF NOT EXISTS idx_memory_quarantine_status\n      ON memory_quarantine(tenant_id, status, quarantined_at DESC);\n";
 export declare function ensureContinuityTables(db: DatabaseSyncLike): void;
+export declare const MEMORIES_FTS_DDL = "CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, content, tags)";
+/** Names of every table and index a `CREATE ... IF NOT EXISTS` in `ddl` makes. */
+export declare function createdObjectNames(ddl: string): string[];
+/** Every object runMigrations re-asserts on a stamped store; the open fast path requires all of them. */
+export declare const REQUIRED_SCHEMA_OBJECTS: readonly string[];
 export declare function ensureContinuityIndexes(db: DatabaseSyncLike): void;
 //# sourceMappingURL=continuity.d.ts.map

package/dist/db/continuity.js

@@ -1,3 +1,4 @@
+import { META_TABLE_DDL } from './meta.js';
 // Shared by migration v48 and the stamped-store self-heal below.
 export const MEMORY_QUARANTINE_DDL = `
     CREATE TABLE IF NOT EXISTS memory_quarantine (
@@ -115,31 +116,48 @@ const CARD_COMMENTS_DDL = `
 // Before the loop on stamped stores: a table lost after its migration stamped
 // is never re-migrated, and v4/v16/v22 ALTER or read it. Fresh stores use the chain.
 export function ensureContinuityTables(db) {
-    db.exec(TASK_SNAPSHOTS_DDL);
-    db.exec(SESSION_EVENTS_DDL);
-    db.exec(SESSION_HANDOFFS_DDL);
-    db.exec(CARDS_DDL);
-    db.exec(CARD_DEPS_DDL);
-    db.exec(CARD_RUNS_DDL);
-    db.exec(CARD_COMMENTS_DDL);
-    db.exec(MEMORY_QUARANTINE_DDL);
+    for (const ddl of CONTINUITY_TABLE_DDL)
+        db.exec(ddl);
 }
+const CONTINUITY_TABLE_DDL = [
+    TASK_SNAPSHOTS_DDL,
+    SESSION_EVENTS_DDL,
+    SESSION_HANDOFFS_DDL,
+    CARDS_DDL,
+    CARD_DEPS_DDL,
+    CARD_RUNS_DDL,
+    CARD_COMMENTS_DDL,
+    MEMORY_QUARANTINE_DDL,
+];
+const CONTINUITY_INDEX_DDL = [
+    `CREATE INDEX IF NOT EXISTS idx_task_snapshots_status_updated ON task_snapshots(status, updated_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_task_snapshots_tenant_status ON task_snapshots(tenant_id, status, updated_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_task_snapshots_tenant_scope ON task_snapshots(tenant_id, scope, status)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_events_session_created ON session_events(session_id, created_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_events_task_created ON session_events(task, created_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_events_tenant_session ON session_events(tenant_id, session_id, created_at DESC, id DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_session ON session_handoffs(session_id, created_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_session ON session_handoffs(tenant_id, session_id, created_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_outcome ON session_handoffs(tenant_id, outcome, created_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_cards_tenant_status ON cards(tenant_id, status, updated_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_card_deps_tenant_child ON card_deps(tenant_id, child)`,
+    `CREATE INDEX IF NOT EXISTS idx_card_deps_tenant_parent ON card_deps(tenant_id, parent)`,
+    `CREATE INDEX IF NOT EXISTS idx_card_runs_tenant_card ON card_runs(tenant_id, card, started DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_card_comments_tenant_card ON card_comments(tenant_id, card_id, created_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_card ON session_handoffs(tenant_id, card_id, created_at DESC)`,
+];
+// Lives with the other re-asserted DDL so the required-object list below derives from one place.
+export const MEMORIES_FTS_DDL = `CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, content, tags)`;
+const CREATED_NAME = /CREATE\s+(?:VIRTUAL\s+)?(?:TABLE|INDEX)\s+IF\s+NOT\s+EXISTS\s+(\w+)/gi;
+/** Names of every table and index a `CREATE ... IF NOT EXISTS` in `ddl` makes. */
+export function createdObjectNames(ddl) {
+    return [...ddl.matchAll(CREATED_NAME)].map((m) => m[1]);
+}
+/** Every object runMigrations re-asserts on a stamped store; the open fast path requires all of them. */
+export const REQUIRED_SCHEMA_OBJECTS = Object.freeze([META_TABLE_DDL, ...CONTINUITY_TABLE_DDL, ...CONTINUITY_INDEX_DDL, MEMORIES_FTS_DDL].flatMap(createdObjectNames));
 // After the loop: tenant_id (v16) and scope (v23) do not exist yet on a genuine old store.
 export function ensureContinuityIndexes(db) {
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_task_snapshots_status_updated ON task_snapshots(status, updated_at DESC, id DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_task_snapshots_tenant_status ON task_snapshots(tenant_id, status, updated_at DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_task_snapshots_tenant_scope ON task_snapshots(tenant_id, scope, status)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_session_events_session_created ON session_events(session_id, created_at DESC, id DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_session_events_task_created ON session_events(task, created_at DESC, id DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_session_events_tenant_session ON session_events(tenant_id, session_id, created_at DESC, id DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_session_handoffs_session ON session_handoffs(session_id, created_at DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_session ON session_handoffs(tenant_id, session_id, created_at DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_outcome ON session_handoffs(tenant_id, outcome, created_at DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_cards_tenant_status ON cards(tenant_id, status, updated_at DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_card_deps_tenant_child ON card_deps(tenant_id, child)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_card_deps_tenant_parent ON card_deps(tenant_id, parent)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_card_runs_tenant_card ON card_runs(tenant_id, card, started DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_card_comments_tenant_card ON card_comments(tenant_id, card_id, created_at DESC)`);
-    db.exec(`CREATE INDEX IF NOT EXISTS idx_session_handoffs_tenant_card ON session_handoffs(tenant_id, card_id, created_at DESC)`);
+    for (const ddl of CONTINUITY_INDEX_DDL)
+        db.exec(ddl);
 }
 //# sourceMappingURL=continuity.js.map

package/dist/db/meta.d.ts

@@ -1,4 +1,5 @@
 import type { DatabaseSyncLike } from './sqlite.js';
+export declare const META_TABLE_DDL = "\n    CREATE TABLE IF NOT EXISTS meta (\n      key TEXT PRIMARY KEY,\n      value TEXT NOT NULL\n    );\n  ";
 export declare function ensureMetaTable(db: DatabaseSyncLike): void;
 export declare function getSchemaVersion(db: DatabaseSyncLike): number;
 export declare function setSchemaVersion(db: DatabaseSyncLike, version: number): void;

package/dist/db/meta.js

@@ -1,11 +1,12 @@
 import { tableExists } from './tables.js';
-export function ensureMetaTable(db) {
-    db.exec(`
+export const META_TABLE_DDL = `
     CREATE TABLE IF NOT EXISTS meta (
       key TEXT PRIMARY KEY,
       value TEXT NOT NULL
     );
-  `);
+  `;
+export function ensureMetaTable(db) {
+    db.exec(META_TABLE_DDL);
 }
 export function getSchemaVersion(db) {
     if (!tableExists(db, 'meta'))

package/dist/db/migrate.d.ts

@@ -5,5 +5,14 @@ export declare class IncompatibleBinaryError extends Error {
 }
 /** Refuse a store stamped for a newer binary. Fails closed: runMigrations creates meta first, so a failed read is a real error. */
 export declare function assertBinaryCompatible(db: DatabaseSyncLike): void;
+/** The fast path's single probe: versions, the binary minimum, the FTS flag, and counts of the meta defaults and required objects. */
+export declare const SCHEMA_PROBE_SQL: string;
 export declare function runMigrations(db: DatabaseSyncLike, hippoRoot?: string, busyWaitMs?: number): void;
+/** Row counts of `memories` and its full-text index, which differ once the index drifts; null when either table is missing. */
+export declare function ftsRowCounts(db: DatabaseSyncLike): {
+    memories: number;
+    fts: number;
+} | null;
+/** Re-syncs `memories_fts` with `memories` when their counts differ and returns whether it did; sleep runs it because a fast open does not. */
+export declare function repairFtsDrift(db: DatabaseSyncLike): boolean;
 //# sourceMappingURL=migrate.d.ts.map

package/dist/db/migrate.js

@@ -4,7 +4,7 @@ import { importLegacyEmbeddingIndex } from '../vector-store.js';
 import { execWithBusyRetry } from './busy.js';
 import { tableExists } from './tables.js';
 import { ensureMetaTable, getMeta, getSchemaVersion, setMeta, setSchemaVersion } from './meta.js';
-import { ensureContinuityIndexes, ensureContinuityTables } from './continuity.js';
+import { MEMORIES_FTS_DDL, REQUIRED_SCHEMA_OBJECTS, ensureContinuityIndexes, ensureContinuityTables } from './continuity.js';
 import { CURRENT_SCHEMA_VERSION, MIGRATIONS } from './migrations/index.js';
 export function getCurrentSchemaVersion() {
     return CURRENT_SCHEMA_VERSION;
@@ -12,15 +12,64 @@ export function getCurrentSchemaVersion() {
 /** Thrown by {@link assertBinaryCompatible}; doctor uses it to pick the upgrade fix over a generic permissions fix. */
 export class IncompatibleBinaryError extends Error {
 }
-/** Refuse a store stamped for a newer binary. Fails closed: runMigrations creates meta first, so a failed read is a real error. */
-export function assertBinaryCompatible(db) {
-    const minRequired = getMeta(db, 'min_compatible_binary');
+function assertMinBinary(minRequired) {
     if (minRequired && compareSemver(minRequired, PACKAGE_VERSION) > 0) {
         throw new IncompatibleBinaryError(`hippo-memory: this database requires hippo-memory >= ${minRequired}, but the running binary is ${PACKAGE_VERSION}. ` +
             `Upgrade hippo-memory to open it; an older binary does not know this schema and could expose private rows or damage the store.`);
     }
 }
+/** Refuse a store stamped for a newer binary. Fails closed: runMigrations creates meta first, so a failed read is a real error. */
+export function assertBinaryCompatible(db) {
+    assertMinBinary(getMeta(db, 'min_compatible_binary'));
+}
+const META_DEFAULTS = [
+    ['schema_version', String(CURRENT_SCHEMA_VERSION)],
+    ['last_retrieval_ids', '[]'],
+    ['last_trace_id', ''],
+    ['total_remembered', '0'],
+    ['total_recalled', '0'],
+    ['total_forgotten', '0'],
+    ['fts5_available', '0'],
+];
+// Names come from our own constants and match \w+, so inlining them as literals is safe.
+const sqlList = (names) => names.map((n) => `'${n}'`).join(', ');
+/** The fast path's single probe: versions, the binary minimum, the FTS flag, and counts of the meta defaults and required objects. */
+export const SCHEMA_PROBE_SQL = `SELECT
+  (SELECT user_version FROM pragma_user_version) AS user_version,
+  (SELECT value FROM meta WHERE key = 'schema_version') AS schema_version,
+  (SELECT value FROM meta WHERE key = 'min_compatible_binary') AS min_binary,
+  (SELECT value FROM meta WHERE key = 'fts5_available') AS fts5,
+  (SELECT COUNT(*) FROM meta WHERE key IN (${sqlList(META_DEFAULTS.map(([key]) => key))})) AS meta_keys,
+  (SELECT COUNT(*) FROM sqlite_master WHERE type IN ('table', 'index') AND name IN (${sqlList(REQUIRED_SCHEMA_OBJECTS)})) AS objects`;
+/** True when the store is current and whole, so the open can skip every DDL statement. Runs the binary check either way. */
+function schemaIsCurrent(db) {
+    let probe;
+    try {
+        // SAFETY: the SELECT names exactly these six columns and always returns one row.
+        probe = db.prepare(SCHEMA_PROBE_SQL).get();
+    }
+    catch (err) {
+        // A store with no meta table yet is the slow path's job; anything else is a real error.
+        if (err instanceof Error && /no such table: meta/.test(err.message))
+            return false;
+        throw err;
+    }
+    if (!probe)
+        return false;
+    assertMinBinary(probe.min_binary);
+    return Number(probe.user_version) === CURRENT_SCHEMA_VERSION
+        && Number(probe.schema_version) === CURRENT_SCHEMA_VERSION
+        && Number(probe.meta_keys) === META_DEFAULTS.length
+        && Number(probe.objects) === REQUIRED_SCHEMA_OBJECTS.length
+        && probe.fts5 === '1';
+}
 export function runMigrations(db, hippoRoot, busyWaitMs) {
+    if (!schemaIsCurrent(db))
+        migrateAndHeal(db, hippoRoot, busyWaitMs);
+    if (hippoRoot)
+        importLegacyVectors(db, hippoRoot);
+}
+function migrateAndHeal(db, hippoRoot, busyWaitMs) {
     ensureMetaTable(db);
     // Before anything writes, so a stale binary never repairs or migrates a store it does not understand.
     assertBinaryCompatible(db);
@@ -30,36 +79,46 @@ export function runMigrations(db, hippoRoot, busyWaitMs) {
     for (const migration of MIGRATIONS) {
         if (migration.version <= currentVersion)
             continue;
-        execWithBusyRetry(db, 'BEGIN IMMEDIATE', busyWaitMs);
-        try {
-            // A newer binary may have migrated and raised the minimum while we waited for the lock.
-            assertBinaryCompatible(db);
-            // Re-read under the write lock: another process may have applied this
-            // migration while we waited, and re-running one is not idempotent.
-            const applied = getSchemaVersion(db);
-            if (applied >= migration.version) {
-                db.exec('COMMIT');
-                currentVersion = applied;
-                continue;
-            }
-            migration.up(db, { hippoRoot });
-            setSchemaVersion(db, migration.version);
-            db.exec('COMMIT');
-            currentVersion = migration.version;
-        }
-        catch (error) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back; keep the original error */ }
-            throw error;
-        }
+        currentVersion = applyMigration(db, migration, hippoRoot, busyWaitMs);
     }
+    healUserVersion(db, currentVersion, busyWaitMs);
     ensureContinuityIndexes(db);
     ensureMetaDefaults(db);
     ensureOptionalFts(db);
-    if (hippoRoot)
-        importLegacyVectors(db, hippoRoot);
+}
+/** Applies one migration under the write lock and returns the version the store is now at. */
+function applyMigration(db, migration, hippoRoot, busyWaitMs) {
+    execWithBusyRetry(db, 'BEGIN IMMEDIATE', busyWaitMs);
+    try {
+        // A newer binary may have migrated and raised the minimum while we waited for the lock.
+        assertBinaryCompatible(db);
+        // Re-read under the write lock: another process may have applied this
+        // migration while we waited, and re-running one is not idempotent.
+        const applied = getSchemaVersion(db);
+        if (applied >= migration.version) {
+            db.exec('COMMIT');
+            return applied;
+        }
+        migration.up(db, { hippoRoot });
+        setSchemaVersion(db, migration.version);
+        db.exec('COMMIT');
+        return migration.version;
+    }
+    catch (error) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* already rolled back; keep the original error */ }
+        throw error;
+    }
+}
+// The fast path requires user_version as well, and a store stamped only in meta would otherwise never reach it.
+function healUserVersion(db, version, busyWaitMs) {
+    // SAFETY: PRAGMA user_version returns one row with one integer column.
+    const row = db.prepare('PRAGMA user_version').get();
+    const target = Math.max(0, Math.trunc(version));
+    if (Number(row?.user_version ?? 0) < target)
+        execWithBusyRetry(db, `PRAGMA user_version = ${target}`, busyWaitMs);
 }
 // A failed import leaves embeddings.json in place for the next open to retry; the store still opens.
 function importLegacyVectors(db, hippoRoot) {
@@ -71,27 +130,18 @@ function importLegacyVectors(db, hippoRoot) {
     }
 }
 function ensureMetaDefaults(db) {
-    const defaults = [
-        ['schema_version', String(CURRENT_SCHEMA_VERSION)],
-        ['last_retrieval_ids', '[]'],
-        ['last_trace_id', ''],
-        ['total_remembered', '0'],
-        ['total_recalled', '0'],
-        ['total_forgotten', '0'],
-        ['fts5_available', '0'],
-    ];
     // Read-first: an already-current store has all 7 keys, so this is one
     // SELECT and zero writes instead of 7 no-op INSERT OR IGNOREs, each of
     // which takes a RESERVED lock even when nothing changes.
-    const keys = defaults.map(([key]) => key);
+    const keys = META_DEFAULTS.map(([key]) => key);
     const present = new Set(db
         .prepare(`SELECT key FROM meta WHERE key IN (${keys.map(() => '?').join(',')})`)
         .all(...keys)
         .map((r) => r.key));
-    if (present.size === defaults.length)
+    if (present.size === META_DEFAULTS.length)
         return;
     const stmt = db.prepare(`INSERT OR IGNORE INTO meta(key, value) VALUES (?, ?)`);
-    for (const [key, value] of defaults) {
+    for (const [key, value] of META_DEFAULTS) {
         if (!present.has(key))
             stmt.run(key, value);
     }
@@ -99,8 +149,8 @@ function ensureMetaDefaults(db) {
 function ensureOptionalFts(db) {
     let available = false;
     try {
-        db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, content, tags)`);
-        backfillFtsIndex(db);
+        db.exec(MEMORIES_FTS_DDL);
+        repairFtsDrift(db);
         available = true;
     }
     catch (err) {
@@ -112,16 +162,23 @@ function ensureOptionalFts(db) {
     if (getMeta(db, 'fts5_available') !== flag)
         setMeta(db, 'fts5_available', flag);
 }
-function backfillFtsIndex(db) {
-    // SAFETY: this get() result's shape matches the single aliased `c` column
-    // named in the SELECT above.
-    const memCount = db.prepare(`SELECT COUNT(*) AS c FROM memories`).get()?.c ?? 0;
-    // SAFETY: this get() result's shape matches the single aliased `c` column named in the SELECT above.
+/** Row counts of `memories` and its full-text index, which differ once the index drifts; null when either table is missing. */
+export function ftsRowCounts(db) {
+    if (!tableExists(db, 'memories_fts') || !tableExists(db, 'memories'))
+        return null;
+    // SAFETY: this get() result's shape matches the single aliased `c` column named in the SELECT.
+    const memories = db.prepare(`SELECT COUNT(*) AS c FROM memories`).get()?.c ?? 0;
     // memories_fts_docsize is FTS5's cheaper one-row-per-document shadow table; fall back for a foreign-built index.
     const ftsTable = tableExists(db, 'memories_fts_docsize') ? 'memories_fts_docsize' : 'memories_fts';
-    const ftsCount = db.prepare(`SELECT COUNT(*) AS c FROM ${ftsTable}`).get()?.c ?? 0;
-    if (memCount === ftsCount)
-        return;
+    // SAFETY: this get() result's shape matches the single aliased `c` column named in the SELECT.
+    const fts = db.prepare(`SELECT COUNT(*) AS c FROM ${ftsTable}`).get()?.c ?? 0;
+    return { memories: Number(memories), fts: Number(fts) };
+}
+/** Re-syncs `memories_fts` with `memories` when their counts differ and returns whether it did; sleep runs it because a fast open does not. */
+export function repairFtsDrift(db) {
+    const counts = ftsRowCounts(db);
+    if (counts === null || counts.memories === counts.fts)
+        return false;
     db.exec(`
     INSERT INTO memories_fts(id, content, tags)
     SELECT m.id, m.content, m.tags_json
@@ -134,5 +191,6 @@ function backfillFtsIndex(db) {
     DELETE FROM memories_fts
     WHERE id NOT IN (SELECT id FROM memories)
   `);
+    return true;
 }
 //# sourceMappingURL=migrate.js.map

package/dist/db.d.ts

@@ -2,6 +2,6 @@ export type { DatabaseSyncLike } from './db/sqlite.js';
 export { isSqliteBusy, STORE_BUSY_MESSAGE, execWithBusyRetry } from './db/busy.js';
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
-export { getCurrentSchemaVersion, IncompatibleBinaryError } from './db/migrate.js';
+export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
 export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, withBusyWait, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
 //# sourceMappingURL=db.d.ts.map

package/dist/db.js

@@ -1,6 +1,6 @@
 export { isSqliteBusy, STORE_BUSY_MESSAGE, execWithBusyRetry } from './db/busy.js';
 export { getSchemaVersion, getMeta, setMeta, isFtsAvailable } from './db/meta.js';
 export { countTableRows, pruneConsolidationRuns } from './db/tables.js';
-export { getCurrentSchemaVersion, IncompatibleBinaryError } from './db/migrate.js';
+export { getCurrentSchemaVersion, IncompatibleBinaryError, ftsRowCounts, repairFtsDrift } from './db/migrate.js';
 export { getHippoDbPath, HOOK_DB_WAIT_MS, noteStoreBusy, withSharedStoreHandles, SERVER_DB_WAIT_MS, withBusyWait, openHippoDb, openHippoDbReadOnly, closeHippoDb, } from './db/open.js';
 //# sourceMappingURL=db.js.map

package/dist/doctor.js

@@ -11,7 +11,7 @@ import { findHippoStoreDir } from './project-identity.js';
 import { getGlobalRoot } from './shared.js';
 import { isInitialized } from './store/open.js';
 import { loadConfig } from './config.js';
-import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, IncompatibleBinaryError } from './db.js';
+import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, ftsRowCounts, IncompatibleBinaryError } from './db.js';
 import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './compaction-record.js';
 import { isEmbeddingAvailable } from './local-embedding.js';
 import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks/shared.js';
@@ -191,6 +191,25 @@ function memoriesCheck(db) {
     }
     return memoryCheck;
 }
+/** Whether the full-text index still matches `memories`; opening a current store no longer checks, so doctor reports and sleep repairs. */
+function ftsCheck(db) {
+    try {
+        const counts = ftsRowCounts(db);
+        if (counts === null)
+            return { id: 'fts', status: 'info', detail: 'no full-text index; search uses slower LIKE matching' };
+        if (counts.memories === counts.fts)
+            return { id: 'fts', status: 'pass', detail: `full-text index in sync (${counts.fts} rows)` };
+        return {
+            id: 'fts',
+            status: 'warn',
+            detail: `full-text index out of sync: ${counts.fts} indexed rows for ${counts.memories} memories, so search can miss memories or match removed ones`,
+            fix: 'hippo sleep   (re-syncs the index)',
+        };
+    }
+    catch (err) {
+        return { id: 'fts', status: 'warn', detail: `cannot read the full-text index: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 function tokensCheck(db, since) {
     try {
         // SAFETY: COUNT/SUM aggregate row.
@@ -217,6 +236,7 @@ function databaseChecks(store, now) {
         const have = getSchemaVersion(db);
         checks.push(schemaCheck(have, getCurrentSchemaVersion()));
         checks.push(memoriesCheck(db));
+        checks.push(ftsCheck(db));
         const since = new Date(now.getTime() - 7 * 86_400_000).toISOString();
         checks.push(tokensCheck(db, since));
         checks.push(failuresCheck(db, since, have));

package/dist/raw-archive.js

@@ -31,19 +31,9 @@ function moveRowToArchive(db, id, row, opts) {
     // Flip kind to 'archived' so the BEFORE DELETE trigger no longer fires, then delete.
     db.prepare(`UPDATE memories SET kind = 'archived' WHERE id = ?`).run(id);
     db.prepare(`DELETE FROM memories WHERE id = ?`).run(id);
-    // FTS5 is a virtual table — no FK CASCADE applies. Purge the FTS row so the
-    // archived content is not searchable after archive. Without this the original
-    // raw text remains in memories_fts until the next DB-open backfill, defeating
-    // GDPR right-to-be-forgotten.
-    if (isFtsAvailable(db)) {
-        try {
-            db.prepare(`DELETE FROM memories_fts WHERE id = ?`).run(id);
-        }
-        catch {
-            // Best effort only. The DELETE on memories already succeeded; FTS will
-            // self-heal on next DB open via backfillFtsIndex.
-        }
-    }
+    // Archived text must be unsearchable at commit, so a failed purge fails (and rolls back) the whole archive.
+    if (isFtsAvailable(db))
+        db.prepare(`DELETE FROM memories_fts WHERE id = ?`).run(id);
 }
 // Emit the archive_raw audit event inside the SAVEPOINT so the audit row is
 // committed atomically with the row deletion. Use the row's own tenant_id

package/dist/store/open.js

@@ -64,13 +64,10 @@ function recordHalfLifeBaseForNewStore(db) {
     setMeta(db, TYPED_HALF_LIFE_META_KEY, '1');
 }
 function bootstrapLegacyStore(db, hippoRoot) {
-    // SAFETY: countRow's shape matches the single `COUNT(*) AS count` column
-    // selected above; `.get()` returns undefined only when no row exists.
-    const countRow = db.prepare(`SELECT COUNT(*) AS count FROM memories`).get();
-    const memoryCount = Number(countRow?.count ?? 0);
-    if (memoryCount > 0)
+    // Existence, not COUNT(*): a count walks every row on each write's open.
+    if (db.prepare(`SELECT 1 AS x FROM memories LIMIT 1`).get() !== undefined)
         return false;
-    // memoryCount misses an all-rejected bootstrap (memories stays empty), which would re-run the
+    // The row check misses an all-rejected bootstrap (memories stays empty), which would re-run the
     // import on every open and duplicate consolidation_runs; this meta flag settles it.
     if (getMeta(db, 'legacy_bootstrap_completed', '0') === '1')
         return false;

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.63.0";
+export declare const PACKAGE_VERSION = "1.63.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.63.0';
+export const PACKAGE_VERSION = '1.63.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/README.md

@@ -1,6 +1,8 @@
 # Hippo Memory - OpenClaw Plugin
 
-Biologically-inspired memory for OpenClaw agents. Memories decay by default, retrieval strengthens them, errors stick longer, and sleep consolidation merges related episodes into one memory.
+Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.
+
+Memories decay by default, retrieval strengthens them, errors stick longer, and sleep consolidation merges related episodes into one memory.
 
 ## Install
 

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

@@ -1,8 +1,8 @@
 {
   "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.63.0",
+  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
+  "version": "1.63.1",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hippo-memory",
-  "version": "1.63.0",
+  "version": "1.63.1",
   "type": "module",
-  "description": "Hippo Memory plugin for OpenClaw - biologically-inspired agent memory",
+  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
   "main": "index.ts",
   "openclaw": {
     "extensions": [
@@ -13,4 +13,4 @@
     "hippo-memory": ">=0.4.0"
   },
   "license": "MIT"
-}
+}

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "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.63.0",
+  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
+  "version": "1.63.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hippo-memory",
-  "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.",
+  "version": "1.63.1",
+  "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",
   "main": "./dist/index.js",