@multiplayer-app/ai-agent-mongo

Pure MongoDB adapter for Multiplayer AI agent repository interfaces. This library compiles Mongoose models and repositories on a caller-supplied mongoose.Connection. It does not read process.env, open connections, or manage shutdown.

Features

• Connection-agnostic: services own URI parsing, options, logging, and lifecycle
• Shared connection: pass the same connection used by other app models (e.g. Sandbox)
• Type-safe schemas: schema definitions only — models are compiled per connection
• Repository factory: createMongoAgentRepositories(connection) wires all repos

Prerequisites

• Node.js >= 18
• TypeScript >= 5.0
• MongoDB >= 6.0
• mongoose >=6.13.8 <7 (peer dependency — host and lib must share one mongoose 6 runtime; do not nest another copy)
• An already-created mongoose.Connection (connected or connecting)

This package does not bundle mongoose. The host must depend on a compatible mongoose 6 (e.g. 6.13.8) and pass that same connection into the factory APIs.

Quick Start

import mongoose from 'mongoose';
import { createMongoAgentRepositories } from '@multiplayer-app/ai-agent-mongo';

const MONGODB_URI = process.env.MONGODB_URI!;

await mongoose.connect(MONGODB_URI, {
  autoIndex: true,
  connectTimeoutMS: 10000,
  socketTimeoutMS: 25000,
  minPoolSize: 3,
});

const repositories = createMongoAgentRepositories(mongoose.connection);

// repositories.chat
// repositories.message
// repositories.activity
// repositories.config
// repositories.tenantAICredential

const chat = await repositories.chat.findById('chat-id');
const messages = await repositories.message.findByChatId('chat-id');

// Service owns shutdown
await mongoose.disconnect();

Public API

createMongoAgentRepositories(connection)

Creates (or reuses) AI-agent models on connection and returns repositories:

| Key | Repository | | --- | --- | | chat | MongoAgentChatRepository | | message | MongoAgentMessageRepository | | activity | MongoActivityRepository | | config | MongoAgentConfigRepository | | tenantAICredential | MongoTenantAICredentialRepository |

createMongoAgentModels(connection)

Lower-level helper if you only need the Mongoose models. Models are registered with connection.model(...), guarded by connection.models[...] so repeated calls on the same connection are safe.

Schema definitions

Schema modules export definitions and document types only (no models at import time):

import { AgentChatSchema, type AgentChatDocument } from '@multiplayer-app/ai-agent-mongo';

Repository classes

You can construct repositories manually with injected models:

import {
  createMongoAgentModels,
  MongoAgentChatRepository,
} from '@multiplayer-app/ai-agent-mongo';

const models = createMongoAgentModels(mongoose.connection);
const chatRepository = new MongoAgentChatRepository(models.AgentChat, models.AgentMessage);

Service-owned lifecycle

Do this in your service (not in this library):

1. Resolve MONGODB_URI / DB name from env or config
2. Set connection options (autoIndex, pool sizes, timeouts, debug, etc.)
3. Attach connection event logging
4. Call mongoose.connect(...) or mongoose.createConnection(...)
5. Pass that connection into createMongoAgentRepositories
6. On shutdown, close the connection yourself

This library never exports connect, disconnect, a default connection, or env-derived config.

Sharing one connection with other models

// Same connection for product models and AI-agent models
await mongoose.connect(process.env.MONGODB_URI!);

// Product / Sandbox models
const User = mongoose.connection.models.User
  ?? mongoose.connection.model('User', UserSchema);

// AI-agent models + repositories on the same connection
const repositories = createMongoAgentRepositories(mongoose.connection);

ESM and CJS

The package ships dual builds:

• ESM: dist/esm/index.js (import)
• CJS: dist/cjs/index.cjs (require)

// CJS
const mongoose = require('mongoose');
const { createMongoAgentRepositories } = require('@multiplayer-app/ai-agent-mongo');

await mongoose.connect(process.env.MONGODB_URI);
const { chat, message } = createMongoAgentRepositories(mongoose.connection);

Testing

Tests create an isolated Mongoose connection (via mongodb-memory-server). They do not set MONGODB_URI for the library.

npm test
npm run test:watch
npm run test:coverage

Related packages

• @multiplayer-app/ai-agent-db — abstract repository interfaces
• @multiplayer-app/ai-agent-types — shared entity types
• @multiplayer-app/ai-agent-node — Node runtime that consumes these repositories

License

MIT