hippo-memory 1.60.0 → 1.62.0

package/dist/session-digest.d.ts

@@ -1,4 +1,4 @@
-import { type SessionTurn } from './capture.js';
+import { type SessionTurn } from './capture/transcript.js';
 import { type MemoryEntry } from './memory.js';
 export declare const SESSION_DIGEST_TAG = "session-digest";
 /** Five-word runs are stock phrases; six in a row is a copied clause. */

package/dist/session-digest.js

@@ -2,15 +2,22 @@
 import { createHash } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { collectSessionTurns, errorMessage, readTranscriptTail, splitSentences, } from './capture.js';
+import { collectSessionTurns } from './capture/transcript.js';
+import { splitSentences } from './capture/extract.js';
 import { isObjectLike, isStringValue } from './capture-contract.js';
 import { PATCH_SUCCESS_LINE, patchPaths, shellPatch } from './codex-patch.js';
 import { loadConfig } from './config.js';
+import { errorMessage } from './log.js';
 import { createMemory, Layer } from './memory.js';
 import { RejectedValueError } from './rejection.js';
 import { maskEmails, redactSecretsStrict } from './secret-detect.js';
-import { SNAPSHOT_AMBIENT_MAX_AGE_MS, isInitialized, loadAllEntries, loadLatestHandoff, writeEntry } from './store.js';
+import { isInitialized } from './store/open.js';
+import { writeEntry } from './store/entry-writes.js';
+import { loadAllEntries } from './store/entry-reads.js';
+import { SNAPSHOT_AMBIENT_MAX_AGE_MS } from './store/sessions.js';
+import { loadLatestHandoff } from './store/handoffs.js';
 import { isSyntheticMessage } from './token-ledger.js';
+import { readTranscriptTail } from './transcript-tail.js';
 export const SESSION_DIGEST_TAG = 'session-digest';
 /** Five-word runs are stock phrases; six in a row is a copied clause. */
 export const ECHO_WINDOW = 6;

package/dist/shared.d.ts

@@ -5,7 +5,9 @@
  * Local .hippo/ stores are per-project.
  */
 import { MemoryEntry } from './memory.js';
-import { SearchResult, type ResultCost } from './search.js';
+import type { SearchResult, ResultCost } from './search/types.js';
+import type { HybridVectorCandidates } from './search/vector.js';
+import type { DatabaseSyncLike } from './db.js';
 /**
  * Returns the path to the global Hippo store.
  * Resolution order: $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo/
@@ -23,6 +25,7 @@ export declare function initGlobal(): void;
 export declare function promoteToGlobal(localRoot: string, id: string, opts?: {
     actor?: string;
     tenantId?: string;
+    afterWrite?: (db: DatabaseSyncLike, globalId: string) => void;
 }): MemoryEntry;
 export interface SearchOptions {
     budget?: number;
@@ -91,6 +94,14 @@ export interface HybridSearchOptions extends SearchOptions {
  * Async version of searchBoth that calls hybridSearch instead of search.
  */
 export declare function searchBothHybrid(query: string, localRoot: string, globalRoot: string, options?: HybridSearchOptions): Promise<SearchResult[]>;
+/** Hybrid ranking of rows already loaded from each store: the local bump, one copy per text, then the shared budget. */
+export declare function rankBothStores(query: string, roots: {
+    local: string;
+    global: string;
+}, entries: {
+    local: MemoryEntry[];
+    global: MemoryEntry[];
+}, vectorCandidates: HybridVectorCandidates, options?: HybridSearchOptions): Promise<SearchResult[]>;
 /** Tags whose rows only a hand-run share or promote may copy to the global store; derived rows inherit them. */
 export declare const NEVER_AUTO_SHARE_TAGS: ReadonlySet<string>;
 export declare function neverAutoShareTags(sources: readonly MemoryEntry[]): string[];

package/dist/shared.js

@@ -9,9 +9,16 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { generateId, COMPACTION_MEMORY_TAG } from './memory.js';
 import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TAGS } from './agent-memories/tools.js';
