@dudousxd/nestjs-agent-store-drizzle 0.8.2 → 0.10.0

package/dist/index.js

@@ -2,7 +2,7 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/schema.ts
-import { index, integer, real, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { index, integer, real, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
 var agentThread = sqliteTable("agent_thread", {
   id: text("id").primaryKey(),
   actorRef: text("actor_ref").notNull(),
@@ -12,6 +12,8 @@ var agentThread = sqliteTable("agent_thread", {
     mode: "boolean"
   }).notNull().default(false),
   activeStreamId: text("active_stream_id"),
+  /** The agent a new turn on this thread defaults to when the caller names none. */
+  defaultAgent: text("default_agent"),
   createdAt: integer("created_at", {
     mode: "timestamp_ms"
   }).notNull(),
@@ -37,6 +39,9 @@ var agentMessage = sqliteTable("agent_message", {
   toolResults: text("tool_results", {
     mode: "json"
   }).$type(),
+  attachments: text("attachments", {
+    mode: "json"
+  }).$type(),
   followUps: text("follow_ups", {
     mode: "json"
   }).$type(),
@@ -44,6 +49,7 @@ var agentMessage = sqliteTable("agent_message", {
     mode: "json"
   }).$type(),
   agentName: text("agent_name"),
+  runId: text("run_id"),
   createdAt: integer("created_at", {
     mode: "timestamp_ms"
   }).notNull()
@@ -75,7 +81,9 @@ var agentToolCall = sqliteTable("agent_tool_call", {
   }),
   /** The run (turn) this call belongs to, for a trace deep-link; null for a pre-rollout row. */
   runId: text("run_id")
-});
+}, (table) => [
+  index("agent_tool_call_message_idx").on(table.messageId)
+]);
 var agentTokenUsage = sqliteTable("agent_token_usage", {
   id: text("id").primaryKey(),
   threadId: text("thread_id").notNull().references(() => agentThread.id, {
@@ -134,17 +142,79 @@ var agentRun = sqliteTable("agent_run", {
     mode: "timestamp_ms"
   }),
   /** sha256 hex of the run's resolved (pre-RAG) system prompt; null for a pre-existing run. */
-  promptHash: text("prompt_hash")
+  promptHash: text("prompt_hash"),
+  /**
+   * The run that delegated this one; null for a turn nobody delegated. The durable runtime's
+   * journal holds the same edge, but only there — this column is what lets a reader of run ROWS
+   * build the delegation tree and roll a child's cost up to the turn that asked for it, including
+   * for a detached child, which outlives its parent's turn and so is paired by nothing in the
+   * transcript.
+   */
+  parentRunId: text("parent_run_id")
 }, (table) => [
   index("agent_run_started_idx").on(table.startedAt)
 ]);
+var agentMemory = sqliteTable("agent_memory", {
+  id: text("id").primaryKey(),
+  /** The opaque scope token. Unique with `key`: one fact per key per scope. */
+  scope: text("scope").notNull(),
+  /** What the fact is ABOUT. Two scopes sharing a key are one question answered twice. */
+  key: text("key").notNull(),
+  /** The fact itself, one line, as the model reads it. */
+  text: text("text").notNull(),
+  originAuthor: text("origin_author").$type().notNull(),
+  /** A pointer that is allowed to dangle — see the table note. */
+  originThreadId: text("origin_thread_id"),
+  originRunId: text("origin_run_id"),
+  originActorRef: text("origin_actor_ref"),
+  /** Always-on: carried in every prompt. Set by a host's console, never by a write. */
+  pinned: integer("pinned", {
+    mode: "boolean"
+  }).notNull().default(false),
+  createdAt: integer("created_at", {
+    mode: "timestamp_ms"
+  }).notNull(),
+  updatedAt: integer("updated_at", {
+    mode: "timestamp_ms"
+  }).notNull()
+}, (table) => [
+  uniqueIndex("agent_memory_scope_key_uq").on(table.scope, table.key)
+]);
+var ragIngestionLog = sqliteTable("rag_ingestion_log", {
+  /** The vector-store document id (chunk ids are `${documentId}#<n>`). */
+  documentId: text("document_id").primaryKey(),
+  status: text("status").$type().notNull(),
+  collection: text("collection"),
+  ownerType: text("owner_type"),
+  ownerId: text("owner_id"),
+  /** Citation-facing origin — the media record's path. */
+  source: text("source"),
+  mimeType: text("mime_type"),
+  size: integer("size"),
+  /** Chunk count on `ingested`; null otherwise. */
+  chunks: integer("chunks"),
+  /** Skip reason on `skipped` (`unsupported-type` | `too-large` | `empty-text`); null otherwise. */
+  reason: text("reason"),
+  /** Error message on `failed`; null otherwise. */
+  error: text("error"),
+  createdAt: integer("created_at", {
+    mode: "timestamp_ms"
+  }).notNull(),
+  updatedAt: integer("updated_at", {
+    mode: "timestamp_ms"
+  }).notNull()
+}, (table) => [
+  index("rag_ingestion_log_collection_idx").on(table.collection, table.updatedAt)
+]);
 var agentSchema = {
   agentThread,
   agentMessage,
   agentToolCall,
   agentTokenUsage,
   agentModelPricing,
-  agentRun
+  agentRun,
+  agentMemory,
+  ragIngestionLog
 };
 
 // src/ensure-schema.ts
@@ -157,6 +227,7 @@ var statements = [
     title TEXT NOT NULL,
     transient INTEGER NOT NULL DEFAULT 0,
     active_stream_id TEXT,
+    default_agent TEXT,
     created_at INTEGER NOT NULL,
     updated_at INTEGER NOT NULL,
     deleted_at INTEGER
@@ -170,9 +241,11 @@ var statements = [
     content TEXT NOT NULL,
     tool_calls TEXT,
     tool_results TEXT,
+    attachments TEXT,
     follow_ups TEXT,
     usage TEXT,
     agent_name TEXT,
+    run_id TEXT,
     created_at INTEGER NOT NULL
   )`,
   `CREATE INDEX IF NOT EXISTS agent_message_thread_created_idx
@@ -192,6 +265,8 @@ var statements = [
     executed_at INTEGER,
     run_id TEXT
   )`,
+  `CREATE INDEX IF NOT EXISTS agent_tool_call_message_idx
+    ON agent_tool_call (message_id)`,
   `CREATE TABLE IF NOT EXISTS agent_token_usage (
     id TEXT PRIMARY KEY NOT NULL,
     thread_id TEXT NOT NULL REFERENCES agent_thread(id) ON DELETE CASCADE,
@@ -230,20 +305,93 @@ var statements = [
     retries INTEGER NOT NULL DEFAULT 0,
     started_at INTEGER NOT NULL,
     settled_at INTEGER,
-    prompt_hash TEXT
+    prompt_hash TEXT,
+    parent_run_id TEXT
   )`,
   `CREATE INDEX IF NOT EXISTS agent_run_started_idx
-    ON agent_run (started_at)`
+    ON agent_run (started_at)`,
+  // `key` and `text` are quoted: both are keywords in at least one engine this DDL is read by, and
+  // they are the SPI's own field names, which is worth more here than dodging the quoting.
+  `CREATE TABLE IF NOT EXISTS agent_memory (
+    id TEXT PRIMARY KEY NOT NULL,
+    scope TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "text" TEXT NOT NULL,
+    origin_author TEXT NOT NULL,
+    origin_thread_id TEXT,
+    origin_run_id TEXT,
+    origin_actor_ref TEXT,
+    pinned INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  )`,
+  `CREATE UNIQUE INDEX IF NOT EXISTS agent_memory_scope_key_uq
+    ON agent_memory (scope, "key")`,
+  `CREATE TABLE IF NOT EXISTS rag_ingestion_log (
+    document_id TEXT PRIMARY KEY NOT NULL,
+    status TEXT NOT NULL,
+    collection TEXT,
+    owner_type TEXT,
+    owner_id TEXT,
+    source TEXT,
+    mime_type TEXT,
+    size INTEGER,
+    chunks INTEGER,
+    reason TEXT,
+    error TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  )`,
+  `CREATE INDEX IF NOT EXISTS rag_ingestion_log_collection_idx
+    ON rag_ingestion_log (collection, updated_at)`
+];
+var additiveColumns = [
+  {
+    table: "agent_message",
+    column: "run_id",
+    ddl: "ALTER TABLE agent_message ADD COLUMN run_id TEXT"
+  },
+  {
+    table: "agent_message",
+    column: "attachments",
+    ddl: "ALTER TABLE agent_message ADD COLUMN attachments TEXT"
+  },
+  {
+    table: "agent_thread",
+    column: "default_agent",
+    ddl: "ALTER TABLE agent_thread ADD COLUMN default_agent TEXT"
+  },
+  {
+    table: "agent_run",
+    column: "parent_run_id",
+    ddl: "ALTER TABLE agent_run ADD COLUMN parent_run_id TEXT"
+  }
 ];
 async function ensureAgentSchema(db) {
   for (const statement of statements) {
     await db.run(sql.raw(statement));
   }
+  for (const { table, column, ddl } of additiveColumns) {
+    const existing = await db.all(sql.raw(`PRAGMA table_info(${table})`));
+    if (!existing.some((row) => row.name === column)) {
+      await db.run(sql.raw(ddl));
+    }
+  }
 }
 __name(ensureAgentSchema, "ensureAgentSchema");
 
 // src/drizzle-agent-store.ts
-import { and, asc, desc, eq, gte, inArray, isNull, lte, sql as sql2 } from "drizzle-orm";
+import { and, asc, desc, eq, gte, inArray, isNotNull, isNull, lte, sql as sql2 } from "drizzle-orm";
+var TURN_MESSAGE_COLUMNS = {
+  id: agentMessage.id,
+  role: agentMessage.role,
+  content: agentMessage.content,
+  agentName: agentMessage.agentName,
+  toolCalls: agentMessage.toolCalls,
+  toolResults: agentMessage.toolResults,
+  attachments: agentMessage.attachments,
+  createdAt: agentMessage.createdAt
+};
 var DrizzleAgentStore = class {
   static {
     __name(this, "DrizzleAgentStore");
@@ -261,6 +409,7 @@ var DrizzleAgentStore = class {
       title: input.title ?? "New chat",
       transient: input.transient ?? false,
       activeStreamId: null,
+      defaultAgent: null,
       createdAt: now,
       updatedAt: now,
       deletedAt: null
@@ -283,6 +432,50 @@ var DrizzleAgentStore = class {
       } : {}
     };
   }
+  /**
+  * The window a turn reads off a thread: its newest `messageLimit` messages (oldest first), the
+  * title, the default agent, and whether the thread has EVER been answered.
+  *
+  * {@link getThread} is the wrong read for a turn. It materializes the transcript — every message,
+  * every attachment, every tool output the thread ever recorded — and the run then journals what it
+  * loaded, so a long thread pays for its whole history on every turn and again on every replay.
+  *
+  * `hasAssistantMessage` is answered over the WHOLE thread, not the returned page: it answers "has
+  * this conversation been answered before?", and a thread whose window happens to hold only the
+  * user's last questions has still been answered. `null` when the thread is unknown or
+  * soft-deleted, same as {@link getThread}.
+  */
+  async loadThreadForTurn(query) {
+    const [thread] = await this.db.select({
+      title: agentThread.title,
+      defaultAgent: agentThread.defaultAgent
+    }).from(agentThread).where(and(eq(agentThread.id, query.threadId), isNull(agentThread.deletedAt)));
+    if (thread === void 0) {
+      return null;
+    }
+    const messages = await this.loadTurnWindow(query.threadId, query.messageLimit);
+    const [answered] = await this.db.select({
+      id: agentMessage.id
+    }).from(agentMessage).where(and(eq(agentMessage.threadId, query.threadId), eq(agentMessage.role, "assistant"))).limit(1);
+    return {
+      title: thread.title,
+      defaultAgent: thread.defaultAgent,
+      hasAssistantMessage: answered !== void 0,
+      messages
+    };
+  }
+  /**
+  * The newest `limit` messages of a thread, oldest first, projected to the columns a model turn
+  * reads. Read newest-first so the LIMIT is the database's job, then reversed for the prompt.
+  */
+  async loadTurnWindow(threadId, limit) {
+    if (limit !== void 0 && limit <= 0) {
+      return [];
+    }
+    const window = this.db.select(TURN_MESSAGE_COLUMNS).from(agentMessage).where(eq(agentMessage.threadId, threadId)).orderBy(desc(agentMessage.createdAt), desc(agentMessage.id));
+    const rows = limit === void 0 ? await window : await window.limit(limit);
+    return rows.reverse().map((row) => this.toStoredMessage(row));
+  }
   async listThreads(actorRef, limit = 50) {
     const threads = await this.db.select().from(agentThread).where(and(eq(agentThread.actorRef, actorRef), eq(agentThread.transient, false), isNull(agentThread.deletedAt))).orderBy(desc(agentThread.updatedAt)).limit(limit);
     const summaries = [];
@@ -313,6 +506,7 @@ var DrizzleAgentStore = class {
       title: source.title,
       transient: false,
       activeStreamId: null,
+      defaultAgent: source.defaultAgent,
       createdAt: now,
       updatedAt: now,
       deletedAt: null
@@ -326,9 +520,14 @@ var DrizzleAgentStore = class {
         content: message.content,
         toolCalls: message.toolCalls,
         toolResults: message.toolResults,
+        attachments: message.attachments,
         followUps: message.followUps,
         usage: message.usage,
         agentName: message.agentName,
+        // The copy is the same message, so it keeps the run that wrote it. A reader asking which
+        // turn produced this text gets the truthful answer; the run's own thread is still the
+        // original, so a run-scoped read never picks the fork's rows up.
+        runId: message.runId,
         createdAt: message.createdAt
       })));
     }
@@ -348,9 +547,10 @@ var DrizzleAgentStore = class {
   }
   async runForToolCall(toolCallId) {
     const [row] = await this.db.select({
+      runId: agentToolCall.runId,
       activeStreamId: agentThread.activeStreamId
     }).from(agentToolCall).innerJoin(agentMessage, eq(agentToolCall.messageId, agentMessage.id)).innerJoin(agentThread, eq(agentMessage.threadId, agentThread.id)).where(eq(agentToolCall.id, toolCallId));
-    return row?.activeStreamId ?? null;
+    return row?.runId ?? row?.activeStreamId ?? null;
   }
   async ownerOfActiveStream(runId) {
     const [thread] = await this.db.select({
@@ -375,7 +575,43 @@ var DrizzleAgentStore = class {
       activeStreamId: runId
     }).where(eq(agentThread.id, threadId));
   }
-  /** Persist the start of a run (turn). Replay-safe: called under a durable localStep. */
+  /**
+  * Patch a thread's `title` and/or `defaultAgent`. Each field is only touched when PRESENT in
+  * `patch` — `defaultAgent: null` clears it (falls back to the app default), while an omitted
+  * `defaultAgent` leaves whatever is stored untouched. A no-op (including `updatedAt`) when the
+  * patch is empty or the thread doesn't exist.
+  */
+  async updateThread(threadId, patch) {
+    const updates = {};
+    if (patch.title !== void 0) {
+      updates.title = patch.title;
+    }
+    if (patch.defaultAgent !== void 0) {
+      updates.defaultAgent = patch.defaultAgent;
+    }
+    if (Object.keys(updates).length === 0) {
+      return;
+    }
+    updates.updatedAt = /* @__PURE__ */ new Date();
+    await this.db.update(agentThread).set(updates).where(eq(agentThread.id, threadId));
+  }
+  /**
+  * The thread's default agent, projected — the caller wants one nullable scalar to decide which
+  * agent answers the next turn, and {@link getThread} would materialize the whole transcript to
+  * hand it over. `null` when the thread is unknown, soft-deleted, or has no default set.
+  */
+  async defaultAgentForThread(threadId) {
+    const [thread] = await this.db.select({
+      defaultAgent: agentThread.defaultAgent
+    }).from(agentThread).where(and(eq(agentThread.id, threadId), isNull(agentThread.deletedAt)));
+    return thread?.defaultAgent ?? null;
+  }
+  /**
+  * Persist the start of a run (turn). Replay-safe: called under a durable localStep.
+  *
+  * Takes the SPI's own {@link RecordRunStartInput} rather than a hand-copied shape: a field added
+  * to the input is otherwise accepted and dropped, silently, by every adapter that re-declares it.
+  */
   async recordRunStart(run) {
     const runRow = {
       id: run.runId,
@@ -389,7 +625,8 @@ var DrizzleAgentStore = class {
       retries: 0,
       startedAt: /* @__PURE__ */ new Date(),
       settledAt: null,
-      promptHash: run.promptHash ?? null
+      promptHash: run.promptHash ?? null,
+      parentRunId: run.parentRunId ?? null
     };
     await this.db.insert(agentRun).values(runRow);
   }
@@ -429,9 +666,11 @@ var DrizzleAgentStore = class {
       content: input.content,
       toolCalls: input.toolCalls ?? null,
       toolResults: input.toolResults ?? null,
+      attachments: input.attachments ?? null,
       followUps: input.followUps ?? null,
       usage: input.usage ?? null,
       agentName: input.agentName ?? null,
+      runId: input.runId ?? null,
       createdAt: now
     };
     await this.db.insert(agentMessage).values(message);
@@ -440,6 +679,11 @@ var DrizzleAgentStore = class {
     }).where(eq(agentThread.id, input.threadId));
     return this.toStoredMessage(message);
   }
+  async setMessageToolResults(messageId, results) {
+    await this.db.update(agentMessage).set({
+      toolResults: results
+    }).where(eq(agentMessage.id, messageId));
+  }
   async truncateFrom(threadId, messageId) {
     const messages = await this.db.select().from(agentMessage).where(eq(agentMessage.threadId, threadId)).orderBy(asc(agentMessage.createdAt), asc(agentMessage.id));
     const cutoff = messages.findIndex((message) => message.id === messageId);
@@ -488,6 +732,39 @@ var DrizzleAgentStore = class {
     }
     await this.db.update(agentToolCall).set(updates).where(eq(agentToolCall.id, input.toolCallId));
   }
+  /**
+  * Of `mediaIds`, the ones a surviving message in one of this actor's threads still carries.
+  *
+  * Reads the `attachments` JSON back out and matches in memory rather than pushing the match into
+  * SQL: the column holds an array of objects, and every dialect this adapter's sibling targets
+  * spells that query differently (`jsonb` containment, `json_table`, `json_each`), while none of
+  * them can use an index for it anyway. The scan is bounded by ONE actor's attachment-bearing
+  * messages, which is a small set — attachments are rare, and a message without one is excluded
+  * by the `is not null` before any JSON is parsed.
+  *
+  * Soft-deleted threads are deliberately included: their message rows survive, so the bytes they
+  * point at are still reachable from stored state and are not garbage.
+  */
+  async referencedMediaIds(actorRef, mediaIds) {
+    if (mediaIds.length === 0) {
+      return [];
+    }
+    const rows = await this.db.select({
+      attachments: agentMessage.attachments
+    }).from(agentMessage).innerJoin(agentThread, eq(agentMessage.threadId, agentThread.id)).where(and(eq(agentThread.actorRef, actorRef), isNotNull(agentMessage.attachments)));
+    const wanted = new Set(mediaIds);
+    const found = /* @__PURE__ */ new Set();
+    for (const row of rows) {
+      for (const attachment of row.attachments ?? []) {
+        if (wanted.has(attachment.mediaId)) {
+          found.add(attachment.mediaId);
+        }
+      }
+    }
+    return [
+      ...wanted
+    ].filter((mediaId) => found.has(mediaId));
+  }
   async recordUsage(input) {
     await this.db.insert(agentTokenUsage).values({
       id: crypto.randomUUID(),
@@ -522,6 +799,7 @@ var DrizzleAgentStore = class {
       transient: thread.transient,
       createdAt: thread.createdAt.toISOString(),
       updatedAt: thread.updatedAt.toISOString(),
+      defaultAgent: thread.defaultAgent,
       ...lastContent !== void 0 ? {
         lastMessagePreview: lastContent.slice(0, 120)
       } : {}
@@ -539,6 +817,9 @@ var DrizzleAgentStore = class {
       ...message.toolResults != null ? {
         toolResults: message.toolResults
       } : {},
+      ...message.attachments != null ? {
+        attachments: message.attachments
+      } : {},
       ...message.followUps != null ? {
         followUps: message.followUps
       } : {},
@@ -547,6 +828,9 @@ var DrizzleAgentStore = class {
       } : {},
       ...message.agentName != null ? {
         agentName: message.agentName
+      } : {},
+      ...message.runId != null ? {
+        runId: message.runId
       } : {}
     };
   }
@@ -580,7 +864,8 @@ __name(isToolKind, "isToolKind");
 var RUN_STATUSES = [
   "running",
   "completed",
-  "failed"
+  "failed",
+  "cancelled"
 ];
 function isRunStatus(value) {
   return RUN_STATUSES.includes(value);
@@ -621,7 +906,8 @@ function toRecentRunRow(run) {
     errorMessage: run.errorMessage ?? null,
     retries: run.retries,
     startedAt: run.startedAt.toISOString(),
-    promptHash: run.promptHash ?? null
+    promptHash: run.promptHash ?? null,
+    parentRunId: run.parentRunId ?? null
   };
 }
 __name(toRecentRunRow, "toRecentRunRow");
@@ -1201,8 +1487,150 @@ var DrizzleGovernanceQueries = class {
   }
 };
 
+// src/drizzle-memory-provider.ts
+import { actorScope } from "@dudousxd/nestjs-agent-core";
+import { and as and3, eq as eq3, inArray as inArray3 } from "drizzle-orm";
+function toRecord(row) {
+  return {
+    id: row.id,
+    key: row.key,
+    text: row.text,
+    scope: row.scope,
+    origin: {
+      author: row.originAuthor,
+      ...row.originThreadId !== null ? {
+        threadId: row.originThreadId
+      } : {},
+      ...row.originRunId !== null ? {
+        runId: row.originRunId
+      } : {},
+      ...row.originActorRef !== null ? {
+        actorRef: row.originActorRef
+      } : {}
+    },
+    updatedAt: row.updatedAt.toISOString(),
+    pinned: row.pinned
+  };
+}
+__name(toRecord, "toRecord");
+var DrizzleMemoryProvider = class {
+  static {
+    __name(this, "DrizzleMemoryProvider");
+  }
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  /**
+  * Every memory visible at `scopes` — asked on EVERY turn, so it is one indexed `scope in (…)`
+  * against the leading column of the (`scope`, `key`) unique index.
+  *
+  * The scope filter is in the QUERY. The library drops out-of-scope records it is handed, but that
+  * is a backstop: a memory held for another actor or another tenant is never selected here, so it
+  * is unreachable rather than outranked.
+  */
+  async list({ scopes }) {
+    if (scopes.length === 0) {
+      return [];
+    }
+    const rows = await this.db.select().from(agentMemory).where(inArray3(agentMemory.scope, [
+      ...scopes
+    ]));
+    return rows.map(toRecord);
+  }
+  /**
+  * Delete one, and only from the actor's OWN scope.
+  *
+  * `memoryForgetVerdict` already holds the library's endpoint to that rule; the `where` repeats it
+  * because `forget` takes an id and nothing else, so a caller reaching this provider by any other
+  * path would otherwise delete a tenant's or the deployment's memory by knowing one id.
+  *
+  * `false` where nothing matched — which covers "no such id" and "not yours" identically, so the
+  * answer cannot be used to find out which memories exist about other people.
+  */
+  async forget({ id, ctx }) {
+    const deleted = await this.db.delete(agentMemory).where(and3(eq3(agentMemory.id, id), eq3(agentMemory.scope, actorScope(ctx.actor)))).returning({
+      id: agentMemory.id
+    });
+    return deleted.length > 0;
+  }
+  /**
+  * Upsert on (`scope`, `key`) — one statement, against the unique index, rather than a read
+  * followed by a write: two turns concluding the same key at once would otherwise race to a
+  * duplicate-key insert and one of them would fail the `remember` tool.
+  *
+  * The conflict `set` names exactly what a rewrite may change, so `pinned`, `createdAt` and `id`
+  * are left alone by construction rather than by an exclusion anyone could forget to extend.
+  * Dropping `pinned` would silently unpin a row the next time the agent restated the fact;
+  * rewriting `createdAt` would lose when the belief was first formed; reassigning `id` would
+  * invalidate the delete handle a person was already shown.
+  */
+  async write({ key, text: text2, scope, origin, ctx }) {
+    assertAuthorMayWriteScope({
+      scope,
+      origin,
+      ctx
+    });
+    const now = /* @__PURE__ */ new Date();
+    const columns = {
+      originAuthor: origin.author,
+      originThreadId: origin.threadId ?? null,
+      originRunId: origin.runId ?? null,
+      originActorRef: origin.actorRef ?? null
+    };
+    const [row] = await this.db.insert(agentMemory).values({
+      id: crypto.randomUUID(),
+      scope,
+      key,
+      text: text2,
+      ...columns,
+      pinned: false,
+      createdAt: now,
+      updatedAt: now
+    }).onConflictDoUpdate({
+      target: [
+        agentMemory.scope,
+        agentMemory.key
+      ],
+      set: {
+        text: text2,
+        ...columns,
+        updatedAt: now
+      }
+    }).returning();
+    if (row === void 0) {
+      throw new Error(`DrizzleMemoryProvider: the upsert of "${key}" at "${scope}" returned no row; the driver does not support RETURNING on conflict.`);
+    }
+    return toRecord(row);
+  }
+  /**
+  * Make one memory always-on, or stop it being one. The operator act the SPI has no method for, on
+  * purpose: a pin grants a fact a permanent place in every future prompt, so nothing an agent can
+  * reach may set it. Authorize it in your own console — this takes no `ScopeContext` because it is
+  * not an actor's act on their own memory.
+  *
+  * `false` where there is no such id.
+  */
+  async pin({ id, pinned }) {
+    const updated = await this.db.update(agentMemory).set({
+      pinned,
+      updatedAt: /* @__PURE__ */ new Date()
+    }).where(eq3(agentMemory.id, id)).returning({
+      id: agentMemory.id
+    });
+    return updated.length > 0;
+  }
+};
+function assertAuthorMayWriteScope({ scope, origin, ctx }) {
+  const own = actorScope(ctx.actor);
+  if (origin.author !== "human" && scope !== own) {
+    throw new Error(`DrizzleMemoryProvider: refusing to write an agent-authored memory at "${scope}"; an agent may write only at "${own}"`);
+  }
+}
+__name(assertAuthorMayWriteScope, "assertAuthorMayWriteScope");
+
 // src/drizzle-pricing-store.ts
-import { and as and3, eq as eq3 } from "drizzle-orm";
+import { and as and4, eq as eq4 } from "drizzle-orm";
 var DrizzlePricingStore = class {
   static {
     __name(this, "DrizzlePricingStore");
@@ -1214,7 +1642,7 @@ var DrizzlePricingStore = class {
   async upsertModelPrice(input) {
     await this.db.update(agentModelPricing).set({
       isCurrent: false
-    }).where(and3(eq3(agentModelPricing.modelId, input.modelId), eq3(agentModelPricing.isCurrent, true)));
+    }).where(and4(eq4(agentModelPricing.modelId, input.modelId), eq4(agentModelPricing.isCurrent, true)));
     await this.db.insert(agentModelPricing).values({
       id: crypto.randomUUID(),
       modelId: input.modelId,
@@ -1227,7 +1655,7 @@ var DrizzlePricingStore = class {
     });
   }
   async listCurrentPrices() {
-    const rows = await this.db.select().from(agentModelPricing).where(eq3(agentModelPricing.isCurrent, true));
+    const rows = await this.db.select().from(agentModelPricing).where(eq4(agentModelPricing.isCurrent, true));
     return rows.map((row) => ({
       modelId: row.modelId,
       inputPricePer1m: row.inputPricePer1m,
@@ -1243,25 +1671,352 @@ var DrizzlePricingStore = class {
   }
 };
 
+// src/drizzle-rag-ingestion-log.ts
+import { subscribe, unsubscribe } from "node:diagnostics_channel";
+import { Injectable, Logger } from "@nestjs/common";
+import { and as and5, asc as asc3, count as count2, desc as desc3, eq as eq5, gt, lt, or } from "drizzle-orm";
+function _ts_decorate(decorators, target, key, desc4) {
+  var c = arguments.length, r = c < 3 ? target : desc4 === null ? desc4 = Object.getOwnPropertyDescriptor(target, key) : desc4, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc4);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var CHANNELS = [
+  {
+    name: "aviary:rag:media.ingested",
+    status: "ingested"
+  },
+  {
+    name: "aviary:rag:media.skipped",
+    status: "skipped"
+  },
+  {
+    name: "aviary:rag:media.failed",
+    status: "failed"
+  },
+  {
+    name: "aviary:rag:media.removed",
+    status: "removed"
+  }
+];
+function str(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+__name(str, "str");
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+__name(num, "num");
+var RAG_INGESTION_LOG_PAGE_ORDER = [
+  desc3(ragIngestionLog.updatedAt),
+  asc3(ragIngestionLog.documentId)
+];
+var DEFAULT_PAGE_SIZE = 200;
+var DEFAULT_BATCH_SIZE = 200;
+function batches(batchSize) {
+  const requested = Math.trunc(batchSize ?? DEFAULT_BATCH_SIZE);
+  return Number.isFinite(requested) && requested >= 1 ? requested : DEFAULT_BATCH_SIZE;
+}
+__name(batches, "batches");
+var CURSOR_COLUMNS = {
+  documentId: ragIngestionLog.documentId,
+  updatedAt: ragIngestionLog.updatedAt
+};
+var DrizzleRagIngestionLog = class _DrizzleRagIngestionLog {
+  static {
+    __name(this, "DrizzleRagIngestionLog");
+  }
+  db;
+  logger = new Logger(_DrizzleRagIngestionLog.name);
+  teardowns = [];
+  inFlight = /* @__PURE__ */ new Set();
+  constructor(db) {
+    this.db = db;
+  }
+  onModuleInit() {
+    for (const channel of CHANNELS) {
+      const listener = /* @__PURE__ */ __name((message) => {
+        const payload = message?.payload;
+        if (payload !== void 0) {
+          this.track(this.record(channel.status, payload));
+        }
+      }, "listener");
+      subscribe(channel.name, listener);
+      this.teardowns.push(() => unsubscribe(channel.name, listener));
+    }
+  }
+  async onModuleDestroy() {
+    for (const teardown of this.teardowns) {
+      teardown();
+    }
+    this.teardowns = [];
+    await this.settle();
+  }
+  /** Await every in-flight write — for graceful shutdown and deterministic tests. */
+  async settle() {
+    await Promise.allSettled([
+      ...this.inFlight
+    ]);
+  }
+  /** The latest recorded outcome per document, newest first. */
+  async list(query = {}) {
+    const rows = this.db.select().from(ragIngestionLog).where(this.where(query)).orderBy(...RAG_INGESTION_LOG_PAGE_ORDER).limit(query.limit ?? DEFAULT_PAGE_SIZE);
+    return query.offset === void 0 ? rows : rows.offset(query.offset);
+  }
+  /**
+  * The same page plus the unpaginated total, so a caller can tell "these are all of them" from
+  * "these are the first N". A list that silently truncates reads as complete when it isn't.
+  *
+  * Offset paging is only sound over a table nobody is deleting from underneath you: a row removed
+  * behind the cursor shifts everything after it back by one, so the next page starts one row late
+  * and that row is never seen. Use {@link iterate} for any sweep that deletes.
+  */
+  async listPage(query = {}) {
+    const [totalRow] = await this.db.select({
+      value: count2()
+    }).from(ragIngestionLog).where(this.where(query));
+    return {
+      rows: await this.list(query),
+      total: totalRow?.value ?? 0
+    };
+  }
+  /**
+  * Every matching row, newest first, streamed in batches — the sweep-safe way to walk this table.
+  *
+  * Paging is *keyset*, not offset: each batch asks for the rows that sort strictly after the last
+  * row yielded, using `(updatedAt, documentId)` — one point in
+  * {@link RAG_INGESTION_LOG_PAGE_ORDER}, which is total because it ends in the primary key. A
+  * cursor made of column values does not move when rows leave the table, which is what makes this
+  * delete-safe *by construction* rather than by the caller carefully advancing an offset by only
+  * the rows it kept.
+  *
+  * **The guarantee, stated once:** a row is yielded exactly when — at the moment the batch that
+  * would contain it is fetched — the row exists, matches `where`, and sorts strictly after the
+  * last row already yielded. Everything below is a consequence of that one sentence.
+  *
+  * What you can rely on:
+  * - **Deleting rows while iterating is safe.** Delete any row you like — the one just yielded, the
+  *   whole batch, rows you have not reached yet — and every row that is still there when the sweep
+  *   reaches its position is visited exactly once. Nothing is skipped and nothing is repeated,
+  *   because deleting a row moves no *other* row's `(updatedAt, documentId)`. (Rows you delete
+  *   *ahead* of the cursor are simply never visited, which is the point of deleting them.)
+  * - **Ties are safe.** A bulk upload stamps a whole batch with the same `updatedAt`; the
+  *   `documentId` tiebreaker keeps consecutive batches disjoint even when every row ties.
+  * - **Each row is yielded at most once**, for as long as `updatedAt` only ever moves forward —
+  *   which is what `record()` does, since it always stamps `now`.
+  *
+  * What this is **not**: a snapshot, or a repeatable read. The sweep observes the table as it is
+  * when each batch is fetched, so:
+  * - A row **inserted** mid-sweep by `record()` is stamped `now`. The order is newest-first, so it
+  *   sorts ahead of a cursor the sweep has already moved past, and is not visited. A sweep
+  *   therefore never sees documents ingested after it started — the behaviour an orphan sweep
+  *   wants, since a document that arrived while you were sweeping is not an orphan. (A *direct*
+  *   insert with a backdated `updatedAt` lands ahead of the cursor and **is** visited; nothing in
+  *   this class writes one.)
+  * - A row **re-ingested** mid-sweep has its `updatedAt` bumped to `now`, moving it ahead of the
+  *   cursor for the same reason. If the sweep had already passed it, it is not visited twice; if it
+  *   had not, it is **missed for this pass**. That is the honest limit: against a concurrent
+  *   writer `iterate` guarantees "at most once", not "at least once". Sweeps that must not miss a
+  *   concurrently-rewritten row should be idempotent and run again.
+  * - Only a row whose `updatedAt` moves *backwards* — which needs a direct write — can be yielded
+  *   twice.
+  * - `collection` / `status` are re-evaluated per batch, so a row that stops matching mid-sweep
+  *   stops being visited.
+  *
+  * There is no `limit`/`offset` here on purpose: `where` says *which* rows, `options` says how the
+  * sweep is run. A sweep that stops early stops by `break`ing out of the `for await`.
+  */
+  iterate(where = {}, options = {}) {
+    return this.sweep(where, batches(options.batchSize), options.after, (filter, limit) => this.db.select().from(ragIngestionLog).where(filter).orderBy(...RAG_INGESTION_LOG_PAGE_ORDER).limit(limit));
+  }
+  /**
+  * Just the document ids of the matching rows, in {@link RAG_INGESTION_LOG_PAGE_ORDER}.
+  *
+  * Returns **all** of them — no 200-row cap, unlike `list` — by sweeping on {@link iterate}'s
+  * keyset internally, so it is correct against concurrent deletes for the same reason `iterate`
+  * is. What the cap protects against is hydrating an unbounded number of wide rows (`error` is a
+  * TEXT column); this selects two columns — the id, plus the `updatedAt` the cursor needs — and
+  * keeps only the ids, so the peak footprint is one batch of two-column rows plus a list of
+  * strings whose size *is* the answer the caller asked for.
+  *
+  * For callers that need the id set of a collection and nothing else: an orphan sweep unioning the
+  * log against the vector store's own document list.
+  */
+  async listDocumentIds(where = {}, options = {}) {
+    const ids = [];
+    const rows = this.sweep(where, batches(options.batchSize), void 0, (filter, limit) => this.db.select(CURSOR_COLUMNS).from(ragIngestionLog).where(filter).orderBy(...RAG_INGESTION_LOG_PAGE_ORDER).limit(limit));
+    for await (const row of rows) {
+      ids.push(row.documentId);
+    }
+    return ids;
+  }
+  /** The latest recorded outcome for one document, or null if it was never attempted. */
+  async get(documentId) {
+    const [row] = await this.db.select().from(ragIngestionLog).where(eq5(ragIngestionLog.documentId, documentId));
+    return row ?? null;
+  }
+  /** Forget one document's record. Returns whether a row was actually removed. */
+  async remove(documentId) {
+    const removed = await this.db.delete(ragIngestionLog).where(eq5(ragIngestionLog.documentId, documentId)).returning({
+      documentId: ragIngestionLog.documentId
+    });
+    return removed.length > 0;
+  }
+  /** Forget every record for a collection — for when the collection itself is deleted. */
+  async removeByCollection(collection) {
+    const removed = await this.db.delete(ragIngestionLog).where(eq5(ragIngestionLog.collection, collection)).returning({
+      documentId: ragIngestionLog.documentId
+    });
+    return removed.length;
+  }
+  /**
+  * The keyset sweep both {@link iterate} and {@link listDocumentIds} are made of. `page` decides
+  * how wide a row is — whole rows for `iterate`, two columns for `listDocumentIds` — and the
+  * `R extends RagIngestionLogCursor` bound says the only thing the sweep needs back: a row it can
+  * read the next cursor off.
+  *
+  * The cursor advances **per yielded row**, not per batch, so a consumer that `break`s mid-batch
+  * leaves it on the last row it actually saw. It is two column values read off that row, so a row
+  * leaving the table cannot move it — the whole reason this is delete-safe by construction.
+  */
+  async *sweep(where, batchSize, after, page) {
+    let cursor = after;
+    for (; ; ) {
+      const rows = await page(this.keyset(where, cursor), batchSize);
+      if (rows.length === 0) {
+        return;
+      }
+      for (const row of rows) {
+        yield row;
+        cursor = {
+          updatedAt: row.updatedAt,
+          documentId: row.documentId
+        };
+      }
+    }
+  }
+  where(query) {
+    return and5(query.collection !== void 0 ? eq5(ragIngestionLog.collection, query.collection) : void 0, query.status !== void 0 ? eq5(ragIngestionLog.status, query.status) : void 0);
+  }
+  /**
+  * The coordinates filter AND'd with "strictly after `cursor` in
+  * {@link RAG_INGESTION_LOG_PAGE_ORDER}".
+  *
+  * The order is `updatedAt desc, documentId asc`, so "after" means an older timestamp, or the same
+  * timestamp and a larger id. Both halves are needed: the `<` alone would re-yield every row tied
+  * with the cursor, and dropping the tie branch would skip them instead.
+  */
+  keyset(where, cursor) {
+    const base = this.where(where);
+    if (cursor === void 0) {
+      return base;
+    }
+    return and5(base, or(lt(ragIngestionLog.updatedAt, cursor.updatedAt), and5(eq5(ragIngestionLog.updatedAt, cursor.updatedAt), gt(ragIngestionLog.documentId, cursor.documentId))));
+  }
+  /**
+  * Upsert one outcome. Keyed by document id so the row always reflects the *current* state — a
+  * retry that succeeds overwrites the failure it replaces, rather than leaving a stale error next
+  * to a working document.
+  */
+  async record(status, payload) {
+    const documentId = str(payload.mediaId);
+    if (documentId === null) {
+      return;
+    }
+    try {
+      const now = /* @__PURE__ */ new Date();
+      const collection = str(payload.collection);
+      const ownerType = str(payload.ownerType);
+      const ownerId = str(payload.ownerId);
+      const source = str(payload.source);
+      const mimeType = str(payload.mimeType);
+      const size = num(payload.size);
+      const outcome = {
+        status,
+        // The three outcome-specific columns are exclusive: null out the ones this status doesn't
+        // own on every write, so a successful retry clears the previous attempt's error rather than
+        // leaving it next to a working document. Always present → always in the conflict `set`.
+        chunks: status === "ingested" ? num(payload.chunks) : null,
+        reason: status === "skipped" ? str(payload.reason) : null,
+        error: status === "failed" ? str(payload.error) : null,
+        updatedAt: now,
+        ...collection !== null ? {
+          collection
+        } : {},
+        ...ownerType !== null ? {
+          ownerType
+        } : {},
+        ...ownerId !== null ? {
+          ownerId
+        } : {},
+        ...source !== null ? {
+          source
+        } : {},
+        ...mimeType !== null ? {
+          mimeType
+        } : {},
+        ...size !== null ? {
+          size
+        } : {}
+      };
+      await this.db.insert(ragIngestionLog).values({
+        documentId,
+        createdAt: now,
+        ...outcome
+      }).onConflictDoUpdate({
+        target: ragIngestionLog.documentId,
+        set: outcome
+      });
+    } catch (error) {
+      this.logger.warn(`Could not record RAG ingestion outcome for ${documentId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  track(promise) {
+    const tracked = promise.finally(() => {
+      this.inFlight.delete(tracked);
+    });
+    this.inFlight.add(tracked);
+  }
+};
+DrizzleRagIngestionLog = _ts_decorate([
+  Injectable(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof AgentDrizzleDb === "undefined" ? Object : AgentDrizzleDb
+  ])
+], DrizzleRagIngestionLog);
+
 // src/drizzle-agent-store.module.ts
 import { AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, AGENT_STORE } from "@dudousxd/nestjs-agent-core";
 import { Module } from "@nestjs/common";
-function _ts_decorate(decorators, target, key, desc3) {
-  var c = arguments.length, r = c < 3 ? target : desc3 === null ? desc3 = Object.getOwnPropertyDescriptor(target, key) : desc3, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc3);
+function _ts_decorate2(decorators, target, key, desc4) {
+  var c = arguments.length, r = c < 3 ? target : desc4 === null ? desc4 = Object.getOwnPropertyDescriptor(target, key) : desc4, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc4);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate, "_ts_decorate");
+__name(_ts_decorate2, "_ts_decorate");
 var DrizzleAgentStoreModule = class _DrizzleAgentStoreModule {
   static {
     __name(this, "DrizzleAgentStoreModule");
   }
   static forRoot(options) {
+    const ragProviders = options.ragIngestionLog === false ? [] : [
+      {
+        provide: DrizzleRagIngestionLog,
+        useFactory: /* @__PURE__ */ __name(() => new DrizzleRagIngestionLog(options.db), "useFactory")
+      }
+    ];
     return {
       module: _DrizzleAgentStoreModule,
       global: true,
       providers: [
+        ...ragProviders,
         {
           provide: DrizzleAgentStore,
           useFactory: /* @__PURE__ */ __name(() => new DrizzleAgentStore(options.db), "useFactory")
@@ -1270,6 +2025,13 @@ var DrizzleAgentStoreModule = class _DrizzleAgentStoreModule {
           provide: AGENT_STORE,
           useExisting: DrizzleAgentStore
         },
+        // Exported, never bound to AGENT_MEMORY: that token's PRESENCE is what turns memory on, so
+        // binding it here would switch the feature on for every host that installs the store. A
+        // host opts in by naming this provider in `AgentModule.forRoot({ memory: { provider } })`.
+        {
+          provide: DrizzleMemoryProvider,
+          useFactory: /* @__PURE__ */ __name(() => new DrizzleMemoryProvider(options.db), "useFactory")
+        },
         {
           provide: DrizzlePricingStore,
           useFactory: /* @__PURE__ */ __name(() => new DrizzlePricingStore(options.db), "useFactory")
@@ -1296,8 +2058,12 @@ var DrizzleAgentStoreModule = class _DrizzleAgentStoreModule {
         }
       ],
       exports: [
+        ...options.ragIngestionLog === false ? [] : [
+          DrizzleRagIngestionLog
+        ],
         DrizzleAgentStore,
         AGENT_STORE,
+        DrizzleMemoryProvider,
         DrizzleGovernanceQueries,
         AGENT_GOVERNANCE_QUERIES,
         DrizzlePricingStore,
@@ -1306,14 +2072,18 @@ var DrizzleAgentStoreModule = class _DrizzleAgentStoreModule {
     };
   }
 };
-DrizzleAgentStoreModule = _ts_decorate([
+DrizzleAgentStoreModule = _ts_decorate2([
   Module({})
 ], DrizzleAgentStoreModule);
 export {
   DrizzleAgentStore,
   DrizzleAgentStoreModule,
   DrizzleGovernanceQueries,
+  DrizzleMemoryProvider,
   DrizzlePricingStore,
+  DrizzleRagIngestionLog,
+  RAG_INGESTION_LOG_PAGE_ORDER,
+  agentMemory,
   agentMessage,
   agentModelPricing,
   agentRun,
@@ -1321,6 +2091,7 @@ export {
   agentThread,
   agentTokenUsage,
   agentToolCall,
-  ensureAgentSchema
+  ensureAgentSchema,
+  ragIngestionLog
 };
 //# sourceMappingURL=index.js.map