@mercury-fw/core 0.25.0

package/src/memory/episodic-store.ts

@@ -0,0 +1,183 @@
+/**
+ * Layer 3 (Qdrant) episodic storage: one point per closed,
+ * summarized session — a raw, dated "what happened", not an
+ * interpretation. Consolidation into semantic memory (per-topic
+ * promotion into the wiki) is a separate, later concern that
+ * reads from this collection; this module only ever writes to it.
+ *
+ * `QdrantClientLike` describes only the subset of `@qdrant/js-client-rest`'s
+ * `QdrantClient` this file actually calls — real client instances satisfy
+ * it structurally, tests use a plain object instead of a real connection.
+ */
+export type QdrantClientLike = {
+  getCollections(): Promise<{ collections: Array<{ name: string }> }>;
+  createCollection(
+    name: string,
+    params: { vectors: { size: number; distance: "Cosine" | "Euclid" | "Dot" | "Manhattan" } },
+  ): Promise<unknown>;
+  upsert(
+    name: string,
+    params: { points: Array<{ id: string; vector: number[]; payload: Record<string, unknown> }> },
+  ): Promise<unknown>;
+  /** @qdrant/js-client-rest 1.19 removed `search` in favour of the universal
+   * `query` endpoint: the vector moves to `query`, and results come back under
+   * `.points` instead of as a bare array. */
+  query(
+    name: string,
+    params: { query: number[]; filter: Record<string, unknown>; limit: number; with_payload: boolean },
+  ): Promise<{ points: Array<{ id: string | number; score: number; payload?: Record<string, unknown> | null }> }>;
+  /**
+   * Optional — not part of the similarity-search surface every caller
+   * needs, only used by `getLastSessionEpisodicSummaries` below. Optional
+   * so `semantic-facts-store.ts`/`tool-corrections-store.ts` (which share
+   * this type but never call `scroll`) don't need a stub in every test
+   * fixture.
+   */
+  scroll?(
+    name: string,
+    params: {
+      filter: Record<string, unknown>;
+      order_by: { key: string; direction: "asc" | "desc" };
+      limit: number;
+      /** Opaque pagination cursor (from a prior page's `next_page_offset`). */
+      offset?: string | number | Record<string, unknown> | null;
+      /** Whether to return point payloads (`listVerbatimBySession` needs them). */
+      with_payload?: boolean;
+    },
+  ): Promise<{
+    points: Array<{ id: string | number; payload?: Record<string, unknown> | null }>;
+    next_page_offset?: string | number | Record<string, unknown> | null;
+  }>;
+  /** Optional — same reasoning as `scroll` above: only `ensureEpisodicCollection` needs it. */
+  createPayloadIndex?(name: string, params: { field_name: string; field_schema: "datetime" | "keyword" }): Promise<unknown>;
+};
+
+/**
+ * Creates `collectionName` (cosine distance, `vectorSize`-dim) if it
+ * doesn't already exist, then ensures the `timestamp`/`userId` payload
+ * indexes exist regardless — `getLastSessionEpisodicSummaries`'s
+ * `order_by`/filter scroll queries fail with an HTTP 400 without them.
+ * Idempotent either way (Qdrant no-ops re-creating an existing index), so
+ * safe to call on every startup, including against a collection that
+ * predates this fix.
+ */
+export async function ensureEpisodicCollection(
+  client: QdrantClientLike,
+  collectionName: string,
+  vectorSize: number,
+): Promise<void> {
+  const { collections } = await client.getCollections();
+  if (!collections.some((c) => c.name === collectionName)) {
+    await client.createCollection(collectionName, { vectors: { size: vectorSize, distance: "Cosine" } });
+  }
+  if (client.createPayloadIndex) {
+    await client.createPayloadIndex(collectionName, { field_name: "timestamp", field_schema: "datetime" });
+    await client.createPayloadIndex(collectionName, { field_name: "userId", field_schema: "keyword" });
+  }
+}
+
+export type EpisodicSummary = {
+  userId: string;
+  sessionKey: string;
+  summary: string;
+  timestamp: string;
+};
+
+/** Embeds `entry.summary` and upserts it as a new point in `collectionName`, payload carrying the full entry. */
+export async function storeEpisodicSummary(
+  client: QdrantClientLike,
+  collectionName: string,
+  embed: (text: string) => Promise<number[]>,
+  entry: EpisodicSummary,
+): Promise<void> {
+  const vector = await embed(entry.summary);
+  await client.upsert(collectionName, {
+    points: [
+      {
+        id: crypto.randomUUID(),
+        vector,
+        payload: { ...entry },
+      },
+    ],
+  });
+}
+
+const DEFAULT_SEARCH_LIMIT = 5;
+
+function isEpisodicSummary(payload: Record<string, unknown> | null): payload is EpisodicSummary {
+  return (
+    payload !== null &&
+    typeof payload.userId === "string" &&
+    typeof payload.sessionKey === "string" &&
+    typeof payload.summary === "string" &&
+    typeof payload.timestamp === "string"
+  );
+}
+
+/**
+ * Past episodic events for a specific user, most relevant to `queryText`
+ * (e.g. "notifications about KAN-123") — lets Mercury see how many times
+ * it already notified this user about a given item before composing a
+ * message. Not a general-purpose semantic consolidation/pattern-extraction
+ * engine (that doesn't exist here) — this only ever reads, never writes
+ * or promotes anything.
+ */
+export async function searchEpisodicMemory(
+  client: QdrantClientLike,
+  collectionName: string,
+  embed: (text: string) => Promise<number[]>,
+  query: { userId: string; queryText: string; limit?: number },
+): Promise<EpisodicSummary[]> {
+  const vector = await embed(query.queryText);
+  const results = await client.query(collectionName, {
+    query: vector,
+    filter: { must: [{ key: "userId", match: { value: query.userId } }] },
+    limit: query.limit ?? DEFAULT_SEARCH_LIMIT,
+    with_payload: true,
+  });
+  return results.points.map((r) => r.payload ?? null).filter(isEpisodicSummary);
+}
+
+const DEFAULT_SESSION_LIMIT = 3;
+
+/**
+ * The last closed session's episodic entries for `userId`, most recent
+ * first — up to `limit` entries, all sharing the same `sessionKey` as the
+ * single most recent entry. Used to seed a brand-new session's context
+ * primer with "what happened last time"; not similarity-scoped like
+ * `searchEpisodicMemory` (there's no query yet to compare against at
+ * session start). Returns an empty array (never throws) if the client
+ * doesn't support `scroll`, or if the user has no prior episodic entries —
+ * this is enrichment, the caller must work fine without it.
+ */
+export async function getLastSessionEpisodicSummaries(
+  client: QdrantClientLike,
+  collectionName: string,
+  query: { userId: string; limit?: number },
+): Promise<EpisodicSummary[]> {
+  if (!client.scroll) {
+    return [];
+  }
+
+  const latest = await client.scroll(collectionName, {
+    filter: { must: [{ key: "userId", match: { value: query.userId } }] },
+    order_by: { key: "timestamp", direction: "desc" },
+    limit: 1,
+  });
+  const mostRecent = latest.points[0]?.payload ?? null;
+  if (!isEpisodicSummary(mostRecent)) {
+    return [];
+  }
+
+  const session = await client.scroll(collectionName, {
+    filter: {
+      must: [
+        { key: "userId", match: { value: query.userId } },
+        { key: "sessionKey", match: { value: mostRecent.sessionKey } },
+      ],
+    },
+    order_by: { key: "timestamp", direction: "desc" },
+    limit: query.limit ?? DEFAULT_SESSION_LIMIT,
+  });
+  return session.points.map((p) => p.payload ?? null).filter(isEpisodicSummary);
+}

