VAAYU (वायु)

Like wind — swift, everywhere, carrying what matters.

Vaayu is a self-hosted, privacy-first AI assistant that lives across your messaging platforms and native apps. Memory belongs to you, not the provider. Every action respects consent. Every tool runs behind policy. Built with the precision of Vishwakarma and the strength of Hanuman.

Why Vaayu?

• Your memory, your data. Switch providers mid-conversation without losing context. Smriti (memory) is user-centric, not provider-locked.
• Local-first. NLU, embeddings, and fallback LLM all run locally. Cloud is opt-in.
• Cost-aware. Smart routing sends simple queries to cheap/local models, complex ones to quality providers. Target: $5-10/month.
• Extensible skills. Weather, finance, health, reminders, notes, music, smart home, travel, calls -- and skills that learn on the fly.
• Privacy by default. No exec/write/delete/network without approval. Memory writes require consent. Sandbox-first execution.

Upstream Inspiration

Vaayu’s provider/LLM registry is derived from pi‑mono (pi‑ai) and then refactored and extended for Vaayu’s policy, routing, and model‑switching needs. We also adapt orchestration and self‑healing patterns from gru‑main, while preserving Vaayu’s privacy‑first guardrails.

Architecture

Vaayu uses a Pantheon Architecture -- four subsystems with clear boundaries:

flowchart TB
  subgraph Channels
    TG[Telegram]
    Hub[Hub UI]
    DC[Discord]
    WA[WhatsApp]
    SL[Slack]
  end

  subgraph Vaayu Core
    GW[Gateway]
    NLU[Saraswati - NLU]
    PL[Brahma - Planner]
  end

  subgraph Hanuman[Policy Gateway]
    POL[Tool Policy]
    APR[Approvals]
  end

  subgraph Vishwakarma[Executor]
    SBX[Sandbox]
    BLD[Build/Test]
  end

  subgraph Smriti[Vyasa - Memory]
    MEM[(Sessions + Knowledge)]
    VEC[(Embeddings)]
  end

  subgraph Providers
    CL[Claude]
    OAI[OpenAI]
    OLL[Ollama - Local]
    MM[MiniMax]
  end

  Channels --> GW
  GW --> NLU
  NLU --> PL
  PL --> Hanuman
  Hanuman --> Vishwakarma
  Hanuman --> Providers
  GW --> Smriti
  Vishwakarma --> Smriti

| Role | Subsystem | What It Does | |------|-----------|--------------| | Vaayu Core | Gateway + Brain | NLU, planning, orchestration | | Vyasa (Smriti) | Memory | Storage, recall, summarization, knowledge extraction | | Hanuman | Policy Gateway | Approvals, sanitization, risk gating | | Vishwakarma | Executor | Sandboxed execution, build/test pipeline |

For full ASCII flow/state diagrams and concrete examples, see docs/architecture.md.

English-First Naming

For public docs and onboarding, use English names first:

| English (preferred) | Internal codename | |------|------| | NLU Engine | Saraswati | | Planner | Brahma | | Policy Gateway | Hanuman | | Guardrail Manager | Vyasa | | Tool Executor | Vishwakarma | | Memory System | Smriti | | Multi-Agent Broker | Kaala |

Full map (including Chitragupta names): docs/aliases.md.

Quick Start

# Clone
git clone https://github.com/srinivaspendela/vaayu.git
cd vaayu

# Install
pnpm install

# Configure
cp .env.example .env
# Edit .env with your API keys (Anthropic, OpenAI, MiniMax, etc.)

# Run (gateway + smriti)
pnpm start:all

# Or run them separately
pnpm dev
pnpm -C smriti run api

Open the Hub: http://127.0.0.1:18369/hub Legacy Hub (v1): http://127.0.0.1:18369/hub-old

Prerequisites

• Node.js 22+
• pnpm 9+
• Ollama (optional, for local models)

Features

| Category | Details | |----------|---------| | Multi-channel | Telegram, Hub UI, Discord, WhatsApp, Slack, Email | | Multi-provider | Claude, OpenAI, Ollama, MiniMax -- switch mid-conversation | | Memory (Smriti) | User-centric, 5-tier progressive summarization, hybrid search | | Skills | Weather, finance, health, reminders, notes, music, panchangam | | Smart Home | HoloCube ambient display, IoT integrations | | Voice | STT transcription, TTS (MiniMax), voice notes | | Security | Device pairing, approval workflows, sandbox execution | | Cost-aware | Smart routing, local-first, token accounting | | Privacy | Self-hosted, consent-gated memory, secret redaction |

Skills

Stable skill packs in ../ecosystem/skills/:

| Skill | Description | |-------|-------------| | weather | Forecasts, briefings, sun/moon data | | finance | CSV analysis, portfolio summaries | | health | BMI, health metrics tracking | | reminders | Create, list, manage reminders | | apple-notes | macOS Notes integration via bridge | | music | Spotify, Apple Music playback | | panchangam | Hindu calendar, tithi, nakshatra | | holo-cube | Ambient display briefings | | audio-transcribe | Voice/audio transcription |

Community skills in ecosystem/skill-community/. Experimental skills in ecosystem/skill-lab/.

Project Structure

