How open-context Avoids Installing 15 Database Drivers
open-context's MCP context store supports 15 database backends, but a plain
npm install pulls in exactly zero of their client packages. Every driver —
Postgres, MongoDB, DynamoDB, SurrealDB, and the rest — is declared as an
optional peer dependency and loaded with a dynamic import()
only when you actually connect to that backend, so the install stays small and you
only pay for the database you picked.
Key takeaways
npm install open-contextbrings in zero database driver packages — JSON file storage and SQLite work with nothing extra.- All 14 other backends are listed under
peerDependencieswithpeerDependenciesMeta.optional: true, so npm never errors on a missing one. - Drivers are loaded with
importOptional(), a thin wrapper around dynamicimport()that turns a missing package into an actionable error instead of a stack trace. npm run db -- adapterslists all 15 backends and marks which ones are actually installed, with no network connection required.- The same rule applies to adding a 16th backend: a new driver file, a new peer dependency entry, nothing else changes for existing users.
Why 15 backends can't mean 15 mandatory dependencies
open-context's context store is BYODB — bring your own
database. The same save_context/recall_context MCP tools work
against a local JSON file, SQLite, Postgres, MongoDB, DynamoDB, or ten other backends,
picked with a single OPENCONTEXT_DB_URL connection string. Almost nobody uses
more than one or two of those at a time, though. If installing the package meant installing
the Postgres client, the MongoDB driver, the AWS SDK for DynamoDB, a native DuckDB binding,
and ten more packages every time, most of that install would be dead weight — and some of
those packages pull in native builds that have no reason to run on a machine that only ever
talks to a JSON file.
The pattern: optional peer dependencies plus dynamic import
The fix is two npm-level features working together: peerDependenciesMeta.optional
in package.json, and a dynamic import() that only runs when a driver
is actually needed.
Declaring the driver as optional
Every non-built-in backend is listed in package.json under both
peerDependencies and peerDependenciesMeta:
"peerDependencies": {
"pg": "^8.0.0",
"mongodb": "^6.0.0 || ^7.0.0",
"@aws-sdk/client-dynamodb": "^3.0.0"
// ...11 more
},
"peerDependenciesMeta": {
"pg": { "optional": true },
"mongodb": { "optional": true },
"@aws-sdk/client-dynamodb": { "optional": true }
// ...11 more
}
A peer dependency normally asks the consumer to install a matching version themselves
rather than having it bundled transitively. Marking it optional tells npm
(and pnpm, and Yarn) not to warn or fail when that package is absent — a consumer who
never touches Postgres never has to see pg mentioned at all.
Importing it only when a backend is used
Declaring a peer dependency doesn't load it — the actual import has to happen
lazily, and only on the code path that needs it. open-context wraps every driver's entry
point with importOptional() (src/store/drivers/optional.ts):
export async function importOptional<T>(
specifier: string,
scheme: DbScheme,
packageName: string = specifier,
): Promise<T> {
try {
return await import(specifier);
} catch (error) {
throw new DriverNotInstalledError(scheme, packageName, error);
}
}
The specifier is passed as a variable, not written as a string literal at the
import() call site — that's what stops TypeScript's bundler from trying to
resolve the module at build time, which would defeat the whole point by requiring the
package to exist on disk just to compile. The Postgres driver (src/store/drivers/postgres.ts)
calls it as importOptional<{ Pool: ... }>('pg', 'postgres', 'pg') only inside
the function that actually opens a Postgres connection — never at module load time.
What you see when a driver isn't installed
If you point OPENCONTEXT_DB_URL at a Postgres database without
npm install pg first, you don't get a bare
Cannot find module 'pg' stack trace. importOptional() catches the
failed import and throws a DriverNotInstalledError with the exact fix:
pg driver is not installed.
Install it with: npm install pg
That single error message is why the pattern is worth the extra indirection: the failure mode of "optional dependency missing" turns into a one-line, copy-pasteable instruction instead of a module-resolution error the user has to decode themselves.
Checking driver status without connecting to anything
You don't have to guess which drivers are installed. npm run db -- adapters
walks the ADAPTERS registry in src/store/index.ts and, for each of
the 15 backends, tries a dry-run import() of its package to report whether it's
ready:
Supported databases
✓ JSON file json:///path/to/contexts.json
✓ SQLite sqlite:///path/to/opencontext.db
· PostgreSQL postgres://USER:PASSWORD@HOST:5432/DATABASE npm install pg
· MongoDB mongodb://USER:PASSWORD@HOST:27017/DATABASE npm install mongodb
✓ ready · driver not installed
This check never opens a socket — it's purely "is this package resolvable," which is why it's instant and safe to run before you've even picked a database.
The same rule applies when adding a 16th backend
This isn't a one-off hack for the current 15 backends; it's the documented contract for
adding any new one. Per the BYODB section of this repo's own contributor guide, adding a
backend means: add its scheme, parse its connection-string fields, write a
Dialect/SqlDriver or DocumentDriver, register it in
ADAPTERS, load it with importOptional(), and add it to
peerDependencies plus peerDependenciesMeta as optional. Every
existing install stays exactly the same size — the new driver only gets pulled in by
whoever actually installs it.
Give Claude a persistent memory backed by any of 15 databases — install once, connect to the one you need.
Get started with open-context →FAQ
Does installing open-context install all 15 database drivers?
No. open-context's database drivers are declared as optional peer dependencies. A plain npm install gives you the JSON file store and SQLite out of the box, with none of the other 13 drivers' packages pulled in.
What happens if I use a database backend without installing its driver?
open-context throws a DriverNotInstalledError with the exact npm install command for that backend's package, instead of a raw module-resolution stack trace.
What is peerDependenciesMeta.optional in package.json?
It is a field next to peerDependencies that tells npm, pnpm, and other package managers a given peer dependency is optional, so they don't warn or fail when a consumer leaves it out.
How do I check which open-context database drivers are installed?
Run npm run db -- adapters. It lists all 15 supported backends and marks each one as ready or not installed, without connecting to any of them.
Why not just bundle all 15 database drivers with open-context?
Most of those drivers are native or heavyweight packages (SQL clients, cloud SDKs) that only matter to the one backend a given user picked. Bundling all 15 would bloat every install and add native build steps nobody asked for.