hippo-memory 1.52.9 → 1.53.0

package/dist/config.js

@@ -82,6 +82,9 @@ const DEFAULT_CONFIG = {
     churnStaleness: {
         enabled: false,
     },
+    agentMemories: {
+        tools: null,
+    },
 };
 function isMemoryValueConfig(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -92,6 +95,15 @@ function isDormantConfig(value) {
 function isChurnStalenessConfig(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function agentMemoryTools(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (Array.isArray(value) && value.every((t) => String(t) === t))
+        return value;
+    console.error(`Warning: config.json's "agentMemories.tools" must be a list of tool ids like ["claude-code", "codex"] ` +
+        `(got ${JSON.stringify(value)}) - importing none.`);
+    return [];
+}
 export function loadConfig(hippoRoot) {
     const configPath = path.join(hippoRoot, 'config.json');
     if (!fs.existsSync(configPath))
@@ -192,6 +204,7 @@ export function loadConfig(hippoRoot) {
             churnStaleness: {
                 enabled: churnStalenessEnabled,
             },
+            agentMemories: { tools: agentMemoryTools(raw.agentMemories?.tools) },
         };
     }
     catch (err) {

package/dist/consolidate.js

@@ -153,7 +153,7 @@ export async function consolidate(hippoRoot, options = {}) {
         for (const e of all)
             e.half_life_days = halfLife.halfLives.get(e.id) ?? e.half_life_days;
     const backingObjects = memoriesBackingObjects(hippoRoot);
-    // Retirable: auto-deletable (never pinned, never raw) and not backing a first-class object.
+    // Retirable: auto-deletable (never pinned, raw or kept for good) and not backing a first-class object.
     const retirable = (entry) => canAutoDelete(entry) && !backingObjects.has(entry.id);
     const snapshot = new Map(structuredClone(all).map((e) => [e.id, e]));
     // Load decay options from config + session context
@@ -174,7 +174,7 @@ export async function consolidate(hippoRoot, options = {}) {
     // so it stays where it is (stored strength refreshed) but sits out the
     // rest of this cycle the way a deleted row would. Anything else goes
     // dormant when config.dormant is on, and is deleted otherwise.
-    // Only called for rows `retirable` allows (never pinned, never raw, never backing a first-class object).
+    // Only called for rows `retirable` allows (never pinned, raw, kept for good or backing a first-class object).
     const retireFaded = (entry, strength) => {
         const why = `(strength ${strength.toFixed(4)} < ${DECAY_THRESHOLD})`;
         // A faded secret is deleted, never kept dormant: keeping it would hold a

package/dist/db.d.ts

@@ -16,7 +16,11 @@ export declare function getCurrentSchemaVersion(): number;
 /** Thrown by {@link assertBinaryCompatible}; doctor uses it to pick the upgrade fix over a generic permissions fix. */
 export declare class IncompatibleBinaryError extends Error {
 }
-export declare function openHippoDb(hippoRoot: string): DatabaseSyncLike;
+export declare function isSqliteBusy(error: unknown): boolean;
+/** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
+export declare function openHippoDb(hippoRoot: string, opts?: {
+    busyWaitMs?: number;
+}): DatabaseSyncLike;
 /** Open an existing store without changing it: no mkdir, WAL switch, migration or mirror cleanup. Throws when hippo.db is missing. */
 export declare function openHippoDbReadOnly(hippoRoot: string): DatabaseSyncLike;
 export declare function getSchemaVersion(db: DatabaseSyncLike): number;

package/dist/db.js

@@ -11,7 +11,7 @@ const require = createRequire(import.meta.url);
 // runtime (Node's built-in synchronous SQLite module); there are no bundled
 // types for it here, so this require + cast is the module's documented boundary.
 const { DatabaseSync } = require('node:sqlite');
-const CURRENT_SCHEMA_VERSION = 48;
+const CURRENT_SCHEMA_VERSION = 49;
 const MIGRATIONS = [
     {
         version: 1,
@@ -2471,6 +2471,36 @@ const MIGRATIONS = [
             db.exec(MEMORY_QUARANTINE_DDL);
         },
     },
+    {
+        version: 49,
+        up: (db) => {
+            // Compaction record (src/compaction-record.ts): one row per Claude Code compaction, written before it (started)
+            // and after it (summarised, done). Not a memory row. Additive only: no min_compatible_binary bump.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS compactions (
+          tenant_id       TEXT NOT NULL DEFAULT 'default',
+          id              TEXT NOT NULL,
+          session_id      TEXT NOT NULL,
+          origin_project  TEXT NOT NULL DEFAULT '',
+          compact_trigger TEXT,
+          cwd             TEXT,
+          transcript_path TEXT,
+          snapshot_saved  INTEGER NOT NULL DEFAULT 0,
+          started_at      TEXT NOT NULL,
+          summarised_at   TEXT,
+          summary         TEXT,
+          items_json      TEXT,
+          items_written   INTEGER NOT NULL DEFAULT 0,
+          status          TEXT NOT NULL DEFAULT 'started' CHECK (status IN ('started','summarised','done','no-summary')),
+          PRIMARY KEY (tenant_id, id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_compactions_session
+          ON compactions(tenant_id, session_id, started_at);
+        CREATE INDEX IF NOT EXISTS idx_compactions_status
+          ON compactions(tenant_id, status);
+      `);
+        },
+    },
 ];
 function tableHasColumn(db, tableName, columnName) {
     if (!/^[a-z_]+$/i.test(tableName))
@@ -2504,7 +2534,7 @@ function assertBinaryCompatible(db) {
             `Upgrade hippo-memory to open it; an older binary does not know this schema and could expose private rows or damage the store.`);
     }
 }
-function isSqliteBusy(error) {
+export function isSqliteBusy(error) {
     const code = error?.errcode;
     return code === 5 || code === 6 || code === 517;
 }
@@ -2526,16 +2556,18 @@ function execWithBusyRetry(db, sql, timeoutMs = 30000) {
         }
     }
 }
-export function openHippoDb(hippoRoot) {
+/** `busyWaitMs` shortens every lock wait of this open, for a hook that must finish inside its own timeout. */
+export function openHippoDb(hippoRoot, opts) {
     fs.mkdirSync(hippoRoot, { recursive: true });
     const db = new DatabaseSync(getHippoDbPath(hippoRoot));
+    const busyWaitMs = opts?.busyWaitMs;
     try {
-        db.exec('PRAGMA busy_timeout = 5000');
-        execWithBusyRetry(db, 'PRAGMA journal_mode = WAL');
+        db.exec(`PRAGMA busy_timeout = ${busyWaitMs ?? 5000}`);
+        execWithBusyRetry(db, 'PRAGMA journal_mode = WAL', busyWaitMs);
         db.exec('PRAGMA synchronous = NORMAL');
         db.exec('PRAGMA wal_autocheckpoint = 100');
         db.exec('PRAGMA foreign_keys = ON');
-        runMigrations(db, hippoRoot);
+        runMigrations(db, hippoRoot, busyWaitMs);
         // Path A backfill: delete any orphan markdown mirrors for already-archived
         // raw_archive rows. Idempotent via per-row raw_archive.mirror_cleaned_at
         // (v21). Wrapped in try/catch — a filesystem failure must not prevent DB open.
@@ -2576,7 +2608,7 @@ export function openHippoDbReadOnly(hippoRoot) {
         throw error;
     }
 }
-function runMigrations(db, hippoRoot) {
+function runMigrations(db, hippoRoot, busyWaitMs) {
     ensureMetaTable(db);
     // Before anything writes, so a stale binary never repairs or migrates a store it does not understand.
     assertBinaryCompatible(db);
@@ -2586,7 +2618,7 @@ function runMigrations(db, hippoRoot) {
     for (const migration of MIGRATIONS) {
         if (migration.version <= currentVersion)
             continue;
-        execWithBusyRetry(db, 'BEGIN IMMEDIATE');
+        execWithBusyRetry(db, 'BEGIN IMMEDIATE', busyWaitMs);
         try {
             // A newer binary may have migrated and raised the minimum while we waited for the lock.
             assertBinaryCompatible(db);

package/dist/doctor.js

@@ -11,6 +11,7 @@ import { findHippoStoreDir } from './project-identity.js';
 import { getGlobalRoot } from './shared.js';
 import { isInitialized } from './store.js';
 import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, IncompatibleBinaryError } from './db.js';
+import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './compaction-record.js';
 import { isEmbeddingAvailable } from './embeddings.js';
 import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
@@ -96,6 +97,36 @@ function sleepCheck(db, now) {
         return { id: 'sleep', status: 'info', detail: `sleep history unavailable (${message})` };
     }
 }
+/** Compaction records the PostCompact hook left unfinished, which `hippo sleep` replays. */
+function compactionsCheck(db, now) {
+    const stuckBefore = new Date(now.getTime() - REPLAY_AFTER_MS).toISOString();
+    const transcriptFloor = new Date(now.getTime() - TRANSCRIPT_FILL_WINDOW_MS).toISOString();
+    try {
+        // SAFETY: COUNT aggregate row.
+        const row = db.prepare(`SELECT COUNT(*) AS total,
+              COUNT(CASE WHEN status = 'summarised' AND summarised_at < ? THEN 1 END) AS summarised,
+              COUNT(CASE WHEN status = 'started' AND started_at < ? AND started_at > ? AND transcript_path IS NOT NULL THEN 1 END) AS started
+       FROM compactions`).get(stuckBefore, stuckBefore, transcriptFloor);
+        const total = Number(row?.total ?? 0);
+        const summarised = Number(row?.summarised ?? 0);
+        const started = Number(row?.started ?? 0);
+        const stuck = summarised + started;
+        if (stuck === 0)
+            return { id: 'compactions', status: 'pass', detail: `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck` };
+        return {
+            id: 'compactions',
+            status: 'warn',
+            detail: `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`,
+            fix: 'hippo sleep   (replays them)',
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return message.includes('no such table')
+            ? { id: 'compactions', status: 'info', detail: 'no compaction records yet (hippo creates them on the next write)' }
+            : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${message}` };
+    }
+}
 /** Run every check. Never throws for a broken install; broken parts become failed checks. */
 export function runDoctor(opts) {
     const cwd = opts.cwd ?? process.cwd();
@@ -162,6 +193,7 @@ export function runDoctor(opts) {
             }
             checks.push(failuresCheck(db, since, have));
             checks.push(sleepCheck(db, now));
+            checks.push(compactionsCheck(db, now));
         }
         catch (err) {
             checks.push({
@@ -185,9 +217,9 @@ export function runDoctor(opts) {
         const hooks = [
             ['hippo context --pinned-only', 'per-prompt memory'],
             ['hippo session-end', 'session-end capture and sleep'],
-            ['hippo pre-compact', 'compaction snapshot and capture'],
+            ['hippo pre-compact', 'compaction snapshot and memories request'],
             ['hippo compact-resume', 'resume after compaction'],
-            ['hippo post-compact', 'the message after compaction'],
+            ['hippo post-compact', 'saving the memories a compaction lists'],
             ['hippo capture-error', 'failed-tool capture'],
         ];
         const missing = hooks.filter(([marker]) => !text.includes(marker)).map(([, what]) => what);

package/dist/dormant.d.ts

@@ -19,8 +19,8 @@
  */
 import type { DatabaseSyncLike } from './db.js';
 import type { MemoryEntry } from './memory.js';
-/** Why sleep made a memory dormant. Only the decay pass does today. */
-export type DormantReason = 'decay';
+/** Why a memory went dormant: sleep's decay pass, or an imported agent memory whose note was deleted. */
+export type DormantReason = 'decay' | 'source-deleted';
 /** One memory that sleep is moving out of active memory into the dormant store. */
 export interface DormantMove {
     /** The memory as it stood when it faded; restored verbatim apart from its recall clock. */
@@ -39,7 +39,7 @@ export interface DormantMemory {
     tags: string[];
     /** Live strength when it went dormant. */
     strength: number;
-    /** Why it went dormant (`decay`). */
+    /** Why it went dormant (`decay` or `source-deleted`). */
     reason: string;
     /** ISO time it went dormant. */
     dormantAt: string;
@@ -73,6 +73,8 @@ export interface DormantSnapshot {
 export declare function readDormantSnapshot(db: DatabaseSyncLike, tenantId: string, id: string): DormantSnapshot | null;
 /** Every dormant memory of a tenant whose snapshot still reads back. */
 export declare function listDormantSnapshots(db: DatabaseSyncLike, tenantId: string): DormantSnapshot[];
+/** Readable snapshots whose entry's source starts with `prefix`; a malformed snapshot is passed over, not an error. */
+export declare function dormantSnapshotsBySourcePrefix(db: DatabaseSyncLike, tenantId: string, prefix: string): DormantSnapshot[];
 /** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
 export declare function replaceDormantEntry(db: DatabaseSyncLike, tenantId: string, id: string, entry: MemoryEntry): void;
 /** Whether a tenant has a dormant memory with this id (snapshot readable or not). */

package/dist/dormant.js

@@ -83,6 +83,15 @@ export function listDormantSnapshots(db, tenantId) {
        FROM dormant_memories WHERE tenant_id = ?`).all(tenantId);
     return rows.flatMap((row) => toSnapshot(row) ?? []);
 }
+/** Readable snapshots whose entry's source starts with `prefix`; a malformed snapshot is passed over, not an error. */
+export function dormantSnapshotsBySourcePrefix(db, tenantId, prefix) {
+    // SAFETY: rows' shape matches the seven columns named in the SELECT.
+    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories
+      WHERE tenant_id = ?
+        AND CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.source') END LIKE ? ESCAPE '\\'`).all(tenantId, `${escapeLike(prefix)}%`);
+    return rows.flatMap((row) => toSnapshot(row) ?? []).filter((s) => String(s.entry.source).startsWith(prefix));
+}
 function toSnapshot(row) {
     const entry = parseSnapshot(row);
     return entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;

package/dist/gated-write.d.ts

@@ -0,0 +1,9 @@
+import type { DatabaseSyncLike } from './db.js';
+import type { MemoryEntry } from './memory.js';
+export type GatedWriteResult = 'written' | 'skipped:not-worth-storing' | 'skipped:secret' | 'skipped:rejected';
+/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
+export declare function gatedWrite(db: DatabaseSyncLike, hippoRoot: string, entry: MemoryEntry, opts?: {
+    actor?: string;
+    worthCheck?: boolean;
+}): GatedWriteResult;
+//# sourceMappingURL=gated-write.d.ts.map

package/dist/gated-write.js

@@ -0,0 +1,24 @@
+// The one write path for text no person typed into hippo: capture, compaction items and imported agent memories.
+import { isContentWorthStoring } from './audit.js';
+import { RejectedValueError } from './rejection.js';
+import { detectSecret } from './secret-detect.js';
+import { auditRejectionRefusal, stampOriginProject, writeEntryDbOnly } from './store.js';
+/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
+export function gatedWrite(db, hippoRoot, entry, opts) {
+    // Off for imported agent memories: a person wrote those notes, and a one-line preference fails the check.
+    if (opts?.worthCheck !== false && !isContentWorthStoring(entry.content))
+        return 'skipped:not-worth-storing';
+    if (detectSecret(entry).flagged)
+        return 'skipped:secret';
+    try {
+        writeEntryDbOnly(db, stampOriginProject(hippoRoot, entry), opts);
+        return 'written';
+    }
+    catch (err) {
+        if (!(err instanceof RejectedValueError))
+            throw err;
+        auditRejectionRefusal(db, err, opts?.actor ?? 'cli');
+        return 'skipped:rejected';
+    }
+}
+//# sourceMappingURL=gated-write.js.map

package/dist/hooks.d.ts

@@ -16,6 +16,8 @@
  *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
  *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
  *      - 0.22.x: separate sleep + capture SessionEnd entries.
+ *    PreCompact and PostCompact entries go in too: the first records the compaction and
+ *    asks the summariser for a "Memories for hippo" list, the second saves that list.
  *    Codex's hooks.json gets only two groups (per-prompt memory and
  *    compact-resume); see installCodexHooks.
  *
@@ -91,7 +93,7 @@ export interface InstallResult {
     installedUserPromptSubmit: boolean;
     installedPreCompact: boolean;
     installedCompactResume: boolean;
-    /** PostCompact -> `hippo post-compact` (tells the user what compaction saved). */
+    /** PostCompact -> `hippo post-compact` (saves the summary's memories, tells the user how many). */
     installedPostCompact: boolean;
     /** PostToolUseFailure -> `hippo capture-error` (failed tool calls become error memories). */
     installedCaptureError: boolean;
@@ -150,7 +152,7 @@ declare const HIPPO_OPENCODE_PLUGIN_MARKER = "HIPPO_OPENCODE_PLUGIN_V1";
 export declare const OPENCODE_PLUGIN_SOURCE = "// HIPPO_OPENCODE_PLUGIN_V1\n// hippo-memory opencode plugin. DO NOT EDIT \u2014 regenerated on every\n// `hippo hook install opencode` from src/hooks.ts OPENCODE_PLUGIN_SOURCE\n// in https://github.com/kitfunso/hippo-memory. Local changes will be lost.\n\nexport const HippoPlugin = async ({ $ }) => {\n  return {\n    event: async ({ event }) => {\n      // Defense in depth: opencode currently runs in Bun where $ is the shell\n      // template helper. A non-Bun runtime would have $ as undefined; fail\n      // closed instead of crashing the host session.\n      if (typeof $ !== \"function\") return;\n      try {\n        if (event.type === \"session.idle\") {\n          await $`hippo session-end`.quiet().nothrow();\n        } else if (event.type === \"session.created\") {\n          await $`hippo last-sleep`.quiet().nothrow();\n        }\n      } catch {\n        // hippo CLI not on PATH or other failure \u2014 never crash the host session.\n      }\n    },\n  };\n};\n";
 export { HIPPO_OPENCODE_PLUGIN_MARKER };
 /** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
-export declare function codexHomeDir(home?: string): string;
+export declare function codexHomeDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export declare function isCodexPresent(home?: string): boolean;
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */

package/dist/hooks.js

@@ -16,6 +16,8 @@
  *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
  *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
  *      - 0.22.x: separate sleep + capture SessionEnd entries.
+ *    PreCompact and PostCompact entries go in too: the first records the compaction and
+ *    asks the summariser for a "Memories for hippo" list, the second saves that list.
  *    Codex's hooks.json gets only two groups (per-prompt memory and
  *    compact-resume); see installCodexHooks.
  *
@@ -124,8 +126,8 @@ function homeDir() {
     return process.env.HOME || process.env.USERPROFILE || os.homedir();
 }
 /** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
-export function codexHomeDir(home = homeDir()) {
-    return process.env.CODEX_HOME || path.join(home, '.codex');
+export function codexHomeDir(home = homeDir(), env = process.env) {
+    return env.CODEX_HOME || path.join(home, '.codex');
 }
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export function isCodexPresent(home = homeDir()) {
@@ -731,8 +733,8 @@ export function installJsonHooks(target) {
         });
         installedUserPromptSubmit = true;
     }
-    // PreCompact: fires on manual AND auto compaction (no matcher). Writes a
-    // working-state snapshot before the transcript summary drops detail.
+    // PreCompact: fires on manual AND auto compaction (no matcher). Records the compaction, asks the
+    // summariser for a "Memories for hippo" list and saves a working-state snapshot before the summary drops detail.
     // Exit-0 contract lives in the verb itself (src/capture.ts cmdPreCompact),
     // not here — this is install-time wiring only.
     let installedPreCompact = false;
@@ -772,9 +774,8 @@ export function installJsonHooks(target) {
         });
         installedCompactResume = true;
     }
-    // PostCompact: tells the user what pre-compact saved. PreCompact itself
-    // must stay silent, because Claude Code hands PreCompact stdout to the
-    // summarising model as instructions; PostCompact stdout is only shown.
+    // PostCompact: saves the memories the summariser listed and prints one line, which Claude Code only shows.
+    // PreCompact stdout, by contrast, is handed to the summariser as instructions, so pre-compact prints just the request.
     let installedPostCompact = false;
     if (!hookArrayContains(hooks.PostCompact, HIPPO_POST_COMPACT_MARKER)) {
         if (!Array.isArray(hooks.PostCompact))

package/dist/memory.d.ts

@@ -213,8 +213,17 @@ export declare function resolveConfidence(entry: MemoryEntry, now?: Date): Confi
  * on an older base (src/half-life-migration.ts).
  */
 export declare const DEFAULT_HALF_LIFE_DAYS = 365;
-export declare const AUTO_DELETABLE_SQL = "pinned = 0 AND kind != 'raw'";
-export declare function canAutoDelete(entry: Pick<MemoryEntry, 'pinned' | 'kind'>): boolean;
+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'. */
+export interface KeepPair {
+    readonly tag: string;
+    readonly sourcePrefix: string;
+}
+export declare const KEEP_PAIRS: readonly KeepPair[];
+export declare const AUTO_DELETABLE_SQL: string;
+export declare function isKeptForGood(entry: Pick<MemoryEntry, 'tags' | 'source' | 'superseded_by'>): boolean;
+export declare function canAutoDelete(entry: Pick<MemoryEntry, 'pinned' | 'kind' | 'tags' | 'source' | 'superseded_by'>): boolean;
 export interface CreateMemoryOptions {
     layer?: Layer;
     tags?: string[];
@@ -239,6 +248,14 @@ export interface CreateMemoryOptions {
 }
 /** Create a new memory entry with defaults. Untyped JavaScript callers that omit the options get the compiled default half-life. */
 export declare function createMemory(content: string, options: CreateMemoryOptions): MemoryEntry;
+/** The row that replaces `old`: a supersede never changes where a memory belongs, so source, scope, session and a stamped origin carry over. */
+export declare function createSuccessor(old: MemoryEntry, content: string, opts: {
+    tenantId: string;
+    baseHalfLifeDays: number;
+    layer?: Layer;
+    tags?: string[];
+    pinned?: boolean;
+}): MemoryEntry;
 /**
  * Compute how well new content fits existing knowledge patterns.
  * Returns 0..1 where:

package/dist/memory.js

@@ -4,6 +4,7 @@
  */
 import { randomUUID } from 'crypto';
 import { isDecayAblated, isOutcomeSlowAblated, isRecallBoostAblated, evalNow, } from './ablation.js';
+import { AGENT_MEMORY_TOOLS, toolSourcePrefix } from './agent-memories/tools.js';
 export var Layer;
 (function (Layer) {
     Layer["Buffer"] = "buffer";
@@ -314,10 +315,22 @@ export function resolveConfidence(entry, now = evalNow()) {
  * on an older base (src/half-life-migration.ts).
  */
 export const DEFAULT_HALF_LIFE_DAYS = 365;
-// Pinned means keep; raw rows leave only through archiveRawMemory. The SQL twin guards the DELETE itself.
-export const AUTO_DELETABLE_SQL = "pinned = 0 AND kind != 'raw'";
+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) })),
+];
+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)})`;
+// Pinned and kept rows stay (a superseded row is not kept: its successor carries the tag and source); raw rows leave only through archiveRawMemory. The SQL twin guards the DELETE itself.
+export const AUTO_DELETABLE_SQL = `pinned = 0 AND kind != 'raw'${KEEP_PAIRS.map((p) => ` AND NOT ${keepPairSql(p)}`).join('')}`;
+export function isKeptForGood(entry) {
+    return !entry.superseded_by && KEEP_PAIRS.some((p) => entry.tags.includes(p.tag) && entry.source.startsWith(p.sourcePrefix));
+}
 export function canAutoDelete(entry) {
-    return !entry.pinned && entry.kind !== 'raw';
+    return !entry.pinned && entry.kind !== 'raw' && !isKeptForGood(entry);
 }
 export function createMemory(content, options = {}) {
     const trimmed = content.trim();
@@ -373,6 +386,25 @@ export function createMemory(content, options = {}) {
     entry.strength = calculateStrength(entry);
     return entry;
 }
+/** The row that replaces `old`: a supersede never changes where a memory belongs, so source, scope, session and a stamped origin carry over. */
+export function createSuccessor(old, content, opts) {
+    const next = createMemory(content, {
+        layer: opts.layer ?? old.layer,
+        tags: opts.tags ?? [...old.tags],
+        pinned: opts.pinned ?? old.pinned,
+        source: old.source,
+        confidence: 'verified',
+        tenantId: opts.tenantId,
+        scope: old.scope,
+        source_session_id: old.source_session_id,
+        baseHalfLifeDays: opts.baseHalfLifeDays,
+    });
+    // A legacy null origin has nothing to carry, so the store stamps it from its own location.
+    if (typeof old.origin_project === 'string') {
+        next.origin_project = old.origin_project;
+    }
+    return next;
+}
 /**
  * Compute how well new content fits existing knowledge patterns.
  * Returns 0..1 where:

package/dist/shared.js

@@ -6,7 +6,8 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { generateId } from './memory.js';
+import { generateId, COMPACTION_MEMORY_TAG } from './memory.js';
+import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TAGS } from './agent-memories/tools.js';
 import { initStore, loadAllEntries, loadIndex, loadSearchEntries, loadRecallSearchEntries, writeEntry, readEntry, } from './store.js';
 import { passesScopeFilterForRecall, passesCliRecallScopeFilter } from './recall-scope.js';
 import { search, hybridSearch, fitBudget } from './search.js';
@@ -224,6 +225,7 @@ const TRANSFERABLE_TAGS = new Set([
 export const NEVER_AUTO_SHARE_TAGS = new Set([
     'git-learned',
     'session-digest',
+    ...AGENT_MEMORY_TAGS,
 ]);
 export function neverAutoShareTags(sources) {
     return [...NEVER_AUTO_SHARE_TAGS].filter((tag) => sources.some((s) => s.tags.includes(tag)));
@@ -232,6 +234,8 @@ export function neverAutoShareTags(sources) {
 export const NO_MERGE_TAGS = new Set([
     'extracted',
     'session-digest',
+    COMPACTION_MEMORY_TAG,
+    ...AGENT_MEMORY_TAGS,
 ]);
 /**
  * Estimate how well a memory would transfer to other projects.
@@ -398,7 +402,7 @@ export function autoShare(localRoot, options = {}) {
         if (isQuarantineScope(entry.scope ?? null))
             return false;
         // Before the score: these rows describe one project only, and a git seed's 'error' tag clears the bar.
-        if (entry.tags.some((t) => NEVER_AUTO_SHARE_TAGS.has(t))) {
+        if (entry.tags.some((t) => NEVER_AUTO_SHARE_TAGS.has(t)) || entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX)) {
             if (options.stats)
                 options.stats.neverAutoShareSkipped = (options.stats.neverAutoShareSkipped ?? 0) + 1;
             return false;
@@ -481,16 +485,15 @@ export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
     // only stamps when the field is missing).
     const currentName = deriveOriginProject(path.dirname(path.resolve(localRoot)));
     let count = 0;
-    // AT1 (plan §3 containment, the roadmap threat this whole feature targets
-    // — a locally-rejected value must not silently resurrect via sync down
-    // from global): per-item catch, no signature change (bare number return;
-    // see the syncGlobalToLocal callers in cli.ts + tests). Counted locally
-    // and printed as one summary line, same pattern as learnFromMemoryMd.
+    // A locally rejected value must not come back through sync down: caught per item, printed as one line.
     let rejected = 0;
     for (const entry of globalEntries) {
         // Skip if already present by ID
         if (localIndex.entries[entry.id])
             continue;
+        // Only the global store's user pass sets an imported note's row aside, so a copy would outlive the note.
+        if (entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX))
+            continue;
         if (localText.has(textKey(entry)))
             continue;
         if (detectSecret(entry).flagged)

package/dist/store.d.ts

@@ -367,7 +367,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 or raw at DELETE time, so a late pin wins).
+ * existed or `automatic` refused it (pinned, raw or kept for good at DELETE time, so a late pin wins).
  */
 export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id: string, opts?: {
     actor?: string;
@@ -400,7 +400,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 or raw since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+ *  (pinned, raw or kept for good 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[];
@@ -415,6 +415,12 @@ export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEn
 export declare function loadAllEntries(hippoRoot: string, tenantId?: string): MemoryEntry[];
 /** Every memory row on an open connection, so a caller can read inside its own transaction. */
 export declare function selectAllEntries(db: DatabaseSyncLike, tenantId?: string): MemoryEntry[];
+/** Live rows whose source starts with `prefix`, on the caller's handle; LIKE folds case, so the prefix is checked again exactly. */
+export declare function selectLiveEntriesBySourcePrefix(db: DatabaseSyncLike, tenantId: string, prefix: string): MemoryEntry[];
+/** Rewrites a live row's tags and its full-text row on the caller's transaction, with no audit row. */
+export declare function setEntryTagsInTx(db: DatabaseSyncLike, entry: MemoryEntry): void;
+/** Removes a row from `memories` and full-text search on the caller's transaction, as sleep's dormant move does, and marks its summary parent dirty. */
+export declare function deleteEntryRowInTx(db: DatabaseSyncLike, entry: MemoryEntry, actor: string): void;
 export declare function loadContentsWithTag(hippoRoot: string, tenantId: string, tag: string): string[];
 export interface AmbientRecallRequest {
     terms: string[];

package/dist/store.js

@@ -1555,7 +1555,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 or raw at DELETE time, so a late pin wins).
+ * existed or `automatic` refused it (pinned, raw or kept for good 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.
@@ -1622,7 +1622,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 or raw since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+ *  (pinned, raw or kept for good 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)
@@ -1810,6 +1810,25 @@ export function selectAllEntries(db, tenantId) {
         : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
     return rows.map(rowToEntry);
 }
+/** Live rows whose source starts with `prefix`, on the caller's handle; LIKE folds case, so the prefix is checked again exactly. */
+export function selectLiveEntriesBySourcePrefix(db, tenantId, prefix) {
+    // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+    const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? AND superseded_by IS NULL AND source LIKE ? ESCAPE '\\'`).all(tenantId, `${prefix.replace(/[%_\\]/g, '\\$&')}%`);
+    return rows.map(rowToEntry).filter((entry) => entry.source.startsWith(prefix));
+}
+/** Rewrites a live row's tags and its full-text row on the caller's transaction, with no audit row. */
+export function setEntryTagsInTx(db, entry) {
+    db.prepare(`UPDATE memories SET tags_json = ?, updated_at = datetime('now') WHERE id = ? AND tenant_id = ?`)
+        .run(JSON.stringify(entry.tags), entry.id, entry.tenantId);
+    syncFtsRow(db, entry);
+}
+/** Removes a row from `memories` and full-text search on the caller's transaction, as sleep's dormant move does, and marks its summary parent dirty. */
+export function deleteEntryRowInTx(db, entry, actor) {
+    db.prepare('DELETE FROM memories WHERE id = ? AND tenant_id = ?').run(entry.id, entry.tenantId);
+    deleteFtsRow(db, entry.id);
+    if (entry.dag_parent_id)
+        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenantId, actor);
+}
 // Content of every tenant row tagged `tag`, without reading the rest of the store.
 // `instr` is a substring prefilter over the raw JSON; `includes` below re-checks exactly.
 export function loadContentsWithTag(hippoRoot, tenantId, tag) {

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.52.9";
+export declare const PACKAGE_VERSION = "1.53.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.52.9';
+export const PACKAGE_VERSION = '1.53.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) => {