Mem0

# MISSION: Scaffold "Mem0" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **Mem0**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: Mem0
- **What It Does**: Mem0 is a memory layer for AI agents: a Python core library (pyproject.toml) defaulting to Qdrant for vector storage and OpenAI for embeddings and LLM calls, with an optional FastAPI hosted server and Next.js dashboard for teams that want it managed.
- **Domain & Category**: AI Memory & Context Engine
- **Production Scale**: 2-5 people
- **Development Mode**: AI-AGENT
- **Architectural Rationale**: Keeping the core library provider-agnostic through optional dependency groups, while the hosted server bundles a fixed set of vector stores, LLM providers, auth, and rate limiting behind its own FastAPI app, lets self-hosters install a minimal footprint without forking the managed-service code path.
- **Live Website Reference**: https://mem0.ai
- **Source Repository**: https://github.com/mem0ai/mem0
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Python, TypeScript, FastAPI, Qdrant, OpenAI, PostgreSQL, Next.js, Redis
- **Primary Language(s)**: Python, TypeScript
- **License of the reference repo**: Apache-2.0
- **Frontend**: Next.js — Powers the standalone dashboard app under server/dashboard.; React — Component layer for the dashboard, on React 19.; Radix UI — Accessible primitives (dialogs, dropdowns, tooltips) used throughout the dashboard.; Tailwind CSS — Styling for the dashboard, extended with the typography plugin and tailwind-merge.
- **Backend & APIs**: Python — Implements the core mem0ai memory library published from the repository root.; FastAPI — Serves the optional hosted memory API in server/, built on top of the mem0ai package.; Uvicorn — ASGI server that runs the FastAPI app; the Dockerfile starts it directly.; Alembic — Manages schema migrations for the hosted server auth and account database.
- **Data & persistence**: Qdrant — Default vector store for the core memory library, used unless another backend is configured.; OpenAI — Default LLM and embedding provider for the core memory library.; PostgreSQL — Backs the hosted server auth and account database via psycopg.; SQLAlchemy — ORM used for relational storage in both the core library and the hosted server.; Redis — Optional vector store backend for the core library, alongside Qdrant.
- **Infrastructure & deploy**: Docker — Separate Dockerfiles package the FastAPI server and the Next.js dashboard as containers.; PostHog — Anonymous telemetry collector, enabled by default in both the library and the hosted server.
- **Tooling, testing & ops**: GitHub Actions — Separate CI/CD workflows build, test, and release the Python SDK, TypeScript SDK, and integrations.; Anthropic — Bundled as a directly supported LLM provider in the hosted server image.
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/mem0ai/mem0 @ f135cb9)
1. **Core memory library ships with a default vector and LLM stack**: pyproject.toml pins qdrant-client and openai as unconditional dependencies of the mem0ai package, so a fresh install has a working vector store and LLM/embedder immediately, while its optional-dependency groups (vector-stores, llms) swap in over a dozen alternative backends.
2. **Hosted server is layered on the core library, not a fork of it**: server/requirements.txt depends on mem0ai itself alongside fastapi and uvicorn, plus its own auth stack (sqlalchemy, alembic, passlib, python-jose) and rate limiting (slowapi), so the hosted API adds a multi-tenant layer on top of the open-source engine.
3. **The server bundles a fixed set of LLM providers, not the full extras**: server/requirements.txt pins anthropic and google-generativeai directly, with a comment noting that adding a provider means rebuilding the image and updating BUNDLED_LLM_PROVIDERS in main.py, instead of installing the broader optional llms dependency group defined in the root pyproject.toml.
4. **The dashboard is a standalone Next.js app, not server-rendered by the API**: server/dashboard/package.json defines its own Next.js 15 project with its own Dockerfile producing a standalone Node build (.next/standalone), so the dashboard is built, containerized, and scaled independently of the FastAPI server it calls.
5. **PostgreSQL plays two different roles depending on which part is deployed**: The root pyproject.toml lists psycopg and psycopg-pool as optional dependencies for using Postgres, via pgvector, as a vector store inside the core library, while server/requirements.txt depends on psycopg unconditionally to back the relational auth and account database used only by the hosted server.
6. **Telemetry is opt-out by default across the library and the server**: Both the root pyproject.toml and server/requirements.txt depend on posthog, and server/requirements.txt documents it directly as anonymous telemetry that is on by default and disabled by setting MEM0_TELEMETRY=false.
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Next.js 15 App Router: default to React Server Components (RSC) for data fetching. Handle mutations through Server Actions with Zod validation. Keep 'use client' directives restricted strictly to interactive leaf components.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer (Qdrant, OpenAI, PostgreSQL, SQLAlchemy, Redis): client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.