hippo-memory 1.70.0 → 1.71.0

package/dist/api/recall.js

@@ -1,12 +1,12 @@
 // Read path: recall (sync) and retrieve (async, adds the vector arm).
 import { envRequireSessionScopedFreshTail } from '../util/env.js';
 import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
-import { loadEntriesByIds, loadFreshRawMemories } from '../store/entry-reads.js';
-import { loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
+import { recallScopeFilter } from '../store/search-rows.js';
 import { estimateTokens } from '../util/token-text.js';
 import { formatHandoffEvidenceLine } from '../core/handoff.js';
-import { activeGoalsWithPolicies, boostByGoals } from '../store/goals.js';
-import { continuityAt, finishRecallAt, storeFor } from '../store/index.js';
+import { boostByGoals } from '../search/goal-boost.js';
+import { storeFor } from '../store/index.js';
+import { sqliteSyncStore } from '../store/sqlite/store.js';
 import { hybridSearch } from '../search/hybrid.js';
 import { physicsSearch } from '../search/physics-search.js';
 import { churnStaleFactor } from '../search/boosts.js';
@@ -15,56 +15,26 @@ import { dropHeldCopies, duplicateKey, storedTextKeys } from '../util/same-text.
 import { isSharedStore, loadConfig } from '../core/config.js';
 import { classifyOriginProject, projectNames } from '../core/project-identity.js';
 import { decidePlanningFallacy, detectPlanningClaim } from '../predictions/planning-fallacy.js';
-import { planningFallacyEvidenceAt } from '../store/planning-fallacy-evidence.js';
 import { detectAnchoring, hashQueryText, biasHintEnabled } from './recall-history.js';
 import { detectAvailabilityBias } from './availability.js';
 import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../store/recall-scope.js';
 import { ownerOrSubject, RecallContractError } from './types.js';
 import { anchoringRows, availabilityRows, callerOf, recallAuditMetadata, recallAuditRow, strengthenOf } from './recall-record.js';
 import { retrieveWithCliCore } from './recall-core.js';
+import { recallLead, recordShownRecall } from './recall-finish.js';
 const DEFAULT_RECALL_LIMIT = 10;
-/**
- * Shared construction helper for `RecallSuppressionSummary`. Used by
- * `api.recall`, `cmdRecall`, and the MCP `hippo_recall` handler so all three
- * pipelines produce the same shape without duplicating field-construction
- * logic. Pass-through identity today; kept as a helper so future field
- * additions land at one site.
- */
-export function buildSuppressionSummary(counts) {
-    return {
-        totalCandidates: counts.totalCandidates,
-        droppedPreRank: counts.droppedPreRank,
-        droppedByBudget: counts.droppedByBudget,
-        summarySubstitutionsAdded: counts.summarySubstitutionsAdded,
-        freshTailAdded: counts.freshTailAdded,
-        suppressedByInterference: counts.suppressedByInterference,
-    };
-}
-/**
- * Domain-level recall on hippo.db only, never `ctx.store`, since it is synchronous: under another store its first open throws
- * `SqliteBlockedError`. Loads BM25-ranked candidates from SQLite scoped to
- * `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`** (contract
- * lock). The CLI `cmdRecall` (cli.ts) writes `last_retrieval_ids` because the
- * CLI is interactive (user is about to run `hippo outcome --good`). SDK callers
- * are programmatic: they either pass explicit ids to `api.outcome` or call
- * `api.getContext` first for the context-then-outcome workflow (getContext
- * DOES write `last_retrieval_ids`). Adding the side-effect here would change
- * `api.recall` from a pure read into a read+write, breaking SDK callers who
- * batch recall calls in a row. Locked by
- * `tests/api-recall-no-side-effects.test.ts`.
- */
+/** Reads hippo.db directly, never `ctx.store`, because it is synchronous (another store would throw `SqliteBlockedError`).
+ *  It never writes `last_retrieval_ids` (contract lock: tests/api-recall-no-side-effects.test.ts). */
 export function recall(ctx, opts) {
     // A member key may not unlock a private or quarantined scope by naming it.
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
     const own = personalScopeOf(ctx.actor) ?? undefined;
-    const all = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own);
+    const store = sqliteSyncStore(ctx.hippoRoot);
+    const all = store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, windowSize, own));
     const plan = planRecall(ctx, opts, all, own);
