hippo-memory 1.44.0 → 1.46.0

package/dist/api.js

@@ -8,15 +8,17 @@
  */
 import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, writeEntryDbOnly, 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, } from './store.js';
 import { RejectedValueError } from './rejection.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
+import { listDormantRows, readDormantSnapshot, deleteDormantRow, hasDormantRow, } from './dormant.js';
+import { recordTokenUse, summarizeTokenUse } from './token-ledger.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
 import { createMemory, applyOutcome, calculateStrength, Layer, } from './memory.js';
 import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
-import { evalNow, isRecallBoostAblated } from './ablation.js';
+import { evalNow } from './ablation.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { createApiKey, listApiKeys, revokeApiKey, } from './auth.js';
 import { applyGoalStackBoost } from './goals.js';
@@ -69,6 +71,13 @@ export class RecallContractError extends Error {
         this.code = code;
     }
 }
+/** The actor's role or identity does not allow the operation. HTTP maps it to 403. */
+export class ForbiddenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ForbiddenError';
+    }
+}
 // v1.25.0: the recall-side scope predicates (PRIVATE_SCOPE_RE, isPrivateScope,
 // passesScopeFilterForRecall) live in recall-scope.ts (leaf) so shared.ts can
 // apply the same default-deny rule to searchBothHybrid's internal loads
@@ -77,9 +86,9 @@ export class RecallContractError extends Error {
 // back-compat (`api.isPrivateScope`, test imports). NOTE: the import statement
 // is required — a bare `export { x } from` re-export does not bind the local
 // names this module's ~9 call sites use.
-import { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
+import { isPrivateScope, passesScopeFilterForRecall, assertScopeRequestAllowed } from './recall-scope.js';
 export { isPrivateScope, passesScopeFilterForRecall };
-export { passesCliRecallScopeFilter } from './recall-scope.js';
+export { passesCliRecallScopeFilter, ScopeForbiddenError } from './recall-scope.js';
 // v39: classifyOriginProject lives in project-identity.ts (leaf) so
 // shared.ts can use it without an api.ts import cycle. Re-exported here for
 // callers that already import the api surface.
@@ -137,6 +146,7 @@ export function remember(ctx, opts) {
         artifact_ref: opts.artifactRef ?? null,
         tags: opts.tags,
         tenantId: ctx.tenantId,
+        baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
     });
     // writeEntry threads ctx.actor.subject into its internal audit hook, so exactly
     // one 'remember' event lands in the log with the supplied actor.
@@ -162,9 +172,8 @@ export function buildSuppressionSummary(counts) {
 }
 /**
  * Domain-level recall. Loads BM25-ranked candidates from SQLite scoped to
- * `ctx.tenantId`. The `mode` flag is accepted for forward compatibility (the
- * CLI exposes hybrid/physics paths) but Task 2 wires only the BM25 candidate
- * loader; later tasks can extend this to call the physics/hybrid scorer.
+ * `ctx.tenantId` and keeps that order whatever `mode` says; `retrieve` is the
+ * mode-aware, strengthening variant the HTTP route uses.
  *
  * **api.recall does NOT mutate `index.last_retrieval_ids`** (v1.11.5 contract
  * lock). The CLI `cmdRecall` (cli.ts) writes `last_retrieval_ids` because the
@@ -177,7 +186,30 @@ export function buildSuppressionSummary(counts) {
  * `tests/api-recall-no-side-effects.test.ts`.
  */
 export function recall(ctx, opts) {
-    const limit = opts.limit ?? 10;
+    // A member key may not unlock a private or quarantined scope by naming it.
+    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
+    const windowSize = recallWindowSize(opts);
+    return recallFrom(ctx, opts, windowSize, loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false));
+}
+/** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (v1.11.5 lock). */
+export async function retrieve(ctx, opts) {
+    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
+    const windowSize = recallWindowSize(opts);
+    let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false);
+    if (opts.mode === 'hybrid' || opts.mode === 'physics') {
+        const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null };
+        const ranked = opts.mode === 'physics'
+            ? await physicsSearch(opts.query, candidates, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
+            : await hybridSearch(opts.query, candidates, searchOpts);
+        const rankedIds = new Set(ranked.map((r) => r.entry.id));
+        candidates = [...ranked.map((r) => r.entry), ...candidates.filter((e) => !rankedIds.has(e.id))];
+    }
+    const result = recallFrom(ctx, opts, windowSize, candidates);
+    strengthenRetrieved(ctx.hippoRoot, result.results.map((r) => r.id), ctx.tenantId);
+    return result;
+}
+/** Contract preflight: throws before any store-touching work. */
+function recallWindowSize(opts) {
     // F5 (v1.6.5) preflight — codex P1: original guard fired AFTER
     // loadSearchEntries (which runs initStore, migrating legacy state on first
     // call). For a true contract preflight we want the throw before any
@@ -207,7 +239,10 @@ export function recall(ctx, opts) {
             throw new RecallContractError('invalid_scorer_window', `scorerWindow must be a positive integer; got ${opts.scorerWindow}`);
         }
     }
