๐ฆ San'e (ุตุงูุน) โ The Arabic-First Personal AI Assistant for the GCC
San'e (ุตุงูุน, Arabic for "The Maker") is an open-source, self-hosted personal AI assistant designed from the ground up for the 400 million Arabic speakers in the Gulf and beyond. It is a localized fork of the powerful OpenClaw framework (MIT), reimagined with a deep understanding of GCC culture, language, and daily life.
Where OpenClaw provides a generic and excellent foundation, San'e provides a soul. It speaks your language, understands your culture, and anticipates your needs โ from prayer times in Kuwait City to government services in Riyadh.
| Language | Status | License | Deployment |
|---|---|---|---|
| TypeScript | โ Active | MIT | Docker / Node.js |
Core Philosophy
Arabic-First, not Arabic-added. San'e is not a translation of an English assistant; it is built with an Arabic-first mindset. All system prompts, configurations, and interactions default to a natural, professional Gulf Arabic register โ the kind a Kuwaiti professional would use with a trusted colleague.
GCC-Native. Culturally-aware skills are at the core of San'e. It understands the rhythms of life in the Gulf, from Ramadan scheduling to Hijri calendar events and government portal navigation.
Open & Self-Hosted. Your data, your assistant. San'e runs on your own hardware (a local machine or any VPS), ensuring complete privacy and control.
Features
Arabic Language Layer
- Default model configured for strong Arabic capability (Claude Sonnet 4.6 via Anthropic API).
- Natural, warm, professional Gulf-Arabic persona โ not formal MSA, not colloquial.
- Seamless RTL text handling across all interfaces.
- Arabic-first onboarding flow (
ู ุง ุงุณู ูุ ููู ุฃุณุงุนุฏูุ).
๐ง Self-Learning & Memory
- Long-Term Memory: Remembers user preferences, facts, and past interactions across sessions.
- Vector Database: Uses a local ChromaDB instance to store and retrieve semantically relevant information.
- Knowledge Extraction: Automatically identifies and saves important facts from conversations.
- User Control: Ask San'e "ุชุฐูุฑ ูุฐุง" (Remember this) to save a fact, or "ู ุง ูู ุชูุถููุงุชูุ" (What are my preferences?) to recall them.
Agent Management Layer (Orchestrator)
San'e now features a sophisticated Agent Management Layer that acts as a "Meta-Orchestrator" (ุงูู ุฏูุฑ ุงูุนุงู ). This layer intelligently routes user requests to the most appropriate specialized agent or skill, ensuring efficient and context-aware responses. It also includes stubs for:
- Model Performance Monitor: To track and optimize AI model performance.
- Conflict Resolver: To manage and resolve conflicting information from various sources.
- Resource Allocator: To ensure cost-effective API and token usage.
GCC Retail & Supermarket Suite (12 Specialized Agents)
San'e now includes a comprehensive Retail Suite with 12 specialized agents designed to enhance your shopping experience in the GCC:
| # | Agent Model | Function |
|---|---|---|
| 1 | Price Scout (ุงูู ุณุชูุดู) | Compares real-time prices across major GCC retailers (Lulu, Carrefour, Panda). |
| 2 | Co-op Finder (ุฏููู ุงูุฌู ุนูุงุช) | Locates Kuwaiti Co-ops (Jam'iyas), their services, and digital flyers. |
| 3 | Offer Hunter (ุตุงุฆุฏ ุงูุนุฑูุถ) | Scans for the best weekly deals and discounts in the region. |
| 4 | Loyalty Manager (ู ุฏูุฑ ุงูููุงุก) | Tracks and manages points for various loyalty programs (MyCLUB, Lulu Points, Blue Rewards). |
| 5 | Freshness Inspector | (Stub) Analyzes product quality (e.g., fruits, vegetables). |
| 6 | Pantry Tracker | (Stub) Predicts when you'll run out of staples based on consumption patterns. |
| 7 | Nutri-Halal Checker | (Stub) Verifies ingredients for Halal compliance and nutritional information. |
| 8 | Cart Optimizer | (Stub) Optimizes shopping lists across multiple stores for the lowest total cost. |
| 9 | Delivery Liaison | (Stub) Interfaces with local delivery services (e.g., Talabat, Jahez). |
| 10 | Recipe-to-Cart | (Stub) Converts traditional GCC recipes into actionable shopping lists. |
| 11 | Budget Controller | (Stub) Tracks and manages monthly grocery spending against set budgets. |
| 12 | Bulk Buy Advisor | (Stub) Provides advice on cost-effective bulk purchasing, especially during seasonal events. |
GCC Cultural Skills (built-in)
| Skill | Description |
|---|---|
| ๐ Prayer Times | Auto-fetches Salah times for Kuwait City, Riyadh, Dubai, Abu Dhabi, Doha, Manama, and Muscat. Sends proactive reminders 15 minutes before each prayer. |
| ๐ Ramadan Mode | Automatically detects Ramadan via the Hijri calendar. Adjusts scheduling logic, provides Iftar/Suhoor times, and adopts a spiritually-aware tone. |
| ๐ Hijri Calendar | Displays both Gregorian and Hijri dates in all date references. Supports conversion between calendar systems. |
| ๐ฐ๐ผ Kuwait Gov Portals | Direct links and guidance for MOI, PACI, Civil ID, Ministry of Health, Municipality, and the Kuwait e-Government portal. |
| ๐ง Knowledge Extraction | Manages the learning process and memory retrieval. |
| ๐ข AgenThink Bridge | A placeholder skill for future integration with the San'e Business and AgenThink Institutional ecosystem. |
Channel Integration
- Telegram (via grammY): Full bot integration with Arabic welcome message, command handling, and session management.
- WhatsApp (via Baileys): QR-code pairing, Arabic welcome message, and persistent sessions.
Deployment
- One-command install script for Ubuntu and macOS.
- Docker Compose file for production VPS deployment.
- Health check endpoint at
/healthfor monitoring. - Web dashboard at port
18789for status overview.
Tech Stack
- Base Framework: OpenClaw (Node.js, TypeScript)
- AI Model: Anthropic Claude Sonnet 4.6 (configurable via
SANE_MODEL) - Memory: ChromaDB (Vector Store), Gemini Embedding API
- Channels: WhatsApp (Baileys), Telegram (grammY)
- Deployment: Docker, Node.js 22+
Getting Started
Prerequisites
- Node.js v22+
- Docker & Docker Compose (for VPS deployment)
- API Keys:
ANTHROPIC_API_KEY(required),GEMINI_API_KEY(required for memory),TELEGRAM_BOT_TOKEN(optional)
1. One-Command Install (Ubuntu / macOS)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/your-org/sane-assistant/main/scripts/install.sh)"
2. Manual Installation
# Clone the repository
git clone https://github.com/your-org/sane-assistant.git
cd sane-assistant
# Install dependencies
npm install -g pnpm
pnpm install
# Configure your assistant
cp .env.example .env
# Edit .env with your API keys and preferences
# Run the interactive onboarding wizard
pnpm sane onboard
# Start the assistant
pnpm start
3. Docker Deployment (VPS)
# Clone and configure
git clone https://github.com/your-org/sane-assistant.git
cd sane-assistant
cp .env.example .env
# Edit .env with your API keys
# Build and run
docker compose up -d --build
# Check status
docker compose logs -f
# Dashboard: http://<your-vps-ip>:18789
Configuration
All configuration is managed via the .env file. Key settings:
| Variable | Default | Description |
|---|---|---|
ANTHROPIC_API_KEY |
โ | Required. Your Anthropic API key. |
GEMINI_API_KEY |
โ | Required for self-learning. Your Google AI Studio API key. |
SANE_MODEL |
claude-sonnet-4-5 |
The AI model to use. |
SANE_LOCATION |
kuwait_city |
Your city for prayer times. Options: kuwait_city, riyadh, dubai, abu_dhabi, doha, manama, muscat. |
SANE_LANGUAGE |
ar |
Default language (ar or en). |
TELEGRAM_BOT_TOKEN |
โ | Your Telegram bot token from @BotFather. |
TELEGRAM_ALLOWED_USERS |
โ | Comma-separated Telegram user IDs allowed to use the bot. |
SANE_PRAYER_REMINDERS |
true |
Enable/disable proactive prayer reminders. |
SANE_RAMADAN_MODE |
auto |
auto (detect via Hijri calendar), on, or off. |
CLI Commands
pnpm sane start # Start the San'e gateway
pnpm sane onboard # Run the interactive setup wizard
pnpm sane chat # Chat directly in the terminal
pnpm sane status # Check if San'e is running
pnpm sane skills # List all loaded skills
The San'e Ecosystem
San'e is the first step in a three-tier ecosystem designed to bring powerful, culturally-aware AI to the Arab world.
| Tier | Product | Status |
|---|---|---|
| 1 | San'e Personal (ุตุงูุน ุงูุดุฎุตู) โ This project. Personal assistant for individuals. | โ Available |
| 2 | San'e Business (ุตุงูุน ุงูุฃุนู ุงู) โ AI solutions for SMEs. | ๐ Coming Soon |
| 3 | AgenThink Institutional โ Enterprise-grade multi-agent platform. | ๐ Coming Soon |
Contributing
San'e is an open-source project, and contributions are welcome. Please fork the repository, create a feature branch, and submit a pull request.
License
San'e is licensed under the MIT License. It is a derivative work of OpenClaw, which is also licensed under MIT.