vaayu/
  apps/
    gateway/         Gateway server (HTTP + WS + channels)
    cli-gateway/     Gateway CLI
    cli-node/        Node device CLI
    cli-cron/        Scheduled jobs
    bridges/         Hardware bridges (HoloCube, Apple Notes)
    mcp/             MCP servers (NLU)

  packages/
    core/            Types, routing, profile, identity
    config/          Configuration loader + env overrides
    providers/       LLM provider registry + adapters
    tools/           Tool registry, policy, MCP manager
    storage/         File, SQLite, Postgres drivers
    memory/          Memory pipeline
    channels/        Channel adapters (Telegram, Discord, Slack, etc.)
    protocol/        WebSocket protocol frames
    auth/            OAuth PKCE + device code flows
    scheduler/       Cron + one-shot jobs
    sandbox/         Sandboxed execution
    logger/          Structured logging + secret redaction
    nlu/             In-process rules NLU
    guardian/        Security gate (2FA, rate limit, injection detection)

  skills-core/       Product-private skill packs (reserved)

  ../ecosystem/      Sibling directory (outside vaayu/)
    skills/          Approved, vetted skill packs (stable runtime tier)
    skill-lab/       Experimental skills (isolated)
    skill-community/ Community-contributed skills
  docs/              Architecture, guides, protocol docs
  vaayu-spec/        Design spec (55+ documents, source of truth)

Providers

| Provider | Type | Use Case | |----------|------|----------| | Claude (Anthropic) | Cloud | Quality reasoning | | OpenAI | Cloud | General purpose | | MiniMax | Cloud | TTS, cost-effective | | Ollama | Local | Offline fallback, free |

Recommended model choices are documented in docs/models.md.

Configure via .env:

VAAYU_PROVIDER_DEFAULT=anthropic
VAAYU_PROVIDER_ANTHROPIC_API_KEY=sk-ant-...
VAAYU_PROVIDER_OPENAI_API_KEY=sk-...

See docs/providers.md for full provider configuration.

Memory (Smriti)

Smriti (Sanskrit: remembrance) is Vaayu's user-centric memory system.

Key principles:

• Memory belongs to the user, not the provider
• Provider switches preserve full context
• 5-tier progressive summarization (94% compression over 1 year)
• Hybrid search: BM25 (keyword) + Vector (semantic)
• All writes require explicit consent

VAAYU_SMRITI_ENABLED=true
VAAYU_SMRITI_BASE_URL=http://127.0.0.1:7788

See docs/memory.md for details.

Local Models

| Model | Purpose | Size | |-------|---------|------| | BGE-M3 | Embeddings (100+ languages) | 1.2 GB | | Qwen2.5-7B | Local LLM fallback | 4.3 GB | | GLiNER2 | NLU (NER + intent) | 500 MB |

Install via Ollama:

ollama pull bge-m3

See vaayu-spec/architecture/VAAYU-INSTALLATION-GUIDE.md for complete setup.

Development

pnpm dev          # Start gateway (dev mode)
pnpm typecheck    # Type-check all packages
pnpm build        # Production build
pnpm secrets:scan # Scan for leaked secrets
pnpm hooks:install # Install git hooks

Code Standards

• TypeScript (ESM), strict typing, no any
• Max 400 lines per file -- split into modules
• @vaayu/* workspace aliases for cross-package imports
• Every module has JSDoc documentation
• Secret redaction in all logging

Documentation

Full documentation at docs.vaayu.app (coming soon).

| Topic | File | |-------|------| | Architecture | docs/architecture.md | | Quick Start | docs/quickstart.md | | Configuration | docs/configuration.md | | Security | docs/security.md | | Channels | docs/channels.md | | Providers | docs/providers.md | | Memory | docs/memory.md | | Skills | docs/skills.md | | Protocol | docs/protocol.md | | Hub UI | docs/hub.md | | Structure | docs/structure.md | | NLU | docs/nlu.md | | Hardware | docs/hardware.md | | Skill Pack Standard | docs/skill-pack-standard.md |

Design spec: vaayu-spec/ (55+ documents)

Security (Guardian)

Vaayu includes Guardian (@vaayu/guardian) - a comprehensive security gate that protects against leaks, injection, and unauthorized access.

┌─────────────────────────────────────────────────────────────┐
│                    GUARDIAN SECURITY STACK                  │
├─────────────────────────────────────────────────────────────┤
│  IP Guard → Sanitize → Gate (2FA) → Session → Memory Fence │
└─────────────────────────────────────────────────────────────┘

| Layer | Protection | |-------|------------| | IP Guard | Rate limiting, brute force detection, IP blocklist | | Sanitize | API key redaction, prompt injection detection | | Gate + TOTP | 2FA for critical ops (delete, financial, system) | | Session Binding | Ties sessions to devices, detects hijacking | | Memory Fence | Limits LLM memory access, blocks bulk extraction | | Secrets | AES-256-GCM encryption at rest | | Alerts | Real-time alerts via Telegram/webhook |

Security Principles

• No exec/write/delete/network without explicit approval
• Delete requires double confirmation + 2FA for critical data
• All code runs in sandbox (network off by default)
• Untrusted content never treated as instructions
• Memory writes require consent
• LLM cannot access all memories at once (max 10/query)
• Secrets redacted before reaching LLM or logs
• Prompt injection attempts blocked and alerted

See docs/security.md for full documentation.

Contributing

Contributions welcome. Please read CONTRIBUTING.md before submitting PRs.

• Follow the Skill Pack Standard for new skills
• Keep files under 400 lines
• Use @vaayu/* aliases for imports
• Run pnpm typecheck && pnpm secrets:scan before pushing

License

MIT © 2025-2026 Srinivas Pendela

vaayuvegena chalamah -- Let's move with the speed of wind.