package/src/memory/memory-provider.ts

@@ -0,0 +1,98 @@
+/**
+ * The memory-provider seam (issue #4, built ahead of the broader #30
+ * design): a memory mechanism that hooks the turn — capturing the
+ * exchange after it happens, and contributing its own recall tools — kept
+ * behind a small interface so the composition root wires it like any
+ * other provider rather than hardwiring it into the pipeline. Only the two
+ * hooks #4 exercises live here; the wider generalization (priming,
+ * summarizer, wiki strategy as swappable providers) is deferred to #30.
+ *
+ * The one implementation today is the verbatim archive
+ * (`./verbatim-archive-store.ts`).
+ */
+import { tool, type Tool } from "ai";
+import { z } from "zod";
+import { appendVerbatimMessage, searchVerbatim } from "./verbatim-archive-store.ts";
+import type { QdrantClientLike } from "./episodic-store.ts";
+
+/** One side of an exchange to archive — the provider stamps its own durable timestamp. */
+export type VerbatimExchange = {
+  userId: string;
+  sessionKey: string;
+  role: "user" | "assistant";
+  content: string;
+};
+
+/** Per-turn identity a provider's recall tools are scoped to. `userId` is what makes recall cross-session. */
+export type MemoryProviderContext = {
+  sessionKey: string;
+  userId: string;
+};
+
+/**
+ * A memory mechanism the composition root can wire in. `captureExchange`
+ * runs after a turn resolves (post-message); `sessionTools` contributes
+ * model-invocable recall for the calling session. Both optional — a
+ * provider may only capture, or only recall.
+ */
+export type MemoryProvider = {
+  captureExchange?(exchange: VerbatimExchange): Promise<void>;
+  sessionTools?(ctx: MemoryProviderContext): Record<string, Tool>;
+};
+
+export type VerbatimArchiveProviderDeps = {
+  client: QdrantClientLike;
+  collectionName: string;
+  embed: (text: string) => Promise<number[]>;
+  /** Test seam; defaults to `() => new Date()`. The provider owns the durable ordering timestamp. */
+  now?: () => Date;
+};
+
+const RECALL_DEFAULT_LIMIT = 5;
+const RECALL_MAX_LIMIT = 20;
+
+/**
+ * Builds the verbatim-archive provider: captures every user/assistant
+ * message verbatim to its Qdrant collection, and exposes a
+ * `recall_verbatim` tool that similarity-searches that archive scoped to
+ * the calling user — letting a later session resurface what was actually
+ * said before, beyond the live history window.
+ */
+export function createVerbatimArchiveProvider(deps: VerbatimArchiveProviderDeps): MemoryProvider {
+  const now = deps.now ?? (() => new Date());
+  return {
+    captureExchange: async (exchange) => {
+      // An empty/whitespace-only message (e.g. a present()-only turn with no
+      // prose) has nothing to archive — skip it rather than store a
+      // meaningless point and embed an empty string.
+      if (exchange.content.trim() === "") {
+        return;
+      }
+      await appendVerbatimMessage(deps.client, deps.collectionName, deps.embed, {
+        ...exchange,
+        timestamp: now().toISOString(),
+      });
+    },
+    sessionTools: (ctx) => {
+      const recall_verbatim = tool({
+        description:
+          "Search the durable verbatim archive of what you and this user actually said in earlier " +
+          "conversations, beyond the current history window — e.g. 'what did we say about KAN-1 last week'. " +
+          "Returns real past messages with their timestamps; quote them, don't reconstruct from memory.",
+        inputSchema: z.object({
+          query: z.string().min(1),
+          limit: z.number().int().positive().max(RECALL_MAX_LIMIT).optional(),
+        }),
+        execute: async ({ query, limit }) => {
+          const messages = await searchVerbatim(deps.client, deps.collectionName, deps.embed, {
+            userId: ctx.userId,
+            queryText: query,
+            limit: limit ?? RECALL_DEFAULT_LIMIT,
+          });
+          return { ok: true as const, messages };
+        },
+      });
+      return { recall_verbatim };
+    },
+  };
+}

