{"id":44414032,"url":"https://github.com/jimtin/zetherion-ai","last_synced_at":"2026-03-12T01:11:54.108Z","repository":{"id":336703329,"uuid":"1150183951","full_name":"jimtin/zetherion-ai","owner":"jimtin","description":"Secure personal AI assistant with encrypted memory, multi-provider LLM routing, and privacy-first design. Inspired by OpenClaw.","archived":false,"fork":false,"pushed_at":"2026-02-28T21:31:44.000Z","size":4586,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T00:48:26.193Z","etag":null,"topics":["ai-agent","encryption","llm","multi-provider","ollama","personal-ai-assistant","privacy","python","security","self-hosted"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jimtin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-05T01:25:28.000Z","updated_at":"2026-02-28T21:28:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jimtin/zetherion-ai","commit_stats":null,"previous_names":["jimtin/sercureclaw"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/jimtin/zetherion-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimtin%2Fzetherion-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimtin%2Fzetherion-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimtin%2Fzetherion-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimtin%2Fzetherion-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimtin","download_url":"https://codeload.github.com/jimtin/zetherion-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimtin%2Fzetherion-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30063390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T18:21:05.932Z","status":"ssl_error","status_checked_at":"2026-03-03T18:20:59.341Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","encryption","llm","multi-provider","ollama","personal-ai-assistant","privacy","python","security","self-hosted"],"created_at":"2026-02-12T08:09:07.894Z","updated_at":"2026-03-12T01:11:54.100Z","avatar_url":"https://github.com/jimtin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zetherion AI\n\n[![CI Pipeline](https://github.com/jimtin/zetherion-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/jimtin/zetherion-ai/actions/workflows/ci.yml)\n[![Test Coverage Gate](https://img.shields.io/badge/coverage-%3E%3D90%25-brightgreen)](https://github.com/jimtin/zetherion-ai/actions)\n[![Tests](https://img.shields.io/badge/tests-3000+-blue)](https://github.com/jimtin/zetherion-ai/actions)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**A privacy-first personal AI assistant that learns how you work.**\n\n---\n\n## What Is This?\n\nZetherion AI is a personal AI assistant designed to accept input from any source. Discord is the first interface, but the architecture is source-agnostic -- a REST API skills layer, email sync, GitHub webhooks, and a heartbeat scheduler all operate independently of how messages arrive. Future interfaces (Slack, Telegram, Teams, or a custom frontend) plug into the same agent core.\n\nYou choose how inference runs. The system supports local models via Ollama for operations that should never leave your machine, and cloud providers (Gemini, Claude, OpenAI) for tasks where you want more capability. A smart router classifies each query and dispatches it to the provider you've configured for that task type -- you control the tradeoff between privacy, cost, and quality.\n\nZetherion doesn't just respond when asked. An observation pipeline passively extracts facts and preferences from your conversations without explicit commands. A heartbeat scheduler proactively surfaces task reminders, email digests, and calendar alerts on its own. A progressive trust system gradually earns autonomy over actions like drafting and sending email replies, expanding what it does automatically as you approve its judgement over time.\n\nEvery piece of memory is encrypted with AES-256-GCM before it touches a database. Everything runs on your own infrastructure, with the current compose topology supporting blue/green API and skills deployments, internal routing, and updater orchestration. The codebase enforces a `\u003e=90%` coverage gate.\n\n---\n\n## Key Features\n\n| Feature | Description |\n| --- | --- |\n| **Source-Agnostic Input** | Accepts input from Discord, REST API, email sync, GitHub webhooks, and future interfaces -- not locked to any single platform |\n| **User-Controlled LLM Routing** | You choose between local inference (Ollama) and cloud providers (Gemini, Claude, OpenAI) -- the router dispatches each query to the right provider based on your configuration |\n| **Passive Observation** | Automatically extracts facts, preferences, and context from conversations without explicit commands via a 3-tier extraction pipeline |\n| **Proactive Prompting** | Heartbeat scheduler surfaces task reminders, email digests, calendar alerts, and overdue notifications without being asked |\n| **Progressive Trust** | Gmail integration starts read-only and gradually earns autonomy to draft and send replies as you approve its judgement over time |\n| **Encrypted Memory** | AES-256-GCM field-level encryption with PBKDF2 key derivation -- your memories are unreadable even if the database is compromised |\n| **Personal Understanding** | Learns your preferences, goals, communication style, and workflows across 8 categories with confidence scoring |\n| **Gmail Integration** | Check email, search threads, and auto-draft replies with per-contact and per-reply-type trust tracking |\n| **GitHub Integration** | Manage issues, pull requests, and repository status with configurable autonomy levels |\n| **Skills Framework** | Extensible architecture for tasks, calendar, email, GitHub, profiles, and custom integrations |\n| **Cost Tracking** | Per-request cost logging across all providers with configurable budget alerts |\n| **Security-First Design** | Distroless containers, prompt injection defense, rate limiting, and no-new-privileges enforcement |\n| **3,000+ Tests** | Coverage gate enforced at `\u003e=90%` -- tested in CI on every commit |\n\n---\n\n## Quick Start\n\n```bash\nmkdir -p ~/Developer\ngit clone https://github.com/jimtin/zetherion-ai.git ~/Developer/PersonalBot\ncd ~/Developer/PersonalBot\n./start.sh      # Mac/Linux  |  .\\start.ps1  # Windows\n```\n\nThe startup script walks you through configuration, pulls Docker images, and launches the current compose topology. See the [full getting-started guide](docs/user/getting-started.md) for detailed setup instructions.\n\n---\n\n## How It Works\n\nZetherion operates in three modes simultaneously:\n\n### Active Interaction\n\nYou ask a question, and the router classifies it and dispatches to the appropriate provider and skill:\n\n```text\nYou:  How do I implement a thread-safe singleton in Python?\nZeth: Here's a thread-safe singleton using a metaclass with a lock...\n      [detailed explanation with code examples]\n```\n\n```text\nYou:  Check my email\nZeth: You have 3 new emails:\n      1. [GitHub] PR #187 approved by @sarah -- ready to merge\n      2. [AWS] Monthly billing summary -- $42.17\n      3. [Team] Meeting moved to Thursday 2pm\n      Want me to draft a reply to any of these?\n```\n\n### Passive Observation\n\nZetherion listens to your conversations and silently extracts facts and preferences. No commands needed -- it builds a model of who you are over time:\n\n```text\nYou:  I've been using pytest a lot lately, prefer fixtures over\n      setup methods. Working on the API validation layer this week.\n\n      [Zetherion silently records: prefers pytest fixtures,\n       current project involves API validation, active this week]\n```\n\nNext time you ask about testing, it already knows your preferences and context.\n\n### Proactive Prompting\n\nThe heartbeat scheduler checks for things you should know about and surfaces them without being asked:\n\n```text\nZeth: Heads up -- \"Review PR #42\" is due in 1 hour and still open.\n\nZeth: Morning email digest: 5 new emails overnight.\n      1 from @sarah (PR feedback) looks urgent.\n      Want me to draft a reply?\n\nZeth: You have a meeting with the platform team in 30 minutes.\n```\n\nProactive actions respect quiet hours (default 10 PM - 7 AM) and rate limits.\n\n---\n\n## Architecture at a Glance\n\n```text\nAny Input Source\n(Discord / REST API / Email / Webhooks / Future interfaces)\n      |\n      v\n+--[ Agent Core ]------+\n|                       |\n|   Security Layer      |-----\u003e Rate Limiting / Prompt Injection Defense\n|                       |\n|   Router              |-----\u003e Intent Classification\n|                       |\n|   Inference Broker    |-----\u003e LLM Providers (your choice):\n|                       |       Local: Ollama (Llama 3.1 8B / 3.2 3B)\n|                       |       Cloud: Gemini / Claude / OpenAI\n+--------+-+-----------+\n         | |\n    +----+ +----+\n    |           |\n    v           v\n Skills      Memory\n (Gmail,     (Qdrant + PostgreSQL)\n  GitHub,    AES-256-GCM encrypted\n  Tasks,\n  Calendar,       Observation Pipeline\n  Profile)        (passive learning)\n    |\n    v\n Heartbeat Scheduler\n (proactive actions)\n```\n\nThe **current compose topology** includes runtime, routing, update, and data services:\n\n| Service | Role |\n| --- | --- |\n| `zetherion-ai-bot` | Discord runtime and agent orchestration |\n| `zetherion-ai-skills-blue/green` | Internal skills control plane with blue/green switching |\n| `zetherion-ai-api-blue/green` | Public API app with blue/green switching |\n| `zetherion-ai-traefik` | Internal traffic switch for skills/API |\n| `zetherion-ai-updater` | Auto-update sidecar for rollout/rollback |\n| `zetherion-ai-cloudflared` | Optional secure tunnel for public API exposure |\n| `postgres` | Relational storage for users, settings, profiles, integrations |\n| `qdrant` | Vector memory store |\n| `ollama` | Local generation/embeddings |\n| `ollama-router` | Dedicated local router model |\n\n---\n\n## LLM Provider Configuration\n\nYou control which providers handle which tasks. The system supports mixing local and cloud inference:\n\n| Provider | Models | Typical Use | Cost |\n| --- | --- | --- | --- |\n| **Ollama (local)** | Llama 3.1 8B, Llama 3.2 3B | Privacy-sensitive operations, routing | Free |\n| **Gemini** | 2.5 Flash | Simple queries, classification | Free tier available |\n| **Claude** | Sonnet 4.5 | Complex reasoning, code generation | Paid |\n| **OpenAI** | GPT-5.2 | Alternative complex reasoning | Paid |\n\nWithout cloud API keys, Zetherion runs entirely on local Ollama models. Add cloud providers when you want more capability for specific task types.\n\n---\n\n## Documentation\n\n| Section | What You'll Find |\n| --- | --- |\n| [User Guide](docs/user/getting-started.md) | Getting started, commands reference, Gmail setup, GitHub integration |\n| [Technical](docs/technical/architecture.md) | Architecture deep-dive, Docker configuration, security model, API reference |\n| [Development](docs/development/setup.md) | Dev environment setup, running 3,000+ tests, CI/CD pipeline |\n| [Project](docs/project/roadmap.md) | Roadmap, design decisions, contribution opportunities |\n\n---\n\n## Requirements\n\n| Requirement | Notes |\n| --- | --- |\n| **Docker Desktop 4.0+** | All services run containerized -- no local Python install needed for running |\n| **Discord bot token** | Free to create at [discord.com/developers](https://discord.com/developers/applications) -- the first supported input source |\n| **Gemini API key** | Required by default runtime configuration (`GEMINI_API_KEY`) |\n| **Anthropic API key** | *Optional* -- enables Claude Sonnet 4.5 for complex reasoning tasks |\n| **OpenAI API key** | *Optional* -- enables GPT-5.2 as an alternative reasoning provider |\n\nDiscord bot token, Gemini API key, and encryption passphrase are required in the current default runtime configuration. Other provider keys are optional.\n\n---\n\n## Contributing\n\nContributions are welcome. The codebase enforces a `\u003e=90%` coverage gate, so the bar for new contributions is straightforward -- write tests, pass CI, and follow the existing patterns. See the [development guide](docs/development/setup.md) for environment setup and testing instructions.\n\nIf you have ideas for new input interfaces, skills, LLM provider integrations, or security improvements, open an issue to discuss before submitting a PR.\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](https://opensource.org/licenses/MIT).\n\n---\n\n*Built for people who want an AI assistant that respects their privacy and works on their terms.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimtin%2Fzetherion-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimtin%2Fzetherion-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimtin%2Fzetherion-ai/lists"}