Metadata-Version: 2.4
Name: aibrain
Version: 0.9.0
Summary: AI agent brain with selective memory routing — your agent, but better every day
Author-email: Matthew McKee <decker.ops@gmail.com>
License: BSL-1.1
Project-URL: Homepage, https://myaibrain.org
Project-URL: Repository, https://github.com/sindecker/aibrain
Project-URL: Issues, https://github.com/sindecker/aibrain/issues
Project-URL: Documentation, https://myaibrain.org/docs
Keywords: ai,agent,memory,brain,mcp,skills,retrieval,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dateutil>=2.9.0
Provides-Extra: api
Requires-Dist: fastapi>=0.111.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "api"
Requires-Dist: websockets>=12.0; extra == "api"
Requires-Dist: apscheduler>=3.10.0; extra == "api"
Requires-Dist: redis>=5.0.0; extra == "api"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=3.0.0; extra == "embeddings"
Requires-Dist: sqlite-vec>=0.1.0; extra == "embeddings"
Provides-Extra: mcp
Requires-Dist: mcp>=0.9.0; extra == "mcp"
Provides-Extra: workflows
Requires-Dist: beautifulsoup4>=4.12.0; extra == "workflows"
Requires-Dist: feedparser>=6.0.0; extra == "workflows"
Requires-Dist: icalendar>=5.0.0; extra == "workflows"
Provides-Extra: browser
Requires-Dist: browser-use>=0.12.0; extra == "browser"
Provides-Extra: docs
Requires-Dist: docling>=2.8.0; extra == "docs"
Provides-Extra: finance
Requires-Dist: yfinance>=0.2.30; extra == "finance"
Provides-Extra: payments
Requires-Dist: stripe>=8.0.0; extra == "payments"
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0.0; extra == "pdf"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Provides-Extra: all
Requires-Dist: aibrain[api,browser,docs,embeddings,finance,mcp,payments,pdf,workflows]; extra == "all"
Dynamic: license-file

# AgentOS -- Your AI agent that remembers, learns, and acts

> **Stop configuring. Start automating.** One install. 41 workflows. Reactive engine. Self-improving. Runs locally, no cloud lock-in.

AgentOS is a self-hosted operating system for AI agents. It gives any agent persistent memory, a reactive workflow engine, a self-improvement loop, multi-model LLM routing, an approval queue, inter-agent messaging, and 41 ready-to-run workflows -- all behind a single browser dashboard. Deploy it on a laptop, a VPS, or in Docker; your agent carries its entire brain with it.

