Tempa The AI that lives in your system core always on · always connected Gmail · Calendar · Google Meet · WhatsApp Unified memory · multi-agent · local-first

https://github.com/Haroon966/Tempa/raw/main/animated_tempa.mp4

✦ Features

✦ Architecture

System overview

Everything funnels through the Tempa daemon (8787). Channels ingest into unified memory; the tools coordinator handles Gmail, Calendar, Meet, Slack, and WhatsApp; Cursor owns coding (Slack engineering asks → durable jobs / PRs / CI).

flowchart TB
    subgraph clients [Clients]
        Dashboard[Dashboard]
        SlackIn[Slack DMs and mentions]
        WhatsAppIn[WhatsApp webhook]
    end

    Daemon["Tempa daemon :8787"]

    subgraph brain [Brains]
        Coord[Tools coordinator specialists]
        CursorJobs[Cursor SDK jobs]
    end

    subgraph memory [Unified memory]
        Chroma[(ChromaDB RAG)]
        Vault[data/vault]
    end

    subgraph channels [Channels and workers]
        SlackOut[Slack Bolt]
        WhatsAppBridge[WhatsApp bridge :8080]
        GoogleAPIs[Gmail and Calendar]
        MeetWorker[Meet worker]
        QAWorker[QA worker]
    end

    subgraph llm [Models]
        Groq[Groq API]
        CursorSDK[Cursor local or cloud]
    end

    Dashboard --> Daemon
    SlackIn --> SlackOut --> Daemon
    WhatsAppIn --> WhatsAppBridge --> Daemon

    Daemon -->|"mail cal meet chat"| Coord
    Daemon -->|"coding work"| CursorJobs
    Coord --> Groq
    Coord --> Chroma
    Coord --> GoogleAPIs
    Coord --> SlackOut
    Coord --> WhatsAppBridge
    Coord --> MeetWorker
    CursorJobs --> CursorSDK
    Vault --> Chroma
    Daemon --> QAWorker
    SlackOut --> SlackIn
    WhatsAppBridge --> WhatsAppIn

Message flow

• Non-coding (inbox, calendar, Meet, casual Slack/WA) → tools coordinator + specialists (Groq). Destructive channel actions still use pending-action / owner approval.
• Coding on Slack (pinned thread or coding heuristic + config/cursor_threads.yaml repo) → Cursor job queue; worker posts progress, opens PRs, waits on CI, escalates after failed fix cycles. No Varys harness ticket / “reply go” for code.
• WhatsApp casual chat still uses the fast Groq path unless routed to the full coordinator.
• Optional VARYS_ORCHESTRATOR_ENABLED tick remains for Notion/Jira/GitHub pollers only — not the chat coding brain.

sequenceDiagram
    participant User
    participant Slack
    participant Daemon as Tempa daemon
    participant Coord as Tools coordinator
    participant Cursor as Cursor job worker

    User->>Slack: message
    Slack->>Daemon: inbound event

    alt coding ask
        Daemon->>Cursor: enqueue job
        Daemon-->>User: working ack
        Cursor-->>User: progress PR CI result
    else channel or chat
        Daemon->>Coord: run_coordinator_full
        Coord-->>User: specialist reply
    end

Memory and vault

Varys vault files and all channel ingest share one Chroma collection — no memory silos.

flowchart LR
    subgraph sources [Memory sources]
        VaultFiles["data/vault/*.md"]
        GmailSync[Gmail sync]
        SlackSync[Slack sync]
        CalendarSync[Calendar sync]
        MeetArchive[Meet transcripts]
        WhatsAppIdx[WhatsApp ingest]
    end

    subgraph ingest [Ingest pipeline]
        VaultSync[vault-sync / tempa vault-sync]
        IngestFn[ingest_text]
    end

    Chroma[(ChromaDB tempa_unified)]

    subgraph meta [Metadata tags]
        Wing[wing e.g. tempa]
        Room[room e.g. memory]
        Tool[tool e.g. vault, gmail]
    end

    VaultFiles --> VaultSync --> IngestFn
    GmailSync --> IngestFn
    SlackSync --> IngestFn
    CalendarSync --> IngestFn
    MeetArchive --> IngestFn
    WhatsAppIdx --> IngestFn
    IngestFn --> Chroma
    IngestFn --> meta
    meta --> Chroma

    Chroma --> ToolsCoord[Tools coordinator RAG]
    Chroma --> CursorCtx[Cursor job prompts via Tempa]

