In-Memory MCP Context Store: Fast Local Testing Guide
opencontext can back its MCP context store entirely in RAM with the connection string
memory:// — no file, no database, no driver to install. Point
OPENCONTEXT_DB_URL at it and every save_context or
recall_context call reads and writes a plain JavaScript Map that
disappears the moment the process exits, which makes it the fastest way to try the tool,
run a demo, or run an automated test suite without touching disk.
Key takeaways
memory://is a built-in opencontext backend with zero install — the same tier as the default JSON file and built-in SQLite.- Data lives only for the lifetime of the Node.js process; restarting the server or CLI empties the store.
- It's the reference implementation of opencontext's shared
DocumentDriverinterface, the same abstraction behind MongoDB, Redis, Firestore, and DynamoDB. - It passes the identical ~50-test storage conformance suite every other backend passes, so behavior is interchangeable, not just "close enough."
- Naming a store after the scheme (
memory://scratch) runs independent, isolated stores side by side in one process — exactly what test suites need.
What memory:// actually is
opencontext's context store sits behind a pluggable adapter interface — the project calls
this BYODB, "bring your own database" — with 15 supported backends spanning JSON files, SQL
engines, document stores, and a multi-model option. memory:// is the simplest
member of that list: a process-local Map keyed by collection (contexts and
bubbles), wrapped in the same six-method driver contract that every document-style backend
implements.
Anything after the scheme names an independent store. memory:// alone always
points at a store named default; memory://scratch opens a
completely separate one. Reconnecting to the same name in the same process hands back the
same data — the store is keyed by name in a module-level registry, not recreated on every
call — which is what makes it behave like a real store instead of silently losing data
between an HTTP request and the MCP server reading it back.
Why this exists alongside 14 persisted backends
Most of opencontext's backend list exists so teams can point the MCP context store at
infrastructure they already run — Postgres, Redis, Cloudflare D1, and so on. memory://
exists for the opposite reason: for the moments persistence is actively unwanted.
- First run. Someone trying opencontext for the first time shouldn't need to think about a file path or a database before
save_contextworks. - Local development. Iterating on the MCP server or the HTTP API without accumulating test contexts in your real
~/.opencontext/contexts.json. - Automated tests. Every test gets a clean store with no file to delete afterward and no shared state to leak between test files run in parallel.
- Demos and CI smoke checks. Spin up the HTTP server, exercise the API, throw the container away.
That last use case is also why the backend is worth documenting on its own: opencontext's
store conformance suite (tests/store/conformance.ts) — roughly 50 tests that
every adapter must pass unmodified — runs against JSON, SQLite, and memory://
with no external services at all, because those three cover all three backend families
(file, SQL, document) without a single Docker container. The in-memory adapter isn't a toy;
it's the fixture the whole test matrix leans on to stay fast.
Using it
The store resolves from the first of these that is set:
OPENCONTEXT_DB_URL, then database.url in
~/.opencontext/config.json, then the legacy OPENCONTEXT_STORE_PATH,
then the default JSON file. Setting the environment variable is the simplest way to force
an in-memory run:
OPENCONTEXT_DB_URL="memory://" npm run mcp:server
Or against the HTTP server, for a throwaway container:
docker run -p 3000:3000 \
-e OPENCONTEXT_DB_URL="memory://" \
adityakarnam/opencontext:latest
No volume mount, no -v flag — because there's nothing on disk to persist. The
CLI's database commands work against it like any other backend:
opencontext db use "memory://"
opencontext db status
Inside a test file, name the store explicitly so parallel test runs never collide, and reset it between tests:
import { createStore } from '../src/store/index.js';
import { resetMemoryStore } from '../src/store/drivers/memory.js';
const store = await createStore('memory://my-test-suite');
// ...run assertions...
resetMemoryStore('my-test-suite');
What you give up
The trade is exactly what the name implies: no durability. There's no file to inspect after
a crash, no replication, and nothing survives a process restart — stopping the MCP server
and starting it again hands Claude an empty store. That's a feature for a test fixture and a
liability for anything you actually want to keep, which is why opencontext's own docs point
newcomers toward the default JSON file or SQLite for real use and reserve memory://
for trying things out.
There's also no cross-process sharing. Two separate node processes each get
their own registry of named stores, so running the HTTP server and the MCP server as
separate processes against memory:// gives each one its own private, disconnected
data — unlike json:// or sqlite://, where both processes read and
write the same file on disk.
How it stacks up against JSON and SQLite
| Backend | Install | Survives a restart? | Best for |
|---|---|---|---|
memory:// | built in | No | Tests, demos, first run |
json:// | built in (default) | Yes | One machine, casual use |
sqlite:// | built in | Yes | Thousands of contexts, concurrent HTTP + MCP servers |
All three need nothing installed beyond opencontext itself, and — per the project's own BYODB contract — all three pass the identical conformance suite, so switching between them for development versus production changes nothing about how opencontext's six MCP tools behave. Only the lifetime of the data changes.
Under the hood: one adapter, six methods
opencontext's document-family backends — memory, mongodb,
redis, firestore, and dynamodb — all implement the same
small DocumentDriver interface: connect, close,
ping, get, put, remove, and
list. A shared createDocumentAdapter function layers search,
tag filtering, ordering, and bubble cascading on top of whichever driver it's given, so none
of that logic is duplicated per backend. The in-memory driver is the simplest possible
implementation of that contract — a Map standing in for a network call — which
is exactly why the project uses it as the reference implementation the shared adapter is
tested against.
This is also the architectural reason adding a new NoSQL backend to opencontext is a small change rather than a rewrite: implement those same six methods against a new store, and the search semantics, ordering guarantees, and MCP tool behavior come for free.
When to graduate off it
Move to a persisted backend the moment you want a context to still be there tomorrow. For a
single machine, that's the default json:// store or sqlite:// once
the store grows past a few thousand entries or you run the HTTP and MCP servers concurrently.
For context shared across machines or teammates, any of opencontext's remote backends —
Postgres, MySQL, Cloudflare D1, and the rest — apply. memory:// was never meant
to compete with those; it's meant to get out of the way until you decide you need one of them.
Try opencontext's MCP server with zero setup — point it at memory:// and start saving context.
FAQ
Does memory:// persist data across restarts?
No. A memory:// store lives only for the lifetime of the Node.js process. Restart the server or the CLI and the store is empty again — that is by design, not a bug.
Is memory:// safe to use in production?
No. It has no disk backing and no replication, so a process crash or restart loses everything. Use it for trying opencontext out, local development, demos, and automated tests — move to SQLite, JSON, or a remote backend for anything you need to keep.
Can I run two separate in-memory stores at once?
Yes. Everything after memory:// names an independent store, so memory://scratch and memory://tests hold separate data in the same process, while plain memory:// always points at the default store.
Do I need to install anything to use the in-memory backend?
No. memory:// is built into opencontext with no optional dependency to install, the same as the default json:// backend and the built-in sqlite:// backend.
Does the in-memory backend behave differently from the other backends?
No. It passes the same storage conformance suite as every other backend, so search, tag filtering, ordering, and bubble behavior are identical. Only persistence differs.