@b4run/memory 0.8.28

package/dist/reconcile.d.ts

@@ -0,0 +1,51 @@
+import type { MemoryKind, MemoryRecord, MemoryStore } from "./types.js";
+export type WritePolicy = {
+    readonly mode: "reconcile";
+} | {
+    readonly mode: "append";
+};
+/** Per-kind write discipline. Semantic facts reconcile (identity match →
+ *  update/supersede); episodic events append (a later episode never
+ *  contradicts an earlier one); reflection insights append too — distillation
+ *  ACCUMULATES insights, and a later insight never contradicts an earlier one
+ *  (superseding stale insights is a future concern). Procedural alone is typed
+ *  but not yet wired — throwing beats baking in accidental semantics.
+ *  Mirrored inline in packages/core/src/capabilities/built-in/memory.ts
+ *  remember (core can't import this package) — keep in sync. */
+export declare function writePolicyFor(kind: MemoryKind): WritePolicy;
+export type WriteOp = {
+    op: "add";
+} | {
+    op: "update";
+    targetId: string;
+} | {
+    op: "supersede";
+    targetId: string;
+};
+/** Deterministic write classification (no LLM): ADD if no identity match; UPDATE if identity+data equal; SUPERSEDE if identity matches but data differs. */
+export declare function classifyWrite(incoming: MemoryRecord, candidates: readonly MemoryRecord[], identityKeys: readonly string[]): WriteOp;
+export interface ApproveResult {
+    readonly approved: MemoryRecord;
+    readonly action: "activated" | "superseded" | "deduped";
+    readonly superseded: readonly MemoryRecord[];
+    readonly identityKeys: readonly string[];
+}
+/**
+ * Approve a candidate WITH supersede reconciliation (fixes the two-actives bug):
+ * same identity + different data → the old active row is superseded; same
+ * identity + identical data → the candidate is dropped (dedupe); no identity
+ * match → plain activation. Used by `b4 memory approve` and the inspector —
+ * the capability's auto-write path keeps its own inline logic by design.
+ * Append-kind candidates (per writePolicyFor, e.g. episodic) bypass
+ * reconciliation entirely — approval is a plain activation, no identity scan.
+ *
+ * NOT transactional: MemoryStore has no CAS primitive, so the read-classify-
+ * write sequence can race a concurrent same-identity auto-write. Worst case is
+ * the pre-existing two-actives state, which self-heals on the next auto-write
+ * or approval of that identity.
+ */
+export declare function approveWithReconcile(store: MemoryStore, id: string, opts: {
+    readonly identityKeys: readonly string[];
+    readonly now: string;
+}): Promise<ApproveResult>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEvE,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AAEtF;;;;;;;gEAOgE;AAChE,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,CAY5D;AAED,MAAM,MAAM,OAAO,GACf;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,GACb;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAA;AAIzC,4JAA4J;AAC5J,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,SAAS,YAAY,EAAE,EACnC,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,OAAO,CAMT;AAQD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS,CAAA;IACvD,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAA;IAC5C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE;IAAE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACvE,OAAO,CAAC,aAAa,CAAC,CAqDxB"}

package/dist/reconcile.js

