Multi-backend persistence layer for AgentX - supports memory, SQLite, Redis, MongoDB, and SQL databases
npm install @agentxjs/persistence> Storage layer for AgentX with pluggable drivers
@agentxjs/persistence provides the persistence layer for AgentX agents, including:
- Image Repository - Store and retrieve agent snapshots
- Container Repository - Manage container metadata
- Session Repository - Persist conversation history
Key Features:
- Subpath Exports - Import only the driver you need (tree-shaking friendly)
- Multiple Backends - SQLite, Redis, MongoDB, MySQL, PostgreSQL
- Zero Config Default - Memory driver works out of the box
- Cross-Runtime - SQLite driver works on both Bun and Node.js 22+
``bash`
bun add @agentxjs/persistence
`typescript
import { createPersistence, memoryDriver } from "@agentxjs/persistence";
const persistence = await createPersistence(memoryDriver());
`
`typescript
import { createPersistence } from "@agentxjs/persistence";
import { sqliteDriver } from "@agentxjs/persistence/sqlite";
const persistence = await createPersistence(sqliteDriver({ path: "./data/agentx.db" }));
`
`typescript
import { createPersistence } from "@agentxjs/persistence";
import { redisDriver } from "@agentxjs/persistence/redis";
const persistence = await createPersistence(redisDriver({ url: "redis://localhost:6379" }));
`
| Driver | Import | Peer Dependencies |
| ---------- | ---------------------------------- | ----------------- |
| Memory | @agentxjs/persistence | None |@agentxjs/persistence/fs
| Filesystem | | None |@agentxjs/persistence/sqlite
| SQLite | | db0 |@agentxjs/persistence/redis
| Redis | | ioredis |@agentxjs/persistence/mongodb
| MongoDB | | mongodb |@agentxjs/persistence/mysql
| MySQL | | mysql2 |@agentxjs/persistence/postgresql
| PostgreSQL | | pg |
Automatically detects runtime:
- Bun: uses bun:sqlite (built-in)node:sqlite
- Node.js 22+: uses (built-in)
`typescript`
sqliteDriver({
path: "./data.db", // Database file path
});
`typescript`
redisDriver({
url: "redis://localhost:6379", // Redis connection URL
});
`typescript`
mongodbDriver({
connectionString: "mongodb://localhost:27017", // MongoDB connection string
databaseName: "agentx", // Database name (optional)
collectionName: "storage", // Collection name (optional)
});
`typescript`
mysqlDriver({
host: "localhost",
port: 3306,
user: "root",
password: "password",
database: "agentx",
});
`typescript`
postgresqlDriver({
host: "localhost",
port: 5432,
user: "postgres",
password: "password",
database: "agentx",
});
Implement the PersistenceDriver interface:
`typescript
import { createPersistence, type PersistenceDriver } from "@agentxjs/persistence";
import { createStorage, type Storage } from "unstorage";
const customDriver: PersistenceDriver = {
async createStorage(): Promise
return createStorage({
driver: yourCustomUnstorageDriver(),
});
},
};
const persistence = await createPersistence(customDriver);
`
`text`
┌────────────────────────────────────────────────────────────┐
│ Persistence │
├────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│ │ Repositories │ │ Storage (unstorage) │ │
│ │ │ │ │ │
│ │ ImageRepo │◄─┼─ memoryDriver() │ │
│ │ ContainerRepo │ │ sqliteDriver({ path }) │ │
│ │ SessionRepo │ │ redisDriver({ url }) │ │
│ │ │ │ mongodbDriver({ ... }) │ │
│ └─────────────────┘ │ mysqlDriver({ ... }) │ │
│ │ postgresqlDriver({ ... }) │ │
│ └─────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────┘
Each driver is a separate entry point to enable tree-shaking:
`typescript
// Only bundles memory driver (no external deps)
import { memoryDriver } from "@agentxjs/persistence";
// Only bundles SQLite driver (requires db0)
import { sqliteDriver } from "@agentxjs/persistence/sqlite";
// Driver dependencies are NOT bundled if not imported
`
This is critical for binary distribution - portagent only imports sqliteDriver, so Redis/MySQL/PostgreSQL dependencies are never bundled.
`json``
{
"exports": {
".": "./dist/index.js",
"./sqlite": "./dist/drivers/sqlite.js",
"./redis": "./dist/drivers/redis.js",
"./mongodb": "./dist/drivers/mongodb.js",
"./mysql": "./dist/drivers/mysql.js",
"./postgresql": "./dist/drivers/postgresql.js"
}
}
- @agentxjs/runtime - Runtime that uses persistence
- agentxjs - High-level unified API
MIT