LibSQL

LibSQL backs Mastra storage domains that the repo intentionally keeps out of MongoDB today.

What It Owns

Mastra eval datasets.
Mastra experiments.
Mastra scorer storage domains.
Local file or in-memory storage for specific dev/test lanes, depending on API configuration.

Architecture Decision

Decision: use LibSQL as the Mastra storage sidecar for datasets, experiments, and scores because the current MongoDB adapter does not cover those Mastra storage domains in this repo.

This is a composite-storage choice, not a second product database. Product chat policy metadata remains in API-owned MongoDB models, and Mastra memory/workflows remain on MongoDB.

How To Upgrade

Upgrade @mastra/libsql with the Mastra package family:

# from apps/api
bun update @mastra/libsql

Then run:

bun run --cwd apps/api check-types
bun run --cwd apps/api test:chat:evals
bun run --cwd apps/api test:chat:experiments

If Mastra release notes call for storage migrations, run mastra migrate against the intended API storage configuration.

Current Limits

In-memory LibSQL resets when the process changes and is only suitable for development/test usage.
File-backed LibSQL is not safe for serverless or ephemeral filesystems unless persistence is explicitly provided.
Do not move product source-of-truth data into LibSQL without a canonical architecture decision.

Canonical Sources

apps/api/src/mastra/runtimeStorage.ts
apps/api/src/env.ts
apps/api/package.json
docs/features/chat/spec.md