Docker layout

flowchart LR
    subgraph host [Your machine]
        ClaudeBin[Claude Code CLI]
        ClaudeCfg["~/.claude auth"]
    end

    subgraph compose [docker compose]
        DaemonC[tempa-daemon :8787]
        BridgeC[whatsapp-bridge :8080]
        MeetC[meet-worker]
        PgC[postgres :5432]
    end

    Data["./data volume<br/>vector, vault, harness, sessions"]

    ClaudeBin -.->|mounted binary| DaemonC
    ClaudeCfg -.->|mounted config| DaemonC
    DaemonC --> Data
    DaemonC --> BridgeC
    DaemonC --> MeetC
    BridgeC --> PgC

✦ Coordinator and Cursor

Slack Cursor coding setup

1. Set CURSOR_API_KEY and Slack allowlist (SLACK_OWNER_USER_ID / SLACK_ALLOWED_USER_IDS). Keep SLACK_ALLOW_ALL=false unless the whole workspace is trusted.
2. Clone repos under ./repos/<name> (or set TEMPA_REPOS_HOST).
3. Copy from config/cursor_threads.yaml.example into config/cursor_threads.yaml: set local_cwd: /repos/<name>, optional repo, required_checks.
4. Ensure the daemon image has git + gh for write/PR jobs; worktrees use /repos/tempa-worktrees.
5. In Slack, @Tempa with a coding ask (or use a pinned threads: entry). Guests are denied. Progress posts land in the thread; jobs appear on the dashboard QA → Tempa Cursor jobs board.

tempa varys status    # harness DB summary (optional tick)
tempa varys tick      # run one orchestrator tick
tempa vault-sync      # index vault into Chroma RAG
./scripts/vendor-varys.sh   # refresh vendored upstream

✦ Quick start

cp .env.example .env

docker compose up -d

python3 -m venv .venv
.venv/bin/pip install -e .
cp .env.example .env

./scripts/run-native.sh

cd dashboard && npm i && npm run dev

Prerequisites — Python 3.11+ · Docker · Groq API key · Google OAuth

✦ Configuration

📄 .env.example · services/whatsapp-bridge/.env.example

✦ CLI

tempa start          # start daemon
tempa setup          # first-run wizard (initializes vault)
tempa chat           # terminal chat
tempa whatsapp-qr    # show WhatsApp QR
tempa meet-auth      # Meet browser auth
tempa varys status   # Varys harness summary
tempa varys tick     # manual orchestrator tick
tempa vault-sync     # index vault into RAG

✦ WhatsApp bridge

In-repo Baileys bridge at services/whatsapp-bridge/ — Evolution-compatible API on port 8080, zero external vendor deps.

./scripts/test-whatsapp-qr.sh

Compatible session data if you used evoapicloud/evolution-api with Postgres evolution / evolution:evolution.

Rename volume evolution_instances → whatsapp_instances, or remount at /app/instances.

Env vars unchanged: EVOLUTION_API_URL · EVOLUTION_API_KEY · TEMPA_INSTANCE_NAME

✦ Slack (Socket Mode)

Bot events (Event Subscriptions): message.im, app_mention, and assistant_thread_started (if using Slack's Assistant chat UI).

• SLACK_BOT_TOKEN (xoxb-…)
• SLACK_APP_TOKEN (xapp-… with connections:write)
• SLACK_OWNER_USER_ID (your Slack member ID for DM auto-reply)

Bot token scopes (OAuth & Permissions) — your app currently needs at least:

• app_mentions:read
• chat:write
• im:history
• im:read ← required to list existing DMs
• im:write ← required to open a new DM (conversations.open); without it, “send this to …” fails
• users:read
• channels:history, channels:read (for @mentions in public channels)

Required for DMs: App Home → Messages Tab ON + allow user messages. Event Subscriptions → bot events message.im and app_mention. After changing scopes/events, reinstall the app to the workspace (OAuth → Install App).

DM the bot or @mention it in a channel. Outbound sends from the coordinator go through pending-action approval.

✦ Development

.venv/bin/pip install -e ".[dev]"    # install dev deps
.venv/bin/pytest                     # run tests
.venv/bin/ruff check src tests       # lint

Tempa v0.1.0 · self-hosted AI personal core agent