---

🌌 What is Aether?

Aether is a massive paradigm shift in personal AI computing. It bridges the gap between passive RAG chatbots and truly autonomous, self-reflecting agents. Built upon the principles of an Active World Model, Aether is an entirely private, Local-First engine that actively monitors your workflow, connects concepts overnight, and alters its own persona based on the rhythm of your day.

Where traditional AI tools simply react to text, Aether simulates and anticipates. Where others suffer from context amnesia, Aether builds Concept Constellations in Qdrant. Where others hallucinate, Aether grounds itself in type-safe Pydantic logic.

📜 Read the Aether Manifesto to understand the core philosophy and technical vision behind the project.

---

✨ State-of-the-Art Features

System / Feature	Description
🧠 Active World Model	Aether runs silent background simulations (world_model.py) to reflect on your daily actions, generating overarching insights and proactive architectural suggestions.
🌙 Sleep Cycle	When you log off, the NightCycleProcessor consolidates your daily files and logs, reducing noise and preparing a Morning Brief for your Dashboard Command Center.
🛠️ Agent Skills	New in v1.4! Create, toggle, and manage specialized agent skills that dynamically inject instructions and triggers into the brain.
⏱️ Digital Circadian Rhythm	Aether dynamically alters its persona based on local system time. Strategist in the morning, Executor at noon, Philosopher in the evening.
🕸️ Concept Constellations	Moving beyond standard RAG vectors. Aether links memories and facts into a dense relational graph within its core SQLite + Qdrant architecture.
🔌 MCP Server (Model Context Protocol)	Aether exposes its SQLite Brain via FastMCP. Connect your VS Code, Cursor, or Claude Desktop directly to Aether to share its long-term memory.
💻 Electron Desktop App	A fully native desktop shell wraps the Next.js Dashboard and Python Kernel into a standalone executable environment.

---

🏗️ Architecture Stack

Aether operates as a massive distributed monolith on your local machine, driven by modern package managers (uv and pnpm).

graph TD
    User["👤 User / Telegram"] <--> HTTP["⚡ FastAPI Kernel"]
    HTTP <--> Agent["🧠 PydanticAI Agent"]
    
    Agent <--> LLM["🤖 Gemini 2.0 / Local Ollama"]
    Agent <--> Qdrant[("🌌 Qdrant Vector Space")]
    Agent <--> SQLite[("🧠 SQLite Brain (Logs/Sessions)")]
    
    SubAgent1["🌙 Sleep Cycle Processor"] --> SQLite
    SubAgent2["🌍 Active World Model"] --> SQLite
    
    Dashboard["🖥️ Next.js / Electron UI"] <--> HTTP
    MCP_IDE["🔌 Claude/Cursor (via MCP)"] <--> SQLite

    style User fill:#1a1a2e,stroke:#a855f7,color:#fff
    style HTTP fill:#16213e,stroke:#3b82f6,color:#fff
    style Agent fill:#0f3460,stroke:#a855f7,color:#fff
    style LLM fill:#533483,stroke:#ec4899,color:#fff
    style Qdrant fill:#16213e,stroke:#3ecf8e,color:#fff
    style SQLite fill:#16213e,stroke:#e2b96f,color:#fff
    style Dashboard fill:#1a1a2e,stroke:#a855f7,color:#fff
    style MCP_IDE fill:#4a154b,stroke:#ec4899,color:#fff

---

🛠️ Technology Core

Layer	Technology
🐍 Backend Kernel	Python 3.12+, FastAPI, Uvicorn, SQLite3, uv managed
🤖 Cognition Frame	PydanticAI (Type-safe and dependency-injected)
🖥️ Command Center	Next.js 16 (App Router), Tailwind CSS 4, Framer Motion
💻 Desktop Shell	Electron, electron-builder
🗄️ Vector Memory	Qdrant (Local Docker or Cloud Hybrid)
🔌 APIs & Protocol	FastMCP (Anthropic Protocol), python-telegram-bot, Tavily Search

---

🚀 One-Click Setup

We have eliminated Docker-hell and requirement-txt conflicts. Aether uses uv for lightning-fast Python dependency syncing and pnpm for Node.

Prerequisites

• curl -LsSf https://astral.sh/uv/install.sh | sh (UV Python Manager)
• Node.js 20+ & npm install -g pnpm
• A Qdrant Cloud Cluster (or local instance)
• API Keys for Google Gemini / Tavily / Telegram.

1-Click Launch Windows / MacOS

Simply clone the repository and run the installation script. It will setup both backend, frontend, build dependencies, and launch the Electron App:

# Windows
.\start_desktop.bat

# Linux / Mac 
./setup.sh

Manual Configuration .env

Place inside /backend/.env:

# AI Models
GEMINI_API_KEY=your_gemini_key
MODEL_OVERRIDE=gemini-2.0-pro-exp-02-05

# Vector Storage
QDRANT_API_KEY=your_qdrant_api_key
QDRANT_URL=https://your-cluster.qdrant.io

# Tools & Bridges
TAVILY_API_KEY=your_tavily_api_key
TELEGRAM_BOT_TOKEN=12345:ABCDEF
TELEGRAM_USER_ID=your_id

---

🔌 Using MCP (Model Context Protocol)

Aether exposes its internal SQLite Brain and Morning Briefs directly to your IDE. This allows you to reference Aether's long-term memory while working in other codebases.

Global Configuration

Add the following to your claude_desktop_config.json or Cursor settings.

[!IMPORTANT] Replace /PATH/TO/ with the actual absolute path to your Aether installation to ensure connectivity from any folder on your machine.

"mcpServers": {
  "aether-core": {
    "command": "uv",
    "args": [
      "--project", "/PATH/TO/aether-agent/backend",
      "run",
      "python", "/PATH/TO/aether-agent/backend/mcp_server.py"
    ]
  }
}

---

🐳 Docker Compose (Self-Hosting)

For NAS or VPS enthusiasts, Aether ships with an incredibly lightweight, production-ready docker-compose.yml. The frontend compiles to a Standalone Node instance, and the backend runs on Alpine Slim. Volume mounts persist your digital memories forever.

docker-compose up -d --build

---

📝 Roadmap & Philosophy

"Aether aims to be more than just a software tool — it's an intelligent entity aware of its existence in time and space."

Aether is fully feature-complete based on our original 6-Phase Master Plan for the Open Source release (37/37 Tasks Done). Now in v1.1.0, we are maintaining the stable public baseline while evolving the core architecture.

---

📝 License

Apache-2.0 © Krzysztof Pika

[!IMPORTANT] Trademarks & Logo: The names "Aether", "Aether Agent" and all associated logos are trademarks of Krzysztof Pika. These are not covered by the Apache 2.0 License. Any use of these trademarks, beyond reasonable and customary description of the software's origin, requires explicit written permission.

---

🌌 Aether Pro & Cloud

For professional users and enterprises requiring high-performance infrastructure, we offer a more powerful, cloud-optimized version of the system.

• Current Pro Version: v1.5.0
• Optimization: Optimized for Cloud environments (Hetzner, AWS, etc.) with enhanced scaling and performance calibration.
• Ready-to-use: Fully configured and hosted instances for those who want to jump straight into production.

🖥️ Aether Pro Interface

Dashboard Intelligence	Neural Persona Calibration
Concept Constellations	Neural Topology Visualization
Advanced Reasoning Chat	Specialized Agent Skills

🌐 Visit the official platform: aetheragent.pl

---