-    const { result, writes } = composeRecall(ctx, opts, { windowSize, all, plan, reads: readRecallSync(ctx, opts, plan) });
-    finishRecallAt(ctx.hippoRoot, { ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit] });
+    const { result, writes } = composeRecall(ctx, opts, { windowSize, all, plan, reads: readRecallSync(store, ctx, opts, plan) });
+    store.finishRecall({ ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit] });
     return result;
 }
 function recallOrigin(opts) {
@@ -73,7 +43,8 @@ function recallOrigin(opts) {
 function inCallerProject(entry, opts) {
     return !opts.project || classifyOriginProject(entry.origin_project, opts.project) !== 'cross-project';
 }
-/** The one recall entry: ranks with the ranker `opts` names, then writes the recall. Only the CLI core ranker writes last_retrieval_ids (contract lock). */
+/** The one recall entry: ranks with the ranker `opts` names, then writes the recall, and records it in full for a surface that sets `recordAs`.
+ *  Only the CLI core ranker writes last_retrieval_ids (contract lock). */
 export async function retrieve(ctx, opts) {
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     if (opts.cliCore)
@@ -84,20 +55,48 @@ export async function retrieve(ctx, opts) {
     if (opts.showRanked)
         return retrieveFromStore(ctx, opts, windowSize, opts.showRanked, own);
     const store = storeFor(ctx);
+    const how = opts.recordAs;
+    if (!how)
+        return retrieveBand(ctx, store, opts, windowSize, own);
+    const result = await retrieveBand(ctx, store, { ...opts, ...recallLead(ctx, how, opts.query, opts.sessionId) }, windowSize, own);
+    await recordShownRecall(ctx, store, how, shownBand(opts, result));
+    return result;
+}
+/** What the band ranker hands to the record: the rows it returns, and the continuity block the reply carries beside them. */
+function shownBand(opts, result) {
+    return {
+        query: opts.query,
+        sessionId: opts.sessionId,
+        topId: result.results[0]?.id ?? null,
+        anchoredOn: result.anchoringHint?.memoryId,
+        items: result.results.length,
+        tokens: result.tokens + (result.continuityTokens ?? 0),
+        ledgerSessionId: opts.sessionId ?? null,
+        written: true, // a failed audit write throws out of the band ranker, so this point is never reached without the rows
+    };
+}
+/** The default ranker: the SQL BM25 band, reordered by hybrid or physics search when `mode` asks. */
+async function retrieveBand(ctx, store, opts, windowSize, own) {
     let candidates = await store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, windowSize, own));
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
         const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null, vectorCandidates: recallVectorSpec(ctx, opts, own), store };
-        const ranked = opts.mode === 'physics'
-            ? await physicsSearch(opts.query, candidates, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
-            : await hybridSearch(opts.query, candidates, searchOpts);
+        const ranked = await rankPool(ctx, opts, 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 plan = planRecall(ctx, opts, candidates, own);
     const { result, writes } = composeRecall(ctx, opts, { windowSize, all: candidates, plan, reads: await readRecall(store, ctx, opts, plan) });
-    await store.finishRecall({ ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit], strengthen: strengthenOf(ctx, result.results.map((r) => r.id)) });
+    await store.finishRecall({
+        ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit], strengthen: strengthenOf(ctx, result.results.map((r) => r.id))
+    });
     return result;
 }
