hippo-memory 1.69.0 → 1.71.0

package/dist/api/recall.js

@@ -1,68 +1,40 @@
 // Read path: recall (sync) and retrieve (async, adds the vector arm).
-import { envRequireSessionScopedFreshTail } from '../env.js';
+import { envRequireSessionScopedFreshTail } from '../util/env.js';
 import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
-import { isRecallBoostAblated } from '../ablation.js';
-import { loadEntriesByIds, loadFreshRawMemories } from '../store/entry-reads.js';
-import { loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
-import { estimateTokens } from '../token-ledger.js';
-import { formatHandoffEvidenceLine } from '../handoff.js';
-import { activeGoalsWithPolicies, boostByGoals } from '../goals.js';
-import { continuityAt, finishRecallAt, storeFor } from '../store-port.js';
+import { recallScopeFilter } from '../store/search-rows.js';
+import { estimateTokens } from '../util/token-text.js';
+import { formatHandoffEvidenceLine } from '../core/handoff.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';
-import { compareEntryIdentity } from '../compare.js';
-import { dropHeldCopies, duplicateKey, storedTextKeys } from '../same-text.js';
-import { isSharedStore, loadConfig } from '../config.js';
-import { classifyOriginProject, projectNames } from '../project-identity.js';
-import { decidePlanningFallacy, detectPlanningClaim, planningFallacyEvidenceAt } from '../predictions/planning-fallacy.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled } from '../recall-history.js';
-import { detectAvailabilityBias } from '../availability.js';
-import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../recall-scope.js';
+import { compareEntryIdentity } from '../core/compare.js';
+import { dropHeldCopies, duplicateKey, storedTextKeys } from '../util/same-text.js';
+import { isSharedStore, loadConfig } from '../core/config.js';
+import { classifyOriginProject, projectNames } from '../core/project-identity.js';
+import { decidePlanningFallacy, detectPlanningClaim } from '../predictions/planning-fallacy.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, recallAuditMetadata, recallAuditRow } from './recall-record.js';
-/**
- * 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`.
- */
+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;
+/** 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, 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) {
@@ -71,29 +43,60 @@ function recallOrigin(opts) {
 function inCallerProject(entry, opts) {
     return !opts.project || classifyOriginProject(entry.origin_project, opts.project) !== 'cross-project';
 }
-/** Mode-aware recall through the served store that strengthens each returned row; never 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)
+        return retrieveWithCliCore(ctx, opts, opts.cliCore);
     const windowSize = recallWindowSize(opts);
     // From the authenticated actor, never from RecallOpts, which a caller fills in.
     const own = personalScopeOf(ctx.actor) ?? undefined;
     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, candidates, plan, await readRecall(store, ctx, opts, plan));
-    await store.finishRecall({ ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit], strengthen: strengthenOf(ctx, result.results.map((r) => r.id)) });
+    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))
+    });
     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 {
@@ -106,9 +109,6 @@ function recallSearchArgs(ctx, opts, limit, own) {
         ownScope: own,
     };
 }
-function strengthenOf(ctx, ids) {
-    return { ids, opts: { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() } };
-}
 /** api.retrieve's vector arm: the recall load's exact-scope rule, current rows only. */
 function recallVectorSpec(ctx, opts, own) {
     return {
@@ -128,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 = [];
@@ -142,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, window, plan, await readRecall(store, ctx, bandOpts, plan, goals), 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))];
@@ -187,7 +187,7 @@ function recallWindowSize(opts) {
 }
 const CONTINUITY_EVENT_LIMIT = 5;
 function planRecall(ctx, opts, all, own) {
-    const limit = opts.limit ?? 10;
+    const limit = opts.limit ?? DEFAULT_RECALL_LIMIT;
     const window = admitCandidates(opts, all, limit, own);
     return {
         limit,
@@ -198,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. */
@@ -228,9 +228,8 @@ function continuityKey(ctx, opts) {
         return null;
     return { owner: ownerOrSubject(ctx.actor), project: opts.project ? projectNames(opts.project) : [] };
 }
-/** The reply and the rows it writes, from the candidates and the plan's reads; touches no store.
- *  `auditBand` false: the caller shows a cut of the band and audits the rows it shows. */
-function composeRecall(ctx, opts, windowSize, all, plan, reads, auditBand = true) {
+function composeRecall(ctx, opts, options) {
+    const { windowSize, all, plan, reads, auditBand = true } = options;
     const { window } = plan;
     const bands = rankBands(opts, plan, reads);
     const rankedOut = bands.rankedOut;
@@ -246,14 +245,14 @@ function composeRecall(ctx, opts, windowSize, all, plan, reads, auditBand = true
         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)
@@ -319,7 +318,9 @@ function rankBands(opts, plan, reads) {
     const baseRanked = baseScored.map((r) => baseItem(r, opts, explainTrace));
     const summaryRanked = substituted.map((s) => summaryItem(s, opts));
     const freshRanked = (opts.freshTailCount ?? 0) > 0
-        ? freshTailBand(opts, reads.freshRaws, baseRanked, summaryRanked, opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)], own)
+        ? freshTailBand(opts, {
+            recent: reads.freshRaws, baseRanked, summaryRanked, shownEntries: opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)], own,
+        })
         : [];
     return {
         rankedOut: [...freshRanked, ...baseRanked, ...summaryRanked],
@@ -334,7 +335,7 @@ function rankBands(opts, plan, reads) {
 // `limit`. Each one is tenant-scoped and re-checked against the scope filter; drillDown recovers the children.
 function substituteOverflow(opts, overflowByParent, parents, limit, own) {
     const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by && passesScopeFilterForRecall(p.scope ?? null, opts.scope, own) && inCallerProject(p, opts));
-    const maxSub = Math.max(1, Math.ceil(limit * 0.3));
+    const maxSub = Math.max(1, Math.ceil(limit * SUMMARY_SUB_FRACTION));
     // Most overflowed children first; compareEntryIdentity only breaks a tie, which used to fall to scan order.
     eligibleParents.sort((a, b) => {
         const ac = overflowByParent.get(a.id)?.length ?? 0;
@@ -380,12 +381,16 @@ function baseItem(r, opts, explainTrace) {
     }
     return item;
 }
-// Score 0.5 keeps a summary below the strong top-N matches but above the weakest leaves.
+// A summary scores below the strong top-N matches but above the weakest leaves.
+const SUMMARY_ITEM_SCORE = 0.5;
+const FRESH_TAIL_ITEM_SCORE = 1.0;
+// Summaries may take this share of the limit.
+const SUMMARY_SUB_FRACTION = 0.3;
 function summaryItem(s, opts) {
     const item = {
         id: s.entry.id,
         content: s.entry.content,
-        score: 0.5,
+        score: SUMMARY_ITEM_SCORE,
         layer: s.entry.layer,
         strength: s.entry.strength,
         isSummary: true,
@@ -396,9 +401,8 @@ function summaryItem(s, opts) {
         item.rerankPipeline = 'api';
     return item;
 }
-// The last N raw rows, so "what did I just see" always covers the recent window. A recent row already in the BM25
-// band is only tagged isFreshTail; new ones are prepended, so every recent row appears exactly once.
-function freshTailBand(opts, recent, baseRanked, summaryRanked, shownEntries, own) {
+function freshTailBand(opts, options) {
+    const { recent, baseRanked, summaryRanked, shownEntries, own } = options;
     const recentScoped = recent.filter((m) => passesScopeFilterForRecall(m.scope ?? null, opts.scope, own) && inCallerProject(m, opts));
     const recentIdSet = new Set(recentScoped.map((m) => m.id));
     for (const r of baseRanked) {
@@ -415,7 +419,7 @@ function freshTailBand(opts, recent, baseRanked, summaryRanked, shownEntries, ow
         const item = {
             id: m.id,
             content: m.content,
-            score: 1.0,
+            score: FRESH_TAIL_ITEM_SCORE,
             layer: m.layer,
             strength: m.strength,
             isFreshTail: true,
@@ -471,9 +475,6 @@ function continuityTokensOf(c) {
         tokenize(filteredHandoff?.cardId) +
         c.recentSessionEvents.reduce((acc, e) => acc + tokenize(e.content), 0);
 }
-function callerOf(ctx) {
-    return { tenantId: ctx.tenantId, actor: ctx.actor.subject };
-}
 // 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.
 function detectRecallAnchoring(opts, topMemoryId) {

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 { DatabaseSyncLike } from '../db.js';
-import { type MemoryKind } from '../memory.js';
+import type { ConnectorEvent } from '../store/port.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,15 +23,8 @@ export interface RememberOpts {
     owner?: string;
     artifactRef?: string;
     tags?: string[];
-    /**
-     * Optional hook invoked inside the same transaction as the underlying
-     * memories INSERT. Used by ingestion connectors to stamp
-     * idempotency / cursor rows atomically with the memory row, so a crash
-     * mid-write cannot produce a memory without its corresponding side-effect
-     * log row (or vice versa). If the callback throws, the INSERT is rolled
-     * back and the error is rethrown.
-     */
-    afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
+    /** 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;
     /** The caller's project: its name becomes the row's origin. Without it the store's fallback applies (NULL on a shared store). */
@@ -26,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;
@@ -37,7 +47,12 @@ export interface RememberResult {
     };
     /** Set only when the content held secret material: untrusted text had it redacted, typed text was stored as sent. */
     warnings?: string[];
+    /** Set only when the write's event was logged before: nothing was stored, so `id` names no row; `memoryId` is the id the first write logged. */
+    duplicate?: {
+        memoryId: string | null;
+    };
 }
-/** Store one memory. With `ctx.store`, its entryWrites group writes the row and its remember row; hippo.db is opened only when there is no store. */
+/** Store one memory: the store's entryWrites group writes the row and its one remember audit row, under the caller's subject.
+ *  A write that carries a connector event or untrusted content goes through connectorWrites, which commits its companion rows with it. */
 export declare function remember<C extends Context>(ctx: C, opts: RememberOpts): StoreReply<C, RememberResult>;
 //# sourceMappingURL=remember.d.ts.map