@dudousxd/nestjs-agent-store-mikro-orm

The AgentStore SPI (from @dudousxd/nestjs-agent-core) backed by MikroORM. The store is a POJO that receives an EntityManager; every operation runs on a fresh em.fork() so per-request identity maps never bleed across concurrent turns.

pnpm add @dudousxd/nestjs-agent-store-mikro-orm @mikro-orm/core @mikro-orm/nestjs

Minimal exampleCopy Anchor Link

forFeature() does not register the entities — add them to your own MikroORM config so they enter the shared ORM's metadata (the store's repositories and the boot heal read it):

import { Module } from '@nestjs/common';
import { MikroOrmModule } from '@mikro-orm/nestjs';
import { AGENT_ENTITIES, MikroOrmAgentStoreModule } from '@dudousxd/nestjs-agent-store-mikro-orm';
import { AgentModule, HeaderActorResolver } from '@dudousxd/nestjs-agent';

@Module({
  imports: [
    MikroOrmModule.forRoot({
      // …driver, dbName
      entities: [...yourEntities, ...AGENT_ENTITIES], // agentEntities() with no collation on SQLite/Postgres
    }),
    MikroOrmAgentStoreModule.forFeature(), // binds AGENT_STORE, AGENT_GOVERNANCE_QUERIES, AGENT_PRICING_STORE, AGENT_CONFIRM_TOKEN_STORE
    AgentModule.forRoot({
      model: myModelProvider,
      // no `store` — the agent reads it from AGENT_STORE
      actorResolver: new HeaderActorResolver(),
    }),
  ],
})
export class AppModule {}

forFeature(options?):

With autoSchema on, the tables are created and healed at boot. With it off, use MikroORM migrations (agentSchemaSql renders the DDL), or call the helper yourself:

import { ensureAgentSchema } from '@dudousxd/nestjs-agent-store-mikro-orm';

await ensureAgentSchema(orm); // fingerprint-gated: creates, adds columns, corrects MySQL collations

The boot heal owns the schemaCopy Anchor Link

With autoSchema on (the default) the store's boot heal is the whole schema story: it creates every agent_* table, adds the columns and indexes a later release declares, and keeps each column in the type and collation its entity declares. An app on this store writes no migrations for these tables (keep them out of your own migration differ with agentManagedTables()), and an upgrade needs nothing but a restart.

Collations are part of that. The entities declare one on every MySQL string column (AGENT_COLLATION, utf8mb4_unicode_ci, and the binary utf8mb4_bin on the values compared exactly: actor and tenant refs, memory scopes, proposal keys, channel state keys such as provider message ids). MikroORM before 7.2 renders no collate clause in create table / add column and does not diff collations, so an earlier heal left those columns in the table default (utf8mb4_0900_ai_ci on MySQL 8, case-insensitive): wamid.AbC and wamid.aBc were one key. The heal now reads the actual collation of every agent column and corrects the ones that differ, one alter table … modify per table with foreign-key checks off on that connection (a referenced key and the columns pointing at it change together, and the foreign keys still hold afterwards). The schema fingerprint covers collations, so a database healed by an earlier version gets the correction on the first boot after the upgrade, once.

The correction is safe on a populated table. Before altering anything it checks that no unique key would merge two rows under the declared collation ('abc' and 'ABC' going to a case-insensitive column) and that no child row matched its parent only case-insensitively. If either would happen it alters nothing, records no fingerprint, and throws AgentSchemaCollationError, naming the key and an example value: merge, rename or delete those rows, and the next boot corrects the columns. Postgres and SQLite name no collation on these columns (their comparisons are already exact), so there the heal has nothing to correct.

Upgrading from a release before Postgres/MySQL were tested for real: agent_message gains a nullable seq (per-thread append order); Postgres gains an index on agent_tool_call.message_id; on MySQL timestamps become datetime(6), long text columns longtext, and identity columns (actor_ref, tenant_ref, memory scope/origin_actor_ref) the binary collation utf8mb4_bin. The MySQL modify statements rebuild the tables once — on a large deployment, boot with forFeature({ autoSchema: false }) and run ensureAgentSchema(orm) from a one-off script in a maintenance window.

Upgrading from a release before reasoning was persisted: agent_message gained three nullable columns. ensureAgentSchema adds them; migration:create picks them up from the entity diff; or by hand:

alter table agent_message add column reasoning text null;
alter table agent_message add column reasoning_ms integer null;
alter table agent_message add column ui json null;

Upgrading from a release before personas: three more nullable columns, picked up the same three ways.

alter table agent_thread add column persona varchar(255) null;
alter table agent_message add column persona varchar(255) null;
alter table agent_queued_message add column persona varchar(255) null;

Upgrading from a release before per-call confirmations and independent approvals: nullable agent_tool_call.confirmation (json) and agent_tool_call.proposal_id, agent_message.action_proposal_outcome (escaped JSON text), agent_queued_message.ui_capabilities (json), and the new agent_action_proposal table. Same three ways; see Action proposals for the rollout order.

ExportsCopy Anchor Link

Action proposals (independent approvals)Copy Anchor Link

MikroOrmAgentStore implements everything actionApprovalMode: 'independent' checks for at boot — ActionProposalStore, ActionProposalWorkerStore, ActionProposalDiscoveryIndexStore, outcome admission, atomic replacement, and the ChatQueueStore queue — on SQLite, Postgres and MySQL. No extra registration: AGENT_STORE is already the proposal store. See Action proposals.

• Entity. AgentActionProposal (agent_action_proposal) keeps the decision, its audit and the execution work in one row, updated by compare-and-swap on revision. SHA-256 physical keys; every read and mutation checks the exact tenant, actor and thread scope. No foreign keys to chat rows. Passing a transactional EntityManager keeps proposal operations inside the caller's transaction.
• Worker discovery. claimNextActionProposal({ workerId, leaseMs }) claims queued or expired-lease work across scopes (at most 32 candidates per call); expireActionProposals({ limit }) expires due pending proposals (limit 1–1000). Privileged — never expose them on user routes.
• Outcomes. Admission locks the proposal and thread and inserts one assistant message carrying agent_message.action_proposal_outcome together with the delivery state, in one transaction.
• SQLite. Writes to one database file are also serialized in-process, so an async transaction does not block the event loop; database locks and version CAS remain the cross-replica authority.

Peer dependenciesCopy Anchor Link

@mikro-orm/core (^6 \|\| ^7), @mikro-orm/nestjs (^6 \|\| ^7), and @nestjs/common (^10 \|\| ^11 \|\| ^12) — plus your driver package (@mikro-orm/postgresql, @mikro-orm/mysql, …).

When to use itCopy Anchor Link

Reach for this adapter when MikroORM is already your app's ORM — MikroOrmModule.forRoot(...) owns the connection, your config registers the agent's entities alongside your own, and forFeature() binds the stores. If you'd rather bring an already-opened handle and skip MikroORM entirely, see store-drizzle.

RelatedCopy Anchor Link

• Persistence — the AgentStore SPI, the bound tokens, and choosing an adapter
• Action proposals — independent approvals on top of this store
• Cost & Governance — the read-model this adapter feeds, and the ledger cost formula