hippo-memory 1.68.0 → 1.70.0

package/dist/{availability.js → api/availability.js}

@@ -1,27 +1,9 @@
-// ---------------------------------------------------------------------------
-// Availability-bias detector (biases over memory state)
-// ---------------------------------------------------------------------------
-//
-// Flags when a recall's returned top-K is dominated by recent entries while
-// substantially older relevant candidates in the same MATCHED pool were passed
-// over. This is the availability / recency heuristic (Tversky-Kahneman): what
-// is most mentally available (recent) gets over-weighted relative to what is
-// most relevant. Hippo's substrate makes this measurable: every entry carries a
-// creation timestamp, so we can compare the age distribution of what was
-// RETURNED against the age distribution of the pool it was drawn from.
-//
-// Soft warning ONLY: this never filters, reorders, or suppresses a result. It surfaces
-// a hint the calling agent may act on, like anchoringHint / planningFallacyHint / suppressionSummary.
-//
-// PURE: no I/O, no env reads. The env gate (HIPPO_AVAILABILITY=off) and the
-// audit emission live in the callers (api.recall, cmdRecall, MCP), mirroring
-// detectAnchoring in recall-history.ts.
-export const DEFAULT_RECENCY_WINDOW_MS = 24 * 60 * 60 * 1000;
+import { DAY_MS } from '../util/time.js';
+export const DEFAULT_RECENCY_WINDOW_MS = DAY_MS;
 export const DEFAULT_RECENT_FRACTION_THRESHOLD = 0.7;
 export const DEFAULT_MIN_RETURNED = 3;
 export const DEFAULT_MIN_POOL = 10;
 export const DEFAULT_MIN_OLDER_PASSED_OVER = 3;
