How supabase-community/natural-db works
Project Type and Purpose
• This is a serverless, cloud-based AI personal assistant built on Supabase.
• It combines Postgres (with pgvector and pg_cron), Supabase Edge Functions, and external services (OpenAI, Telegram, Zapier) to provide persistent memory, scheduled tasks, real-time web search, and multi-channel I/O.
File Structure
• Top-level
• README.md – high-level overview and architecture description
• supabase/ – Supabase project directory
• supabase/config.toml – Supabase project config
• supabase/migrations/…_create_initial_schema.sql – DB schema (extensions, memories schema, roles, cron setup)
• supabase/functions/
• natural-db/
– index.ts (main AI brain: orchestration, tool integration, DB operations)
– db-utils.ts (Postgres helpers, execute_sql tool)
– tools.ts (wrappers for web search, Zapier MCP, scheduling, etc.)
• telegram-input/index.ts – webhook handler for incoming Telegram messages
• telegram-outgoing/index.ts – response formatter and delivery
Extract Key Architectural Insights from README
• Core building blocks:
• Scoped Postgres schema (“memories”) with a dedicated role
• Three memory types: message history, semantic (pgvector), structured SQL
• Scheduled prompts via pg_cron
• Web Search tool for real-time info
• Zapier MCP integration (emails, calendar, notifications)
• Telegram Bot interface via webhooks
• Edge Functions serve as microservices responding to events or cron triggers
Main Components & Interactions
a. Components
1. Telegram Bot (external)
2. Supabase Edge Function: telegram-input
3. Supabase Edge Function: natural-db
4. Supabase Edge Function: telegram-outgoing
5. Postgres Database
– memories schema (structured tables + system_prompts)
– pgvector extension (semantic memory)
– pg_cron extension (scheduled triggers)
6. OpenAI (LLM & web search tool)
7. Zapier MCP (external actions)
b. Relationships & Data Flow
• Telegram user → Telegram Bot webhook → telegram-input function
• telegram-input → calls natural-db for processing
• natural-db
• uses db-utils to execute SQL in memories schema
• calls tools: web search, Zapier MCP, pg_cron schedule
• writes/reads from Postgres (message history, semantic embeddings, structured tables)
• natural-db → emits response to telegram-outgoing
• telegram-outgoing → posts reply back to Telegram Bot
• Cron jobs (pg_cron) automatically invoke natural-db on schedule
• natural-db → calls OpenAI APIs for LLM, embedding, web search
Architectural Patterns & Design Principles
• Event-driven microservices (Edge Functions triggered by HTTP/Webhook or cron)
• Single responsibility per function (ingest, core logic, outbound)
• Principle of least privilege (memories_role scoped to memories schema)
• Layered memory architecture (short-term, semantic, structured)
• Tool-oriented integration (each external capability wrapped in a tool interface)
Technologies & Frameworks to Highlight
• Supabase Edge Functions (TypeScript on Deno)
• PostgreSQL extensions: pgvector, pg_cron, pg_net (for HTTP calls)
• OpenAI API (LLM, embeddings, web search)
• Telegram Bot API (webhooks)
• Zapier MCP Integration
• Supabase CLI / Dashboard for deployment
Detailed Component Breakdown (
• Telegram Interface
• Telegram Bot → HTTPS webhook → telegram-input
• Ingestion Layer
• telegram-input → HTTP → natural-db
• Core Processing
• natural-db
– Calls db-utils (execute_sql)
– Calls tools.ts (LLM, embeddings, web search, Zapier MCP)
– Schedules tasks via pg_cron
• Data Layer
• Postgres
– memories schema tables
– public.system_prompts
– Extensions (pgvector, pg_cron)
• Outgoing Layer
• natural-db → push to telegram-outgoing → Telegram API
• Scheduled Autonomy
• pg_cron → triggers natural-db on schedule