-import { initStore, loadAllEntries, loadIndex, loadSearchEntries, loadRecallSearchEntries, tallySources, writeEntry, readEntry, } from './store.js';
+import { initStore } from './store/open.js';
+import { writeEntry } from './store/entry-writes.js';
+import { loadAllEntries, readEntry } from './store/entry-reads.js';
+import { loadSearchEntries, loadRecallSearchEntries, recallScopeFilter } from './store/search-rows.js';
+import { tallySources } from './store/candidates.js';
+import { loadIndex } from './store/index-and-stats.js';
 import { passesScopeFilterForRecall, passesCliRecallScopeFilter } from './recall-scope.js';
-import { search, hybridSearch, fitBudget } from './search.js';
+import { search } from './search/bm25-search.js';
+import { hybridSearch } from './search/hybrid.js';
+import { fitBudget } from './search/finalize.js';
 import { evalNow } from './ablation.js';
 import { deriveOriginProject, classifyOriginProject, resolveGlobalRootDir } from './project-identity.js';
 import { detectSecret } from './secret-detect.js';
@@ -77,7 +84,7 @@ export function promoteToGlobal(localRoot, id, opts) {
         source: `promoted:${localRoot}`,
         origin_project: entry.origin_project ?? deriveOriginProject(path.dirname(path.resolve(localRoot))),
     };
-    writeEntry(globalRoot, globalEntry, { actor: opts?.actor });
+    writeEntry(globalRoot, globalEntry, { actor: opts?.actor, afterWrite: opts?.afterWrite });
     // Fire-and-forget: embedMemory gates on availability and never rejects.
     void embedMemory(globalRoot, globalEntry);
     return globalEntry;