package/src/memory/semantic-facts-store.ts

@@ -0,0 +1,89 @@
+/**
+ * Layer 3 (Qdrant) semantic facts storage — one collection, separate from
+ * `episodic-store.ts`. Episodic points are a raw dated account of a whole
+ * session; semantic facts are `{topic, value}` pairs extracted from a
+ * session, clustered per user+topic, and deterministically promoted to a
+ * standing wiki note. This module only owns the collection lifecycle;
+ * extraction, clustering, and promotion are separate concerns built on
+ * top of it.
+ */
+import type { QdrantClientLike } from "./episodic-store.ts";
+
+/** Creates `collectionName` (cosine distance, `vectorSize`-dim) if it doesn't already exist — safe to call on every startup. */
+export async function ensureSemanticFactsCollection(
+  client: QdrantClientLike,
+  collectionName: string,
+  vectorSize: number,
+): Promise<void> {
+  const { collections } = await client.getCollections();
+  if (collections.some((c) => c.name === collectionName)) {
+    return;
+  }
+  await client.createCollection(collectionName, { vectors: { size: vectorSize, distance: "Cosine" } });
+}
+
+export type SemanticFactEntry = {
+  userId: string;
+  topic: string;
+  value: string;
+  timestamp: string;
+};
+
+/**
+ * Embeds `entry.topic` alone (never `topic + value`) and upserts it as a
+ * new point in `collectionName`, payload carrying the full entry. One
+ * point per extracted fact, never an update-in-place — consolidation
+ * reads the whole history back via `searchSemanticFactsByTopic` and
+ * decides what to promote.
+ */
+export async function storeSemanticFact(
+  client: QdrantClientLike,
+  collectionName: string,
+  embed: (text: string) => Promise<number[]>,
+  entry: SemanticFactEntry,
+): Promise<void> {
+  const vector = await embed(entry.topic);
+  await client.upsert(collectionName, {
+    points: [
+      {
+        id: crypto.randomUUID(),
+        vector,
+        payload: { ...entry },
+      },
+    ],
+  });
+}
+
+const DEFAULT_SEARCH_LIMIT = 5;
+
+function isSemanticFactEntry(payload: Record<string, unknown> | null): payload is SemanticFactEntry {
+  return (
+    payload !== null &&
+    typeof payload.userId === "string" &&
+    typeof payload.topic === "string" &&
+    typeof payload.value === "string" &&
+    typeof payload.timestamp === "string"
+  );
+}
+
+/**
+ * Past facts for a specific user, clustered by topic similarity — the
+ * read side consolidation uses to gather "every occurrence of roughly
+ * this topic" before counting a dominant value. Filters by userId so
+ * one user's facts never leak into another's cluster.
+ */
+export async function searchSemanticFactsByTopic(
+  client: QdrantClientLike,
+  collectionName: string,
+  embed: (text: string) => Promise<number[]>,
+  query: { userId: string; topic: string; limit?: number },
+): Promise<SemanticFactEntry[]> {
+  const vector = await embed(query.topic);
+  const results = await client.query(collectionName, {
+    query: vector,
+    filter: { must: [{ key: "userId", match: { value: query.userId } }] },
+    limit: query.limit ?? DEFAULT_SEARCH_LIMIT,
+    with_payload: true,
+  });
+  return results.points.map((r) => r.payload ?? null).filter(isSemanticFactEntry);
+}

