AI Agent Platform

Portable AI agent platform that runs from a USB stick, powered by a local LLM via Ollama.

Architecture

ai-agent-platform/
├── courier/          # MCP server — AI agent context, memory, and sync tracking
├── dock/             # Systray app — USB detection, mount management, status
├── sync-engine/      # Bidirectional file sync with conflict detection
├── agent-core/       # Orchestrator — connects Ollama + Courier + sync
├── installer/        # Cross-platform setup scripts (Linux/macOS/Windows)
└── shared/           # Common types, config, logging, errors, paths

New Features (Recent Updates)

• Graceful Degradation: Agent-core works without Courier, retries connection every 30s
• Health & Readiness Endpoints: /health and /ready for container orchestration
• Metrics Dashboard: /metrics page with Chart.js latency visualizations
• Sync Progress Tracking: Real-time sync status via sync-status.json file
• Config File Watching: Auto-reload config when platform.json changes
• RFC 7807 Error Responses: Standard problem detail responses for HTTP errors
• Rate Limiting: 100 requests/minute per client for MCP tools
• Backup Before Import: Automatic backup to backups/ directory
• File Size Validation: Max 100MB file size limit in sync-engine
• Conflict Resolution: 4 rename patterns (parenthesized, host_copy, usb_copy, timestamp)
• Platform Icons: Custom icons for Linux, macOS, Windows tray

Components

Courier (✅ Complete)

The MCP server that provides AI agents with persistent memory and sync tracking.

• 24 MCP tools for CRUD, search, sync events, and file manifests
• 130+ tests with 78-91% coverage
• Atomic writes, graceful shutdown, config auto-discovery
• Fuzzy search, memory priority/relationships, background cleanup
• Rate limiting, backup before import

See courier/README.md for details.

Dock (✅ Complete)

System tray application that:

• Auto-detects USB insertion/removal (polls every 2s)
• Shows real-time sync progress in tray status
• Loads platform-specific icons from dock/icons/
• Gracefully shuts down all components on USB removal
• Cross-platform: Linux (AppIndicator), macOS, Windows

Sync Engine (✅ Complete)

File synchronization service that:

• Monitors files for changes via fsnotify
• Bidirectional sync between USB and host
• SHA256 checksum-based change detection
• Progress tracking via sync-status.json
• Conflict resolution with 4 rename patterns
• Max file size: 100MB
• Retry logic with exponential backoff

Agent Core (✅ Complete)

The orchestrator that:

• Starts/stops the Ollama local LLM
• Graceful degradation when Courier unavailable
• Multi-model support via /api/tags
• Web dashboard at :8080 — status, models, metrics, auto-refresh
• Health/readiness endpoints (/health, /ready)
• Metrics page with Chart.js (/metrics)

Installer (✅ Complete)

Cross-platform setup with install + uninstall scripts:

• Linux: systemd service + udev rules
• macOS: launchd plist
• Windows: Task Scheduler

Shared (✅ Complete)

Common code shared across components:

• config — PlatformConfig with validation, auto-discovery, file watching
• log — Structured logging with component tagging (JSON/text)
• errors — 8 sentinel errors + RFC 7807 ProblemDetail responses
• paths — Cross-platform USB mount point detection

Quick Start

# Build all components
make build

# Run all tests
make test

# Lint all components
make lint

# Run with coverage
make coverage

# Cross-compile release binaries
make release

Dashboard Endpoints

Endpoint	Description
http://localhost:8080/	Main dashboard (status, model, uptime)
http://localhost:8080/metrics	Metrics with latency charts
http://localhost:8080/api/status	JSON status
http://localhost:8080/api/models	Available Ollama models
http://localhost:8080/api/metrics	JSON metrics
http://localhost:8080/health	Health check
http://localhost:8080/ready	Readiness check

Configuration

Config file: platform.json (auto-reload on change)

{
  "ollama_model": "llama3.2",
  "ollama_host": "http://localhost:11434",
  "sync_enabled": true,
  "conflict_policy": "host",
  "conflict_rename_pattern": "parenthesized"
}

Conflict rename patterns: parenthesized, host_copy, usb_copy, timestamp

Phase Status

Phase	Status	Description
Phase 1: Courier MCP Server	✅ Complete	24 tools, 130+ tests
Phase 2: Platform Scaffolding	✅ Complete	Monorepo, all components building
Phase 3: Integration & Polish	✅ Complete	Shared modules, tests, installers
Phase 4: Production Readiness	✅ Complete	USB detection, retry, dashboard, metrics
Phase 5: Advanced Features	⬜ Planned	Voice I/O, encryption, cloud sync

See IMPLEMENTATION_PLAN.md for details.

Final Metrics

Component	Build	Tests	Coverage
courier	✅	130+	78-91%
shared	✅	30+	100%
sync-engine	✅	14	—
agent-core	✅	5	—
dock	✅	7	—
installer	—	—	—
Total	5/5	180+	All passing

Development

Each component has its own build system and tests. See individual README files for details.