Skip to main content
Tuturuuu AI memory is backed by an internal Postgres/pgvector sidecar through the server-only @tuturuuu/ai/memory boundary. Product routes must not call the sidecar from the browser and must not create product-specific memory stores.

​
Scope

Memory scope is always user + workspace. The shared helper builds a stable container tag from those two identifiers and stores product, surface, route, locale, timezone, conversation, and workspace metadata on each write. Default recall is cross-product within that user + workspace container. Use metadata filters only when a route needs a narrower product or surface view.

​
Runtime

Use withAiMemory for AI SDK calls when the route has a user and workspace. Use ingestAiMemoryEvent, buildAiMemoryContext, and the Mira-compatible tool executors for explicit memory reads and writes. Reads fail open by default, and writes are best effort. Every embedding used for memory add/search is generated through the metered @tuturuuu/ai embedding helper before the sidecar is called. If credits, pricing, token counting, or billable attribution cannot be verified, the memory operation skips before calling Google. Structural metering failures disable memory for the user scope. Keep SUPERMEMORY_FAIL_OPEN=true unless a product explicitly requires strict persistence. Required server-side env: 
SUPERMEMORY_ENABLED=true
SUPERMEMORY_BASE_URL=http://supermemory:8787
SUPERMEMORY_API_KEY=...
SUPERMEMORY_TIMEOUT_MS=1500
SUPERMEMORY_FAIL_OPEN=true
SUPERMEMORY_DATABASE_URL=postgres://...
For Docker blue/green and watcher deployments, the Docker helper auto-generates and injects the internal API key, bundled Postgres password, database URL, internal base URL, fail-open setting, and timeout. Use DOCKER_SUPERMEMORY_API_KEY, DOCKER_SUPERMEMORY_POSTGRES_PASSWORD, DOCKER_SUPERMEMORY_DATABASE_URL, or DOCKER_SUPERMEMORY_ENABLED=false only when an operator needs to override that generated runtime. An explicit false value also removes the sidecar from Docker blue/green support builds and health gates. SUPERMEMORY_API_KEY is internal infrastructure configuration. Never expose it through browser-visible env vars or client responses.

​
User Controls

Workspace settings live behind: 
GET/PATCH /api/v1/workspaces/:wsId/ai/memory/settings
GET /api/v1/workspaces/:wsId/ai/memory/items
DELETE /api/v1/workspaces/:wsId/ai/memory/items/:memoryId
POST /api/v1/workspaces/:wsId/ai/memory/export
The settings dialog exposes enable/disable, product toggles, search/list, delete, and export controls. API routes call private schema RPCs through the server-side Supabase admin client.

​
Migration

Legacy mira_memories rows are imported with the admin-only backfill endpoint: 
POST /api/v1/admin/ai/memory/backfill-mira
Backfill is idempotent through stable customId values. Rows without a legacy workspace are imported into the user’s default or personal workspace and tagged with legacy_mira metadata.

​
Self-Hosting

The Docker fleet runs the first-party memory sidecar as an internal support service named supermemory for compatibility with existing base URL, API key, watcher, and Compose wiring. The sidecar stores 3072-dimensional gemini-embedding-2 vectors in extensions.halfvec(3072) with HNSW cosine indexes, plus GIN indexes for metadata and full-text hybrid search. The supermemory-db-migrate service applies apps/supermemory/db schema changes before the runtime starts. The watcher and cron recovery path use the same generated Docker env, so recreating web-blue-green-watcher does not require manually exporting memory service secrets. There is no SUPERMEMORY_IMAGE enterprise-image contract. Connectors such as Google Drive, OneDrive, and Notion are disabled for the first rollout. Product ingestion should persist concise summaries only; do not ingest raw files or binaries unless the source is user-owned, enabled, and explicitly appropriate for memory.