package/src/memory/tool-corrections-store.ts

@@ -0,0 +1,72 @@
+/**
+ * Layer 3 (Qdrant) procedural-correction staging — separate collection
+ * from `semantic-facts-store.ts`: that one is keyed by userId (a fact
+ * about a specific person), this one is keyed by tool (a fact about a
+ * CLI, true for whoever uses it next). Kept as its own collection rather
+ * than overloading `semantic-facts-store.ts`'s `userId` field with a tool
+ * name — a tool name in a field called `userId` would be a standing
+ * source of confusion for anyone reading this collection later.
+ */
+import type { QdrantClientLike } from "./episodic-store.ts";
+
+/** Creates `collectionName` (cosine distance, `vectorSize`-dim) if it doesn't already exist — safe to call on every startup. */
+export async function ensureToolCorrectionsCollection(
+  client: QdrantClientLike,
+  collectionName: string,
+  vectorSize: number,
+): Promise<void> {
+  const { collections } = await client.getCollections();
+  if (collections.some((c) => c.name === collectionName)) {
+    return;
+  }
+  await client.createCollection(collectionName, { vectors: { size: vectorSize, distance: "Cosine" } });
+}
+
+export type ToolCorrectionEntry = {
+  tool: string;
+  topic: string;
+  value: string;
+  timestamp: string;
+};
+
+/** Embeds `entry.topic` alone (never `topic + value`), same reasoning as `storeSemanticFact` — upserts a new point, never an update-in-place. */
+export async function storeToolCorrection(
+  client: QdrantClientLike,
+  collectionName: string,
+  embed: (text: string) => Promise<number[]>,
+  entry: ToolCorrectionEntry,
+): Promise<void> {
+  const vector = await embed(entry.topic);
+  await client.upsert(collectionName, {
+    points: [{ id: crypto.randomUUID(), vector, payload: { ...entry } }],
+  });
+}
+
+const DEFAULT_SEARCH_LIMIT = 5;
+
+function isToolCorrectionEntry(payload: Record<string, unknown> | null): payload is ToolCorrectionEntry {
+  return (
+    payload !== null &&
+    typeof payload.tool === "string" &&
+    typeof payload.topic === "string" &&
+    typeof payload.value === "string" &&
+    typeof payload.timestamp === "string"
+  );
+}
+
+/** Past corrections for a specific tool, clustered by topic similarity — filters by `tool` so one tool's corrections never leak into another's cluster. */
+export async function searchToolCorrectionsByTopic(
+  client: QdrantClientLike,
+  collectionName: string,
+  embed: (text: string) => Promise<number[]>,
+  query: { tool: string; topic: string; limit?: number },
+): Promise<ToolCorrectionEntry[]> {
+  const vector = await embed(query.topic);
+  const results = await client.query(collectionName, {
+    query: vector,
+    filter: { must: [{ key: "tool", match: { value: query.tool } }] },
+    limit: query.limit ?? DEFAULT_SEARCH_LIMIT,
+    with_payload: true,
+  });
+  return results.points.map((r) => r.payload ?? null).filter(isToolCorrectionEntry);
+}