+/** The ranked pool: physics when `mode` says so, hybrid otherwise; each caller supplies its own search options. */
+function rankPool(ctx, opts, pool, searchOpts) {
+    return opts.mode === 'physics'
+        ? physicsSearch(opts.query, pool, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
+        : hybridSearch(opts.query, pool, searchOpts);
+}
 /** The recall load's arguments: exact scope, current rows only, the caller's project and personal scope. */
 function recallSearchArgs(ctx, opts, limit, own) {
     return {
@@ -129,9 +128,7 @@ async function retrieveFromStore(ctx, opts, windowSize, show, own) {
     const pool = loaded.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope, own));
     // No scope option: the scope boost follows HIPPO_SCOPE and the skill env, as MCP recall always ranked.
     const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, vectorCandidates: recallVectorSpec(ctx, opts, own), store };
-    let ranked = opts.mode === 'physics'
-        ? await physicsSearch(opts.query, pool, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
-        : await hybridSearch(opts.query, pool, searchOpts);
+    let ranked = await rankPool(ctx, opts, pool, searchOpts);
     // One goal read serves both boosts; the ranked list's log rows come first, so its scores win the log's first-write.
     const goals = opts.sessionId && !opts.goalTag ? await store.activeGoals({ sessionId: opts.sessionId, tenantId: ctx.tenantId }) : null;
     let rankedLog = [];
@@ -143,7 +140,9 @@ async function retrieveFromStore(ctx, opts, windowSize, show, own) {
     const window = ranked.slice(0, windowSize).map((r) => r.entry);
     const bandOpts = { ...opts, suppressRecallTrace: true };
     const plan = planRecall(ctx, bandOpts, window, own);
-    const { result, writes } = composeRecall(ctx, bandOpts, { windowSize, all: window, plan, reads: await readRecall(store, ctx, bandOpts, plan, goals), auditBand: false });
+    const { result, writes } = composeRecall(ctx, bandOpts, {
+        windowSize, all: window, plan, reads: await readRecall(store, ctx, bandOpts, plan, goals), auditBand: false
+    });
     // Rows the vector arm added count as candidates too.
     const inPool = new Set(pool.map((e) => e.id));
     const candidates = [...pool, ...ranked.map((r) => r.entry).filter((e) => !inPool.has(e.id))];
@@ -199,16 +198,16 @@ function planRecall(ctx, opts, all, own) {
         claim: detectPlanningClaim(opts.query),
     };
 }
-/** The plan's reads on hippo.db directly, for the synchronous recall that cannot await the port. */
-function readRecallSync(ctx, opts, plan) {
-    const { hippoRoot, tenantId } = ctx;
+/** The plan's reads on the synchronous store, for the recall that cannot await the port. */
+function readRecallSync(store, ctx, opts, plan) {
+    const { tenantId } = ctx;
     const freshCount = opts.freshTailCount ?? 0;
     return {
-        goals: plan.goalBoost ? activeGoalsWithPolicies(hippoRoot, { sessionId: plan.goalBoost.sessionId, tenantId }) : null,
-        parents: plan.overflow.size > 0 ? loadEntriesByIds(hippoRoot, [...plan.overflow.keys()], tenantId) : [],
-        freshRaws: freshCount > 0 ? loadFreshRawMemories(hippoRoot, freshCount, tenantId, opts.freshTailSessionId, recallOrigin(opts)) : [],
-        continuity: opts.includeContinuity ? continuityAt(hippoRoot, tenantId, CONTINUITY_EVENT_LIMIT, continuityKey(ctx, opts)) : undefined,
-        planning: plan.claim ? planningFallacyEvidenceAt(hippoRoot, tenantId, plan.claim.classQueryTokens) : null,
+        goals: plan.goalBoost ? store.activeGoals({ sessionId: plan.goalBoost.sessionId, tenantId }) : null,
+        parents: plan.overflow.size > 0 ? store.entriesByIds([...plan.overflow.keys()], tenantId) : [],
+        freshRaws: freshCount > 0 ? store.freshRawEntries(freshCount, tenantId, opts.freshTailSessionId, recallOrigin(opts) ?? null) : [],
+        continuity: opts.includeContinuity ? store.continuity(tenantId, CONTINUITY_EVENT_LIMIT, continuityKey(ctx, opts)) : undefined,
+        planning: plan.claim ? store.planningFallacyEvidence(tenantId, plan.claim.classQueryTokens) : null,
     };
 }
 /** The plan's reads through the store; `goals` already read by the caller skips that read. */
@@ -246,14 +245,14 @@ function composeRecall(ctx, opts, options) {
         continuity,
         continuityTokens: continuity ? continuityTokensOf(continuity) : undefined,
         windowSize,
-        suppressionSummary: buildSuppressionSummary({
+        suppressionSummary: {
             totalCandidates: all.length,
             droppedPreRank: window.droppedPreRank + bands.heldDropped,
             droppedByBudget: window.droppedByBudget,
             summarySubstitutionsAdded: bands.summarySubstitutions,
             freshTailAdded: bands.freshTailAdded,
             suppressedByInterference,
-        }),
+        },
     };
     // The hint and the no-class-match / tiebreak watching variant are mutually exclusive; both go out as optional fields.
     if (planning?.output.hint)

package/dist/api/refine.d.ts

@@ -0,0 +1,7 @@
+import type { MemoryEntry } from '../core/memory.js';
+import type { Context } from './types.js';
+/** Marks a merged memory a model has rewritten, so a later pass skips it. */
+export declare const REFINED_TAG = "llm-refined";
+/** Store a model's rewrite of a merged memory: the new text replaces the old one, and the row gains the refined tag once. */
+export declare function storeRefinement(ctx: Context, entry: MemoryEntry, refined: string): void;
+//# sourceMappingURL=refine.d.ts.map

package/dist/api/refine.js

@@ -0,0 +1,10 @@
+// The write half of `hippo refine`: the model call stays with the caller, the rewritten row is stored here.
+import { writeEntry } from '../store/entry-writes.js';
+/** Marks a merged memory a model has rewritten, so a later pass skips it. */
+export const REFINED_TAG = 'llm-refined';
+/** Store a model's rewrite of a merged memory: the new text replaces the old one, and the row gains the refined tag once. */
+export function storeRefinement(ctx, entry, refined) {
+    const tags = entry.tags.includes(REFINED_TAG) ? entry.tags : [...entry.tags, REFINED_TAG];
+    writeEntry(ctx.hippoRoot, { ...entry, content: refined, tags }, { actor: ctx.actor.subject });
+}
+//# sourceMappingURL=refine.js.map

package/dist/api/remember-local.d.ts

@@ -0,0 +1,57 @@
+import type { ConfidenceLevel, Layer, MemoryEntry, MemoryKind } from '../core/memory.js';
+import type { HippoDbContext } from './types.js';
+/** One write by a caller in this process, every field already parsed and checked by it. */
+export interface LocalRememberInput {
+    readonly content: string;
+    /** Every tag the row stores; the salience gate reads these. */
+    readonly tags: readonly string[];
+    /** The tags schema fit is scored on, for a caller that added path and scope tags of its own to `tags`; without it, `tags`. */
+    readonly fitTags?: readonly string[];
+    readonly kind?: MemoryKind;
+    readonly scope?: string;
+    readonly owner?: string;
+    readonly artifactRef?: string;
+    readonly layer?: Layer;
+    readonly pinned?: boolean;
+    readonly confidence?: ConfidenceLevel;
+    readonly source?: string;
+    /** Store it whatever the salience gate would say, as `hippo remember --force` asks and `hippo watch` always does. */
+    readonly force?: boolean;
+}
+/** The gate's start-weak verdict as the stored row carries it. */
+export interface StartedWeak {
+    readonly reason: string;
+    readonly strength: number;
+}
+/** `stored` carries the row as the store holds it after the write; `skipped` is the gate dropping the write, with nothing stored or counted. */
+export type LocalRememberOutcome = {
+    readonly status: 'stored';
+    readonly entry: MemoryEntry;
+    readonly startedWeak?: StartedWeak;
+} | {
+    readonly status: 'skipped';
+    readonly reason: string;
+    readonly score: number;
+};
+/** One local write on hippo.db: gate, write, read-back, counter, then the embedding, started and never awaited. A refused value throws as `remember` does. */
+export declare function rememberLocally(ctx: HippoDbContext, input: LocalRememberInput): LocalRememberOutcome;
+/** What a caller asks of fact extraction. The key comes from the caller, which read it from its own environment. */
+export interface FactExtractionRequest {
+    /** The caller asked for extraction (`--extract`); the store's config can turn it on without that. */
+    readonly requested: boolean;
+    readonly apiKey?: string;
+    readonly fetcher?: typeof fetch;
+}
+/** `off`: nobody asked. `no_key`: asked, with no key to call the model. `ran`: the facts the model gave and each reason it gave fewer. */
+export type FactExtraction = {
+    readonly status: 'off';
+} | {
+    readonly status: 'no_key';
+} | {
+    readonly status: 'ran';
+    readonly facts: number;
+    readonly failures: readonly string[];
+};
+/** Extracts facts from a row just stored and stores them beside it. Best-effort: a failure is named in the result, never thrown. */
+export declare function extractRememberedFacts(ctx: HippoDbContext, entry: MemoryEntry, request: FactExtractionRequest): Promise<FactExtraction>;
+//# sourceMappingURL=remember-local.d.ts.map

package/dist/api/remember-local.js

@@ -0,0 +1,90 @@
+// The local remember pipeline for a caller in this process (`hippo remember`, `hippo watch`): schema fit, the salience gate, the
+// write, the read-back, the `remembered` counter and the embedding kick-off, in that order. Fact extraction is a second step,
+// which the caller runs after it has reported the write. Nothing here prints; the caller reports from what comes back.
+import { loadConfig } from '../core/config.js';
+import { computeSalience } from '../core/salience.js';
+import { loadNewestEntries, schemaFitInStore } from '../store/candidates.js';
+import { embedMemory } from '../store/embeddings/index.js';
+import { loadAllEntries, readEntry } from '../store/entry-reads.js';
+import { updateStats } from '../store/index-and-stats.js';
+import { errorMessage } from '../util/log.js';
+import { remember } from './remember.js';
+const WEAK_HALF_LIFE_FACTOR = 0.5;
+/** The gate's verdict on one write, or null where it does not judge: the store has it off, or the write is pinned or forced. */
+function salienceVerdict(ctx, input) {
+    const { salience } = loadConfig(ctx.hippoRoot);
+    if (!salience.enabled || input.pinned || input.force)
+        return null;
+    // computeSalience compares against the last `recentWindow` rows only; below 1 its slice takes every row, so that case still loads them all.
+    const window = Math.trunc(salience.recentWindow);
+    const recent = Number.isSafeInteger(window) && window >= 1
+        ? loadNewestEntries(ctx.hippoRoot, ctx.tenantId, window)
+        : loadAllEntries(ctx.hippoRoot, ctx.tenantId);
+    return computeSalience(input.content, [...input.tags], recent, {
+        recentWindow: salience.recentWindow,
+        overlapThreshold: salience.overlapThreshold,
+        minContentLength: salience.minContentLength,
+        maxRepeatErrors: salience.maxRepeatErrors,
+    });
+}
+/** The row `remember` just wrote, as the store holds it: the report, the embedding and the extraction all work on that. */
+function storedEntry(ctx, id) {
+    const entry = readEntry(ctx.hippoRoot, id, ctx.tenantId);
+    if (!entry)
+        throw new Error(`memory ${id} was written but cannot be read back`);
+    return entry;
+}
+/** One local write on hippo.db: gate, write, read-back, counter, then the embedding, started and never awaited. A refused value throws as `remember` does. */
+export function rememberLocally(ctx, input) {
+    const schemaFit = schemaFitInStore(ctx.hippoRoot, ctx.tenantId, input.content, input.fitTags ?? input.tags);
+    const verdict = salienceVerdict(ctx, input);
+    if (verdict?.decision === 'skip')
+        return { status: 'skipped', reason: verdict.reason, score: verdict.score };
+    const startedWeak = verdict?.decision === 'start_weak' ? { reason: verdict.reason, strength: verdict.score } : undefined;
+    const { id } = remember(ctx, {
+        content: input.content,
+        kind: input.kind,
+        scope: input.scope,
+        owner: input.owner,
+        artifactRef: input.artifactRef,
+        tags: [...input.tags],
+        local: {
+            layer: input.layer,
+            pinned: input.pinned,
+            source: input.source,
+            confidence: input.confidence,
+            schemaFit,
+            weaken: startedWeak && { strength: startedWeak.strength, halfLifeFactor: WEAK_HALF_LIFE_FACTOR },
+        },
+    });
+    const entry = storedEntry(ctx, id);
+    updateStats(ctx.hippoRoot, { remembered: 1 });
+    // Best-effort and slow (a model load or a network call), so the caller is not held for it.
+    void embedMemory(ctx.hippoRoot, entry);
+    return startedWeak ? { status: 'stored', entry, startedWeak } : { status: 'stored', entry };
+}
+/** Extracts facts from a row just stored and stores them beside it. Best-effort: a failure is named in the result, never thrown. */
+export async function extractRememberedFacts(ctx, entry, request) {
+    const { extraction } = loadConfig(ctx.hippoRoot);
+    if (!request.requested && extraction.enabled !== true)
+        return { status: 'off' };
+    const { apiKey, fetcher } = request;
+    if (!apiKey)
+        return { status: 'no_key' };
+    const failures = [];
+    let facts = 0;
+    try {
+        // Loaded on demand, so a write that extracts nothing does not pay for the module.
+        const { extractFacts, storeExtractedFacts } = await import('../learn/extract.js');
+        const found = await extractFacts(entry.content, { apiKey, model: extraction.model, fetcher, onError: (msg) => { failures.push(msg); } });
+        if (found.length > 0) {
+            storeExtractedFacts(ctx.hippoRoot, entry, found);
+            facts = found.length;
+        }
+    }
+    catch (cause) {
+        failures.push(errorMessage(cause));
+    }
+    return { status: 'ran', facts, failures };
+}
+//# sourceMappingURL=remember-local.js.map

package/dist/api/remember.d.ts

@@ -1,6 +1,21 @@
 import type { ConnectorEvent } from '../store/port.js';
-import { type MemoryKind } from '../core/memory.js';
+import { type ConfidenceLevel, type Layer, type MemoryKind, type TraceOutcome } from '../core/memory.js';
 import type { Context, StoreReply } from './types.js';
+/** Row fields the caller's own process decides, as the CLI does from its flags and its salience gate. */
+export interface RememberLocal {
+    layer?: Layer;
+    pinned?: boolean;
+    confidence?: ConfidenceLevel;
+    source?: string;
+    schemaFit?: number;
+    traceOutcome?: TraceOutcome;
+    sourceSessionId?: string | null;
+    /** A salience gate's start-weak verdict: the row starts at `strength`, and its half-life is multiplied by `halfLifeFactor`, never below one day. */
+    weaken?: {
+        readonly strength: number;
+        readonly halfLifeFactor: number;
+    };
+}
 export interface RememberOpts {
     content: string;
     kind?: MemoryKind;
@@ -19,6 +34,8 @@ export interface RememberOpts {
     };
     /** Store it in the caller's own personal scope, readable by its owner alone in every project; needs an owner on the actor and no `scope`. */
     personal?: boolean;
+    /** Never set from a request body: a route or tool that copied it would let a client pin a row or pick its layer and source. */
+    local?: RememberLocal;
 }
 export interface RememberResult {
     id: string;

package/dist/api/remember.js

@@ -31,7 +31,15 @@ function prepareRemember(ctx, opts) {
     const requestedScope = rememberScope(ctx, opts);
     const vetted = vetSecrets(opts.content, opts.tags ?? [], opts.untrusted === true);
     const detection = opts.untrusted ? detectInstruction(vetted.content) : { flagged: false, reason: null };
-    const entry = createMemory(vetted.content, {
+    const local = opts.local ?? {};
+    const created = createMemory(vetted.content, {
+        layer: local.layer,
+        pinned: local.pinned,
+        confidence: local.confidence,
+        source: local.source,
+        schema_fit: local.schemaFit,
+        trace_outcome: local.traceOutcome,
+        source_session_id: local.sourceSessionId,
         kind: opts.kind ?? 'distilled',
         scope: detection.flagged ? quarantineScopeFor(requestedScope) : requestedScope,
         owner: opts.owner ?? null,
@@ -40,11 +48,15 @@ function prepareRemember(ctx, opts) {
         tenantId: ctx.tenantId,
         baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
     });
+    const entry = local.weaken ? weakened(created, local.weaken) : created;
     // Aliases only widen what a reader matches; a row has one origin. A personal row's '' follows its owner into every project.
     const origin = opts.personal ? '' : opts.project?.name;
     const stamped = origin !== undefined ? { ...entry, origin_project: origin } : entry;
     return { entry: stamped, requestedScope, detection, warnings: vetted.warnings };
 }
+function weakened(entry, weaken) {
+    return { ...entry, strength: weaken.strength, half_life_days: Math.max(1, entry.half_life_days * weaken.halfLifeFactor) };
+}
 function rememberResult(ctx, prepared, written) {
     const { entry, detection, warnings } = prepared;
     const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };

package/dist/api/sleep-run.d.ts

@@ -1,7 +1,6 @@
 import { loadAllEntries } from '../store/entry-reads.js';
-import { deleteEntry } from '../store/delete-and-batch.js';
 import { auditMemories } from '../store/audit.js';
-import { autoShare } from '../sharing/shared.js';
+import { autoShare } from '../sharing/share.js';
 import { consolidate } from '../consolidate/sleep.js';
 import { loadConfig } from '../core/config.js';
 import { deduplicateStore } from '../consolidate/dedupe.js';
@@ -17,7 +16,6 @@ export interface SleepPhases {
     auditMemories: typeof auditMemories;
     autoShare: typeof autoShare;
     loadAllEntries: typeof loadAllEntries;
-    deleteEntry: typeof deleteEntry;
     computeAmbientState: typeof computeAmbientState;
     loadConfig: typeof loadConfig;
     loadPendingExtractionTenants: typeof loadPendingExtractionTenants;

package/dist/api/sleep-run.js

@@ -1,9 +1,9 @@
 // The sleep pipeline behind `sleep`, with its phase dependencies injectable; kept out of the package root.
 import { loadAllEntries } from '../store/entry-reads.js';
-import { deleteEntry, memoriesBackingObjects } from '../store/delete-and-batch.js';
+import { memoriesBackingObjects } from '../store/delete-and-batch.js';
 import { reportAuditWriteFailure, auditMemories } from '../store/audit.js';
 import { sqliteSyncStore } from '../store/sqlite/store.js';
-import { autoShare } from '../sharing/shared.js';
+import { autoShare } from '../sharing/share.js';
 import { consolidate } from '../consolidate/sleep.js';
 import { failedUnitOf } from '../store/delete-and-batch.js';
 import { loadConfig } from '../core/config.js';
@@ -11,6 +11,7 @@ import { deduplicateStore } from '../consolidate/dedupe.js';
 import { computeAmbientState } from '../core/ambient.js';
 import { loadPendingExtractionTenants, markPendingProcessedUpTo } from '../store/graph-queue.js';
 import { extractGraphChunked } from '../graph/extract.js';
+import { removeAuditErrors } from './audit.js';
 import { errorMessage } from '../util/log.js';
 const DEFAULT_SLEEP_PHASES = {
     consolidate,
@@ -18,7 +19,6 @@ const DEFAULT_SLEEP_PHASES = {
     auditMemories,
     autoShare,
     loadAllEntries,
-    deleteEntry,
     computeAmbientState,
     loadConfig,
     loadPendingExtractionTenants,
@@ -28,18 +28,15 @@ const DEFAULT_SLEEP_PHASES = {
 export async function runSleep(ctx, opts, overrides = {}) {
     const dryRun = Boolean(opts.dryRun);
     const phases = { ...DEFAULT_SLEEP_PHASES, ...overrides };
-    // Phase counters for the consolidate audit emit (in finally).
-    // Accumulated as each phase completes so partial-failure paths still report
-    // accurate "what got done before the failure" data.
+    // Phase counters for the consolidate audit emit (in finally), accumulated per phase so a partial failure still reports what got done.
     const counts = { consolidation: 0, dedup: 0, auditDeleted: 0, ambient: 0 };
     let phaseError = null;
     try {
         return await runSleepPhases(ctx, opts, phases, counts);
     }
     catch (err) {
-        // SAFETY: phaseError is read via phaseError.message / (phaseError !==
-        // null) below, both safe even if a non-Error was thrown; this mirrors
-        // the existing lenient (err as Error) pattern used throughout this catch chain.
+        // SAFETY: phaseError is only read via phaseError.message / (phaseError !== null) below, safe even if a non-Error was thrown;
+        // this mirrors the lenient (err as Error) pattern used through this catch chain.
         phaseError = err;
         throw err;
     }
@@ -60,14 +57,15 @@ async function runSleepPhases(ctx, opts, phases, counts) {
     if (dedupResult.removed > 0)
         result.deduped = dedupSummary(dedupResult);
     // Phase 3: Quality audit (remove junk, report warnings; a dry run skips rows earlier phases would remove).
-    counts.auditDeleted = runQualityAudit(ctx, phases, { dryRun, consolidateResult, dedupResult, result });
+    const audited = runQualityAudit(ctx, phases, { dryRun, consolidateResult, dedupResult, result });
+    counts.auditDeleted = audited.removed;
     if (dryRun)
         return result;
     // Phase 4: Auto-share high-transfer-score memories to global.
     if (!opts.noShare)
         shareOnSleep(ctx, phases, result);
     // Phase 5: Post-sleep ambient state summary.
-    counts.ambient = summarizeAmbient(ctx, phases, result);
+    counts.ambient = summarizeAmbient(ctx, phases, result, audited.remaining);
     await drainGraphQueue(ctx, phases, snapshot, result);
     return result;
 }
@@ -115,28 +113,26 @@ function dedupSummary(dedupResult) {
         crossDups,
     };
 }
+/** `removed` counts audit errors deleted (or that would be under dryRun); `remaining` is what the audit read, less the rows it deleted. */
 function runQualityAudit(ctx, phases, options) {
     const { dryRun, consolidateResult, dedupResult, result } = options;
     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, memoriesBackingObjects(ctx.hippoRoot));
     if (auditOut.issues.length === 0)
-        return 0;
+        return { removed: 0, remaining: allEntries };
     const errors = auditOut.issues.filter((i) => i.severity === 'error');
     const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
-    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++;
-    }
+    const gone = dryRun ? errors.map((issue) => issue.memoryId) : removeAuditErrors(ctx, 'sleep-audit', errors);
+    const removed = gone.length;
+    const deleted = new Set(gone);
     if (removed > 0 || warnings.length > 0) {
         result.audit = {
             errorsRemoved: removed,
             warningCount: warnings.length,
         };
     }
-    return removed;
+    return { removed, remaining: allEntries.filter((e) => !deleted.has(e.id)) };
 }
 function shareOnSleep(ctx, phases, result) {
     const sleepConfig = phases.loadConfig(ctx.hippoRoot);
@@ -156,11 +152,11 @@ function shareOnSleep(ctx, phases, result) {
     }
 }
 /** Returns the ambient total the audit row reports: 0 when ambient is off or no current row is left. */
-function summarizeAmbient(ctx, phases, result) {
+function summarizeAmbient(ctx, phases, result, loaded) {
     const postSleepConfig = phases.loadConfig(ctx.hippoRoot);
     if (!postSleepConfig.ambient.enabled)
         return 0;
-    const postSleepEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !e.superseded_by);
+    const postSleepEntries = loaded.filter((e) => !e.superseded_by);
     if (postSleepEntries.length === 0)
         return 0;
     result.ambient = phases.computeAmbientState(postSleepEntries);

package/dist/api/sleep.d.ts

@@ -4,23 +4,17 @@ import type { Context } from './types.js';
 export interface SleepOpts {
     /** Report what a sleep would change without applying it; sharing, the ambient summary and the graph refresh are skipped. */
     dryRun?: boolean;
-    /** Skip copying high-scoring memories to the global store under `HIPPO_HOME`. Default false, so every tenant's memories are eligible; multi-tenant callers pass `true`. */
+    /** Skip copying high-scoring memories to the global store under `HIPPO_HOME`. Default
+     * false, so every tenant's memories are eligible; multi-tenant callers pass `true`. */
     noShare?: boolean;
 }
 export interface SleepResult {
     active: number;
     removed: number;
-    /**
-     * Faded memories the decay pass moved to the dormant store instead of
-     * deleting (config `dormant.enabled`). Absent when 0. Per-invocation
-     * activity counter, same class as `removed`.
-     */
+    /** Faded memories the decay pass moved to the dormant store instead of deleting (config `dormant.enabled`); absent when 0. Per-invocation counter, like
+     * `removed`. */
     dormant?: number;
-    /**
-     * Dormant memories deleted for good this sleep because they outlived
-     * `dormant.retentionDays`. Absent when 0. Same per-invocation class as
-     * `removed`.
-     */
+    /** Dormant memories deleted for good this sleep for outliving `dormant.retentionDays`; absent when 0. Per-invocation counter, like `removed`. */
     dormantExpired?: number;
     mergedEpisodic: number;
     newSemantic: number;
@@ -36,26 +30,13 @@ export interface SleepResult {
         warningCount: number;
     };
     shared?: number;
-    /**
-     * Count of memories the auto-share secret veto withheld this sleep
-     * — rows that passed every other admission gate (transfer score,
-     * not-already-global) and were blocked solely by `detectSecret`. Absent
-     * when 0 or when auto-share did not run.
-     */
+    /** Memories the auto-share secret veto withheld: rows that passed every other gate but `detectSecret`; absent when 0 or auto-share did not run. */
     secretSkipped?: number;
-    /**
-     * Count of auto-share candidates the GLOBAL store's rejection
-     * tombstone refused this sleep; copy paths must not let one rejected
-     * candidate abort the batch. Absent when 0 or when auto-share did not run.
-     */
+    /** Auto-share candidates the GLOBAL store's rejection tombstone refused (one must not abort the batch); absent when 0 or auto-share did not run. */
     rejectedSkipped?: number;
     ambient?: AmbientState | null;
-    /**
-     * Graph re-extraction totals across the tenants rebuilt
-     * this sleep. Absent when no tenant was dirty, and under dryRun (the graph
-     * phase runs only on a real sleep). Cross-tenant aggregate, one reason
-     * /v1/sleep stays loopback-only.
-     */
+    /** Graph re-extraction totals across tenants rebuilt this sleep; absent when none was dirty or under dryRun.
+     * Cross-tenant aggregate: one reason /v1/sleep stays loopback-only. */
     graph?: {
         tenants: number;
         entities: number;