@@ -0,0 +1,110 @@
+/** Per-kind write discipline. Semantic facts reconcile (identity match →
+ *  update/supersede); episodic events append (a later episode never
+ *  contradicts an earlier one); reflection insights append too — distillation
+ *  ACCUMULATES insights, and a later insight never contradicts an earlier one
+ *  (superseding stale insights is a future concern). Procedural alone is typed
+ *  but not yet wired — throwing beats baking in accidental semantics.
+ *  Mirrored inline in packages/core/src/capabilities/built-in/memory.ts
+ *  remember (core can't import this package) — keep in sync. */
+export function writePolicyFor(kind) {
+    switch (kind) {
+        case "semantic":
+            return { mode: "reconcile" };
+        case "episodic":
+        case "reflection":
+            return { mode: "append" };
+        default:
+            throw new Error(`memory kind '${kind}' is not yet wired (semantic, episodic and reflection are)`);
+    }
+}
+function identityOf(data, keys) {
+    return keys.map((k) => JSON.stringify(data[k] ?? null)).join(" ");
+}
+/** Deterministic write classification (no LLM): ADD if no identity match; UPDATE if identity+data equal; SUPERSEDE if identity matches but data differs. */
+export function classifyWrite(incoming, candidates, identityKeys) {
+    const incomingId = identityOf(incoming.data, identityKeys);
+    const match = candidates.find((c) => identityOf(c.data, identityKeys) === incomingId);
+    if (!match)
+        return { op: "add" };
+    const same = JSON.stringify(match.data) === JSON.stringify(incoming.data);
+    return same ? { op: "update", targetId: match.id } : { op: "supersede", targetId: match.id };
+}
+/** Upper bound on active rows scanned for an identity match during approval.
+ *  Namespaces beyond this size would silently skip reconciliation for the
+ *  overflow rows — accepted trade-off: real namespaces are orders of magnitude
+ *  smaller, and an unbounded scan risks pathological reads. */
+const ACTIVE_SCAN_LIMIT = 10_000;
+/**
+ * Approve a candidate WITH supersede reconciliation (fixes the two-actives bug):
+ * same identity + different data → the old active row is superseded; same
+ * identity + identical data → the candidate is dropped (dedupe); no identity
+ * match → plain activation. Used by `b4 memory approve` and the inspector —
+ * the capability's auto-write path keeps its own inline logic by design.
+ * Append-kind candidates (per writePolicyFor, e.g. episodic) bypass
+ * reconciliation entirely — approval is a plain activation, no identity scan.
+ *
+ * NOT transactional: MemoryStore has no CAS primitive, so the read-classify-
+ * write sequence can race a concurrent same-identity auto-write. Worst case is
+ * the pre-existing two-actives state, which self-heals on the next auto-write
+ * or approval of that identity.
+ */
+export async function approveWithReconcile(store, id, opts) {
+    const candidate = await store.get(id);
+    if (!candidate)
+        throw new Error(`memory ${id} not found`);
+    if (candidate.status !== "candidate")
+        throw new Error(`memory ${id} is '${candidate.status}', not a candidate`);
+    if (writePolicyFor(candidate.kind).mode === "append") {
+        // Append-only kinds: approval is a plain activation — no identity scan.
+        await store.update(id, { status: "active", updatedAt: opts.now });
+        const approved = await store.get(id);
+        if (!approved)
+            throw new Error(`approved memory ${id} vanished`);
+        return { approved, action: "activated", superseded: [], identityKeys: opts.identityKeys };
+    }
+    const actives = await store.search({
+        namespace: candidate.namespace,
+        status: "active",
+        kind: candidate.kind,
+        limit: ACTIVE_SCAN_LIMIT,
+    });
+    const op = classifyWrite(candidate, actives, opts.identityKeys);
+    if (op.op === "update") {
+        const existing = actives.find((r) => r.id === op.targetId);
+        if (!existing)
+            throw new Error(`reconcile target ${op.targetId} vanished`);
+        // Deliberately does NOT refresh the surviving record (unlike the auto
+        // path's idempotent-update): approving a duplicate shouldn't reorder recency.
+        await store.delete(id);
+        return {
+            approved: existing,
+            action: "deduped",
+            superseded: [],
+            identityKeys: opts.identityKeys,
+        };
+    }
+    if (op.op === "supersede") {
+        const target = actives.find((r) => r.id === op.targetId);
+        if (!target)
+            throw new Error(`reconcile target ${op.targetId} vanished`);
+        // Activate first, then demote — same order as the capability's auto path
+        // (put active record → store.supersede). store.supersede also appends the
+        // demoted id to this record's `supersedes` via a Set (both sqlite and
+        // pgvector), so the explicit link here cannot double-append.
+        await store.update(id, {
+            status: "active",
+            updatedAt: opts.now,
+            supersedes: [...(candidate.supersedes ?? []), target.id],
+        });
+        await store.supersede(target.id, id);
+        const approved = await store.get(id);
+        if (!approved)
+            throw new Error(`approved memory ${id} vanished`);
+        return { approved, action: "superseded", superseded: [target], identityKeys: opts.identityKeys };
+    }
+    await store.update(id, { status: "active", updatedAt: opts.now });
+    const approved = await store.get(id);
+    if (!approved)
+        throw new Error(`approved memory ${id} vanished`);
+    return { approved, action: "activated", superseded: [], identityKeys: opts.identityKeys };
+}

package/dist/score.d.ts