package/src/memory/verbatim-archive-store.ts

@@ -0,0 +1,202 @@
+/**
+ * The verbatim conversation archive (issue #4): a durable, lossless
+ * Qdrant collection holding the complete user↔model exchange, one point
+ * per message, distinct from every other memory layer.
+ *
+ * How it differs from the neighbours in this directory:
+ * - Layer-1 history (`../session/history.ts`) is a sliding window that
+ *   summarizes itself away — lossy by design.
+ * - The episodic store (`./episodic-store.ts`) captures a *summary* of a
+ *   closed session — derived, not raw.
+ * This archive instead keeps what was actually said, verbatim, so a later
+ * session can resurface it and re-read it in light of new facts. It only
+ * ever appends and reads; nothing here evicts (retention bounding is a
+ * separate, later concern).
+ *
+ * Reuses `episodic-store.ts`'s structural `QdrantClientLike` — the same
+ * subset of the real client every store in this directory shares.
+ */
+import type { QdrantClientLike } from "./episodic-store.ts";
+
+/**
+ * Creates `collectionName` (cosine distance, `vectorSize`-dim) if it
+ * doesn't already exist, then ensures the `userId` keyword payload index
+ * regardless — `searchVerbatim` filters by `userId` server-side, and the
+ * index keeps that filter usable as the archive grows. Idempotent
+ * (Qdrant no-ops re-creating an existing index), so safe to call on every
+ * startup, including against a collection created before this existed.
+ */
+export async function ensureVerbatimCollection(
+  client: QdrantClientLike,
+  collectionName: string,
+  vectorSize: number,
+): Promise<void> {
+  const { collections } = await client.getCollections();
+  if (!collections.some((c) => c.name === collectionName)) {
+    await client.createCollection(collectionName, { vectors: { size: vectorSize, distance: "Cosine" } });
+  }
+  if (client.createPayloadIndex) {
+    // `userId` for searchVerbatim's per-person filter; `sessionKey` for
+    // listVerbatimBySession's per-conversation filter; `timestamp` (datetime)
+    // for its chronological `order_by`. Qdrant rejects a filter/order_by on an
+    // unindexed field with a 400, so all three must exist.
+    await client.createPayloadIndex(collectionName, { field_name: "userId", field_schema: "keyword" });
+    await client.createPayloadIndex(collectionName, { field_name: "sessionKey", field_schema: "keyword" });
+    await client.createPayloadIndex(collectionName, { field_name: "timestamp", field_schema: "datetime" });
+  }
+}
+
+/** A single verbatim message as it was emitted in chat. `timestamp` (ISO 8601, ms precision) is the durable ordering key. */
+export type VerbatimMessage = {
+  userId: string;
+  sessionKey: string;
+  role: "user" | "assistant";
+  content: string;
+  timestamp: string;
+};
+
+/** Embeds `entry.content` and upserts it as a new point in `collectionName`, payload carrying the full verbatim message. */
+export async function appendVerbatimMessage(
+  client: QdrantClientLike,
+  collectionName: string,
+  embed: (text: string) => Promise<number[]>,
+  entry: VerbatimMessage,
+): Promise<void> {
+  const vector = await embed(entry.content);
+  await client.upsert(collectionName, {
+    points: [
+      {
+        id: crypto.randomUUID(),
+        vector,
+        payload: { ...entry },
+      },
+    ],
+  });
+}
+
+const DEFAULT_SEARCH_LIMIT = 5;
+
+/** Narrows an arbitrary payload to a `VerbatimMessage`, rejecting null/malformed points (e.g. from an older schema). */
+function isVerbatimMessage(payload: Record<string, unknown> | null): payload is VerbatimMessage {
+  return (
+    payload !== null &&
+    typeof payload.userId === "string" &&
+    typeof payload.sessionKey === "string" &&
+    (payload.role === "user" || payload.role === "assistant") &&
+    typeof payload.content === "string" &&
+    typeof payload.timestamp === "string"
+  );
+}
+
+/**
+ * The verbatim messages for a specific user most relevant to `queryText`
+ * — e.g. "what did we say about KAN-1 last week". Filtered by `userId` so
+ * one user's transcript never leaks into another's. Only reads; returns
+ * the raw messages, ordering left to the caller (each carries its own
+ * `timestamp`).
+ */
+export async function searchVerbatim(
+  client: QdrantClientLike,
+  collectionName: string,
+  embed: (text: string) => Promise<number[]>,
+  query: { userId: string; queryText: string; limit?: number },
+): Promise<VerbatimMessage[]> {
+  const vector = await embed(query.queryText);
+  const results = await client.query(collectionName, {
+    query: vector,
+    filter: { must: [{ key: "userId", match: { value: query.userId } }] },
+    limit: query.limit ?? DEFAULT_SEARCH_LIMIT,
+    with_payload: true,
+  });
+  return results.points.map((r) => r.payload ?? null).filter(isVerbatimMessage);
+}
+
+/**
+ * How many recent messages `listVerbatimSessions` scans to build the
+ * conversation list. Qdrant has no native DISTINCT, so we dedup client-side
+ * over a bounded window of the newest points — a conversation whose newest
+ * message falls outside this window won't appear. Ample for a live-testing UI
+ * sidebar; retention/aggregation is a separate later concern.
+ */
+const SESSION_SCAN_LIMIT = 500;
+
+/** One conversation in the list view: its key, the timestamp of its most recent message, and a short preview of it. */
+export type VerbatimSession = {
+  sessionKey: string;
+  lastTimestamp: string;
+  preview: string;
+};
+
+/** Max characters of the most-recent message shown as a conversation's preview. */
+const PREVIEW_CHARS = 120;
+
+/**
+ * The known conversations, most-recently-active first — the sidebar a UI shows
+ * to switch between conversations. Scrolls the newest `SESSION_SCAN_LIMIT`
+ * messages (timestamp desc) and dedups by `sessionKey`, keeping each
+ * conversation's most recent message for its timestamp and preview, then caps
+ * the result at `limit`. Returns empty if the client can't scroll.
+ */
+export async function listVerbatimSessions(
+  client: QdrantClientLike,
+  collectionName: string,
+  query: { limit: number },
+): Promise<{ conversations: VerbatimSession[] }> {
+  if (!client.scroll) {
+    return { conversations: [] };
+  }
+  const result = await client.scroll(collectionName, {
+    filter: { must: [] },
+    order_by: { key: "timestamp", direction: "desc" },
+    limit: SESSION_SCAN_LIMIT,
+    with_payload: true,
+  });
+  const messages = result.points.map((p) => p.payload ?? null).filter(isVerbatimMessage);
+  const seen = new Map<string, VerbatimSession>();
+  for (const m of messages) {
+    if (seen.has(m.sessionKey)) {
+      continue; // desc order → first occurrence is the most recent
+    }
+    seen.set(m.sessionKey, {
+      sessionKey: m.sessionKey,
+      lastTimestamp: m.timestamp,
+      preview: m.content.length <= PREVIEW_CHARS ? m.content : `${m.content.slice(0, PREVIEW_CHARS)}…`,
+    });
+  }
+  return { conversations: [...seen.values()].slice(0, query.limit) };
+}
+
+/** A page of a conversation's verbatim messages, plus the opaque cursor for the next page (null when exhausted). */
+export type VerbatimPage = {
+  messages: VerbatimMessage[];
+  nextOffset: string | number | Record<string, unknown> | null;
+};
+
+/**
+ * The verbatim messages of one conversation (`sessionKey`) in chronological
+ * order — the durable transcript a UI renders when it (re)loads a conversation.
+ * Unlike `searchVerbatim` this is a plain scroll (no similarity), filtered by
+ * `sessionKey` (the true per-conversation key; in the HTTP surface it equals
+ * the client's `conversationId`) and ordered by `timestamp` ascending, paged
+ * via the opaque `offset` cursor. Returns empty if the client can't scroll.
+ */
+export async function listVerbatimBySession(
+  client: QdrantClientLike,
+  collectionName: string,
+  query: { sessionKey: string; limit: number; offset?: string | number | Record<string, unknown> | null },
+): Promise<VerbatimPage> {
+  if (!client.scroll) {
+    return { messages: [], nextOffset: null };
+  }
+  const result = await client.scroll(collectionName, {
+    filter: { must: [{ key: "sessionKey", match: { value: query.sessionKey } }] },
+    order_by: { key: "timestamp", direction: "asc" },
+    limit: query.limit,
+    offset: query.offset,
+    with_payload: true,
+  });
+  return {
+    messages: result.points.map((p) => p.payload ?? null).filter(isVerbatimMessage),
+    nextOffset: result.next_page_offset ?? null,
+  };
+}