-const MS_PER_DAY = 24 * 60 * 60 * 1000;
 const MS_PER_HOUR = 60 * 60 * 1000;
 function median(nums) {
     if (nums.length === 0)
@@ -30,6 +12,11 @@ function median(nums) {
     const mid = Math.floor(sorted.length / 2);
     return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
 }
+function parseTimestamps(refs) {
+    return refs
+        .map((e) => ({ id: e.id, ts: Date.parse(e.created) }))
+        .filter((e) => Number.isFinite(e.ts));
+}
 /**
  * Detect availability/recency bias in a recall result.
  *
@@ -52,24 +39,20 @@ export function detectAvailabilityBias(opts) {
     const minReturned = opts.minReturned ?? DEFAULT_MIN_RETURNED;
     const minPool = opts.minPool ?? DEFAULT_MIN_POOL;
     const minOlderPassedOver = opts.minOlderPassedOver ?? DEFAULT_MIN_OLDER_PASSED_OVER;
-    const topK = opts.topK
-        .map((e) => ({ id: e.id, ts: Date.parse(e.created) }))
-        .filter((e) => Number.isFinite(e.ts));
-    const pool = opts.pool
-        .map((e) => ({ id: e.id, ts: Date.parse(e.created) }))
-        .filter((e) => Number.isFinite(e.ts));
+    const topK = parseTimestamps(opts.topK);
+    const pool = parseTimestamps(opts.pool);
     if (topK.length < minReturned || pool.length < minPool)
         return null;
     const recentCount = topK.filter((e) => now - e.ts <= recencyWindowMs).length;
     const recentFraction = recentCount / topK.length;
     if (recentFraction <= recentFractionThreshold)
         return null;
-    const topKMedianAgeDays = median(topK.map((e) => (now - e.ts) / MS_PER_DAY));
-    const poolMedianAgeDays = median(pool.map((e) => (now - e.ts) / MS_PER_DAY));
+    const topKMedianAgeDays = median(topK.map((e) => (now - e.ts) / DAY_MS));
+    const poolMedianAgeDays = median(pool.map((e) => (now - e.ts) / DAY_MS));
     if (poolMedianAgeDays <= topKMedianAgeDays)
         return null;
     const topKIds = new Set(topK.map((e) => e.id));
-    const olderCandidatesPassedOver = pool.filter((e) => !topKIds.has(e.id) && (now - e.ts) / MS_PER_DAY > topKMedianAgeDays).length;
+    const olderCandidatesPassedOver = pool.filter((e) => !topKIds.has(e.id) && (now - e.ts) / DAY_MS > topKMedianAgeDays).length;
     if (olderCandidatesPassedOver < minOlderPassedOver)
         return null;
     const pct = Math.round(recentFraction * 100);

package/dist/{context-auto.js → api/context-auto.js}

@@ -1,4 +1,5 @@
 import { execFileSync } from 'child_process';
+const MAX_DIFF_TERMS = 10;
 const SKIPPED_PATH_TERMS = ['src', 'dist', 'test', 'tests', 'node_modules', 'index'];
 // stderr is dropped because git's warnings (line-ending notices, for one) would otherwise become query terms.
 function readGit(args) {
@@ -13,7 +14,7 @@ export function autoDetectContext() {
                 .split('\n')
                 .flatMap((f) => f.replace(/[/\\.]/g, ' ').split(/\s+/))
                 .filter((t) => t.length > 2 && !SKIPPED_PATH_TERMS.includes(t))
-                .slice(0, 10);
+                .slice(0, MAX_DIFF_TERMS);
             if (terms.length > 0)
                 return terms.join(' ');
         }

package/dist/{context-render.d.ts → api/context-render.d.ts}

@@ -1,7 +1,7 @@
-import { type MemoryEntry } from './memory.js';
-import { type SessionHandoff } from './handoff.js';
-import type { SessionEvent, TaskSnapshot } from './store/rows.js';
-import type { AssembleCost, AssembleResult, AssembledContextItem, ContextCost, ContextResultEntry, DrillDownChild, DrillDownCost, DrillDownResult } from './api.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type SessionHandoff } from '../core/handoff.js';
+import type { SessionEvent, TaskSnapshot } from '../store/rows.js';
+import type { AssembleCost, AssembleResult, AssembledContextItem, ContextCost, ContextResultEntry, DrillDownChild, DrillDownCost, DrillDownResult } from './index.js';
 export declare function snapshotText(s: TaskSnapshot): string;
 export declare function handoffText(h: SessionHandoff): string;
 /** Needs at least one event; the header reads the latest. */

package/dist/{context-render.js → api/context-render.js}

@@ -1,9 +1,10 @@
 // The strings a context block prints. The budget prices these same strings, so selection and print cannot drift.
-import { calculateStrength, confidenceFacets, confidenceLabel } from './memory.js';
-import { evalNow } from './ablation.js';
-import { estimateTokens } from './token-ledger.js';
-import { renderAmbientSummary } from './ambient.js';
-import { formatHandoffEvidenceLine } from './handoff.js';
+import { calculateStrength, confidenceFacets, confidenceLabel } from '../core/memory.js';
+import { evalNow } from '../core/ablation.js';
+import { estimateTokens } from '../util/token-text.js';
+import { renderAmbientSummary } from '../core/ambient.js';
+import { formatHandoffEvidenceLine } from '../core/handoff.js';
+import { DATE_PREFIX_CHARS } from '../util/token-text.js';
 export function snapshotText(s) {
     return [
         '## Active Task Snapshot\n',
@@ -78,7 +79,7 @@ export function contextLine(item, framing, showStrength, now, strengthPct = Math
     const label = confidenceLabel(e, now);
     const confTag = `[${label.text}]${label.warn ? ' ⚠️' : ''}`;
     if (framing === 'observe') {
-        const dateStr = new Date(e.created).toISOString().slice(0, 10);
+        const dateStr = new Date(e.created).toISOString().slice(0, DATE_PREFIX_CHARS);
         // Verified rules print without the date prefix.
         if (confidenceFacets(e, now).tier === 'verified')
             return `- **${confTag} ${globalPrefix}${e.content}**${tagStr}${strengthStr}`;

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

@@ -1,12 +1,22 @@
 import type { AmbientLoadResult } from '../store/candidates.js';
-import { type MemoryEntry } from '../memory.js';
-import { type HippoConfig } from '../config.js';
-import type { ProjectRef } from '../project-identity.js';
-import type { DeliveryObserver } from '../delivery-recorder.js';
+import { type MemoryEntry } from '../core/memory.js';
+import type { ContextReads, HippoStore } from '../store/index.js';
+import { type HippoConfig } from '../core/config.js';
+import type { ProjectRef } from '../core/project-identity.js';
+import type { DeliveryObserver } from '../store/delivery-recorder.js';
 import type { ContextCost, ContextOpts, ContextResultEntry } from './context-types.js';
 import type { Context } from './types.js';
+/** One store getContext reads rows from: its base search and its context reads. */
+export interface ContextSource {
+    readonly store: HippoStore;
+    readonly reads: ContextReads;
+}
 /** What getContext resolved from opts and config before it read a row. */
 export interface ContextPlan {
+    /** The served store, else hippo.db under the root. */
+    local: ContextSource;
+    /** The served store when it is not hippo.db; then every read and write goes through it and no hippo.db opens. */
+    other: HippoStore | undefined;
     pinnedOnly: boolean;
     limit: number;
     includeRecent: number;

package/dist/api/context-select.js

@@ -1,18 +1,18 @@
 // getContext's selection stages: the pinned-only branch, the strongest-first branch and the search branch.
-import { openHippoDb, closeHippoDb } from '../db.js';
 import { recallScopeFilter } from '../store/search-rows.js';
-import { loadIndex } from '../store/index-and-stats.js';
-import { calculateStrength } from '../memory.js';
-import { appendAuditEvent, auditQueryFields } from '../audit.js';
-import { isWorthSurfacing } from '../memory-quality.js';
-import { rankBothStores } from '../shared.js';
-import { evalNow } from '../ablation.js';
+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 { hybridSearch } from '../search/hybrid.js';
 import { physicsSearch } from '../search/physics-search.js';
-import { DEFAULT_LOCAL_BUMP } from '../search/types.js';
-import { compareScoredResults } from '../compare.js';
-import { scopeMatch } from '../scope.js';
-import { promptTokens, contentTokens, gatePromptRecall, } from '../prompt-recall.js';
+import { DEFAULT_LOCAL_BUMP } from '../core/search-types.js';
+import { compareScoredResults } from '../core/compare.js';
+import { scopeMatch } from '../sharing/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.
@@ -61,10 +61,10 @@ export function selectPinned(opts, plan, left, pools, admission) {
     // Prompt recall gates the backfill on the prompt instead of recency.
     if (plan.promptRecallPending) {
         const candidates = () => promptRecallCandidates(plan, pools, admission.admit, rankedPinned, nowP);
-        backfillFromPrompt(opts, plan, pinnedCfg, candidates, picked, recentBudget);
+        backfillFromPrompt(opts, plan, { pinnedCfg, candidates, picked, recentBudget });
     }
     else if (plan.includeRecent > 0) {
-        backfillRecent(plan, localPool, globalPool, picked, recentBudget, nowP);
+        backfillRecent(plan, { localPool, globalPool, picked, recentBudget, nowP });
     }
     admitWithinBudget(rankedPinned, picked, effBudget, obs);
     return picked.items;
@@ -75,11 +75,10 @@ function rankPinned(plan, pinnedLocal, pinnedGlobal, nowP) {
         ...pinnedGlobal.map((e) => ({ entry: e, isGlobal: true })),
     ]
         .map(({ entry, isGlobal }) => {
-        const scopeSig = scopeMatch(entry.tags, plan.activeScope);
-        const sBst = scopeSig === 1 ? 1.5 : scopeSig === -1 ? 0.5 : 1.0;
+        const scopeBoost = scopeBoostFor(scopeMatch(entry.tags, plan.activeScope));
         return {
             entry,
-            score: calculateStrength(entry, nowP) * (isGlobal ? GLOBAL_DISCOUNT : 1) * sBst,
+            score: calculateStrength(entry, nowP) * (isGlobal ? GLOBAL_DISCOUNT : 1) * scopeBoost,
             tokens: plan.price(entry, isGlobal),
             isGlobal,
         };
@@ -115,12 +114,15 @@ function admitWithinBudget(rows, picked, budget, obs) {
         picked.used += r.tokens;
     }
 }
-function backfillFromPrompt(opts, plan, pinnedCfg, candidates, picked, recentBudget) {
+// Overlap a candidate needs with the prompt when the config sets none.
+const DEFAULT_PROMPT_RECALL_THRESHOLD = 0.04;
+function backfillFromPrompt(opts, plan, options) {
+    const { pinnedCfg, candidates, picked, recentBudget } = options;
     const rawMetric = pinnedCfg.pinnedInject.promptRecallMetric;
     const metric = rawMetric === 'cosine' ? 'cosine' : 'jaccard';
     const gate = {
         metric,
-        threshold: finiteOr(pinnedCfg.pinnedInject.promptRecallThreshold, 0.04, 0),
+        threshold: finiteOr(pinnedCfg.pinnedInject.promptRecallThreshold, DEFAULT_PROMPT_RECALL_THRESHOLD, 0),
         minShared: finiteOr(pinnedCfg.pinnedInject.promptRecallMinShared, 2, 0),
         maxItems: finiteOr(pinnedCfg.pinnedInject.promptRecallMaxItems, 5, 1),
     };
@@ -182,7 +184,8 @@ function promptRecallCandidates(plan, pools, admit, rankedPinned, nowP) {
     }
     return candidateItems;
 }
-function backfillRecent(plan, localPool, globalPool, picked, recentBudget, nowP) {
+function backfillRecent(plan, options) {
+    const { localPool, globalPool, picked, recentBudget, nowP } = options;
     const recent = [
         ...localPool.map((entry) => ({ entry, isGlobal: plan.primaryIsGlobal })),
         ...globalPool.map((entry) => ({ entry, isGlobal: true })),
@@ -239,17 +242,19 @@ export function selectStrongest(plan, left, pools) {
 export async function selectBySearch(ctx, plan, left, pools, admission) {
     const minResults = plan.cost ? 0 : undefined; // a priced block skips an oversize top hit too, so the budget bounds it
     const results = plan.hasGlobal && !plan.primaryIsGlobal
-        ? await searchBothStores(ctx, plan, left, minResults, pools, admission.bothStoresAdmit)
-        : await searchLocalRows(ctx, plan, left, minResults, pools.local.entries, admission.admit);
-    auditContextRecall(ctx, plan, results.length);
+        ? await searchBothStores(ctx, plan, { left, minResults, pools, admit: admission.bothStoresAdmit })
+        : await searchLocalRows(ctx, plan, { left, minResults, localEntries: pools.local.entries, admit: admission.admit });
+    await auditContextRecall(ctx, plan, results.length);
     return results;
 }
-// The pools were admitted at load, before ranking, dedupe and budget: a post-filter would let an excluded row fill the
-// budget or shadow its admitted duplicate.
-async function searchBothStores(ctx, plan, left, minResults, pools, admit) {
+async function searchBothStores(ctx, plan, options) {
+    const { left, minResults, pools, admit } = options;
     const { cost, price } = plan;
-    const localIndex = loadIndex(ctx.hippoRoot);
-    const isGlobalHit = (e) => !localIndex.entries[e.id];
+    // A local pool row is local by construction; sync keeps a global row's id on its local copy, so the global pool is looked up.
+    const poolIds = (pool) => [...pool.entries, ...(pool.recall ?? [])].map((e) => e.id);
+    const localIds = new Set(poolIds(pools.local));
+    const alsoLocal = heldIdLookup(ctx.hippoRoot, ctx.tenantId, poolIds(pools.global).filter((id) => !localIds.has(id)));
+    const isGlobalHit = (e) => !localIds.has(e.id) && !alsoLocal(e.id);
     const roots = { local: ctx.hippoRoot, global: plan.globalRoot };
     const merged = await rankBothStores(plan.query, roots, { local: pools.local.entries, global: pools.global.entries }, contextVectorSpec(ctx, plan, admit), {
         budget: left,
@@ -268,11 +273,13 @@ async function searchBothStores(ctx, plan, left, minResults, pools, admit) {
 function contextVectorSpec(ctx, plan, admit) {
     return { tenantId: ctx.tenantId, scope: recallScopeFilter(plan.exactScope, 'exact', plan.ownScope), includeSuperseded: false, admit };
 }
-async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit) {
+async function searchLocalRows(ctx, plan, options) {
+    const { left, minResults, localEntries, admit } = options;
     const { cost, price, primaryIsGlobal, query, config: ctxConfig } = plan;
     const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
     const localCost = cost && ((r) => price(r.entry, primaryIsGlobal));
     const vectorCandidates = contextVectorSpec(ctx, plan, admit);
+    const store = plan.local.store;
     const ctxResults = usePhysicsCtx
         ? await physicsSearch(query, localEntries, {
             budget: left,
@@ -282,6 +289,7 @@ async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit)
             physicsConfig: ctxConfig.physics,
             scope: plan.activeScope,
             vectorCandidates,
+            store,
         })
         : await hybridSearch(query, localEntries, {
             budget: left,
@@ -290,6 +298,7 @@ async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit)
             hippoRoot: ctx.hippoRoot,
             scope: plan.activeScope,
             vectorCandidates,
+            store,
         });
     return ctxResults.map((r) => ({
         entry: r.entry,
@@ -299,39 +308,20 @@ async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit)
     }));
 }
 // Same 'recall' op api.recall emits; the pinned-only and no-query branches never search, so they never emit.
-function auditContextRecall(ctx, plan, resultCount) {
-    const ctxRecallMetadata = {
-        ...auditQueryFields(plan.query),
-        results: resultCount,
-        mode: 'context',
+async function auditContextRecall(ctx, plan, resultCount) {
+    const row = {
+        tenantId: ctx.tenantId,
+        actor: ctx.actor.subject,
+        op: 'recall',
+        metadata: { ...auditQueryFields(plan.query), results: resultCount, mode: 'context' },
     };
-    if (plan.hasLocal) {
-        const localDb = openHippoDb(ctx.hippoRoot);
-        try {
-            appendAuditEvent(localDb, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'recall',
-                metadata: ctxRecallMetadata,
-            });
-        }
-        finally {
-            closeHippoDb(localDb);
-        }
-    }
-    if (plan.hasGlobal && !plan.primaryIsGlobal) {
-        const globalDb = openHippoDb(plan.globalRoot);
-        try {
-            appendAuditEvent(globalDb, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'recall',
-                metadata: ctxRecallMetadata,
-            });
-        }
-        finally {
-            closeHippoDb(globalDb);
-        }
+    if (plan.other) {
+        await plan.other.appendAuditEvents([row]);
+        return;
     }
+    if (plan.hasLocal)
+        recordAuditEvent(ctx.hippoRoot, row);
+    if (plan.hasGlobal && !plan.primaryIsGlobal)
+        recordAuditEvent(plan.globalRoot, row);
 }
 //# sourceMappingURL=context-select.js.map

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

@@ -1,9 +1,9 @@
 import type { TaskSnapshot, SessionEvent } from '../store/rows.js';
-import type { SessionHandoff } from '../handoff.js';
-import type { MemoryEntry } from '../memory.js';
-import type { DeliveryObserver } from '../delivery-recorder.js';
-import type { AmbientState } from '../ambient.js';
-import type { ProjectRef } from '../project-identity.js';
+import type { SessionHandoff } from '../core/handoff.js';
+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).

package/dist/api/context.d.ts

@@ -1,5 +1,5 @@
-import { type MemoryEntry } from '../memory.js';
-import { type ProjectRef } from '../project-identity.js';
+import { type MemoryEntry } from '../core/memory.js';
+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';
@@ -9,8 +9,6 @@ export { oneCopyPerMemory } from './context-select.js';
  * flagged rows with no project origin never ambient-inject.
  */
 export declare function ambientSecretAdmit(e: MemoryEntry, currentProject: ProjectRef): boolean;
-/** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
-export declare const CONTEXT_CANDIDATE_CAP = 2000;
 /**
  * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
  * fallback / hybrid search) + active task snapshot + session handoff + recent