@@ -0,0 +1,54 @@
+export interface RecallWeights {
+    readonly relevance?: number;
+    readonly recency?: number;
+    readonly confidence?: number;
+}
+export interface RecallRankingOptions {
+    readonly weights?: RecallWeights;
+    readonly recencyHalfLifeMs?: number;
+    readonly candidatePool?: number;
+}
+export declare const DEFAULT_RECALL_WEIGHTS: {
+    readonly relevance: 0.6;
+    readonly recency: 0.3;
+    readonly confidence: 0.1;
+};
+export declare const DEFAULT_RECENCY_HALF_LIFE_MS: number;
+export declare const DEFAULT_CANDIDATE_POOL = 256;
+/**
+ * BM25-smoothed inverse document frequency. Always positive — a token present
+ * in every memory (df = corpusSize) still carries a small weight rather than
+ * zeroing out or going negative (as unsmoothed idf would).
+ */
+export declare function idf(df: number, corpusSize: number): number;
+/**
+ * Exponential recency decay in (0, 1]. age = referenceMs − updatedMs, clamped ≥ 0;
+ * invalid/absent timestamps degrade to age 0 (decay 1). Non-positive/non-finite
+ * halfLife falls back to the default.
+ */
+export declare function recencyDecay(updatedAt: string, referenceNow: string, halfLifeMs?: number): number;
+/**
+ * Composite recall score: wRel·relevance + wRec·recency + wConf·confidence.
+ *
+ * relevance = Σ idf(matched query tokens) / Σ idf(all query tokens) — the
+ * fraction of the query's information this memory matches (0..1). Query
+ * tokens matching nothing inflate only the shared denominator, so relative
+ * ordering is unaffected.
+ *
+ * recency = 2^(−age / halfLife), age measured from `referenceNow` back to
+ * `updatedAt`, clamped ≥ 0. Invalid timestamps degrade to age 0. A
+ * non-positive or non-finite halfLifeMs falls back to the default.
+ *
+ * `queryTokens` are expected to be deduplicated, as produced by `tokenize()`.
+ */
+export declare function scoreMemory(args: {
+    readonly memoryTokens: ReadonlySet<string>;
+    readonly queryTokens: readonly string[];
+    readonly dfByToken: ReadonlyMap<string, number>;
+    readonly corpusSize: number;
+    readonly updatedAt: string;
+    readonly confidence: number;
+    readonly referenceNow: string;
+    readonly options?: RecallRankingOptions;
+}): number;
+//# sourceMappingURL=score.d.ts.map

package/dist/score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.d.ts","sourceRoot":"","sources":["../src/score.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,eAAO,MAAM,sBAAsB;aACjC,SAAS,EAAE,GAAG;aACd,OAAO,EAAE,GAAG;aACZ,UAAU,EAAE,GAAG;CACP,CAAA;AAEV,eAAO,MAAM,4BAA4B,QAA2B,CAAA;AACpE,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAEzC;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAI1D;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CASjG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC1C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAA;CACxC,GAAG,MAAM,CAiBT"}

package/dist/score.js

@@ -0,0 +1,66 @@
+// Pure recall scoring — no I/O, no clock, no randomness. Deterministic by
+// construction so aimock fixtures and eval replays stay stable. See
+// docs/superpowers/specs/2026-07-05-smarter-recall-design.md.
+export const DEFAULT_RECALL_WEIGHTS = {
+    relevance: 0.6,
+    recency: 0.3,
+    confidence: 0.1,
+};
+export const DEFAULT_RECENCY_HALF_LIFE_MS = 14 * 24 * 60 * 60 * 1000;
+export const DEFAULT_CANDIDATE_POOL = 256;
+/**
+ * BM25-smoothed inverse document frequency. Always positive — a token present
+ * in every memory (df = corpusSize) still carries a small weight rather than
+ * zeroing out or going negative (as unsmoothed idf would).
+ */
+export function idf(df, corpusSize) {
+    const d = Math.max(0, df);
+    const n = Math.max(d, corpusSize);
+    return Math.log(1 + (n - d + 0.5) / (d + 0.5));
+}
+function clamp01(v) {
+    return Number.isFinite(v) ? (v < 0 ? 0 : v > 1 ? 1 : v) : 0;
+}
+/**
+ * Exponential recency decay in (0, 1]. age = referenceMs − updatedMs, clamped ≥ 0;
+ * invalid/absent timestamps degrade to age 0 (decay 1). Non-positive/non-finite
+ * halfLife falls back to the default.
+ */
+export function recencyDecay(updatedAt, referenceNow, halfLifeMs) {
+    const hl = typeof halfLifeMs === "number" && Number.isFinite(halfLifeMs) && halfLifeMs > 0
+        ? halfLifeMs
+        : DEFAULT_RECENCY_HALF_LIFE_MS;
+    const ref = Date.parse(referenceNow);
+    const upd = Date.parse(updatedAt);
+    const ageMs = Number.isNaN(ref) || Number.isNaN(upd) ? 0 : Math.max(0, ref - upd);
+    return 2 ** (-ageMs / hl);
+}
+/**
+ * Composite recall score: wRel·relevance + wRec·recency + wConf·confidence.
+ *
+ * relevance = Σ idf(matched query tokens) / Σ idf(all query tokens) — the
+ * fraction of the query's information this memory matches (0..1). Query
+ * tokens matching nothing inflate only the shared denominator, so relative
+ * ordering is unaffected.
+ *
+ * recency = 2^(−age / halfLife), age measured from `referenceNow` back to
+ * `updatedAt`, clamped ≥ 0. Invalid timestamps degrade to age 0. A
+ * non-positive or non-finite halfLifeMs falls back to the default.
+ *
+ * `queryTokens` are expected to be deduplicated, as produced by `tokenize()`.
+ */
+export function scoreMemory(args) {
+    const weights = { ...DEFAULT_RECALL_WEIGHTS, ...args.options?.weights };
+    let matchedIdf = 0;
+    let totalIdf = 0;
+    for (const t of args.queryTokens) {
+        const w = idf(args.dfByToken.get(t) ?? 0, args.corpusSize);
+        totalIdf += w;
+        if (args.memoryTokens.has(t))
+            matchedIdf += w;
+    }
+    const relevance = totalIdf > 0 ? matchedIdf / totalIdf : 0;
+    const recency = recencyDecay(args.updatedAt, args.referenceNow, args.options?.recencyHalfLifeMs);
+    const confidence = clamp01(args.confidence);
+    return weights.relevance * relevance + weights.recency * recency + weights.confidence * confidence;
+}