![AgentOS](https://img.shields.io/badge/AgentOS-v0.9.0-00F5D4?style=flat-square) ![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square) ![Python](https://img.shields.io/badge/python-3.11+-blue?style=flat-square) ![React](https://img.shields.io/badge/react-19-61DAFB?style=flat-square) ![Workflows](https://img.shields.io/badge/workflows-41-00F5D4?style=flat-square) ![Routes](https://img.shields.io/badge/API_routes-165+-00F5D4?style=flat-square) ![Components](https://img.shields.io/badge/components-33-61DAFB?style=flat-square)

![AgentOS Dashboard](demos/01_home_dashboard.png)

> **See the full walkthrough:** [Demo Screenshots & Guide](demos/DEMO_WALKTHROUGH.md) -- 32 screenshots covering every dashboard component.

---

## Quick Start

```bash
python3 -m venv ~/aibrain-env && source ~/aibrain-env/bin/activate
pip install aibrain
aibrain setup    # interactive wizard — walks you through everything
aibrain server   # dashboard at http://localhost:8001
```

The setup wizard handles config, API keys, database init, and workflow selection. No manual file editing needed.

**Alternative: Docker**
```bash
git clone https://github.com/sindecker/aibrain.git && cd aibrain
cp config.json.example config.json   # edit with your API keys and preferences
docker compose up --build             # dashboard at http://localhost:5173
```

**Brain commands** — export, import, and merge agent knowledge:
```bash
aibrain brain stats                    # show brain statistics
aibrain brain export                   # export brain to JSON
aibrain brain import brain.json        # import another brain's knowledge
aibrain brain merge /path/or/git-url   # merge from git repo or local path
```

For local development without Docker, see [Development Setup](#development-setup) below.

---

## Features

**30 Dashboard Components** -- Home, Memories, Knowledge Graph, Workflows, **Visual Workflow Builder**, **Content Pipeline**, Chat, Approvals, Agents, Activity Timeline, Library, Webhooks, Costs, MCP Hub, Skills Marketplace, Settings, Setup Wizard, Command Palette, Mobile Layout, Mobile Pairing, Toast notifications, Notification Center, Keyboard Shortcuts, System Logs, API Playground, Backup Manager, Task Runner, Integrations Hub, Onboarding Tour, and Error Boundary. Every aspect of your agent is visible and controllable from the browser.

**41 Automated Workflows** -- Pre-built workflows across ten categories (productivity, research, finance, job hunting, social, comms, devops, health, intelligence, system). Includes Morning Briefing (daily digest), Email-to-Task (approval-gated), Smart File Organizer, Cross-Domain Question Generator (anomaly detection), Memory Consolidation, Evolution Experiments, Security Report Generator, Agent Heartbeat, and SQLite Backup. Enable any workflow with a single toggle; schedules are fully configurable via cron expressions.

**Multi-Model LLM Router** -- Route tasks to local Ollama (free) or cloud Claude/GPT with automatic fallback via litellm. Track costs per model, per workflow, per day. Test provider connections directly from Settings.

**Natural Language Workflow Creation** -- Describe an automation in plain English ("Every morning check my email and summarize it") and AgentOS generates the workflow script and schedule.

**Visual Workflow Builder** -- Canvas-based drag-and-drop node editor. Four node types (trigger, action, condition, output) with 15 subtypes. Connect nodes with bezier curves, auto-layout with topological sort, save/load named workflows, export as JSON. Zero external dependencies -- pure canvas rendering.

**Knowledge Graph with Entity Extraction** -- Visualize memory connections as an interactive force-directed graph. Pattern-based NER automatically extracts technologies, URLs, emails, IPs, and proper names. Edges show references, shared tags, topic similarity, and entity connections with color-coded types and hover labels.

**Command Palette (Ctrl+K)** -- Global search across pages, actions, memories, workflows, and skills. Prefix with `>` for unified data search. Arrow-key navigation, instant routing.

**Real-time Notifications** -- WebSocket push for approval requests, activity events, and system alerts. Browser desktop notifications when approvals arrive. Live activity feed with auto-reconnect. Tab title shows pending approval count.

**Cost & Observability Dashboard** -- See exactly what your agent did, how much it cost, and where it failed. Trace every LLM call with token counts, latency, and cost. Set daily/monthly budgets with visual progress bars and overspend warnings.

**Mobile PWA** -- Install on your phone, pair via QR code, approve actions with one tap. Replaces Telegram as your mobile interface.

**SQLite + FTS5 Memory** -- Full-text searchable memory database with tagging, typing, and graph visualization. Export/import your agent's entire brain as JSON with one click from the dashboard.

**Skill Marketplace** -- Browse installed skills by category (Security, Development, Design, Automation, Media, Data, Communication). Install new skills from URL or pasted Markdown. Delete skills you no longer need. See which skills are connected to workflows and which are orphaned.

**Built-in Scheduler** -- APScheduler-backed cron engine reads `scheduled_jobs.json` on startup. Add, enable, disable, or trigger workflows from the UI or API. Run logs and next-fire times are always visible.

**Approval Queue** -- Workflows can request human approval before executing sensitive actions. Approve or reject from the dashboard or chat panel. WebSocket push keeps every client in sync with real-time desktop notifications.

**Real-time Chat** -- WebSocket chat panel with built-in commands (`/status`, `/approvals`, `/schedule`, `/costs`, `/content`, `/create`, `/help`). Messages are logged and accessible via REST for non-WebSocket clients.

**Deep Health Checks** -- `/health/deep` tests every subsystem: memory DB, scheduler, approvals, LLM providers, entity extractor, trace DB, and WebSocket connections. Results displayed in Settings.

**Content Pipeline** -- Full content management dashboard for creating, scheduling, and publishing across 7 platforms (LinkedIn, X/Twitter, Instagram, YouTube, Telegram, Email Newsletter, Blog). AI-powered content generation, queue and calendar views, platform-specific badges, and status tracking from draft through publication.

**Home Dashboard** -- Unified overview showing memory count, active workflows, pending approvals, LLM costs, recent activity, and upcoming scheduled jobs. Quick-action buttons navigate to any section.

**Multi-Agent Mesh** -- Broker integration and peer registry let multiple agents communicate. Register peers, send messages through the broker, and monitor connectivity from the Agents view.

**Webhook Event Triggers** -- Register incoming webhooks with optional HMAC signature validation. Webhooks trigger workflows on external events (GitHub pushes, payment notifications, CI results) as an alternative to polling on a schedule.

**System Logs** -- Terminal-style real-time log viewer with auto-scroll, pause/resume, level filtering (INFO/WARNING/ERROR/DEBUG), text search, and export to .txt.

**API Playground** -- Postman-style interactive endpoint tester with 17 pre-configured endpoints, query param inputs, JSON body editor, and response viewer with timing.

**Backup Manager** -- Create, restore, download, and delete memory snapshots. One-click brain export/import with file upload.

**Task Runner** -- Visual task queue with progress bars, duration tracking, cancel/retry actions, and live status updates.

**Integrations Hub** -- Central view of 12 services across 6 categories (Messaging, AI, Dev, Automation, Commerce, Finance) with connected/disconnected status and inline config.

**Onboarding Tour** -- 8-step guided walkthrough for first-time users with progress dots, skip option, and localStorage persistence.

**Keyboard Shortcuts** -- Press `?` for a full shortcut overlay. `N` toggles the notification center. `Ctrl+K` opens the command palette.

**Responsive Dashboard** -- The frontend works on any screen size. REST endpoints for chat and approvals work without WebSocket support.

**Reactive Workflow Engine** -- State-driven workflow execution inspired by the FlyWire fruit fly connectome and the Rete algorithm. Nodes fire when prerequisites are met, not in sequence. 180 lines, domain-agnostic, async-native. Forward chaining, refraction, priority-based conflict resolution, and SQLite-backed checkpoint recovery. Every workflow is a reactive graph, not a script.

**Evolution Engine** -- Self-improving automation. Outcomes feed patterns, patterns generate hypotheses, hypotheses run experiments, experiments get measured and kept or reverted. Self-criticism, loop detection, and positive pattern reinforcement. Your workflows get measurably better over time.

**Pattern Bus** -- Cross-domain event infrastructure. Every state change across every domain emits a DomainEvent to a SQLite-backed event table. Aggregator nodes detect anomalies and correlations. The foundation for self-initiated agent reasoning.

**Inter-Agent Messaging** -- Redis-backed pub/sub protocol for multi-agent coordination. Publish/subscribe events, request-response between agents, broadcast to all. Deploy Neuro locally and Case on a VPS -- they communicate through the broker.

**Durable Workflow Execution** -- Step-level retry with SQLite persistence. If a workflow fails mid-step, it resumes from the last successful step on restart. No external dependencies -- built on top of the reactive engine's checkpoint store.

**Docker Production Build** -- Multi-stage Dockerfile (Python 3.11 + Node 20) produces a single container running the API, scheduler, and nginx-served frontend with Redis broker for inter-agent messaging. Health checks and automatic restarts included.

**Cross-platform Launchers** -- `start.sh` (Unix/Mac), `start.bat` (Windows), and `Makefile` targets for dev, install, build, docker, and clean.

---

## Architecture

```
                          +------------------+
                          |     Browser      |
                          +--------+---------+
                                   |
                          HTTP / WebSocket
                                   |
                     +-------------+-------------+
                     |         nginx :5173        |
                     |   static frontend + proxy  |
                     +-------------+-------------+
                                   |
                            /api/* | /ws/*
                                   |
    +------------------------------+------------------------------+
    |                  FastAPI Backend :8001                       |
    |                                                             |
    |  +----------+  +-----------+  +-------+  +--------------+  |
    |  | Memory   |  | Reactive  |  | Chat  |  | Evolution    |  |
    |  | (SQLite  |  | Engine    |  | (WS)  |  | Engine       |  |
    |  |  + FTS5) |  | (Rete +   |  |       |  | (self-       |  |
    |  |          |  |  FlyWire) |  |       |  |  improving)  |  |
    |  +----+-----+  +-----+-----+  +---+---+  +------+-------+  |
    |       |              |             |             |           |
    |  +----+-----+  +----+------+  +---+---+  +------+-------+  |
    |  | Approval |  | Workflows |  | Agent |  | Pattern Bus  |  |
    |  | Queue    |  | (27 .py)  |  | Broker|  | (events)     |  |
    |  +----------+  +-----------+  +---+---+  +--------------+  |
    +--------------------------------------------+-+--------------+
                |              |                 |
          agentos.db    scheduled_jobs.json   Redis :6379
```

---

## Configuration

Copy `config.json.example` to `config.json` and fill in the values you need. Empty strings use sensible defaults. All fields are optional -- configure only what you use.

Three tiers of configuration (in priority order):

1. **Environment variables**: `AGENTOS_MEMORY_DB`, `AGENTOS_CRON_JOBS`, etc.
2. **config.json**: Copy `config.json.example` and customize
3. **Defaults**: Relative to the AgentOS root directory

### Key Fields

| Field | Description |
|---|---|
| `llm_provider` | LLM routing: `auto`, `claude`, `openai`, `ollama`, or `claude_cli` |
| `user_name` | Your name (shown in greeting and reports) |
| `budget_daily` | Daily LLM spending limit in USD (e.g., `5.00`) |
| `budget_monthly` | Monthly LLM spending limit in USD (e.g., `50.00`) |
| `agent_name` | Display name for your agent |
| `anthropic_api_key` | API key for Claude-powered workflows |
| `openai_api_key` | API key for OpenAI/GPT-powered workflows |
| `ollama_url` | Ollama API URL (default: `http://localhost:11434`) |
| `memory_db` | Path to SQLite memory database (default: `memory/memory.db`) |
| `cron_jobs` | Path to scheduled jobs registry (default: `scheduled_jobs.json`) |
| `skills_dir` | Directory containing agent skills |
| `email_accounts` | Array of email accounts to monitor (IMAP/SMTP config per account) |
| `email_reply_mode` | `"prompted"` (queue for approval) or `"auto"` |
| `email_auto_reply_senders` | Whitelist of senders for auto-reply mode |
| `location_name`, `location_lat`, `location_lon` | Location for weather workflows |
| `calendar_url`, `google_calendar_credentials` | Calendar integration |
| `github_token`, `github_username` | GitHub API access |
| `watched_repos`, `github_repos` | Repos to monitor for activity |
| `rss_feeds` | RSS/Atom feed URLs for the digest workflow |
| `arxiv_queries` | Search terms for the arXiv paper tracker |
| `job_keywords` | Keywords for job search workflow |
| `social_keywords` | Brand/topic terms for social listening |
| `price_watchlist` | Crypto/stock tickers with type, id, and display name |
| `habits` | Habits to track in the evening check-in |
| `scan_dirs` | Directories for file declutter workflow |
| `document_watch_dirs` | Directories for document parsing workflow |
| `uptime_targets` | URLs to monitor with expected HTTP status codes |

---

## Workflows

All 27 workflows live in the `workflows/` directory. Each is a self-contained Python script. Enable them individually through the dashboard or by setting `"enabled": true` in `scheduled_jobs.json`.

### Productivity

| Workflow | Schedule | Description |
|---|---|---|
| `weather_briefing` | 6:30 AM daily | Morning weather forecast for your location |
| `daily_planner` | 7:00 AM daily | Task plan from calendar, emails, and priorities |
| `file_declutter` | 2:00 AM Sunday | Clean up Downloads and Desktop folders |
| `habit_tracker` | 9:00 PM daily | Evening habit check-in and streak tracking |
| `bookmark_organizer` | 3:00 AM Saturday | Categorize and deduplicate bookmarks |
| `calendar_manager` | Every 6 hours | Extract events from emails, create reminders |
| `document_parser` | Every 4 hours | Parse PDFs/DOCX/images into searchable memories |

### Research

| Workflow | Schedule | Description |
|---|---|---|
| `rss_digest` | 8:00 AM daily | Summarize new articles from RSS feeds |
| `daily_research` | 9:30 AM daily | Rotating research across 5 topic categories |
| `arxiv_tracker` | 10:00 AM weekdays | Track new papers matching your queries |
| `social_listener` | Every 4 hours | Monitor social media for keyword mentions |

### Finance

| Workflow | Schedule | Description |
|---|---|---|
| `price_watcher` | Every 2 hours | Crypto/stock price alerts on significant moves |
| `expense_tracker` | 10:00 PM daily | Parse receipts and track daily expenses |

### Job Hunting

| Workflow | Schedule | Description |
|---|---|---|
| `job_search_apply` | 9:00 AM weekdays | Search job boards and auto-apply to matches |
| `interview_prep` | 8:00 AM daily | Prepare briefings for upcoming interviews |

### Communications

| Workflow | Schedule | Description |
|---|---|---|
| `email_triage` | Every 30 min | Check all email accounts, categorize messages |
| `email_auto_reply` | Every 15 min | Draft and send replies (prompted or auto mode) |
| `newsletter_digest` | 7:00 AM Monday | Weekly digest of newsletters across accounts |
| `contact_enricher` | 4:00 AM Sunday | Enrich contacts from email headers |
| `content_calendar` | 8:00 AM Monday | Generate content ideas and posting schedule |

### DevOps

| Workflow | Schedule | Description |
|---|---|---|
| `github_digest` | 9:00 AM weekdays | Summarize GitHub activity across your repos |
| `git_monitor` | Every 30 min | Monitor repos for PRs, issues, CI failures |
| `uptime_monitor` | Every 5 min | Check service availability, alert on downtime |
| `dependency_auditor` | 3:00 AM Monday | Scan for outdated or vulnerable dependencies |

All workflows use **free APIs only**: Open-Meteo, CoinGecko, ArXiv, Hacker News, Reddit JSON. No paid API keys required for basic operation.

---

## API Endpoints

The backend exposes a REST API at `http://localhost:8001`. All resource endpoints are prefixed with `/api/agent` unless noted otherwise.

### Memory

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/memories` | List memories (paginated) |
| GET | `/api/agent/memories/search?q=` | Full-text search across all memories |
| GET | `/api/agent/memories/summary` | Memory count and type breakdown |
| GET | `/api/agent/memories/graph` | Graph nodes and edges for visualization |
| GET | `/api/agent/memories/export` | Export entire brain as JSON |
| POST | `/api/agent/memories/import` | Import brain from JSON |
| GET | `/api/agent/memories/{id}` | Get a single memory |
| POST | `/api/agent/memories` | Create a new memory |
| PUT | `/api/agent/memories/{id}` | Update a memory |
| DELETE | `/api/agent/memories/{id}` | Delete a memory |
| POST | `/api/agent/memories/extract-entities` | Backfill entity extraction on all memories |

### Workflows and Scheduler

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/crons` | List all scheduled jobs |
| PUT | `/api/agent/crons/{name}` | Update a job's schedule or config |
| GET | `/api/agent/crons/upcoming` | Next-fire times for all jobs |
| GET | `/api/agent/crons/groups` | Jobs grouped by category |
| GET | `/api/agent/workflows` | List all available workflows |
| GET | `/api/agent/workflows/{name}` | Get workflow details and source |
| POST | `/api/agent/workflows/{name}/enable` | Enable a workflow |
| POST | `/api/agent/workflows/{name}/disable` | Disable a workflow |
| POST | `/api/agent/workflows/{name}/run` | Trigger a workflow immediately |
| GET | `/api/agent/scheduler/status` | Scheduler health and job count |
| POST | `/api/agent/scheduler/reload` | Reload all jobs from disk |

### Approval Queue

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/approvals` | List items (filter by status/category) |
| GET | `/api/agent/approvals/summary` | Pending count and category breakdown |
| GET | `/api/agent/approvals/{id}` | Get a single approval item |
| POST | `/api/agent/approvals` | Create an approval request |
| POST | `/api/agent/approvals/{id}/approve` | Approve an item |
| POST | `/api/agent/approvals/{id}/reject` | Reject an item |

### Chat

| Method | Endpoint | Description |
|---|---|---|
| WebSocket | `/ws/chat` | Real-time chat with history replay on connect |
| GET | `/api/agent/chat/history` | Recent chat messages (REST fallback) |
| POST | `/api/agent/chat/send` | Send a chat message (REST fallback) |

### Agent Mesh

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/status` | Agent status and system info |
| GET | `/api/agent/activity` | Activity timeline |
| POST | `/api/agent/activity` | Log an activity event |
| GET | `/api/agent/peers` | List registered peer agents |
| POST | `/api/agent/peers` | Register a new peer |
| DELETE | `/api/agent/peers/{name}` | Remove a peer |
| POST | `/api/agent/broker/send` | Send a message through the broker |
| GET | `/api/agent/broker/recv` | Receive messages from the broker |
| GET | `/api/agent/broker/status` | Broker connectivity status |

### Webhooks

| Method | Endpoint | Description |
|---|---|---|
| GET | `/webhooks` | List registered webhooks |
| POST | `/webhooks` | Register a new webhook |
| PUT | `/webhooks/{name}` | Update a webhook configuration |
| DELETE | `/webhooks/{name}` | Remove a webhook |
| POST | `/webhooks/{name}` | Invoke a webhook (external callers) |
| GET | `/webhooks/{name}/history` | Invocation history for a webhook |

### Search

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/search?q=` | Unified search across memories, workflows, and skills |

### Skills

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/skills` | List installed agent skills |
| GET | `/api/agent/skills/{name}` | Get skill details |
| POST | `/api/agent/skills/install` | Install a skill from URL or pasted content |
| DELETE | `/api/agent/skills/{name}` | Remove an installed skill |

### Configuration

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/config` | Get current configuration |
| PUT | `/api/agent/config` | Update configuration |
| POST | `/api/agent/config/test-provider` | Test LLM provider connectivity |

### Tasks

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/tasks` | List all tasks |
| POST | `/api/agent/tasks` | Create a new task |
| POST | `/api/agent/tasks/{id}/cancel` | Cancel a running task |
| POST | `/api/agent/tasks/{id}/retry` | Retry a failed task |

### Backups

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/backups` | List all backups |
| POST | `/api/agent/backups` | Create a new backup |
| POST | `/api/agent/backups/{id}/restore` | Restore from a backup |
| GET | `/api/agent/backups/{id}/download` | Download a backup file |
| DELETE | `/api/agent/backups/{id}` | Delete a backup |

### Logs and Costs

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/agent/logs` | Structured log viewer |
| GET | `/api/agent/costs/summary` | LLM cost summary |
| GET | `/api/agent/costs/history` | Daily cost breakdown |

### System

| Method | Endpoint | Description |
|---|---|---|
| GET | `/health` | Health check with scheduler and approval status |
| GET | `/health/deep` | Deep health check — tests all subsystems |
| WebSocket | `/ws/notifications` | Real-time push notifications for approvals and activity |

---

## Docker Deployment

The included `docker-compose.yml` runs the full stack: app server, frontend, and Redis broker.

```bash
# Copy and configure environment
cp env.example .env   # edit with your API keys

# Build and start
docker compose up --build -d

# View logs
docker compose logs -f agentos

# Stop
docker compose down
```

The stack exposes:

- **5173** -- Dashboard UI (nginx serving the built React app)
- **8001** -- Backend API (FastAPI + uvicorn)
- **6379** -- Redis broker (inter-agent messaging)

Volumes persist your data across restarts:

- `./data` -- SQLite databases (agentos.db)
- `./memory` -- Legacy memory database
- `./config.json` -- Your configuration
- `./workflows` -- Workflow scripts

For VPS-only deployment (no frontend, agent-to-agent only):

```bash
docker compose -f docker-compose.vps.yml up -d
```

The Dockerfile uses a multi-stage build: Python 3.11 for the backend, Node 20 for the frontend build, and a final slim image with nginx for production serving. Health checks run every 30 seconds against the `/api/health` endpoint.

---

## MCP Server — Connect Any AI Agent

AgentOS includes an MCP (Model Context Protocol) server that gives any compatible AI agent persistent memory with selective routing. Connect Claude Code, Cursor, Windsurf, or any MCP client.

**Performance:** #1 on LongMemEval benchmark (Ra@5=0.789, NDCG@5=0.796) — beats Contriever (110M params) and Stella V5 (1.5B params) with a 22MB model + rule-based routing.

### Setup

Add to your `.claude.json` or `.mcp.json`:

```json
{
  "mcpServers": {
    "aibrain-memory": {
      "command": "python",
      "args": ["/path/to/aibrain/mcp_server.py"]
    }
  }
}
```

### Three Modes

| Mode | Config | What Ships | Performance |
|------|--------|-----------|-------------|
| **No ML** | `AGENTOS_EMBEDDING_MODEL=none` | FTS5 only, 0 deps | NDCG 0.692 |
| **Default** | (no config needed) | MiniLM 22MB, 384-dim | Ra@5 0.789, NDCG 0.796 |
| **bge-base** | `AGENTOS_EMBEDDING_MODEL=BAAI/bge-base-en-v1.5` | 110MB, 768-dim | Ra@5 0.791, NDCG 0.812 |
| **Custom** | `AGENTOS_EMBEDDING_MODEL=your/model` | Any sentence-transformer | Routing adapts |

### Tools Provided

- `memory_store` — Store a memory (auto-enriched for better retrieval)
- `memory_search` — Search with selective routing (auto-detects query type, or pass `search_type` hint)
- `memory_recall` — Recall top memories by importance

### Dependencies

```bash
pip install mcp sentence-transformers sqlite-vec
```

All optional — the server gracefully degrades. No embeddings? FTS5 only. No enricher? Raw content. No sqlite-vec? Skip vector search.

---

## Development Setup

The fastest way to start both backend and frontend:

```bash
# Windows
start.bat

# Unix/Mac
./start.sh

# Or using Make
make dev
```

To run manually without the launchers:

```bash
# Backend
cd backend
pip install -r requirements.txt
python -m uvicorn main:app --host 0.0.0.0 --port 8001 --reload

# Frontend (separate terminal)
cd frontend
npm install
npm run dev
```

Other Make targets: `make install`, `make build`, `make docker`, `make clean`.

The frontend dev server runs on port 5173 and proxies API requests to port 8001.

---

## Connect Your Agent

AgentOS works with any AI agent -- Claude, GPT, Gemini, Ollama, LangChain, CrewAI, or your own.

### Option 1: Just tell your agent

Paste this to any AI agent (Claude Code, ChatGPT, etc.):

```
You have access to AgentOS at http://localhost:8001
Store memories: POST /api/agent/memories  Body: {"name": "...", "content": "...", "type": "reference", "tags": ""}
Search memories: GET /api/agent/memories/search?q=your+query
Send chat: POST /api/agent/chat/send  Body: {"content": "message", "role": "agent"}
Dashboard: http://localhost:5173
```

### Option 2: Python SDK

```python
from agentos_sdk import AgentOS

aos = AgentOS("http://localhost:8001")
aos.remember("user prefers dark mode", tags=["preference"])
results = aos.recall("dark mode")
aos.say("Task complete.")
approval = aos.request_approval("Deploy to production")
```

### Option 3: Example agents

```bash
# Claude
python examples/claude_agent.py

# OpenAI GPT
python examples/openai_agent.py

# Local LLM (Ollama -- no API key needed)
python examples/ollama_agent.py
```

The SDK uses only Python stdlib (urllib) -- zero dependencies. See `agentos_sdk.py` for the full API.

---

## Remote Access

Open `http://<your-machine-ip>:5173` from any browser on your network. The responsive design adapts to any screen size. For remote access over the internet, use an SSH tunnel or put behind a reverse proxy with auth.

---

## Brain Export and Import

Transfer your agent's entire memory to another machine:

```bash
# Export
curl http://localhost:8001/api/agent/memories/export > brain.json

# Import on new machine
curl -X POST http://localhost:8001/api/agent/memories/import \
  -H "Content-Type: application/json" \
  -d @brain.json
```

Duplicates are automatically skipped during import.

---

## Project Structure

```
agentos/
├── agentos_sdk.py            # Python SDK — connect any agent
├── setup_wizard.py           # Interactive first-run setup
├── docker-compose.yml        # One-command Docker deploy
├── Dockerfile                # Multi-stage production build
├── Makefile                  # dev, install, build, docker, clean
├── start.sh                  # Unix/Mac launcher
├── start.bat                 # Windows launcher
├── config.json.example       # Configuration template
├── scheduled_jobs.json       # 24 workflow schedules
├── backend/
│   ├── main.py               # FastAPI server + scheduler + chat + WS
│   ├── agentos_api.py        # Memory, cron, workflow, skill, search APIs
│   ├── chat_responder.py     # Multi-provider LLM chat (Claude/GPT/Ollama/CLI)
│   ├── llm_router.py         # litellm-backed unified model routing
│   ├── entity_extractor.py   # Pattern-based NER for knowledge graph
│   ├── trace_logger.py       # LLM call tracing with cost tracking
│   ├── action_executor.py    # Approved action execution engine
│   ├── workflow_generator.py # Natural language to workflow script
│   ├── webhooks.py           # Webhook registration and invocation
│   ├── scheduler.py          # APScheduler cron engine
│   ├── approval_queue.py     # Human-in-the-loop approval system
│   └── requirements.txt      # Python dependencies
├── frontend/
│   ├── src/App.jsx           # Router + 28-component navigation
│   └── src/components/
│       ├── HomeDashboard.jsx      # System overview with sparklines
│       ├── MemoryDashboard.jsx    # Memory search, browse, edit
│       ├── MemoryGraph.jsx        # Force-directed knowledge graph
│       ├── CronDashboard.jsx      # Workflow scheduling and control
│       ├── ChatPanel.jsx          # WebSocket chat with commands
│       ├── ApprovalQueue.jsx      # Human-in-the-loop approvals
│       ├── AgentStatus.jsx        # Agent health and peer mesh
│       ├── ActivityTimeline.jsx   # Real-time activity feed (WS)
│       ├── WorkflowBuilder.jsx    # Visual drag-and-drop workflow editor
│       ├── WorkflowLibrary.jsx    # Content pipeline and library
│       ├── WebhooksDashboard.jsx  # Webhook management
│       ├── CostDashboard.jsx      # LLM cost tracking and budgets
│       ├── MCPHub.jsx             # MCP server management
│       ├── SkillMarketplace.jsx   # Skill browse, install, delete
│       ├── Settings.jsx           # Config, provider testing, health
│       ├── SetupWizard.jsx        # First-run guided setup
│       ├── CommandPalette.jsx     # Global Ctrl+K search overlay
│       ├── NotificationCenter.jsx # Real-time notification panel
│       ├── KeyboardShortcuts.jsx  # Shortcut overlay (press ?)
│       ├── SystemLogs.jsx         # Terminal-style log viewer
│       ├── ApiPlayground.jsx      # Interactive API tester
│       ├── BackupManager.jsx      # Memory backup/restore
│       ├── TaskRunner.jsx         # Task queue with progress
│       ├── Integrations.jsx       # Service connection hub
│       ├── OnboardingTour.jsx     # First-run walkthrough
│       ├── ErrorBoundary.jsx      # React error boundary
│       ├── MobileLayout.jsx       # Mobile-optimized layout
│       ├── MobilePairing.jsx      # QR code pairing for mobile
│       └── Toast.jsx              # Toast notification component
├── examples/
│   ├── basic_agent.py        # Minimal agent example
│   ├── claude_agent.py       # Claude-powered agent
│   ├── openai_agent.py       # GPT-powered agent
│   └── ollama_agent.py       # Local LLM agent (no API key)
├── workflows/                # 24 self-contained workflow scripts
└── memory/
    └── memory.db             # SQLite + FTS5 database
```

---

## Keyboard Shortcuts

| Shortcut | Action |
|---|---|
| `Ctrl+K` | Open command palette |
| `?` | Show keyboard shortcuts overlay |
| `N` | Toggle notification center |
| `>query` | Search memories, workflows, and skills from palette |
| `Escape` | Close any modal or palette |
| `Arrow keys` | Navigate command palette results |
| `Enter` | Select highlighted palette result |

---

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/your-feature`)
3. Commit your changes with a descriptive message explaining what changed and why
4. Push to your fork and open a pull request

Please keep PRs focused on a single change. All workflows use free APIs only -- maintain that principle for new additions.

---

## License

MIT