-    const windowSize = opts.scorerWindow ?? DEFAULT_SEARCH_CANDIDATE_LIMIT;
+    return opts.scorerWindow ?? DEFAULT_SEARCH_CANDIDATE_LIMIT;
+}
+function recallFrom(ctx, opts, windowSize, all) {
+    const limit = opts.limit ?? 10;
     // v1.7.1 — root-cause fix for the `unknown:legacy` leak. Scope predicate
     // is now pushed into `loadSearchRows` SQL via `loadRecallSearchEntries`.
     // - opts.scope undefined / '': SQL excludes `unknown:legacy`.
@@ -233,16 +268,16 @@ export function recall(ctx, opts) {
     let droppedByBudgetCount = 0;
     let summarySubstitutionsCount = 0;
     let freshTailAddedCount = 0;
-    const all = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope);
     // v1.12.13 / C5 — WYSIATI totalCandidates counter (post tenant + SQL scope
     // predicate, pre JS scope filter).
     totalCandidatesCount = all.length;
+    const current = all.filter((e) => !e.superseded_by);
     let entries;
     if (opts.scope !== undefined && opts.scope !== '') {
         // SQL already exact-matched in loadRecallSearchEntries; keep the JS
         // filter as defense-in-depth so a future SQL-clause regression cannot
         // silently surface cross-scope rows.
-        entries = all.filter((e) => e.scope === opts.scope);
+        entries = current.filter((e) => e.scope === opts.scope);
     }
     else {
         // SQL already excluded `unknown:legacy` AND (v1.25.0) pre-filtered
@@ -252,7 +287,7 @@ export function recall(ctx, opts) {
         // anchored `<source>:private:*` rule (v1.2.1 generalization) and
         // defense-in-depth: connector authors cannot silently surface private
         // rows to no-scope callers even if the SQL clause regresses.
-        entries = all.filter((e) => !isPrivateScope(e.scope ?? null));
+        entries = current.filter((e) => !isPrivateScope(e.scope ?? null));
     }
     // v1.12.13 / C5 — WYSIATI dropped_pre_rank counter (JS scope filter drops
     // for api.recall; cmdRecall pipeline rolls --outcome/--layer/--as-of/etc.
@@ -326,7 +361,7 @@ export function recall(ctx, opts) {
             const eligibleParentIds = Array.from(overflowByParent.keys()).filter((pid) => (overflowByParent.get(pid)?.length ?? 0) >= 2 && !baseIds.has(pid));
             if (eligibleParentIds.length > 0) {
                 const parents = loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId);
-                const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && passesScopeFilterForRecall(p.scope ?? null, opts.scope));
+                const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by && passesScopeFilterForRecall(p.scope ?? null, opts.scope));
                 const maxSub = Math.max(1, Math.ceil(limit * 0.3));
                 // Order parents by overflow count descending so the most
                 // information-dense substitutions come first. Overflow count is the
@@ -441,7 +476,7 @@ export function recall(ctx, opts) {
         // prepended (NOT rows already in baseRanked that got tagged isFreshTail).
         freshTailAddedCount = freshRanked.length;
         rankedOut = [...freshRanked, ...baseRanked, ...summaryRanked];
-        tokensOut = rankedOut.reduce((acc, r) => acc + Math.ceil(r.content.length / 4), 0);
+        tokensOut = rankedOut.reduce((acc, r) => acc + estimateTokens(r.content), 0);
         totalOut = entries.length;
         // TODO(a1-task-4): emit via the shared audit hook in store.ts so we don't
         // double-emit. Recall does not currently write through writeEntry, so no
@@ -523,7 +558,7 @@ export function recall(ctx, opts) {
             sessionHandoff: filteredHandoff,
             recentSessionEvents: filteredEvents,
         };
-        const tokenize = (s) => s ? Math.ceil(s.length / 4) : 0;
+        const tokenize = (s) => s ? estimateTokens(s) : 0;
         continuityTokens =
             tokenize(filteredSnapshot?.task) +
                 tokenize(filteredSnapshot?.summary) +
@@ -689,6 +724,7 @@ export function recall(ctx, opts) {
  *   - all rows fail the scope/tenant filter
  */
 export function assemble(ctx, sessionId, opts = {}) {
+    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
     const budget = opts.budget ?? 4000;
     const freshTailCount = opts.freshTailCount ?? 10;
     const summarizeOlder = opts.summarizeOlder ?? true;
@@ -736,7 +772,7 @@ export function assemble(ctx, sessionId, opts = {}) {
         const eligibleParentIds = Array.from(olderByParent.keys()).filter((pid) => (olderByParent.get(pid)?.length ?? 0) >= 2);
         const parents = eligibleParentIds.length > 0
             ? loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId)
-                .filter((p) => (p.dag_level ?? 0) === 2)
+                .filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by)
                 .filter((p) => passesScopeFilterForRecall(p.scope ?? null, opts.scope))
             : [];
         const claimedRawIds = new Set();
@@ -788,7 +824,7 @@ export function assemble(ctx, sessionId, opts = {}) {
     olderItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
     tailItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
     let items = [...olderItems, ...tailItems];
-    let tokens = items.reduce((acc, it) => acc + Math.ceil(it.content.length / 4), 0);
+    let tokens = items.reduce((acc, it) => acc + estimateTokens(it.content), 0);
     let evicted = 0;
     while (tokens > budget && items.length > 0) {
         let worstIdx = -1;
@@ -803,7 +839,7 @@ export function assemble(ctx, sessionId, opts = {}) {
         }
         if (worstIdx === -1)
             break;
-        const cost = Math.ceil(items[worstIdx].content.length / 4);
+        const cost = estimateTokens(items[worstIdx].content);
         items = items.filter((_, i) => i !== worstIdx);
         tokens -= cost;
         evicted++;
@@ -887,7 +923,7 @@ export function drillDown(ctx, summaryId, opts = {}) {
         const out = [];
         let used = 0;
         for (const c of collected) {
-            const t = Math.ceil(c.content.length / 4);
+            const t = estimateTokens(c.content);
             if (out.length > 0 && used + t > opts.budget) {
                 truncated = true;
                 break;
@@ -1258,11 +1294,13 @@ export function archiveRaw(ctx, id, reason, opts = {}) {
  * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
  * `tenantId` and uses the resolved Bearer's tenant exclusively.
  *
- * Per A5 v2 follow-ups (TODOS.md), `auth_create` is currently unaudited —
- * we intentionally match that behavior here for consistency. When A5 v2
- * lands and adds the audit op, this function should mirror the cli handler.
+ * Only an admin actor can mint (ForbiddenError otherwise), so a member key
+ * can never create a key, least of all an admin one.
  */
 export function authCreate(ctx, opts) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can create API keys');
+    }
     const db = openHippoDb(ctx.hippoRoot);
     try {
         const role = opts.role ?? 'admin';
@@ -1311,6 +1349,9 @@ export function authList(ctx, opts) {
     }
 }
 export function authRevoke(ctx, keyId) {
+    if (ctx.actor.role !== 'admin' && ctx.actor.subject !== `api_key:${keyId}`) {
+        throw new ForbiddenError('A member key can revoke only itself');
+    }
     const db = openHippoDb(ctx.hippoRoot);
     try {
         // SAFETY: row's shape matches the three columns named in the SELECT
@@ -1767,21 +1808,11 @@ export async function getContext(ctx, opts = {}) {
         const toUpdate = selectedItems.map((s) => s.entry);
         const updatedEntries = markRetrieved(toUpdate);
         const localIndex = loadIndex(ctx.hippoRoot);
-        // EVAL-ONLY ablation (see ablation.ts): under the recall flag,
-        // markRetrieved returns unmutated entries (ids preserved for outcome
-        // attribution) and persistence is skipped (identical-row writes still
-        // refresh updated_at / mirrors / DAG dirty flags).
-        if (!isRecallBoostAblated()) {
-            for (const u of updatedEntries) {
-                const targetRoot = localIndex.entries[u.id]
-                    ? ctx.hippoRoot
-                    : hasGlobal
-                        ? globalRoot
-                        : ctx.hippoRoot;
-                writeEntry(targetRoot, u);
-            }
-        }
-        localIndex.last_retrieval_ids = updatedEntries.map((u) => u.id);
+        const retrievedIds = updatedEntries.map((u) => u.id);
+        const strengthenedHere = strengthenRetrieved(ctx.hippoRoot, retrievedIds);
+        if (hasGlobal)
+            strengthenRetrieved(globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)));
+        localIndex.last_retrieval_ids = retrievedIds;
         // LC1 F1 structural fix (docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
         // write the trace FIRST — post-limit, post-annotation `selectedItems`
         // actually returned, on a fresh short-lived connection (the audit
@@ -1833,6 +1864,174 @@ export async function getContext(ctx, opts = {}) {
         ambientState,
     };
 }
+/**
+ * Record memory text handed to an agent in the token ledger (ROADMAP TE0).
+ * Best-effort: never throws, because a ledger failure must not fail the
+ * recall or context call that produced the text.
+ */
+export function recordTokens(ctx, surface, use) {
+    try {
+        const db = openHippoDb(ctx.hippoRoot);
+        try {
+            recordTokenUse(db, {
+                tenantId: ctx.tenantId,
+                sessionId: use.sessionId ?? null,
+                surface,
+                event: 'inject',
+                items: use.items,
+                tokens: use.tokens,
+            });
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch {
+        // Ledger is best-effort.
+    }
+}
+/**
+ * Token ledger totals for the tenant over the last `days` days (default 30):
+ * tokens sent per surface, blocks skipped as unchanged and the tokens that
+ * saved, and mean tokens per session.
+ */
+export function tokenSummary(ctx, opts = {}) {
+    const days = opts.days !== undefined && Number.isFinite(opts.days) && opts.days > 0 ? opts.days : 30;
+    const since = new Date(Date.now() - days * 86_400_000).toISOString();
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return summarizeTokenUse(db, ctx.tenantId, since);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
+ * active memory instead of deleting, when `dormant.enabled` is on. Newest
+ * first; `opts.query` keeps rows containing every term (case-insensitive).
+ */
+export function listDormant(ctx, opts = {}) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return listDormantRows(db, ctx.tenantId, opts);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Bring a dormant memory back into active memory. It returns as if just
+ * recalled: `last_retrieved` is now, so it gets a full half-life before it
+ * can fade again. Every other field is the snapshot taken when it went
+ * dormant.
+ *
+ * Throws when the tenant has no dormant memory with that id (another
+ * tenant's id reads the same way), when a live memory already holds the id,
+ * and RejectedValueError when the value has been rejected since. On any
+ * throw the dormant copy stays where it is.
+ */
+export function restoreDormant(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        let restored;
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const dormant = readDormantSnapshot(db, ctx.tenantId, id);
+            if (!dormant) {
+                throw new Error(`dormant memory not found: ${id}`);
+            }
+            if (db.prepare(`SELECT 1 FROM memories WHERE id = ?`).get(id) !== undefined) {
+                throw new Error(`memory ${id} is already active; forget it before restoring its dormant copy`);
+            }
+            const now = new Date();
+            // Dormant rows are long-lived, so a snapshot can predate a field added
+            // later: createMemory supplies a default for anything it lacks, then
+            // the snapshot overrides every field it does carry, content included.
+            // (The placeholder only satisfies createMemory's minimum length, so a
+            // legacy row shorter than 3 chars can still be restored.)
+            const revived = {
+                ...createMemory('dormant snapshot defaults'),
+                ...dormant.entry,
+                last_retrieved: now.toISOString(),
+            };
+            restored = stampOriginProject(ctx.hippoRoot, { ...revived, strength: calculateStrength(revived, now) });
+            writeEntryDbOnly(db, restored, { actor: ctx.actor.subject });
+            deleteDormantRow(db, ctx.tenantId, id);
+            // A restore is a labelled "forgot it, then needed it" event: the
+            // signal a learned lifecycle (ROADMAP LC3) trains on. Same transaction
+            // as the restore, so the label exists exactly when the restore does.
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'dormant_restore',
+                targetId: id,
+                metadata: {
+                    reason: dormant.reason,
+                    strengthAtDormancy: dormant.strength,
+                    dormantAt: dormant.dormantAt,
+                    daysDormant: Math.max(0, (now.getTime() - Date.parse(dormant.dormantAt)) / (24 * 60 * 60 * 1000)),
+                },
+            });
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already rolled back */ }
+            if (err instanceof RejectedValueError) {
+                auditRejectionRefusal(db, err, ctx.actor.subject);
+            }
+            throw err;
+        }
+        writeEntryMirrors(ctx.hippoRoot, db, restored);
+        return restored;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Permanently delete a dormant memory: the explicit "forget it for good"
+ * that dormant storage leaves to the user. Throws when the tenant has no
+ * dormant memory with that id.
+ */
+export function forgetDormant(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        if (!deleteDormantRow(db, ctx.tenantId, id)) {
+            throw new Error(`dormant memory not found: ${id}`);
+        }
+        try {
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'forget',
+                targetId: id,
+                metadata: { dormant: true },
+            });
+        }
+        catch {
+            // Best-effort, like every other forget audit row: the delete stands.
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    // Counted like every other permanent removal (forget, archiveRaw).
+    updateStats(ctx.hippoRoot, { forgotten: 1 });
+}
+/** Whether the tenant holds a dormant memory with this id (for "not found" hints). */
+export function isDormant(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return hasDormantRow(db, ctx.tenantId, id);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 const DEFAULT_SLEEP_PHASES = {
     consolidate,
     deduplicateStore,
@@ -1896,10 +2095,16 @@ export async function sleep(ctx, opts = {}) {
             dryRun,
             details: consolidateResult.details,
         };
-        if (dryRun)
-            return result;
+        // Set only when non-zero, so a store without dormant memories gets a
+        // byte-identical result (HTTP /v1/sleep, the CLI render snapshot).
+        if (consolidateResult.dormant > 0) {
+            result.dormant = consolidateResult.dormant;
+        }
+        if (consolidateResult.dormantExpired > 0) {
+            result.dormantExpired = consolidateResult.dormantExpired;
+        }
         // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
-        const dedupResult = phases.deduplicateStore(ctx.hippoRoot);
+        const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject });
         dedupCount = dedupResult.removed;
         if (dedupResult.removed > 0) {
             const semDups = dedupResult.pairs.filter((p) => p.keptLayer === 'semantic' && p.removedLayer === 'semantic').length;
@@ -1912,25 +2117,29 @@ export async function sleep(ctx, opts = {}) {
                 crossDups,
             };
         }
-        // Phase 3: Quality audit (remove junk, report warnings).
-        const allEntries = phases.loadAllEntries(ctx.hippoRoot);
+        // 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);
         if (auditOut.issues.length > 0) {
             const errors = auditOut.issues.filter((i) => i.severity === 'error');
             const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
-            if (errors.length > 0) {
-                for (const issue of errors) {
-                    phases.deleteEntry(ctx.hippoRoot, issue.memoryId);
-                }
+            let removed = 0;
+            for (const issue of errors) {
+                const reason = `sleep-audit: ${issue.reason}`;
+                if (dryRun || phases.deleteEntry(ctx.hippoRoot, issue.memoryId, { actor: ctx.actor.subject, reason, automatic: true }))
+                    removed++;
             }
-            auditDeletedCount = errors.length;
-            if (errors.length > 0 || warnings.length > 0) {
+            auditDeletedCount = removed;
+            if (removed > 0 || warnings.length > 0) {
                 result.audit = {
-                    errorsRemoved: errors.length,
+                    errorsRemoved: removed,
                     warningCount: warnings.length,
                 };
             }
         }
+        if (dryRun)
+            return result;
         // Phase 4: Auto-share high-transfer-score memories to global.
         if (!opts.noShare) {
             const sleepConfig = phases.loadConfig(ctx.hippoRoot);

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryEntry } from './memory.js';
+import { type MemoryEntry } from './memory.js';
 import type { DatabaseSyncLike } from './db.js';
 import type { JsonObject } from './working-memory.js';
 export type AuditSeverity = 'warning' | 'error';
@@ -16,7 +16,7 @@ export interface AuditResult {
 export declare function auditMemory(entry: MemoryEntry): AuditIssue | null;
 export declare function auditMemories(entries: MemoryEntry[]): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;
-export type AuditOp = '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';
+export type AuditOp = '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' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve';
 export interface AppendAuditOpts {
     tenantId: string;
     actor: string;

package/dist/audit.js

@@ -1,3 +1,4 @@
+import { canAutoDelete } from './memory.js';
 const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
     'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'it',
@@ -109,6 +110,14 @@ function hasNoSpecificity(text) {
     return words.length < 8 && VAGUE_ONLY.test(text);
 }
 export function auditMemory(entry) {
+    const issue = classifyMemory(entry);
+    // Error means "auto-remove"; a pinned or raw row is never auto-removed, so it can only warn.
+    if (issue?.severity === 'error' && !canAutoDelete(entry)) {
+        return { ...issue, severity: 'warning', reason: `${issue.reason} (${entry.pinned ? 'pinned' : 'raw'}, kept)` };
+    }
+    return issue;
+}
+function classifyMemory(entry) {
     const content = entry.content.trim();
     if (content.length < 3) {
         return { memoryId: entry.id, content, severity: 'error', reason: 'too short (< 3 chars)' };

package/dist/autolearn.d.ts

@@ -7,7 +7,7 @@ import { MemoryEntry } from './memory.js';
  * Create a MemoryEntry capturing a command failure.
  * Content format: "Command '<cmd>' failed: <truncated stderr>"
  */
-export declare function captureError(exitCode: number, stderr: string, command: string): MemoryEntry;
+export declare function captureError(exitCode: number, stderr: string, command: string, tenantId?: string): MemoryEntry;
 /**
  * Parse git log output for actionable lessons.
  * Looks for fix:, revert:, bug:, error:, hotfix: commit messages.

package/dist/autolearn.js

@@ -11,7 +11,7 @@ import { isContentWorthStoring } from './audit.js';
  * Create a MemoryEntry capturing a command failure.
  * Content format: "Command '<cmd>' failed: <truncated stderr>"
  */
-export function captureError(exitCode, stderr, command) {
+export function captureError(exitCode, stderr, command, tenantId) {
     // Truncate to first 500 chars to avoid storing megabytes of build logs
     const wasTruncated = stderr.length > 500;
     const truncated = stderr.slice(0, 500).trim();
@@ -29,6 +29,7 @@ export function captureError(exitCode, stderr, command) {
         tags,
         source: 'autolearn',
         confidence: 'observed',
+        tenantId,
     });
 }
 /**

package/dist/capture-error.d.ts

@@ -0,0 +1,20 @@
+import type { JsonValue } from './working-memory.js';
+/** Why a failure was not stored, or `stored`. */
+export type CaptureErrorOutcome = 'stored' | 'duplicate' | 'skipped-interrupt' | 'skipped-routine' | 'skipped-invalid';
+/** Normalised form used to spot repeats of the same failure. */
+export declare function failureSignature(text: string): string;
+/**
+ * The memory text for a failure payload, or the reason it is not stored.
+ * Pure: no store access.
+ */
+export declare function lessonFromFailure(payload: JsonValue): {
+    text: string;
+} | {
+    skip: Exclude<CaptureErrorOutcome, 'stored' | 'duplicate'>;
+};
+/**
+ * Store a failure payload as an error memory unless it is routine or a
+ * repeat of an auto-captured error already in the store.
+ */
+export declare function captureToolFailure(hippoRoot: string, tenantId: string, payload: JsonValue): CaptureErrorOutcome;
+//# sourceMappingURL=capture-error.d.ts.map