package/dist/sqlite-browse-sql.d.ts

@@ -0,0 +1,30 @@
+import type { SQLInputValue } from "node:sqlite";
+import type { BrowseCursorPayload } from "./browse-cursor.js";
+import type { ResolvedBrowseSort } from "./browse-order.js";
+import type { BrowseFilter } from "./types.js";
+/**
+ * Append one normalized filter to a SQLite WHERE list. Column names come from this
+ * switch and nowhere else; every value is bound.
+ *
+ * Text matching uses literal substring primitives (`instr`, `substr`) rather than
+ * LIKE, so `%`, `_` and `\` in a user's search term need no escaping and can never
+ * change the predicate. Case-insensitivity is `lower()`, which folds ASCII only in
+ * SQLite without ICU: `lower('CAFÉ')` is `'cafÉ'` here and `'café'` in Postgres, so a
+ * non-ASCII needle matches on one backend and misses on the other. The conformance
+ * suite asserts ONE reading for both stores and therefore cannot pin that divergence —
+ * every fixture there is ASCII, and this comment is the whole documentation of it.
+ */
+export declare function appendSqliteBrowseFilter(filter: BrowseFilter, where: string[], params: SQLInputValue[]): void;
+/**
+ * Everything strictly after `cursor` in `order`, as a WHERE fragment.
+ *
+ * Row-value comparisons cannot express mixed asc/desc, so this is the expanded
+ * OR-chain — plus a REDUNDANT leading range guard. The guard is logically implied by
+ * the chain and is still mandatory: it is what lets the planner seek the leading index
+ * column instead of scanning the whole index (0.54 ms vs 22.8 ms at 1M rows).
+ *
+ * Parameters are pushed in the exact textual order they appear, so the caller can
+ * concatenate this fragment after its filter clauses without renumbering.
+ */
+export declare function sqliteKeysetWhere(order: readonly ResolvedBrowseSort[], cursor: BrowseCursorPayload, params: SQLInputValue[]): string;
+//# sourceMappingURL=sqlite-browse-sql.d.ts.map

package/dist/sqlite-browse-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-browse-sql.d.ts","sourceRoot":"","sources":["../src/sqlite-browse-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAG3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,aAAa,EAAE,GACtB,IAAI,CA8HN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,kBAAkB,EAAE,EACpC,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,aAAa,EAAE,GACtB,MAAM,CAiCR"}

package/dist/sqlite-browse-sql.js