@@ -141,13 +148,10 @@ export function searchBoth(query, localRoot, globalRoot, options = {}) {
  * Async version of searchBoth that calls hybridSearch instead of search.
  */
 export async function searchBothHybrid(query, localRoot, globalRoot, options = {}) {
-    const { budget = 4000, now = evalNow(), embeddingWeight, explain, mmr, mmrLambda, localBump = 1.2, minResults, cost, scope, includeSuperseded, asOf, tenantId, summaryDeboost, summaryFreshness, entryFilter, recallScope } = options;
+    const { includeSuperseded, asOf, tenantId, entryFilter, recallScope } = options;
     // When an admission filter is active, lift the per-store candidate cap
     // (default 200): excluded rows matching the query could otherwise fill the
     // window before any admitted row is even loaded (codex gating round 6).
-    // Only ambient-context query mode sets entryFilter, and that path is
-    // interactive - never the per-turn pinned-only hook - so ranking the full
-    // match set is acceptable.
     // 5000 = 25x the default 200-row window: large enough that exclusion
     // crowding is a non-issue on real stores, bounded so a common query term
     // on a 100k-row store cannot stall an interactive call by ranking every
@@ -166,27 +170,29 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
             ? loadRecallSearchEntries(root, query, searchWindow, tenantId, recallScope.requested, recallScope.additive ? 'additive' : 'exact', Boolean(includeSuperseded) || Boolean(asOf))
             : loadSearchEntries(root, query, searchWindow, tenantId);
     };
-    let localEntries = loadEntries(localRoot);
-    let globalEntries = loadEntries(globalRoot);
-    if (recallScope) {
-        const passes = (e) => recallScope.additive
-            ? passesCliRecallScopeFilter(e.scope ?? null, recallScope.requested)
-            : passesScopeFilterForRecall(e.scope ?? null, recallScope.requested);
-        localEntries = localEntries.filter(passes);
-        globalEntries = globalEntries.filter(passes);
-    }
-    if (entryFilter) {
-        localEntries = localEntries.filter(entryFilter);
-        globalEntries = globalEntries.filter(entryFilter);
-    }
-    if (localEntries.length === 0 && globalEntries.length === 0)
+    const passesScope = (e) => !recallScope || (recallScope.additive
+        ? passesCliRecallScopeFilter(e.scope ?? null, recallScope.requested)
+        : passesScopeFilterForRecall(e.scope ?? null, recallScope.requested));
+    const admit = (e) => passesScope(e) && (!entryFilter || entryFilter(e));
+    const localEntries = loadEntries(localRoot).filter(admit);
+    const globalEntries = loadEntries(globalRoot).filter(admit);
+    // The vector arm loads under the same SQL rules as loadEntries, then the same JS admission.
+    const vectorCandidates = {
+        tenantId,
+        scope: recallScope ? recallScopeFilter(recallScope.requested, recallScope.additive ? 'additive' : 'exact') : undefined,
+        includeSuperseded: !recallScope || Boolean(includeSuperseded) || Boolean(asOf),
+        admit,
+    };
+    return rankBothStores(query, { local: localRoot, global: globalRoot }, { local: localEntries, global: globalEntries }, vectorCandidates, options);
+}
+/** Hybrid ranking of rows already loaded from each store: the local bump, one copy per text, then the shared budget. */
+export async function rankBothStores(query, roots, entries, vectorCandidates, options = {}) {
+    const { budget = 4000, now = evalNow(), embeddingWeight, explain, mmr, mmrLambda, localBump = 1.2, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness } = options;
+    if (entries.local.length === 0 && entries.global.length === 0)
         return [];
-    const localResults = await hybridSearch(query, localEntries, {
-        budget, now, hippoRoot: localRoot, embeddingWeight, explain, mmr, mmrLambda, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness,
-    });
-    const globalResults = await hybridSearch(query, globalEntries, {
-        budget, now, hippoRoot: globalRoot, embeddingWeight, explain, mmr, mmrLambda, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness,
-    });
+    const shared = { budget, now, embeddingWeight, explain, mmr, mmrLambda, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness, vectorCandidates };
+    const localResults = await hybridSearch(query, entries.local, { ...shared, hippoRoot: roots.local });
+    const globalResults = await hybridSearch(query, entries.global, { ...shared, hippoRoot: roots.global });
     // Tag global results. Local memories get a configurable priority bump.
     const tagged = [
         ...localResults.map((r) => ({

package/dist/skills.d.ts

@@ -21,6 +21,7 @@
  * Lifecycle: active -> superseded (a newer version replaces it) or active ->
  * closed (retired). Export renders ACTIVE skills only.
  */
+import { type KeysetPosition } from './keyset.js';
 export type SkillStatus = 'active' | 'superseded' | 'closed';
 export declare const VALID_SKILL_STATES: ReadonlySet<SkillStatus>;
 /** Field caps (untrusted at the HTTP/SDK boundary). instructions is a body, so a
@@ -66,6 +67,8 @@ export interface SaveSkillOpts {
 export interface ListSkillsOpts {
     status?: SkillStatus;
     limit?: number;
+    /** Resume after this row: the position the previous page ended on. */
+    after?: KeysetPosition;
 }
 /**
  * Create a skill (or a new version that supersedes an existing one). Writes the

package/dist/skills.js

@@ -23,11 +23,12 @@
  */
 import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry } from './store.js';
+import { writeEntry } from './store/entry-writes.js';
 import { assertTenantId } from './tenant.js';
 import { createMemory, Layer } from './memory.js';
 import { appendAuditEvent } from './audit.js';
 import { objectHalfLifeDays } from './half-life-migration.js';
+import { keysetAfter } from './keyset.js';
 export const VALID_SKILL_STATES = new Set([
     'active',
     'superseded',
@@ -110,9 +111,76 @@ function buildSkillContent(skillName, instructions, trigger) {
     content += `\n\n${instructions}`;
     return content;
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
+// Preflight the supersede target BEFORE inserting the new row (so the new
+// autoincrement id can never be its own supersede target); read the
+// predecessor version in the same SELECT for server-derived versioning.
+// Mirrors saveProcess / savePolicy (codex P1 2026-05-28).
+function preflightSkillSupersede(db, tenantId, supersedesId) {
+    // SAFETY: row shape matches the `status, version` columns named in the SELECT below.
+    const pred = db.prepare(`SELECT status, version FROM skills WHERE id = ? AND tenant_id = ?`).get(supersedesId, tenantId);
+    if (!pred) {
+        throw new NotFoundError(`saveSkill: skill ${supersedesId} to supersede not found for tenant ${tenantId}`);
+    }
+    if (pred.status !== 'active') {
+        throw new ConflictError(`saveSkill: skill ${supersedesId} is not active (status='${pred.status}'); only active skills can be superseded.`);
+    }
+    return pred.version + 1;
+}
+function insertSkillRow(db, memoryId, w, version) {
+    const result = db.prepare(`
+    INSERT INTO skills(
+      memory_id, tenant_id, skill_name, instructions, trigger_text, version,
+      status, superseded_by, superseded_at, change_summary, closed_at, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
+  `).run(memoryId, w.tenantId, w.name, w.instructions, w.trigger, version, w.changeSummary, w.now);
+    return Number(result.lastInsertRowid ?? 0);
+}
+function supersedeSkillRow(db, w, supersedesId, skillId, version) {
+    const sup = db.prepare(`
+    UPDATE skills
+    SET status = 'superseded', superseded_by = ?, superseded_at = ?
+    WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
+  `).run(skillId, w.now, supersedesId, w.tenantId, skillId);
+    if (sup.changes === 0) {
+        throw new ConflictError(`saveSkill: skill ${supersedesId} could not be superseded (no longer active or self-reference).`);
+    }
+    appendAuditEvent(db, {
+        tenantId: w.tenantId,
+        actor: w.actor,
+        op: 'skill_supersede',
+        targetId: String(supersedesId),
+        metadata: {
+            skill_id: supersedesId,
+            superseded_by: skillId,
+            new_version: version,
+        },
+    });
+}
+/** The afterWrite body: preflight, INSERT, supersede, reload, create audit, all in one SAVEPOINT. */
+function writeSkillRow(db, memoryId, w) {
+    const version = w.supersedesId !== undefined ? preflightSkillSupersede(db, w.tenantId, w.supersedesId) : 1;
+    const skillId = insertSkillRow(db, memoryId, w, version);
+    if (w.supersedesId !== undefined)
+        supersedeSkillRow(db, w, w.supersedesId, skillId, version);
+    // SAFETY: row's shape matches the columns named in SKILL_COLS above.
+    const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ?`)
+        .get(skillId);
+    if (!row)
+        throw new Error('saveSkill: failed to reload saved skill row');
+    // GDPR-light metadata: ids + flags only, no skill text.
+    appendAuditEvent(db, {
+        tenantId: w.tenantId,
+        actor: w.actor,
+        op: 'skill_create',
+        targetId: String(skillId),
+        metadata: {
+            skill_id: skillId,
+            version,
+            has_trigger: w.trigger !== null,
+        },
+    });
+    return row;
+}
 /**
  * Create a skill (or a new version that supersedes an existing one). Writes the
  * memory mirror + the skills row atomically inside writeEntry's SAVEPOINT. When
@@ -136,72 +204,21 @@ export function saveSkill(hippoRoot, tenantId, opts, actor = 'cli') {
         baseHalfLifeDays: objectHalfLifeDays(hippoRoot),
         tenantId,
     });
+    const w = {
+        tenantId,
+        actor,
+        name,
+        instructions: opts.instructions,
+        trigger,
+        changeSummary,
+        supersedesId: opts.supersedesSkillId,
+        now,
+    };
     let savedRow;
     writeEntry(hippoRoot, mem, {
         actor,
         afterWrite: (db, memoryId) => {
-            // Preflight the supersede target BEFORE inserting the new row (so the new
-            // autoincrement id can never be its own supersede target); read the
-            // predecessor version in the same SELECT for server-derived versioning.
-            // Mirrors saveProcess / savePolicy (codex P1 2026-05-28).
-            let version = 1;
-            if (opts.supersedesSkillId !== undefined) {
-                // SAFETY: row shape matches the `status, version` columns named in the SELECT below.
-                const pred = db.prepare(`SELECT status, version FROM skills WHERE id = ? AND tenant_id = ?`).get(opts.supersedesSkillId, tenantId);
-                if (!pred) {
-                    throw new NotFoundError(`saveSkill: skill ${opts.supersedesSkillId} to supersede not found for tenant ${tenantId}`);
-                }
-                if (pred.status !== 'active') {
-                    throw new ConflictError(`saveSkill: skill ${opts.supersedesSkillId} is not active (status='${pred.status}'); only active skills can be superseded.`);
-                }
-                version = pred.version + 1;
-            }
-            const result = db.prepare(`
-        INSERT INTO skills(
-          memory_id, tenant_id, skill_name, instructions, trigger_text, version,
-          status, superseded_by, superseded_at, change_summary, closed_at, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, 'active', NULL, NULL, ?, NULL, ?)
-      `).run(memoryId, tenantId, name, opts.instructions, trigger, version, changeSummary, now);
-            const skillId = Number(result.lastInsertRowid ?? 0);
-            if (opts.supersedesSkillId !== undefined) {
-                const sup = db.prepare(`
-          UPDATE skills
-          SET status = 'superseded', superseded_by = ?, superseded_at = ?
-          WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
-        `).run(skillId, now, opts.supersedesSkillId, tenantId, skillId);
-                if (sup.changes === 0) {
-                    throw new ConflictError(`saveSkill: skill ${opts.supersedesSkillId} could not be superseded (no longer active or self-reference).`);
-                }
-                appendAuditEvent(db, {
-                    tenantId,
-                    actor,
-                    op: 'skill_supersede',
-                    targetId: String(opts.supersedesSkillId),
-                    metadata: {
-                        skill_id: opts.supersedesSkillId,
-                        superseded_by: skillId,
-                        new_version: version,
-                    },
-                });
-            }
-            // SAFETY: row's shape matches the columns named in SKILL_COLS above.
-            const row = db.prepare(`SELECT ${SKILL_COLS} FROM skills WHERE id = ?`)
-                .get(skillId);
-            if (!row)
-                throw new Error('saveSkill: failed to reload saved skill row');
-            savedRow = row;
-            // GDPR-light metadata: ids + flags only, no skill text.
-            appendAuditEvent(db, {
-                tenantId,
-                actor,
-                op: 'skill_create',
-                targetId: String(skillId),
-                metadata: {
-                    skill_id: skillId,
-                    version,
-                    has_trigger: trigger !== null,
-                },
-            });
+            savedRow = writeSkillRow(db, memoryId, w);
         },
     });
     if (!savedRow) {
@@ -278,6 +295,7 @@ export function loadSkillById(hippoRoot, tenantId, id) {
 export function loadSkills(hippoRoot, tenantId, opts = {}) {
     assertTenantId('loadSkills', tenantId);
     const limit = opts.limit ?? 100;
+    const after = keysetAfter('created_at', 'id', opts.after);
     const db = openHippoDb(hippoRoot);
     try {
         let rows;
@@ -288,19 +306,19 @@ export function loadSkills(hippoRoot, tenantId, opts = {}) {
             // SAFETY: rows' shape matches the columns named in SKILL_COLS above.
             rows = db.prepare(`
         SELECT ${SKILL_COLS} FROM skills
-        WHERE tenant_id = ? AND status = ?
+        WHERE tenant_id = ? AND status = ?${after.sql}
         ORDER BY created_at DESC, id DESC
         LIMIT ?
-      `).all(tenantId, opts.status, limit);
+      `).all(tenantId, opts.status, ...after.params, limit);
         }
         else {
             // SAFETY: rows' shape matches the columns named in SKILL_COLS above.
             rows = db.prepare(`
         SELECT ${SKILL_COLS} FROM skills
-        WHERE tenant_id = ?
+        WHERE tenant_id = ?${after.sql}
         ORDER BY created_at DESC, id DESC
         LIMIT ?
-      `).all(tenantId, limit);
+      `).all(tenantId, ...after.params, limit);
         }
         return rows.map(rowToSkill);
     }

package/dist/stdin.js

@@ -1,6 +1,6 @@
+import { envStdinWaitMs } from './env.js';
 function defaultWaitMs() {
-    const parsed = Number.parseInt(process.env.HIPPO_STDIN_WAIT_MS ?? '', 10);
-    return parsed > 0 ? parsed : 1000;
+    return envStdinWaitMs() ?? 1000;
 }
 /** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of
  * idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`), refreshed on each chunk

package/dist/store/audit-event.d.ts

@@ -0,0 +1,19 @@
+import { openHippoDb } from '../db.js';
+import { type AuditOp } from '../audit.js';
+import { RejectedValueError } from '../rejection.js';
+import type { JsonValue } from './rows.js';
+/**
+ * Emit an audit event for a mutation against `db`. Wrapped so a broken audit
+ * log can never crash the surrounding mutation — the SQLite store is still the
+ * source of truth and audit failures are diagnosable from the missing rows.
+ */
+export declare function audit(db: ReturnType<typeof openHippoDb>, op: AuditOp, targetId?: string, metadata?: Record<string, JsonValue>, actor?: string, tenantId?: string): void;
+/**
+ * Refusal audit for the AT1 rejection guard (plan §3). Written by the
+ * transaction OWNER post-rollback — writeEntry's catch (no outer tx exists
+ * there, so this lands in a fresh implicit transaction) and api.supersede's
+ * catch (after its own ROLLBACK) — never inside a scope the caller's own
+ * rollback could claw back. Best-effort `audit()` semantics: never throws.
+ */
+export declare function auditRejectionRefusal(db: ReturnType<typeof openHippoDb>, err: RejectedValueError, actor: string): void;
+//# sourceMappingURL=audit-event.d.ts.map

package/dist/store/audit-event.js

@@ -0,0 +1,33 @@
+import { resolveTenantId } from '../tenant.js';
+import { appendAuditEvent, reportAuditWriteFailure } from '../audit.js';
+/**
+ * Emit an audit event for a mutation against `db`. Wrapped so a broken audit
+ * log can never crash the surrounding mutation — the SQLite store is still the
+ * source of truth and audit failures are diagnosable from the missing rows.
+ */
+export function audit(db, op, targetId, metadata, actor = 'cli', tenantId) {
+    try {
+        appendAuditEvent(db, {
+            tenantId: tenantId ?? resolveTenantId({}),
+            actor,
+            op,
+            targetId,
+            metadata,
+        });
+    }
+    catch (error) {
+        // The mutation has already succeeded; a broken audit table must not undo it.
+        reportAuditWriteFailure(op, String(error), targetId);
+    }
+}
+/**
+ * Refusal audit for the AT1 rejection guard (plan §3). Written by the
+ * transaction OWNER post-rollback — writeEntry's catch (no outer tx exists
+ * there, so this lands in a fresh implicit transaction) and api.supersede's
+ * catch (after its own ROLLBACK) — never inside a scope the caller's own
+ * rollback could claw back. Best-effort `audit()` semantics: never throws.
+ */
+export function auditRejectionRefusal(db, err, actor) {
+    audit(db, 'reject_refusal', err.entryId, { digest: err.digest, reason: err.reason }, actor, err.tenantId);
+}
+//# sourceMappingURL=audit-event.js.map

package/dist/store/candidates.d.ts

@@ -0,0 +1,42 @@
+import type { MemoryEntry, StrengthInputs } from '../memory.js';
+export interface AmbientRecallRequest {
+    terms: string[];
+    limit: number;
+}
+export interface AmbientLoadResult {
+    entries: MemoryEntry[];
+    recall?: MemoryEntry[];
+}
+/** Exported so the plan test runs the exact SQL; idx_memories_pinned (db.ts v51) serves it. */
+export declare const AMBIENT_PINNED_WHERE = "pinned = 1 AND superseded_by IS NULL AND tenant_id = ? ORDER BY created ASC, id ASC";
+/** Exported so the plan test runs the exact SQL; idx_memories_created_drift (db.ts v51) serves it. */
+export declare const AMBIENT_DRIFT_SQL = "SELECT 1 FROM memories WHERE superseded_by IS NULL AND tenant_id = ? AND (length(created) <> 24 OR created NOT LIKE '%Z') LIMIT 1";
+export declare function loadAmbientCandidates(hippoRoot: string, tenantId: string, recentNeeded: number, admit: (e: MemoryEntry) => boolean, recall?: AmbientRecallRequest): AmbientLoadResult;
+/** The rows a non-pinned context read may admit; each predicate is one getContext's admission applies again in JS. */
+export interface ContextCandidateFilter {
+    /** Envelope scope asked for by name; absent applies recall's default deny. */
+    exactScope?: string;
+    /** Rows of this project and user-global rows pass; absent admits every origin. */
+    project?: string;
+    /** Most rows returned; past it, the rows decay has worn least win. */
+    cap: number;
+    now: Date;
+}
+/** Live tenant rows passing `filter`, at most `filter.cap`, in loadAllEntries' order; below the cap, every such row. */
+export declare function loadContextCandidates(hippoRoot: string, tenantId: string, filter: ContextCandidateFilter): MemoryEntry[];
+/** A row's strength inputs and tags, without its text or the JSON lists a full row parses. */
+export type StrengthRow = StrengthInputs & Pick<MemoryEntry, 'tags'>;
+/** Every tenant row as a StrengthRow, for whole-store health numbers; defaults match rowToEntry's. */
+export declare function loadStrengthRows(hippoRoot: string, tenantId: string): StrengthRow[];
+/** Text and source of tenant rows holding any of `words`; a row equal to a text apart from spacing holds its every word. */
+export declare function loadTextsHoldingWords(hippoRoot: string, tenantId: string, words: readonly string[]): Array<Pick<MemoryEntry, 'content' | 'source'>>;
+export interface SourceTally {
+    source: string;
+    count: number;
+    latest: string;
+    /** `created`, a unit separator, then `id` of the source's first row in loadAllEntries' order. */
+    first: string;
+}
+/** Row count and newest `created` per source, for peer listings that need no row; all tenants when `tenantId` is absent. */
+export declare function tallySources(hippoRoot: string, tenantId?: string): SourceTally[];
+//# sourceMappingURL=candidates.d.ts.map

package/dist/store/candidates.js

@@ -0,0 +1,152 @@
+import { closeHippoDb } from '../db.js';
+import { RECALL_DEFAULT_DENY_SCOPES } from '../recall-scope.js';
+import { MEMORY_SELECT_COLUMNS, rowToEntry, parseJsonArray } from './rows.js';
+import { openStore } from './open.js';
+import { pickRarestFtsQuery, loadRecallSearchEntriesFromDb } from './search-rows.js';
+const AMBIENT_SCOPED = 'superseded_by IS NULL AND tenant_id = ?';
+/** Exported so the plan test runs the exact SQL; idx_memories_pinned (db.ts v51) serves it. */
+export const AMBIENT_PINNED_WHERE = `pinned = 1 AND ${AMBIENT_SCOPED} ORDER BY created ASC, id ASC`;
+/** Exported so the plan test runs the exact SQL; idx_memories_created_drift (db.ts v51) serves it. */
+export const AMBIENT_DRIFT_SQL = `SELECT 1 FROM memories WHERE ${AMBIENT_SCOPED} AND (length(created) <> 24 OR created NOT LIKE '%Z') LIMIT 1`;
+// The pins plus the `recentNeeded` newest rows that pass `admit`, for ambient
+// injection. One connection; `recall` piggybacks the Z1 FTS query on it too.
+export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit, recall) {
+    // A SQL LIMIT takes an integer; the Array.slice this replaced truncated one,
+    // and include_recent is any non-negative finite number at the HTTP edge.
+    const needed = Math.trunc(recentNeeded);
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: every `where` below starts from MEMORY_SELECT_COLUMNS' table.
+        const run = (where, params) => db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE ${where}`).all(...params).map(rowToEntry);
+        const byId = new Map();
+        const scoped = AMBIENT_SCOPED;
+        for (const e of run(AMBIENT_PINNED_WHERE, [tenantId])) {
+            if (admit(e))
+                byId.set(e.id, e);
+        }
+        if (needed > 0) {
+            // Text order is chronological only for canonical UTC ISO (memory.ts).
+            const drifted = db.prepare(AMBIENT_DRIFT_SQL).get(tenantId) !== undefined;
+            // `id DESC` mirrors getContext's comparator, not loadFreshRawMemories'
+            // cross-ingest-stable order: that would change what the hook injects.
+            const window = Math.max(needed * 4, 32);
+            const windowed = drifted
+                ? []
+                : run(`${scoped} ORDER BY created DESC, id DESC LIMIT ?`, [tenantId, window]);
+            let kept = windowed.filter(admit);
+            if (drifted || (kept.length < needed && windowed.length === window)) {
+                kept = run(`${scoped} ORDER BY created DESC, id DESC`, [tenantId]).filter(admit);
+            }
+            for (const e of kept)
+                byId.set(e.id, e);
+        }
+        // loadAllEntries' order: rankedPinned's comparator can tie and Array.sort
+        // is stable, so input order is load-bearing downstream.
+        const entries = [...byId.values()].sort((a, b) => {
+            const byCreated = a.created.localeCompare(b.created);
+            return byCreated !== 0 ? byCreated : a.id.localeCompare(b.id);
+        });
+        if (!recall)
+            return { entries };
+        const ftsQuery = pickRarestFtsQuery(db, recall.terms);
+        const recallEntries = ftsQuery
+            ? loadRecallSearchEntriesFromDb(db, ftsQuery, recall.limit, tenantId, undefined, 'exact', false)
+            : [];
+        return { entries, recall: recallEntries };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+// calculateStrength's decay exponent with its reward factor, pins first: the strongest rows, without scoring each one in JS.
+const DECAY_RANK_SQL = `pinned DESC,
+  CASE WHEN half_life_days > 0 THEN (julianday(?) - julianday(last_retrieved))
+    / (half_life_days * (1.0 + 0.5 * (COALESCE(outcome_positive, 0) - COALESCE(outcome_negative, 0))
+      / (COALESCE(outcome_positive, 0) + COALESCE(outcome_negative, 0) + 1.0))) END ASC NULLS LAST,
+  id ASC`;
+/** Live tenant rows passing `filter`, at most `filter.cap`, in loadAllEntries' order; below the cap, every such row. */
+export function loadContextCandidates(hippoRoot, tenantId, filter) {
+    const where = ['tenant_id = ?', `COALESCE(superseded_by, '') = ''`];
+    const params = [tenantId];
+    if (filter.exactScope) {
+        where.push('scope = ?');
+        params.push(filter.exactScope);
+    }
+    else {
+        // isRestrictedScope's rule; NOT LIKE folds ASCII case as its /:private:/i does.
+        where.push(`(scope IS NULL OR (scope NOT IN (${RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ')}) AND scope NOT LIKE '%:private:%'))`);
+        params.push(...RECALL_DEFAULT_DENY_SCOPES);
+    }
+    if (filter.project !== undefined) {
+        where.push(`(origin_project = '' OR origin_project = ?)`);
+        params.push(filter.project);
+    }
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: the outer SELECT names exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set; the rank sort carries ids only.
+        const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id IN (
+        SELECT id FROM memories WHERE ${where.join(' AND ')} ORDER BY ${DECAY_RANK_SQL} LIMIT ?
+      ) ORDER BY created ASC, id ASC`).all(...params, filter.now.toISOString(), Math.max(0, Math.trunc(filter.cap)));
+        return rows.map(rowToEntry);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Every tenant row as a StrengthRow, for whole-store health numbers; defaults match rowToEntry's. */
+export function loadStrengthRows(hippoRoot, tenantId) {
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: rows' shape matches the columns named in the SELECT below.
+        const rows = db.prepare(`SELECT pinned, created, last_retrieved, half_life_days, retrieval_count, emotional_valence, outcome_positive, outcome_negative, tags_json
+       FROM memories WHERE tenant_id = ?`).all(tenantId);
+        return rows.map((row) => ({
+            pinned: Boolean(row.pinned),
+            created: row.created,
+            last_retrieved: row.last_retrieved,
+            half_life_days: Number(row.half_life_days ?? 7),
+            retrieval_count: Number(row.retrieval_count ?? 0),
+            emotional_valence: row.emotional_valence ?? 'neutral',
+            outcome_positive: Number(row.outcome_positive ?? 0),
+            outcome_negative: Number(row.outcome_negative ?? 0),
+            tags: parseJsonArray(row.tags_json),
+        }));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Text and source of tenant rows holding any of `words`; a row equal to a text apart from spacing holds its every word. */
+export function loadTextsHoldingWords(hippoRoot, tenantId, words) {
+    const unique = [...new Set(words)];
+    const out = [];
+    const db = openStore(hippoRoot);
+    try {
+        // Chunked so one statement stays far under SQLite's bound-parameter limit.
+        for (let i = 0; i < unique.length; i += 200) {
+            const chunk = unique.slice(i, i + 200);
+            // SAFETY: rows' shape matches the two columns named in the SELECT below.
+            const rows = db.prepare(`SELECT content, source FROM memories WHERE tenant_id = ? AND (${chunk.map(() => 'instr(content, ?) > 0').join(' OR ')})`).all(tenantId, ...chunk);
+            for (const row of rows)
+                out.push({ content: row.content, source: row.source ?? 'cli' });
+        }
+        return out;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Row count and newest `created` per source, for peer listings that need no row; all tenants when `tenantId` is absent. */
+export function tallySources(hippoRoot, tenantId) {
+    const db = openStore(hippoRoot);
+    try {
+        const where = tenantId !== undefined ? 'WHERE tenant_id = ?' : '';
+        // SAFETY: rows' shape matches the four aliased columns in the SELECT below.
+        return db.prepare(`SELECT COALESCE(source, 'cli') AS source, COUNT(*) AS count, MAX(created) AS latest, MIN(created || char(31) || id) AS first
+       FROM memories ${where} GROUP BY COALESCE(source, 'cli')`).all(...(tenantId !== undefined ? [tenantId] : []));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=candidates.js.map