package/src/model/client.ts

@@ -0,0 +1,33 @@
+/**
+ * Constructs the Ollama provider Mercury uses for every LLM call (main
+ * agent turns and Layer 1 summarization alike).
+ *
+ * Why it exists: the Ollama endpoint Mercury talks to varies by
+ * deployment (a local GPU box in development, a different host in
+ * production) and must always come from configuration, never be
+ * hardcoded or silently defaulted to `localhost` — this is the single
+ * place that reads that configuration, so the fail-fast behavior only
+ * has to be correct once.
+ *
+ * Used by: `src/index.ts` (wiring), which passes the resulting
+ * provider's model instance into `createSummarizer` (src/session/summarizer.ts)
+ * and `runTurn` (src/session/agent-turn.ts).
+ */
+import { createOllama, type OllamaProvider } from "ai-sdk-ollama";
+
+/**
+ * Returns an Ollama provider bound to `OLLAMA_HOST`.
+ *
+ * Throws synchronously if `OLLAMA_HOST` is unset or empty — there is no
+ * fallback to `localhost`, since which Ollama endpoint to use is a
+ * deployment decision, not something Mercury's code should guess.
+ */
+export function getOllamaProvider(): OllamaProvider {
+  const baseURL = process.env.OLLAMA_HOST;
+  if (!baseURL) {
+    throw new Error(
+      "OLLAMA_HOST is not set — never default to localhost",
+    );
+  }
+  return createOllama({ baseURL });
+}