hippo-memory 1.70.0 → 1.72.0

package/dist/api/recall.js

@@ -1,12 +1,11 @@
-// Read path: recall (sync) and retrieve (async, adds the vector arm).
+// Read path: retrieve, the one recall entry.
 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 { hybridSearch } from '../search/hybrid.js';
 import { physicsSearch } from '../search/physics-search.js';
 import { churnStaleFactor } from '../search/boosts.js';
@@ -15,65 +14,22 @@ 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 { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../core/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`.
- */
-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 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] });
-    return result;
-}
 function recallOrigin(opts) {
     return opts.project ? projectNames(opts.project) : undefined;
 }
 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 +40,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 +113,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 +125,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,27 +183,17 @@ 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;
-    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,
-    };
-}
 /** The plan's reads through the store; `goals` already read by the caller skips that read. */
 async function readRecall(store, ctx, opts, plan, goals) {
     const { tenantId } = ctx;
     const freshCount = opts.freshTailCount ?? 0;
+    const parentIds = plan.overflow.size > 0 ? [...plan.overflow.keys()] : null;
+    const continuity = opts.includeContinuity ? { key: continuityKey(ctx, opts) } : null;
     return {
         goals: goals !== undefined ? goals : plan.goalBoost ? await store.activeGoals({ sessionId: plan.goalBoost.sessionId, tenantId }) : null,
-        parents: plan.overflow.size > 0 ? await store.entriesByIds([...plan.overflow.keys()], tenantId) : [],
+        parents: parentIds ? await store.entriesByIds(parentIds, tenantId) : [],
         freshRaws: freshCount > 0 ? await store.freshRawEntries(freshCount, tenantId, opts.freshTailSessionId, recallOrigin(opts) ?? null) : [],
-        continuity: opts.includeContinuity ? await store.continuity(tenantId, CONTINUITY_EVENT_LIMIT, continuityKey(ctx, opts)) : undefined,
+        continuity: continuity ? await store.continuity(tenantId, CONTINUITY_EVENT_LIMIT, continuity.key) : undefined,
         planning: plan.claim ? await store.planningFallacyEvidence(tenantId, plan.claim.classQueryTokens) : null,
     };
 }
@@ -246,14 +220,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)
@@ -462,19 +436,19 @@ function scopeContinuity(block, opts, own) {
 function continuityTokensOf(c) {
     const filteredSnapshot = c.activeSnapshot;
     const filteredHandoff = c.sessionHandoff;
-    const tokenize = (s) => s ? estimateTokens(s) : 0;
-    return tokenize(filteredSnapshot?.task) +
-        tokenize(filteredSnapshot?.summary) +
-        tokenize(filteredSnapshot?.next_step) +
-        tokenize(filteredHandoff?.summary) +
-        tokenize(filteredHandoff?.nextAction) +
-        (filteredHandoff?.artifacts ?? []).reduce((acc, a) => acc + tokenize(a), 0) +
-        (filteredHandoff?.constraints ?? []).reduce((acc, c) => acc + tokenize(c), 0) +
-        tokenize(filteredHandoff?.evidence ? formatHandoffEvidenceLine(filteredHandoff.evidence) : null) +
-        tokenize(filteredHandoff?.outcome) +
-        tokenize(filteredHandoff?.targetRuntime) +
-        tokenize(filteredHandoff?.cardId) +
-        c.recentSessionEvents.reduce((acc, e) => acc + tokenize(e.content), 0);
+    const tokenCount = (s) => s ? estimateTokens(s) : 0;
+    return tokenCount(filteredSnapshot?.task) +
+        tokenCount(filteredSnapshot?.summary) +
+        tokenCount(filteredSnapshot?.next_step) +
+        tokenCount(filteredHandoff?.summary) +
+        tokenCount(filteredHandoff?.nextAction) +
+        (filteredHandoff?.artifacts ?? []).reduce((acc, a) => acc + tokenCount(a), 0) +
+        (filteredHandoff?.constraints ?? []).reduce((acc, c) => acc + tokenCount(c), 0) +
+        tokenCount(filteredHandoff?.evidence ? formatHandoffEvidenceLine(filteredHandoff.evidence) : null) +
+        tokenCount(filteredHandoff?.outcome) +
+        tokenCount(filteredHandoff?.targetRuntime) +
+        tokenCount(filteredHandoff?.cardId) +
+        c.recentSessionEvents.reduce((acc, e) => acc + tokenCount(e.content), 0);
 }
 // A pure read of the caller's recallHistory snapshot against this top-1. HIPPO_ANCHORING=off skips even the detect
 // call; CLI paths pass no history (cmdRecall computes its own hint), so the hint stays absent there.

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 '../search/embed-memories.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;
@@ -8,7 +23,8 @@ export interface RememberOpts {
     owner?: string;
     artifactRef?: string;
     tags?: string[];
-    /** The connector event this write answers. The store logs it in the memory's own transaction; an event logged before stores nothing and answers `duplicate`. */
+    /** The connector event this write answers. The store logs it in the memory's own transaction; an event logged before stores nothing and
+     * answers `duplicate`. */
     event?: ConnectorEvent;
     /** Connector-ingested content an agent doesn't control; gates detectInstruction. CLI/HTTP/MCP never set this. */
     untrusted?: boolean;
@@ -19,6 +35,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

@@ -7,7 +7,7 @@ import { loadConfig } from '../core/config.js';
 import { vetSecrets } from '../util/secret-detect.js';
 import { assertCallerProject } from '../core/project-identity.js';
 import { BadRequestError } from '../core/api-errors.js';
-import { assertClientScope, personalScopeOf } from '../store/recall-scope.js';
+import { assertClientScope, personalScopeOf } from '../core/recall-scope.js';
 import { andThen, notPorted, onStore } from './on-store.js';
 /** The scope a write lands in: the caller's own personal scope when asked for, else the client's, which may not be a personal one. */
 function rememberScope(ctx, opts) {
@@ -21,7 +21,8 @@ function rememberScope(ctx, opts) {
         throw new BadRequestError('send personal or scope, not both');
     const own = personalScopeOf(ctx.actor);
     if (own === null) {
-        throw new BadRequestError('personal memories need a key its owner minted, or a sign-in; owner ids over 239 characters or with control characters cannot hold them');
+        throw new BadRequestError('personal memories need a key its owner minted, or a sign-in; owner ids over 239 characters or with control characters cannot ' +
+            'hold them');
     }
     return own;
 }
@@ -31,7 +32,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 +49,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/session-end.d.ts

@@ -0,0 +1,22 @@
+import type { HandoffEvidence } from '../core/handoff.js';
+import type { TaskSnapshot } from '../store/rows.js';
+import type { Context } from './types.js';
+/** What closing one ended session needs from the host; the two readers run only when the handoff is written. */
+export interface SessionClose {
+    sessionId: string | null;
+    /** A reply's end, not the session's: the handoff is updated in place and the snapshot stays for the next compaction. */
+    turn: boolean;
+    /** The transcript's working state, or null with no readable transcript. */
+    workingState: () => Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null;
+    evidence: () => HandoffEvidence;
+    /** One line to the session-end log. */
+    log: (line: string) => void;
+}
+/** Writes the session's handoff, then closes its snapshot unless `turn`; each step logs its own failure and never throws.
+ *  The handoff goes first, while the snapshot writeSessionEndHandoff reads is still active. */
+export declare function closeEndedSession(ctx: Context, close: SessionClose): void;
+/** Books the ending session's re-reads in each store its ledger rows can land in (`ctx.hippoRoot` and global); returns the log lines. */
+export declare function bookSessionRereads(ctx: Context, transcriptPath: string | undefined, sessionId: string | null): Promise<string[]>;
+/** The block a compaction lost: the fresh task snapshot and its session trail, or null with none or another session's snapshot. */
+export declare function compactResumeBlock(ctx: Context, payloadSessionId: string | null): string | null;
+//# sourceMappingURL=session-end.d.ts.map

package/dist/api/session-end.js

@@ -0,0 +1,101 @@
+// The store writes a session's end makes after sleep and capture (handoff, snapshot close, re-read count), and the
+// compact-resume read; the hook verbs keep stdin, spawning and the log file.
+import * as path from 'path';
+import { isInitialized } from '../core/project-identity.js';
+import { closeTaskSnapshotsForSession, listSessionEvents, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot } from '../store/sessions.js';
+import { writeSessionEndHandoff } from '../store/handoffs.js';
+import { readApiCalls, recordRereads } from '../store/token-ledger.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { truncateCodePointSafe } from '../util/transcript-tail.js';
+import { errorMessage, log } from '../util/log.js';
+import { COMPACT_RESUME_EVENT_CONTENT_CAP, COMPACT_RESUME_MAX_AGE_MS, compactResumeText } from './context-render.js';
+/** Writes the session's handoff, then closes its snapshot unless `turn`; each step logs its own failure and never throws.
+ *  The handoff goes first, while the snapshot writeSessionEndHandoff reads is still active. */
+export function closeEndedSession(ctx, close) {
+    if (close.sessionId)
+        writeEndHandoff(ctx, close.sessionId, close);
+    if (close.turn) {
+        close.log('skip snapshot close: turn mode');
+        return;
+    }
+    closeSnapshot(ctx, close.sessionId, close.log);
+}
+function writeEndHandoff(ctx, sessionId, close) {
+    try {
+        const ownSnapshot = loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId)?.session_id === sessionId;
+        // A never-compacted session has no snapshot; read even when it has one, as another session's PreCompact can take the slot before the write.
+        const derived = close.workingState();
+        if (!ownSnapshot && !derived) {
+            close.log('skip: no snapshot or transcript for session');
+            return;
+        }
+        const handoff = writeSessionEndHandoff(ctx.hippoRoot, ctx.tenantId, sessionId, close.evidence(), derived, undefined, { inPlace: close.turn });
+        close.log(handoff ? `wrote handoff for session ${sessionId}` : `skip: kept the existing handoff for session ${sessionId}`);
+    }
+    catch (err) {
+        close.log(`handoff write failed: ${errorMessage(err)}`);
+    }
+}
+// If session-end never fires (crash, kill -9), the freshness bound in loadFreshActiveTaskSnapshot is the backstop.
+function closeSnapshot(ctx, sessionId, line) {
+    try {
+        if (sessionId) {
+            const closed = closeTaskSnapshotsForSession(ctx.hippoRoot, ctx.tenantId, sessionId);
+            line(`closed ${closed} active snapshot(s) for session ${sessionId}`);
+        }
+        else {
+            line('skip: no session_id in SessionEnd payload, active snapshot left untouched');
+        }
+    }
+    catch (err) {
+        line(`snapshot close failed: ${errorMessage(err)}`);
+    }
+}
+/** Books the ending session's re-reads in each store its ledger rows can land in (`ctx.hippoRoot` and global); returns the log lines. */
+export async function bookSessionRereads(ctx, transcriptPath, sessionId) {
+    if (!transcriptPath || !sessionId)
+        return [];
+    let read;
+    try {
+        read = await readApiCalls(transcriptPath);
+    }
+    catch (err) {
+        return [`skip re-read count: cannot read the transcript: ${errorMessage(err)}`];
+    }
+    const roots = new Set([ctx.hippoRoot, getGlobalRoot()].filter((root) => isInitialized(root)).map((root) => path.resolve(root)));
+    const lines = [];
+    let tokens = 0;
+    for (const root of roots) {
+        try {
+            tokens += recordRereads(root, ctx.tenantId, sessionId, read.calls);
+        }
+        catch (err) {
+            lines.push(`re-read count failed: ${errorMessage(err)}`);
+        }
+    }
+    const skipped = read.malformed > 0 ? `, ${read.malformed} unparsable transcript lines skipped` : '';
+    lines.push(`re-read ${tokens} tokens over ${read.calls.length} model calls for session ${sessionId}${skipped}`);
+    return lines;
+}
+/** The block a compaction lost: the fresh task snapshot and its session trail, or null with none or another session's snapshot. */
+export function compactResumeBlock(ctx, payloadSessionId) {
+    const snapshot = loadFreshActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, { maxAgeMs: COMPACT_RESUME_MAX_AGE_MS });
+    // Concurrent sessions must not cross-restore: only when both ids are present and differ, so a manual run with no payload id still prints.
+    if (!snapshot || (payloadSessionId !== null && snapshot.session_id !== null && payloadSessionId !== snapshot.session_id))
+        return null;
+    // A bad trail row costs the trail, not the snapshot; stderr stays out of the model's context.
+    let events = [];
+    try {
+        if (snapshot.session_id) {
+            events = listSessionEvents(ctx.hippoRoot, ctx.tenantId, { session_id: snapshot.session_id }).map((e) => ({
+                ...e,
+                content: truncateCodePointSafe(e.content, COMPACT_RESUME_EVENT_CONTENT_CAP),
+            }));
+        }
+    }
+    catch (err) {
+        log.warn(`hippo compact-resume: trail skipped: ${errorMessage(err)}`);
+    }
+    return compactResumeText(snapshot, events);
+}
+//# sourceMappingURL=session-end.js.map

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 { auditMemories } from '../core/memory-audit.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;