Deployment
Start local in one command; scale to distributed when you need it.
TemporalStore runs the same engine two ways. Local mode is a single node on local disk — perfect for development, edge, and self-hosting. Distributed mode fans the same serving core across a proxy, a metaserver, and many datanodes, with replicated durability and, at enterprise scale, shared storage.
Two modes, one engine
The same API and data models; the topology grows underneath.
Your application code does not change between modes — it writes events and builds context packs the same way. What changes is how many processes serve those calls and where durable data lives.
Same clients, same models. Local mode is one process on local disk; distributed mode spreads shards across datanodes with replicated or shared durable storage.
Local mode
One node, local disk, running in a minute.
Use local mode for development, CI, edge deployments, single-tenant self-hosting, and trying the store on your own data. It needs nothing but a container runtime; add Ollama if you want fully local, open-source embeddings and readers.
docker run -d --name temporalstore \
-p 8080:8080 \
-v $PWD/ts-data:/var/lib/temporalstore \
ghcr.io/bjmeetsfo/temporalstore:latest \
--mode local --data-dir /var/lib/temporalstore# embeddings + a small local reader, no API keys
ollama pull nomic-embed-text
ollama pull qwen2.5:1.5b
export TS_EMBED_URL=http://127.0.0.1:11434
export TS_READER_URL=http://127.0.0.1:11434/v1from temporalstore import Client
ts = Client("http://localhost:8080")
ts.put_event(table="agent_memory", entity="workspace_7",
ts_ms=now_ms, attrs={"kind": "decision", "text": "..."})
pack = ts.context(entity="workspace_7", since="24h",
summarize=True, token_budget=4096)Distributed mode
Scale reads and writes across a cluster.
Distributed mode adds a proxy (routing and batching), a metaserver (shard placement and membership), and multiple datanodes that each own a set of shards. Durability is provided by MatrixRaft (consensus-replicated WAL) or, at enterprise scale, by MatrixObject shared storage so compute and storage scale independently.
services:
metaserver:
image: ghcr.io/bjmeetsfo/temporalstore:latest
command: --role metaserver --listen 0.0.0.0:9100
datanode-a:
image: ghcr.io/bjmeetsfo/temporalstore:latest
command: --role datanode --meta metaserver:9100 --shards 0-341
datanode-b:
image: ghcr.io/bjmeetsfo/temporalstore:latest
command: --role datanode --meta metaserver:9100 --shards 342-683
proxy:
image: ghcr.io/bjmeetsfo/temporalstore:latest
command: --role proxy --meta metaserver:9100
ports: ["8080:8080"]Clients still talk to a single endpoint (the proxy) and use the same API as local mode. Add datanodes to grow capacity; the metaserver rebalances shards. Choose the durability backend below.
Storage backend
Pick the durable tier for your deployment.
| Backend | Mode | Best for | Licensing |
|---|---|---|---|
| Local disk | Local | Single node, dev, edge, self-hosted. | Open source |
| MatrixRaft | Distributed | Replicated high availability without shared storage; fixed replica set. | Open source |
| MatrixObject Enterprise | Distributed | Disaggregated, concurrent read/write, elastic capacity at five-nines. Details | Enterprise |
Which mode should I run?
Start local; go distributed when one node is not enough.
| If you need… | Mode |
|---|---|
| Development, CI, a demo, or a single-tenant self-host | Local |
| Edge or on-device context with no cluster to run | Local |
| High availability and failover for agent memory | Distributed + MatrixRaft |
| Horizontal scale for concurrent reads/writes across many entities | Distributed |
| Disaggregated compute/storage, elastic retention, five-nines | Distributed + MatrixObject Enterprise |
Keep reading