@dudousxd/nestjs-agent-store-drizzle

Like the MikroORM adapter, this module binds AGENT_STORE, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE and AGENT_CONFIRM_TOKEN_STORE on a global Nest module. Import it once — the agent, dashboard, and telescope surfaces resolve these tokens app-wide with no re-binding.

It is additive only: the DDL is rendered from the dialect's schema object, so it creates any missing table, adds any column or index a running database lacks, and never drops a column or changes a type. On Postgres and MySQL it holds a cross-replica lock (pg_advisory_xact_lock / get_lock) so replicas booting an empty database at once do not race their CREATE TABLEs; on Postgres the whole heal is one transaction. It runs only when you call it — the module does not call it for you.

Prefer drizzle-kit migrations in production: point drizzle-kit at your dialect's schema object, or emit agentSchemaDdl(dialect) (the full CREATE TABLE / CREATE INDEX list). On your own migrations, the additive statements are yours to write — on SQLite, for a database that predates them:

ALTER TABLE agent_thread ADD COLUMN default_agent TEXT;
ALTER TABLE agent_message ADD COLUMN run_id TEXT;
ALTER TABLE agent_message ADD COLUMN attachments TEXT;
ALTER TABLE agent_run ADD COLUMN parent_run_id TEXT;
ALTER TABLE agent_message ADD COLUMN reasoning TEXT;
ALTER TABLE agent_message ADD COLUMN reasoning_ms INTEGER;
ALTER TABLE agent_message ADD COLUMN ui TEXT;
CREATE INDEX agent_tool_call_message_idx ON agent_tool_call (message_id);
ALTER TABLE agent_message ADD COLUMN feedback TEXT;
ALTER TABLE agent_message ADD COLUMN seq INTEGER;
ALTER TABLE agent_thread ADD COLUMN model TEXT;
ALTER TABLE agent_thread ADD COLUMN queue_pause TEXT;
-- approval policies
ALTER TABLE agent_tool_call ADD COLUMN approver TEXT;
ALTER TABLE agent_tool_call ADD COLUMN expires_at INTEGER;
ALTER TABLE agent_tool_call ADD COLUMN remember INTEGER;
ALTER TABLE agent_tool_call ADD COLUMN decided_via TEXT;
-- personas
ALTER TABLE agent_thread ADD COLUMN persona TEXT;
ALTER TABLE agent_message ADD COLUMN persona TEXT;
ALTER TABLE agent_queued_message ADD COLUMN persona TEXT;
-- per-call confirmations (action preflight)
ALTER TABLE agent_tool_call ADD COLUMN confirmation TEXT;
-- independent approvals
ALTER TABLE agent_tool_call ADD COLUMN proposal_id TEXT;
ALTER TABLE agent_message ADD COLUMN action_proposal_outcome TEXT;
ALTER TABLE agent_queued_message ADD COLUMN ui_capabilities TEXT;

Whole tables added since (agent_queued_message, agent_stream_frame, agent_confirm_token, agent_channel_state, agent_action_proposal) come from agentSchemaDdl(dialect) or the schema object. On Postgres the JSON columns are jsonb, on MySQL json.

It reads the attachments JSON column agent_message has carried since attachments shipped, so an existing database answers correctly the moment you upgrade — no new table, no column, no backfill. The match runs in memory rather than in SQL (the column holds an array of objects, no dialect indexes that), bounded to one actor's attachment-bearing messages (a message still waiting in a thread's queue counts too). A soft-deleted thread still counts as holding its references: the rows survive, so the bytes are still reachable.

Memory rows live in agent_memory, created by ensureAgentSchema like the rest. That looks inconsistent next to skills, whose rows are always the host's, and the difference is what a row can be related to: a skill plausibly joins your own entities, while a memory is a key, a fact, an opaque scope token and an origin. origin_thread_id is the one column here that is deliberately not a foreign key — a memory outlives the conversation it came from, and a cascade off agent_thread would delete beliefs when a transcript aged out.

DrizzleAgentStoreModule.forRoot({ db }) exports DrizzleMemoryProvider but never binds AGENT_MEMORY: that token's presence is what turns memory on, so binding it would give the feature to every host that installed the store.

@dudousxd/nestjs-agent-rag-media owns no storage: it publishes aviary:rag:* diagnostics, and a store subscribes. DrizzleRagIngestionLog is this adapter's subscriber, which is why ensureAgentSchema creates a table named outside the agent_ family, indexed by (collection, updated_at) for the per-collection listing. store-mikro-orm carries the same capability as MikroOrmRagIngestionLog — the choice of ORM adapter does not decide whether a deployment can audit its ingestions.

The table is the only place a document that produced no chunks is visible at all: an extraction that came back empty, a mime type with no extractor, an embedding call that threw. VectorStore.listDocuments() knows only about successes, so without this table a scanned PDF that silently failed to index reads exactly like one nobody ever uploaded.

DrizzleAgentStoreModule.forRoot({ db }) binds and exports it by default; { ragIngestionLog: false } binds nothing at all, for a host that records outcomes itself or ingests no media.

Every turn is recorded as a run in agentRun (status, duration, error code/message, retry count, a promptHash for correlating error-rate shifts with prompt changes). DrizzleGovernanceQueries reads it for the dashboard's Reliability section and for pendingApprovals/toolStats — no separate table or wiring needed, it's created by ensureAgentSchema like every other table here.

An action's preparation preflight can return its own confirmation wording for one call. It is stored in the nullable JSON column agent_tool_call.confirmation and returned in StoredMessage.approvals, so a reload shows the same card text. ensureAgentSchema adds the column; on your own migrations add it before upgrading.

Proposals written before discovery shipped have discovery_index_version = 0, and workers only discover version-1 rows. Mixed old and new writers are unsupported.

1. Stop writers running the older package version.

2. Apply the additive schema — ensureAgentSchema(db), or your drizzle-kit migration from the updated schema object: proposal execution_status, lease_expires_at, proposal_expires_at, discovery_index_version (default 0), delivery_status, delivery_lease_expires_at, replacement_group_key, outcome_id_key and their indexes; plus the message, tool-call and queued-message columns above.

3. Run the bounded backfill until it returns 0:

   Copy Text

   while (await store.backfillActionProposalDiscoveryIndex({ limit: 1000 })) {
     // each batch returns the number of rows it upgraded
   }

   Each call (limit 1–1000) rewrites discovery metadata from the stored snapshot under the row's version fence; it never changes the payload or runs a tool. Workers never backfill implicitly.

4. Deploy the new writers and workers, then enable actionApprovalMode: 'independent'.