open-context open-context
November 3, 2026 · 6 min read

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-context brings in zero database driver packages — JSON file storage and SQLite work with nothing extra.
  • All 14 other backends are listed under peerDependencies with peerDependenciesMeta.optional: true, so npm never errors on a missing one.
  • Drivers are loaded with importOptional(), a thin wrapper around dynamic import() that turns a missing package into an actionable error instead of a stack trace.
  • npm run db -- adapters lists 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.