Edge

turbomem supports opt-in edge deployment via Upstash Vector - a remote vector database over HTTP. PGlite and sqlite-vec remain the default local backends for Node/Bun; you only need this guide when deploying to stateless edge runtimes.

When to use edge vs local storage

Runtime	Recommended storage
Node, Bun, local-first apps	"pglite" (default) or "sqlite-vec"
Cloudflare Workers, Vercel Edge, Deno Deploy	"upstash-vector"

Edge runtimes are stateless, there is no writable filesystem, and memory in an isolate does not survive between requests. Local PGlite or sqlite-vec paths will not persist on edge. Use a remote vector store instead.

No migration required

Existing PGlite or sqlite-vec setups keep working unchanged. Edge storage is an additional opt-in path.

How edge deployment works

Edge runtime ──► TurboMemory ──► Embedding API (fetch)
                      │
                      └──► Upstash Vector (HTTP)

1. Facts are extracted and embedded using fetch-based providers.
2. Vectors and metadata are stored in your Upstash index over REST.
3. Search queries embed the text, then query Upstash for similar vectors.

See Architecture for the full pipeline.

Prerequisites

Before writing code:

• [ ] An Upstash account (free tier available)
• [ ] A Vector index created in the console (see below)
• [ ] An embedding provider API key - Google (gemini-embedding-001) or Voyage (voyage-4) recommended. See Providers for the full model list.
• [ ] An extraction provider API key - Google (gemini-3.5-flash) recommended for edge. See Providers for the full model list.

Step 1: Create an Upstash Vector index

turbomem does not create the index for you. Set it up once in the Upstash Console:

1. Go to console.upstash.com → Vector → Create Index
2. Choose a name (e.g. turbomem-prod)
3. Set Dimensions to match your embedding model (see table below)
4. Set Similarity function to Cosine (matches PGlite and sqlite-vec)
5. Create the index
6. Open the index → Connect tab → copy UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN

Dimensions must match your embedding model

The index dimension count is fixed at creation time. If it does not match your embedding adapter, init() throws DimensionMismatchError. Create a new index when you change models.

Dimensions reference

Embeddings preset	Default dimensions	Set Upstash index to
"openai" (text-embedding-3-small)	1536	1536
"openai" (text-embedding-3-large)	3072	3072
"google" (gemini-embedding-001)	3072	768, 1536, or 3072 (match your google.dimensions config)
"voyage"	1024	1024 (or match your voyage.dimensions)
"local"	384	Not recommended on edge

See Providers for the full embedding reference.

Step 2: Install

npm install turbomem @upstash/vector

@upstash/vector is an optional peer dependency - only required when using storage: "upstash-vector".

Step 3: Environment variables

# Upstash Vector (from console Connect tab)
export UPSTASH_VECTOR_REST_URL=https://...
export UPSTASH_VECTOR_REST_TOKEN=...

# Embedding + extraction (Google example)
export GEMINI_API_KEY=...

Variable	Required	Used by
UPSTASH_VECTOR_REST_URL	Yes (unless set in config)	Upstash storage
UPSTASH_VECTOR_REST_TOKEN	Yes (unless set in config)	Upstash storage
GEMINI_API_KEY	Yes (Google stack)	Embeddings + extraction
VOYAGE_API_KEY	Yes (Voyage embeddings)	Embeddings

Step 4: Configure turbomem

import { TurboMemory } from "turbomem";

const memory = new TurboMemory({
  storage: "upstash-vector",
  upstashVector: {
    url: process.env.UPSTASH_VECTOR_REST_URL,
    token: process.env.UPSTASH_VECTOR_REST_TOKEN,
    // namespace: "my-app", // optional
  },
  embeddings: "google",
  google: {
    apiKey: process.env.GEMINI_API_KEY,
    dimensions: 768, // must match your Upstash index
  },
  extraction: {
    provider: "google",
    model: "gemini-3.5-flash",
    apiKey: process.env.GEMINI_API_KEY,
  },
});

await memory.init();

await memory.addFacts(["The user prefers edge deployments"], { userId: "user_123" });

const results = await memory.search("deployment preferences", { userId: "user_123" });

Or pass the adapter directly:

import { TurboMemory, UpstashVectorStorageAdapter } from "turbomem";

const memory = new TurboMemory({
  storage: new UpstashVectorStorageAdapter({
    url: process.env.UPSTASH_VECTOR_REST_URL,
    token: process.env.UPSTASH_VECTOR_REST_TOKEN,
  }),
  // ...
});

Recommended provider stack

Component	Recommended	Avoid on edge
Storage	"upstash-vector"	"pglite", "sqlite-vec"
Embeddings	"google", "voyage"	"local" (heavy WASM cold start)
Extraction	"google"	-

Runtime notes

Cloudflare Workers

Set secrets with wrangler secret put UPSTASH_VECTOR_REST_URL (and token, API keys). No filesystem access, Upstash over HTTP is the right fit.

Vercel Edge Functions

Add environment variables in your project settings. If using Next.js App Router, mark the route as edge-compatible in your route config.

Node / serverless (not edge)

PGlite is usually simpler for Node deployments with disk access. Upstash is optional here too, useful when you want shared remote storage across serverless instances.

Limitations

• getAll() - paginates the full index and filters client-side. Can be slow on large indexes.
• deleteAll() - Upstash metadata filter deletes perform a full index scan (O(n)).
• Eventual consistency - newly upserted vectors may take a moment before appearing in search results.
• Cost - Upstash charges per request; PGlite uses free local disk.
• CLI - the turbomem CLI targets local PGlite. Edge users integrate via the SDK.

Troubleshooting

Error	Cause	Fix
DimensionMismatchError	Index dimensions ≠ embedding model	Create a new index with correct dimensions, or adjust google.dimensions
ConfigError (missing @upstash/vector)	Peer not installed	npm install @upstash/vector
Upsert/query fails (401)	Wrong URL or token	Re-copy credentials from Upstash Connect tab
Empty search results right after insert	Eventual consistency	Retry after a brief delay

Next steps

• Storage - full backend comparison
• Configuration - upstashVector config reference
• Providers - embedding dimensions and API keys
• Architecture - pipeline overview