hippo-memory 1.70.0 → 1.72.0

package/dist/api/context-select.js

@@ -4,20 +4,20 @@ import { heldIdLookup } from '../store/entry-reads.js';
 import { calculateStrength } from '../core/memory.js';
 import { auditQueryFields, recordAuditEvent } from '../store/audit.js';
 import { isWorthSurfacing } from '../core/memory-quality.js';
-import { rankBothStores } from '../sharing/shared.js';
-import { evalNow } from '../core/ablation.js';
+import { rankBothStores } from '../sharing/search-both.js';
+import { evalNow, strengthAblation } from '../core/ablation.js';
 import { hybridSearch } from '../search/hybrid.js';
-import { physicsSearch } from '../search/physics-search.js';
+import { physicsSearchIn } from '../search/physics-search.js';
 import { DEFAULT_LOCAL_BUMP } from '../core/search-types.js';
 import { compareScoredResults } from '../core/compare.js';
-import { scopeMatch } from '../sharing/scope.js';
+import { scopeMatch } from '../core/active-scope.js';
 import { scopeBoostFor } from '../search/boosts.js';
 import { promptTokens, contentTokens, gatePromptRecall, } from '../core/prompt-recall.js';
 const GLOBAL_DISCOUNT = 1 / DEFAULT_LOCAL_BUMP;
 // Share and promote copy a memory to the global store under a new id, so equal content is the only link.
 // A pinned copy wins, then the stronger one after the ranking's own global discount; a tie keeps the local copy.
 export function oneCopyPerMemory(local, global, now) {
-    const score = (e, isGlobal) => calculateStrength(e, now) * (isGlobal ? GLOBAL_DISCOUNT : 1);
+    const score = (e, isGlobal) => calculateStrength(e, now, { ablation: strengthAblation() }) * (isGlobal ? GLOBAL_DISCOUNT : 1);
     const best = new Map();
     const offer = (entry, isGlobal) => {
         const held = best.get(entry.content);
@@ -51,9 +51,8 @@ export function selectPinned(opts, plan, left, pools, admission) {
     const [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, nowP);
     obs?.dropMissing([...localEntries, ...globalEntries], [...localPool, ...globalPool], 'load', 'duplicate');
     const picked = { items: [], ids: new Set(), used: 0 };
-    // Pinned entries are explicit user intent, the recent-N list an automatic
-    // backfill. Both loops share ONE budget and the recent loop runs first, so
-    // pins are ranked here and reserve their share before it can spend.
+    // Pinned entries are explicit intent, the recent-N list an automatic backfill; both share ONE budget and the recent loop runs first,
+    // so pins are ranked here and reserve their share before it can spend.
     const pinnedLocal = localPool.filter((e) => e.pinned);
     const pinnedGlobal = globalPool.filter((e) => e.pinned);
     const rankedPinned = rankPinned(plan, pinnedLocal, pinnedGlobal, nowP);
@@ -78,7 +77,7 @@ function rankPinned(plan, pinnedLocal, pinnedGlobal, nowP) {
         const scopeBoost = scopeBoostFor(scopeMatch(entry.tags, plan.activeScope));
         return {
             entry,
-            score: calculateStrength(entry, nowP) * (isGlobal ? GLOBAL_DISCOUNT : 1) * scopeBoost,
+            score: calculateStrength(entry, nowP, { ablation: strengthAblation() }) * (isGlobal ? GLOBAL_DISCOUNT : 1) * scopeBoost,
             tokens: plan.price(entry, isGlobal),
             isGlobal,
         };
@@ -201,7 +200,7 @@ function backfillRecent(plan, options) {
         .slice(0, plan.includeRecent)
         .map(({ entry, isGlobal }) => ({
         entry,
-        score: calculateStrength(entry, nowP) * (isGlobal ? GLOBAL_DISCOUNT : 1),
+        score: calculateStrength(entry, nowP, { ablation: strengthAblation() }) * (isGlobal ? GLOBAL_DISCOUNT : 1),
         tokens: plan.price(entry, isGlobal),
         isGlobal,
     }));
@@ -214,7 +213,7 @@ export function selectStrongest(plan, left, pools) {
     const localRanked = localPool
         .map((e) => ({
         entry: e,
-        score: calculateStrength(e, now),
+        score: calculateStrength(e, now, { ablation: strengthAblation() }),
         tokens: plan.price(e, plan.primaryIsGlobal),
         isGlobal: plan.primaryIsGlobal,
     }))
@@ -222,7 +221,7 @@ export function selectStrongest(plan, left, pools) {
     const globalRanked = globalPool
         .map((e) => ({
         entry: e,
-        score: calculateStrength(e, now) * GLOBAL_DISCOUNT,
+        score: calculateStrength(e, now, { ablation: strengthAblation() }) * GLOBAL_DISCOUNT,
         tokens: plan.price(e, true),
         isGlobal: true,
     }))
@@ -281,15 +280,13 @@ async function searchLocalRows(ctx, plan, options) {
     const vectorCandidates = contextVectorSpec(ctx, plan, admit);
     const store = plan.local.store;
     const ctxResults = usePhysicsCtx
-        ? await physicsSearch(query, localEntries, {
+        ? await physicsSearchIn({ root: ctx.hippoRoot, store }, query, localEntries, {
             budget: left,
             minResults,
             cost: localCost,
-            hippoRoot: ctx.hippoRoot,
             physicsConfig: ctxConfig.physics,
             scope: plan.activeScope,
             vectorCandidates,
-            store,
         })
         : await hybridSearch(query, localEntries, {
             budget: left,

package/dist/api/context-types.d.ts

@@ -4,17 +4,8 @@ import type { MemoryEntry } from '../core/memory.js';
 import type { DeliveryObserver } from '../store/delivery-recorder.js';
 import type { AmbientState } from '../core/ambient.js';
 import type { ProjectRef } from '../core/project-identity.js';
-/**
- * Options for `getContext` — assemble a budget-bounded context bundle
- * (recalled memories + active task snapshot + handoff + recent events).
- *
- * Named `getContext` (not `context`) to avoid collision with the `Context`
- * interface above and the ubiquitous `ctx: Context` convention. Follows the
- * existing `getEntry` naming pattern in store.ts.
- *
- * Rendering opts (`format`, `framing`, `rendered`) and host-side opts (`auto`) stay in the CLI,
- * because its print helpers are shared with `cmdRecall` / `cmdSnapshot` / `cmdHandoffShow`.
- */
+/** Options for `getContext`: a budget-bounded bundle of recalled memories, active task snapshot, handoff and recent events.
+ * Rendering opts (`format`, `framing`, `rendered`) and host-side opts (`auto`) stay in the CLI, whose print helpers are shared. */
 export interface ContextOpts {
     q?: string;
     /** Default 1500 tokens. */
@@ -24,30 +15,16 @@ export interface ContextOpts {
     scope?: string;
     /** Envelope scope to match exactly, as in `recall`: admits that scope even when private, after the actor's scope check. */
     exactScope?: string;
-    /** With `pinnedOnly`, also inject the N most recent writes that pass the
-     *  quality floor (`isWorthSurfacing`). Filtering happens BEFORE
-     *  the take-N, so a caller asking for 5 gets 5 qualifying entries rather
-     *  than 5-minus-junk; pinned entries bypass the floor. Entries are only
-     *  skipped for this read, never mutated or deleted. Ignored when
-     *  `pinnedOnly` is false — no other path reads it. */
+    /** With `pinnedOnly`, also inject the N most recent writes that pass the quality floor (`isWorthSurfacing`); pinned entries bypass it.
+     *  Filtering happens BEFORE the take-N, so asking for 5 gets 5 qualifying entries. Ignored when `pinnedOnly` is false. */
     includeRecent?: number;
-    /** v39 memory scope isolation: re-include other-project memories that the
-     *  origin partition excludes by default. They come back tagged
-     *  `category: 'cross-project'` so renderers can demarcate them. */
+    /** Re-include other-project memories the origin partition excludes by default; they come back tagged `category: 'cross-project'`. */
     crossProject?: boolean;
-    /** The active project for the origin partition ('' = not in a project): a
-     *  name, or an identity whose rows may also carry its legacy folder name.
-     *  Defaults to `resolveProjectIdentity(process.cwd())`; surfaces whose
-     *  process cwd is not the caller's project (HTTP server) should pass it. */
+    /** The active project for the origin partition ('' = not in a project): a name, or an identity whose rows may carry its legacy folder name.
+     *  Defaults to `resolveProjectIdentity(process.cwd())`; surfaces whose cwd is not the caller's project (HTTP server) should pass it. */
     currentProject?: ProjectRef;
-    /** The calling
-     *  session's id. Stamped on this call's recall trace, and the owner-match input to
-     *  `loadFreshActiveTaskSnapshot` — when it strictly equals the active
-     *  snapshot's `session_id`, the read is unbounded (same-session
-     *  continuity); otherwise the snapshot must pass the freshness bound to
-     *  surface. Absent (undefined/null/'') never short-circuits as a match;
-     *  it just means every snapshot goes through the age check. Host-resolved
-     *  (stdin payload, HIPPO_SESSION_ID, else the host's session var) so this stays host-agnostic. */
+    /** The calling session's id, stamped on this call's recall trace. When it strictly equals the active snapshot's `session_id` the read is unbounded;
+     *  otherwise the snapshot must pass the freshness bound. Absent (undefined/null/'') never matches. Host-resolved, so this stays host-agnostic. */
     currentSessionId?: string | null;
     /** Raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
     prompt?: string;
@@ -83,9 +60,7 @@ export interface ContextResultEntry {
     promptRecall?: boolean;
     /** v39: the entry's owning project ('' = user-global, null = legacy row). */
     origin?: string | null;
-    /** v39: how the origin relates to the active project. 'cross-project'
-     *  entries only appear when ContextOpts.crossProject was set (or isolation
-     *  is disabled). */
+    /** How the origin relates to the active project; 'cross-project' appears only when `crossProject` was set (or isolation is disabled). */
     category?: 'project' | 'user-global' | 'cross-project';
 }
 export interface ContextResult {

package/dist/api/context.d.ts

@@ -3,28 +3,11 @@ import { type ProjectRef } from '../core/project-identity.js';
 import type { ContextOpts, ContextResult } from './context-types.js';
 import { type Context } from './types.js';
 export { oneCopyPerMemory } from './context-select.js';
-/**
- * The secret half of the ambient policy on its own, for callers
- * that apply their own scope rule. A flagged row is only admitted inside its owning project;
- * flagged rows with no project origin never ambient-inject.
- */
+/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only inside its owning project. */
 export declare function ambientSecretAdmit(e: MemoryEntry, currentProject: ProjectRef): boolean;
-/**
- * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
- * fallback / hybrid search) + active task snapshot + session handoff + recent
- * session events. Budget-bounded, tenant-scoped. Mutates `last_retrieval_ids`
- * + emits a 'recall' audit row for non-pinned, non-'*' queries.
- *
- * Behaves like the pre-extraction `cmdContext` data-loading + selection
- * pipeline. CLI presentation (markdown / json / additional-context rendering)
- * stays in `cli.ts`.
- *
- * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
- * `ctx.tenantId`. Cross-tenant rows are filtered out.
- *
- * @returns An empty result (`entries: []`, snapshot/handoff/events undefined)
- * when there's nothing to surface (no memories AND no snapshot AND no handoff
- * AND no recent events).
- */
+/** Tokens a context block may use when the caller sets no budget; the hook command and the CLI default match it. */
+export declare const DEFAULT_CONTEXT_BUDGET = 1500;
+/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit row for non-pinned, non-'*' queries.
+ * Returns an empty result when there are no memories, snapshot, handoff or recent events. CLI rendering stays in `cli.ts`. */
 export declare function getContext(ctx: Context, opts?: ContextOpts): Promise<ContextResult>;
 //# sourceMappingURL=context.d.ts.map

package/dist/api/context.js

@@ -1,42 +1,30 @@
 // Ambient context injection: the admission policy and getContext.
-import { isInitialized } from '../store/open.js';
 import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
 import { freshActiveSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessions.js';
 import { estimateTokens } from '../util/token-text.js';
 import { markRetrieved, COMPACTION_MEMORY_TAG } from '../core/memory.js';
 import { isWorthSurfacing } from '../core/memory-quality.js';
-import { getGlobalRoot } from '../sharing/shared.js';
-import { evalNow } from '../core/ablation.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { evalNow, strengthAblation } from '../core/ablation.js';
 import { dropHeldCopies } from '../util/same-text.js';
 import { BadRequestError } from '../core/api-errors.js';
 import { isSharedStore, loadConfig } from '../core/config.js';
-import { rethrowIfSqliteBlocked } from '../db/index.js';
+import { rethrowIfSqliteBlocked } from '../util/sqlite-blocked.js';
 import { errorMessage, log } from '../util/log.js';
-import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot, projectId, projectNames } from '../core/project-identity.js';
+import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot, isInitialized, projectId, projectNames, } from '../core/project-identity.js';
 import { promptTokens } from '../core/prompt-recall.js';
 import { detectSecret } from '../util/secret-detect.js';
 import { isSessionDigestRow } from '../core/session-digest-row.js';
 import { addAmbientTallies, ambientStateFromTallies } from '../core/ambient.js';
 import { requireGroup, sqliteStore, storeFor } from '../store/index.js';
-import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../store/recall-scope.js';
+import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../core/recall-scope.js';
 import { finiteOr, selectBySearch, selectPinned, selectStrongest, } from './context-select.js';
 import { andThen, onStore } from './on-store.js';
 import { strengthenOf } from './recall-record.js';
 import { ownerOrSubject } from './types.js';
 export { oneCopyPerMemory } from './context-select.js';
-/**
- * v39: the single ambient-injection admission policy, shared by getContext
- * and the CLI-side ambient-state summary so the two cannot drift.
- *
- * - Secret veto is UNCONDITIONAL: neither crossProject nor
- *   contextProjectIsolation:false re-includes secrets. A flagged row only
- *   injects inside its owning project; flagged rows with no project origin
- *   (''/null) never ambient-inject at all. Explicit recall is unaffected -
- *   recalling a secret is a deliberate act.
- * - Envelope parity: private/quarantine scopes never inject unless `exactScope` names one.
- * - Origin partition: other-project rows are excluded unless
- *   `includeCrossProject`.
- */
+/** The single ambient-injection admission policy, shared by getContext and the CLI ambient-state summary so they cannot drift.
+ * Secret veto is unconditional (flagged rows inject only in their own project); private scopes need `exactScope`, other projects `includeCrossProject`. */
 function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, own) {
     if (!ambientSecretAdmit(e, currentProject))
         return false;
@@ -46,11 +34,7 @@ function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, o
         return true;
     return classifyOriginProject(e.origin_project, currentProject) !== 'cross-project';
 }
-/**
- * The secret half of the ambient policy on its own, for callers
- * that apply their own scope rule. A flagged row is only admitted inside its owning project;
- * flagged rows with no project origin never ambient-inject.
- */
+/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only inside its owning project. */
 export function ambientSecretAdmit(e, currentProject) {
     if (!detectSecret(e).flagged)
         return true;
@@ -59,6 +43,8 @@ export function ambientSecretAdmit(e, currentProject) {
         return false;
     return projectNames(currentProject).includes(origin);
 }
+/** Tokens a context block may use when the caller sets no budget; the hook command and the CLI default match it. */
+export const DEFAULT_CONTEXT_BUDGET = 1500;
 /** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
 const CONTEXT_CANDIDATE_CAP = 2000;
 /** A store's base search and context reads; a store without the group throws StoreNotPortedError. */
@@ -98,25 +84,10 @@ async function loadAmbientEntries(source, tenantId, options) {
     const entries = loaded.entries.filter((e) => ownTenant(e) && recheck(e));
     return loaded.recall ? { entries, recall: loaded.recall.filter(ownTenant) } : { entries };
 }
-/**
- * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
- * fallback / hybrid search) + active task snapshot + session handoff + recent
- * session events. Budget-bounded, tenant-scoped. Mutates `last_retrieval_ids`
- * + emits a 'recall' audit row for non-pinned, non-'*' queries.
- *
- * Behaves like the pre-extraction `cmdContext` data-loading + selection
- * pipeline. CLI presentation (markdown / json / additional-context rendering)
- * stays in `cli.ts`.
- *
- * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
- * `ctx.tenantId`. Cross-tenant rows are filtered out.
- *
- * @returns An empty result (`entries: []`, snapshot/handoff/events undefined)
- * when there's nothing to surface (no memories AND no snapshot AND no handoff
- * AND no recent events).
- */
+/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit row for non-pinned, non-'*' queries.
+ * Returns an empty result when there are no memories, snapshot, handoff or recent events. CLI rendering stays in `cli.ts`. */
 export async function getContext(ctx, opts = {}) {
-    const budget = opts.budget ?? 1500;
+    const budget = opts.budget ?? DEFAULT_CONTEXT_BUDGET;
     assertScopeRequestAllowed(ctx.actor, opts.exactScope);
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
@@ -247,8 +218,14 @@ function openBlockBudget(plan, opts, budget) {
     obs?.facts({ projectName: projectId(plan.currentProject), budgetTokens: blockBudget, promptRecall: promptRecallPending });
     if (pinnedOnly && !config.pinnedInject.enabled)
         obs?.disabled();
+    if (!pinnedOnly)
+        obs?.queried(plan.query);
     return cost
-        ? Math.max(0, blockBudget - cost.fixed(blockBudget, { cross: plan.includeCrossProject, promptRecall: promptRecallPending, ambient: !pinnedOnly && config.ambient.enabled }))
+        ? Math.max(0, blockBudget - cost.fixed(blockBudget, {
+            cross: plan.includeCrossProject,
+            promptRecall: promptRecallPending,
+            ambient: !pinnedOnly && config.ambient.enabled,
+        }))
         : blockBudget;
 }
 const NO_TASK_STATE = { snapshot: null, handoff: null, events: [] };
@@ -348,6 +325,12 @@ async function loadPools(ctx, plan, admission, recallRequest) {
 /** The `limit` cut, then the held-copy drop, then each entry's origin annotation. */
 function finalizeSelection(picked, plan) {
     const { obs } = plan;
+    // Ranking reports nothing itself, so its results are offered here and the cuts below can name what they drop.
+    if (!plan.pinnedOnly && obs) {
+        const pool = plan.query === '*' ? 'strength' : 'search';
+        obs.offer(picked.filter((r) => r.isGlobal !== true).map((r) => r.entry), false, pool);
+        obs.offer(picked.filter((r) => r.isGlobal === true).map((r) => r.entry), true, pool);
+    }
     let selected = picked;
     if (plan.limit < selected.length) {
         const cut = selected.slice(0, plan.limit);
@@ -390,7 +373,7 @@ async function traceEmptyContext(ctx, opts, plan) {
 /** Strengthens and marks the returned rows, then writes the trace and index together. */
 async function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
     const toUpdate = selected.map((s) => s.entry);
-    const updatedEntries = markRetrieved(toUpdate);
+    const updatedEntries = markRetrieved(toUpdate, undefined, { ablation: strengthAblation() });
     const retrievedIds = updatedEntries.map((u) => u.id);
     const trace = {
         tenantId: ctx.tenantId,
@@ -405,7 +388,10 @@ async function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
     };
     const writes = { goalLog: [], audit: [], trace, strengthen: strengthenOf(ctx, retrievedIds) };
     // hippo.db keeps the ids as its last recall, which feeds only outcomeForLastRecall, and it alone reads a second root.
-    await onStore(ctx, (port, local) => andThen(local.finishLastRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined), () => port.bumpRecallStats(selected.length)));
+    await onStore(ctx, (port, local) => andThen(local.finishLastRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined), (traceId) => {
+        plan.obs?.traced(traceId);
+        return port.bumpRecallStats(selected.length);
+    }));
     // Replace selectedItems entries with markRetrieved-updated copies so
     // the returned ContextResult reflects post-recall state.
     const items = selected.map((s) => ({
@@ -416,7 +402,13 @@ async function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
     return { items, ambientState: plan.config.ambient.enabled ? await readAmbientState(ctx, plan) : undefined };
 }
 async function readAmbientState(ctx, plan) {
-    const filter = { exactScope: plan.exactScope, ownScope: plan.ownScope, project: plan.originProject, currentProject: projectNames(plan.currentProject), now: evalNow() };
+    const filter = {
+        exactScope: plan.exactScope,
+        ownScope: plan.ownScope,
+        project: plan.originProject,
+        currentProject: projectNames(plan.currentProject),
+        now: evalNow(),
+    };
     const sources = [
         ...(plan.hasLocal ? [plan.local.reads] : []),
         ...(plan.hasGlobal && !plan.primaryIsGlobal ? [sourceOf(sqliteStore(plan.globalRoot)).reads] : []),

package/dist/api/continuity.d.ts

@@ -0,0 +1,47 @@
+import type { HandoffOutcome, SessionHandoff } from '../core/handoff.js';
+import type { SessionEvent, TaskSnapshot } from '../store/rows.js';
+import { appendSessionEvent, listSessionEvents, saveActiveTaskSnapshot } from '../store/sessions.js';
+import { wmClear, wmFlush, wmPush, wmRead, type WorkingMemoryItem } from '../store/working-memory.js';
+import type { Context } from './types.js';
+/** What a snapshot save carries. */
+export type SnapshotSaveInput = Parameters<typeof saveActiveTaskSnapshot>[2];
+/** What a session event append carries. */
+export type SessionEventAppendInput = Parameters<typeof appendSessionEvent>[2];
+/** What a session event listing filters on. */
+export type SessionEventListOpts = NonNullable<Parameters<typeof listSessionEvents>[2]>;
+/** Save the caller's active task snapshot. */
+export declare function snapshotSave(ctx: Context, input: SnapshotSaveInput): TaskSnapshot;
+/** Clear the caller's active task snapshot; false when there was none. */
+export declare function snapshotClear(ctx: Context, status: string): boolean;
+/** The caller's active task snapshot, or null. */
+export declare function snapshotLoad(ctx: Context): TaskSnapshot | null;
+/** Append a session event in the caller's tenant. */
+export declare function sessionEventAppend(ctx: Context, event: SessionEventAppendInput): SessionEvent;
+/** List the caller's session events. */
+export declare function sessionEventList(ctx: Context, opts: SessionEventListOpts): SessionEvent[];
+export interface LatestContinuity {
+    snapshot: TaskSnapshot | null;
+    events: SessionEvent[];
+}
+/** The active snapshot plus recent events for `sessionId`, falling back to the snapshot's own session. */
+export declare function continuityLatest(ctx: Context, opts: {
+    sessionId?: string;
+    limit: number;
+}): LatestContinuity;
+/** Stamp the outcome on the caller's handoff for `sessionId`; returns the rows stamped. */
+export declare function handoffStampOutcome(ctx: Context, sessionId: string, outcome: HandoffOutcome): number;
+/** Save a session handoff in the caller's tenant. */
+export declare function handoffSave(ctx: Context, handoff: Omit<SessionHandoff, 'updatedAt'>): SessionHandoff;
+/** The caller's latest handoff, optionally for one session. */
+export declare function handoffLatest(ctx: Context, sessionId?: string): SessionHandoff | null;
+/** The caller's handoff by id, or null. */
+export declare function handoffById(ctx: Context, id: number): SessionHandoff | null;
+/** Push a working memory entry in the caller's tenant; returns its row id. */
+export declare function workingMemoryPush(ctx: Context, opts: Omit<Parameters<typeof wmPush>[1], 'tenantId'>): number;
+/** The caller's working memory entries, most important first. */
+export declare function workingMemoryRead(ctx: Context, opts: Omit<NonNullable<Parameters<typeof wmRead>[1]>, 'tenantId'>): WorkingMemoryItem[];
+/** Delete the caller's working memory entries; returns the count. */
+export declare function workingMemoryClear(ctx: Context, opts: Omit<NonNullable<Parameters<typeof wmClear>[1]>, 'tenantId'>): number;
+/** Flush the caller's working memory at session end; returns the count. */
+export declare function workingMemoryFlush(ctx: Context, opts: Omit<NonNullable<Parameters<typeof wmFlush>[1]>, 'tenantId'>): number;
+//# sourceMappingURL=continuity.d.ts.map

package/dist/api/continuity.js

@@ -0,0 +1,66 @@
+// Where-you-left-off ops: task snapshot, session events, handoffs and working memory.
+import { appendSessionEvent, clearActiveTaskSnapshot, listSessionEvents, loadActiveTaskSnapshot, saveActiveTaskSnapshot, } from '../store/sessions.js';
+import { loadHandoffById, loadLatestHandoff, saveSessionHandoff, stampHandoffOutcome } from '../store/handoffs.js';
+import { wmClear, wmFlush, wmPush, wmRead } from '../store/working-memory.js';
+/** Save the caller's active task snapshot. */
+export function snapshotSave(ctx, input) {
+    return saveActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, input);
+}
+/** Clear the caller's active task snapshot; false when there was none. */
+export function snapshotClear(ctx, status) {
+    return clearActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, status);
+}
+/** The caller's active task snapshot, or null. */
+export function snapshotLoad(ctx) {
+    return loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId);
+}
+/** Append a session event in the caller's tenant. */
+export function sessionEventAppend(ctx, event) {
+    return appendSessionEvent(ctx.hippoRoot, ctx.tenantId, event);
+}
+/** List the caller's session events. */
+export function sessionEventList(ctx, opts) {
+    return listSessionEvents(ctx.hippoRoot, ctx.tenantId, opts);
+}
+/** The active snapshot plus recent events for `sessionId`, falling back to the snapshot's own session. */
+export function continuityLatest(ctx, opts) {
+    const snapshot = loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId);
+    const events = listSessionEvents(ctx.hippoRoot, ctx.tenantId, {
+        session_id: opts.sessionId || snapshot?.session_id || undefined,
+        limit: opts.limit,
+    });
+    return { snapshot, events };
+}
+/** Stamp the outcome on the caller's handoff for `sessionId`; returns the rows stamped. */
+export function handoffStampOutcome(ctx, sessionId, outcome) {
+    return stampHandoffOutcome(ctx.hippoRoot, ctx.tenantId, sessionId, outcome);
+}
+/** Save a session handoff in the caller's tenant. */
+export function handoffSave(ctx, handoff) {
+    return saveSessionHandoff(ctx.hippoRoot, ctx.tenantId, handoff);
+}
+/** The caller's latest handoff, optionally for one session. */
+export function handoffLatest(ctx, sessionId) {
+    return loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, sessionId);
+}
+/** The caller's handoff by id, or null. */
+export function handoffById(ctx, id) {
+    return loadHandoffById(ctx.hippoRoot, ctx.tenantId, id);
+}
+/** Push a working memory entry in the caller's tenant; returns its row id. */
+export function workingMemoryPush(ctx, opts) {
+    return wmPush(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+}
+/** The caller's working memory entries, most important first. */
+export function workingMemoryRead(ctx, opts) {
+    return wmRead(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+}
+/** Delete the caller's working memory entries; returns the count. */
+export function workingMemoryClear(ctx, opts) {
+    return wmClear(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+}
+/** Flush the caller's working memory at session end; returns the count. */
+export function workingMemoryFlush(ctx, opts) {
+    return wmFlush(ctx.hippoRoot, { ...opts, tenantId: ctx.tenantId });
+}
+//# sourceMappingURL=continuity.js.map

package/dist/{cli → api}/correction-latency.d.ts

@@ -18,19 +18,7 @@ export interface CorrectionLatencyReport {
     maxMs: number | null;
     pairs: CorrectionPair[];
 }
-/**
- * Correction latency = wall-clock delta between when hippo first saw the
- * change-of-truth and when the supersession actually landed.
- *
- * For each (old, new) chain via `old.superseded_by = new.id`:
- *   - `correctedAt` = `new.created` (always)
- *   - `observedAt`  = source row's `created` if `new.extracted_from` is set,
- *                     else `new.created` (no earlier observation possible)
- *
- * Pairs split into two cohorts:
- *   - `extraction` — derived from a raw receipt; latency is meaningful
- *   - `manual`     — direct supersede call; latency is trivially 0 and
- *                    excluded from percentiles to avoid masking real lag
- */
+/** Correction latency = `new.created` minus the observation time (the extracted-from row's `created`, else `new.created`).
+ * Manual supersedes have latency 0 and are excluded from percentiles so they do not mask real lag. */
 export declare function buildCorrectionLatency(entries: MemoryEntry[]): CorrectionLatencyReport;
 //# sourceMappingURL=correction-latency.d.ts.map

package/dist/{cli → api}/correction-latency.js

@@ -10,20 +10,8 @@ function percentile(sorted, q) {
         return sorted[lo];
     return sorted[lo] + (sorted[hi] - sorted[lo]) * (idx - lo);
 }
-/**
- * Correction latency = wall-clock delta between when hippo first saw the
- * change-of-truth and when the supersession actually landed.
- *
- * For each (old, new) chain via `old.superseded_by = new.id`:
- *   - `correctedAt` = `new.created` (always)
- *   - `observedAt`  = source row's `created` if `new.extracted_from` is set,
- *                     else `new.created` (no earlier observation possible)
- *
- * Pairs split into two cohorts:
- *   - `extraction` — derived from a raw receipt; latency is meaningful
- *   - `manual`     — direct supersede call; latency is trivially 0 and
- *                    excluded from percentiles to avoid masking real lag
- */
+/** Correction latency = `new.created` minus the observation time (the extracted-from row's `created`, else `new.created`).
+ * Manual supersedes have latency 0 and are excluded from percentiles so they do not mask real lag. */
 export function buildCorrectionLatency(entries) {
     const byId = new Map();
     for (const e of entries)

package/dist/api/dormant.d.ts

@@ -1,29 +1,13 @@
 import { type DormantMemory, type ListDormantOpts } from '../store/dormant.js';
 import { type MemoryEntry } from '../core/memory.js';
 import type { Context } from './types.js';
-/**
- * A tenant's dormant memories (src/store/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).
- */
+/** A tenant's dormant memories (src/store/dormant.ts): what sleep moved out of active memory when `dormant.enabled` is on. Newest first;
+ * `opts.query` keeps rows containing every term (case-insensitive). */
 export declare function listDormant(ctx: Context, opts?: ListDormantOpts): DormantMemory[];
-/**
- * Bring a dormant memory back into active memory. It returns as if just
- * recalled, with a full half-life. A row audit repair set aside returns
- * `verified`, so no quality check judges it 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, or another person's personal row, 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.
- */
+/** Restores a dormant memory as if just recalled, with a full half-life; a row set aside by audit repair returns `verified`.
+ * Throws if the tenant has no such dormant id or a live memory holds it, and RejectedValueError if the value was since rejected (the dormant copy stays). */
 export declare function restoreDormant(ctx: Context, id: string): MemoryEntry;
-/**
- * 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.
- */
+/** Permanently deletes a dormant memory, the explicit "forget it for good"; throws when the tenant has no dormant memory with that id. */
 export declare function forgetDormant(ctx: Context, id: string): void;
 /** Whether the tenant holds a dormant memory with this id that the caller may touch (for "not found" hints). */
 export declare function isDormant(ctx: Context, id: string): boolean;

package/dist/api/dormant.js

@@ -3,29 +3,19 @@ import { ConflictError, NotFoundError } from '../core/api-errors.js';
 import { stampOriginProject } from '../store/entry-row.js';
 import { updateStatsUnlessBusy } from '../store/index-and-stats.js';
 import { loadDormantMemories, holdsDormantMemory, restoreDormantMemory, forgetDormantMemory, } from '../store/dormant.js';
+import { strengthAblation } from '../core/ablation.js';
 import { createMemory, calculateStrength } from '../core/memory.js';
 import { loadConfig } from '../core/config.js';
-import { canTouchScope, personalScopeOf, touchableScopeSql } from '../store/recall-scope.js';
+import { canTouchScope, personalScopeOf } from '../core/recall-scope.js';
+import { touchableScopeSql } from '../store/rule-sql.js';
 const touchable = (ctx) => touchableScopeSql('', personalScopeOf(ctx.actor));
-/**
- * A tenant's dormant memories (src/store/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).
- */
+/** A tenant's dormant memories (src/store/dormant.ts): what sleep moved out of active memory when `dormant.enabled` is on. Newest first;
+ * `opts.query` keeps rows containing every term (case-insensitive). */
 export function listDormant(ctx, opts = {}) {
     return loadDormantMemories(ctx.hippoRoot, ctx.tenantId, opts, touchable(ctx));
 }
-/**
- * Bring a dormant memory back into active memory. It returns as if just
- * recalled, with a full half-life. A row audit repair set aside returns
- * `verified`, so no quality check judges it 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, or another person's personal row, 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.
- */
+/** Restores a dormant memory as if just recalled, with a full half-life; a row set aside by audit repair returns `verified`.
+ * Throws if the tenant has no such dormant id or a live memory holds it, and RejectedValueError if the value was since rejected (the dormant copy stays). */
 export function restoreDormant(ctx, id) {
     const outcome = restoreDormantMemory(ctx.hippoRoot, {
         tenantId: ctx.tenantId,
@@ -42,11 +32,8 @@ export function restoreDormant(ctx, id) {
     return outcome.entry;
 }
 function reviveSnapshot(ctx, dormant, now) {
-    // 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.)
+    // A snapshot can predate a field added later: createMemory supplies defaults, then the snapshot overrides every field it carries.
+    // The placeholder content only meets createMemory's minimum length, so a legacy row under 3 chars still restores.
     const revived = {
         ...createMemory('dormant snapshot defaults', { baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays }),
         ...dormant.entry,
@@ -54,13 +41,9 @@ function reviveSnapshot(ctx, dormant, now) {
     };
     if (dormant.reason === 'quality-repair')
         revived.confidence = 'verified';
-    return stampOriginProject(ctx.hippoRoot, { ...revived, strength: calculateStrength(revived, now) });
+    return stampOriginProject(ctx.hippoRoot, { ...revived, strength: calculateStrength(revived, now, { ablation: strengthAblation() }) });
 }
-/**
- * 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.
- */
+/** Permanently deletes a dormant memory, the explicit "forget it for good"; throws when the tenant has no dormant memory with that id. */
 export function forgetDormant(ctx, id) {
     const forgotten = forgetDormantMemory(ctx.hippoRoot, { tenantId: ctx.tenantId, id, actor: ctx.actor.subject, admit: touchable(ctx) });
     if (!forgotten)