@@ -0,0 +1,178 @@
+import { namespacePrefixUpperBound, utcDayAfter, utcDayStart } from "./browse-range.js";
+import { BrowseQueryError } from "./browse-validate.js";
+/**
+ * Append one normalized filter to a SQLite WHERE list. Column names come from this
+ * switch and nowhere else; every value is bound.
+ *
+ * Text matching uses literal substring primitives (`instr`, `substr`) rather than
+ * LIKE, so `%`, `_` and `\` in a user's search term need no escaping and can never
+ * change the predicate. Case-insensitivity is `lower()`, which folds ASCII only in
+ * SQLite without ICU: `lower('CAFÉ')` is `'cafÉ'` here and `'café'` in Postgres, so a
+ * non-ASCII needle matches on one backend and misses on the other. The conformance
+ * suite asserts ONE reading for both stores and therefore cannot pin that divergence —
+ * every fixture there is ASCII, and this comment is the whole documentation of it.
+ */
+export function appendSqliteBrowseFilter(filter, where, params) {
+    switch (filter.field) {
+        case "status":
+        case "kind": {
+            const column = filter.field;
+            const placeholders = filter.values.map(() => "?").join(",");
+            where.push(filter.op === "in"
+                ? `${column} IN (${placeholders})`
+                : `${column} NOT IN (${placeholders})`);
+            params.push(...filter.values);
+            return;
+        }
+        case "content": {
+            switch (filter.op) {
+                case "contains":
+                    where.push("instr(lower(content), lower(?)) > 0");
+                    params.push(filter.value);
+                    return;
+                case "notContains":
+                    where.push("instr(lower(content), lower(?)) = 0");
+                    params.push(filter.value);
+                    return;
+                case "startsWith":
+                    where.push("instr(lower(content), lower(?)) = 1");
+                    params.push(filter.value);
+                    return;
+                case "endsWith":
+                    // Negative substr() takes the LAST n characters; a needle longer than the
+                    // content yields the whole content, which cannot equal it. Correct by
+                    // construction, no length guard needed.
+                    where.push("substr(lower(content), -length(?)) = lower(?)");
+                    params.push(filter.value, filter.value);
+                    return;
+                case "equals":
+                    where.push("lower(content) = lower(?)");
+                    params.push(filter.value);
+                    return;
+                case "notEquals":
+                    where.push("lower(content) <> lower(?)");
+                    params.push(filter.value);
+                    return;
+                default: {
+                    // Every op has its own case above, so this binding is `never` today: an op
+                    // added to the union stops the BUILD here rather than reaching a caller as
+                    // `<>` — wrong rows, no signal, and two dialects to forget.
+                    const unmapped = filter;
+                    throw new BrowseQueryError(`unhandled content filter op: ${JSON.stringify(unmapped.op)}`);
+                }
+            }
+        }
+        case "namespace": {
+            if (filter.op === "equals") {
+                where.push("namespace = ?");
+                params.push(filter.value);
+                return;
+            }
+            // Byte-exact prefix as a half-open RANGE: metacharacters stay literal and the
+            // comparison stays case-sensitive. Sargable, with the same ORDER BY trade the
+            // store's own `namespacePrefix` documents.
+            const upper = namespacePrefixUpperBound(filter.value);
+            where.push(upper === undefined ? "namespace >= ?" : "namespace >= ? AND namespace < ?");
+            params.push(filter.value);
+            if (upper !== undefined)
+                params.push(upper);
+            return;
+        }
+        case "confidence": {
+            if (filter.op === "between") {
+                // Inclusive on both ends, matching the grid's local `between`.
+                where.push("confidence >= ? AND confidence <= ?");
+                params.push(filter.min, filter.max);
+                return;
+            }
+            const operators = { eq: "=", neq: "<>", gt: ">", gte: ">=", lt: "<", lte: "<=" };
+            where.push(`confidence ${operators[filter.op]} ?`);
+            params.push(filter.value);
+            return;
+        }
+        case "updatedAt": {
+            // Bounds are the fixed-width `YYYY-MM-DDT00:00:00.000Z` form and the comparison
+            // is lexicographic, so a row buckets to the right UTC day only while its stored
+            // updated_at is that same form. Nothing enforces that — MemoryRecord types
+            // updatedAt as a bare string — so `2026-08-02T20:00:00-05:00` lands in the day it
+            // READS as, not the day it is. Both schemas flag the unnormalized column for
+            // ORDER BY; here it decides membership, not just order.
+            switch (filter.op) {
+                case "onDay":
+                    where.push("updated_at >= ? AND updated_at < ?");
+                    params.push(utcDayStart(filter.day), utcDayAfter(filter.day));
+                    return;
+                case "beforeDay":
+                    where.push("updated_at < ?");
+                    params.push(utcDayStart(filter.day));
+                    return;
+                case "afterDay":
+                    where.push("updated_at >= ?");
+                    params.push(utcDayAfter(filter.day));
+                    return;
+                case "betweenDays":
+                    // Inclusive of BOTH days.
+                    where.push("updated_at >= ? AND updated_at < ?");
+                    params.push(utcDayStart(filter.fromDay), utcDayAfter(filter.untilDay));
+                    return;
+                default: {
+                    const unmapped = filter;
+                    throw new BrowseQueryError(`unhandled updatedAt filter op: ${JSON.stringify(unmapped.op)}`);
+                }
+            }
+        }
+        default: {
+            // Every field has its own case above, so this binding is `never`: a field added
+            // to the union stops the BUILD here rather than reaching a caller unfiltered.
+            // Still throws at runtime — the untyped HTTP caller reaches this too, and
+            // BrowseQueryError rather than Error because that boundary maps a rejection by
+            // NAME: a plain Error 500s where this must 400.
+            const unmapped = filter;
+            throw new BrowseQueryError(`unhandled browse filter field: ${unmapped.field}`);
+        }
+    }
+}
+/**
+ * Everything strictly after `cursor` in `order`, as a WHERE fragment.
+ *
+ * Row-value comparisons cannot express mixed asc/desc, so this is the expanded
+ * OR-chain — plus a REDUNDANT leading range guard. The guard is logically implied by
+ * the chain and is still mandatory: it is what lets the planner seek the leading index
+ * column instead of scanning the whole index (0.54 ms vs 22.8 ms at 1M rows).
+ *
+ * Parameters are pushed in the exact textual order they appear, so the caller can
+ * concatenate this fragment after its filter clauses without renumbering.
+ */
+export function sqliteKeysetWhere(order, cursor, params) {
+    const first = order[0];
+    // A plain Error 500s at the boundary that maps this module's throws to 400 by name.
+    if (!first)
+        throw new BrowseQueryError("keyset requires at least one ordered key");
+    const guard = `${first.column} ${first.dir === "desc" ? "<=" : ">="} ?`;
+    params.push(cursor.key[0]);
+    const terms = [];
+    for (let i = 0; i < order.length; i += 1) {
+        const parts = [];
+        for (let j = 0; j < i; j += 1) {
+            // Narrowed rather than `order[j]?.column`: out of range this throws, where
+            // optional chaining would interpolate the literal identifier `undefined`.
+            const entry = order[j];
+            parts.push(`${entry.column} = ?`);
+            params.push(cursor.key[j]);
+        }
+        const entry = order[i];
+        parts.push(`${entry.column} ${entry.dir === "desc" ? "<" : ">"} ?`);
+        params.push(cursor.key[i]);
+        terms.push(parts.length === 1 ? parts[0] : `(${parts.join(" AND ")})`);
+    }
+    const tail = [];
+    for (let j = 0; j < order.length; j += 1) {
+        const entry = order[j];
+        tail.push(`${entry.column} = ?`);
+        params.push(cursor.key[j]);
+    }
+    tail.push("id > ?");
+    params.push(cursor.id);
+    terms.push(`(${tail.join(" AND ")})`);
+    return `${guard} AND (${terms.join(" OR ")})`;
+}

package/dist/sqlite-store.d.ts

@@ -0,0 +1,10 @@
+import { type RecallRankingOptions } from "./score.js";
+import type { MemoryStore, VectorRankingOptions } from "./types.js";
+export declare function sqliteMemoryStore(opts: {
+    path: string;
+    /** Recall ranking tuning; all fields defaulted. See score.ts. */
+    recall?: RecallRankingOptions;
+    /** Store-level hybrid tuning; used when a query omits `vector`. All fields defaulted. */
+    vector?: VectorRankingOptions;
+}): MemoryStore;
+//# sourceMappingURL=sqlite-store.d.ts.map

package/dist/sqlite-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-store.d.ts","sourceRoot":"","sources":["../src/sqlite-store.ts"],"names":[],"mappings":"AAeA,OAAO,EAA0B,KAAK,oBAAoB,EAAsB,MAAM,YAAY,CAAA;AAGlG,OAAO,KAAK,EAA6B,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AA+I9F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,iEAAiE;IACjE,MAAM,CAAC,EAAE,oBAAoB,CAAA;IAC7B,yFAAyF;IACzF,MAAM,CAAC,EAAE,oBAAoB,CAAA;CAC9B,GAAG,WAAW,CAged"}