Introduction

SOMA is a personal AI assistant with knowledge-graph memory. It captures, recalls, and reasons about the things you care about — books, people, projects, habits, workouts, meetings — and it does it from three surfaces: a web app, a Telegram bot, and a set of background workflows that ingest mail and calendar events.

Design stance

• Dark-first, warm, precise, quiet. The visual language is borrowed from alfred_ai, Linear, and Reflect. One amber accent, no alternative. Borders over shadows. Type-first density. No light mode on MVP.
• One graph, five tables. Every user-facing noun is a row in entities, typed by type. No per-domain tables. New domain = new type literal. The rest is edges, events, facts, sources.
• Tools own writes. Every DB mutation flows through a Mastra tool in @soma/tools. UIs and bots call server actions; server actions call tools. Single write path = single place to validate, embed, trace.
• RLS mandatory. Every table ships with USING (user_id = auth.uid()) policies, enforced even on single-user MVP. Retrofitting RLS later is brutal.
• Zod in @soma/core is the source of truth. One schema → backend validation + TS types + frontend forms. Never duplicated.

What's in the monorepo

• apps/web — Next.js 15 App Router. RSC pages, server actions, streaming chat. Also hosts the Inngest workflow handler and the Telegram webhook.
• apps/bot — grammY bot definition (used as a library by apps/web, plus a local polling dev mode).
• apps/docs — this site (Astro + Starlight).
• apps/mobile — Expo RN stub.
• packages/agent — Mastra agents, prompts, memory, Inngest functions, observability.
• packages/tools — The tool registry: memory_*, search_*, graph_*, schedule_*, external/*.
• packages/db — Drizzle schema, migrations, RLS SQL.
• packages/core — Zod schemas for entities, events, facts, sources.
• packages/ui — shadcn + design tokens.
• packages/api-client — TanStack Query hooks.
• packages/config — shared tsconfig / ESLint / Vitest configs.

Where to read next

• System architecture — how requests flow through the stack.
• Design philosophy — the why behind the structural choices.
• Data model — the five tables in detail.