AI Agent: Email

Elegant Software Solutions

Intelligent AI-powered email management agent built as a Claude Code MCP Server. Enables natural language email interaction with a sophisticated 3-layer hybrid rules engine combining deterministic pattern matching, semantic vector search, and LLM classification—all with strict budget controls to prevent API cost overruns.

9K+

Lines of Code

MCP Tools

15+

DB Tables

300+

Pattern Library

System Design & Integration

Contribution as Principal Architect

Architected 3-layer evaluation system with short-circuit optimization
Designed PostgreSQL schema with pgvector for 1536-dimension embeddings
Implemented OAuth 2.0 PKCE flow with Fernet encryption for tokens
Created delta query sync system for efficient email fetching

Core Capabilities

Natural Language Email

Conversational email management through Claude Code CLI—users simply talk about their email and SoundWave handles operations while learning preferences.

Multi-Account Management

Support for 10+ Microsoft 365 accounts with account-specific learning, encrypted OAuth tokens, and automatic refresh.

Intelligent Triage

Three-layer AI evaluation system balances cost vs accuracy: free pattern matching handles 70%+ of emails, semantic search catches similarities, LLM handles complex cases.

Confidence-Based Automation

Progressive automation levels based on learned confidence—from asking user to silent action—with pattern detection after 3+ similar decisions.

VIP Contact System

5-tier priority system for contacts with automatic folder routing, relationship tracking, and organization association.

14-Category Classification

LLM classification into urgent_client_request, project_update, meeting_request, newsletter, marketing, transactional, and 8 more categories with confidence scoring.

Budget-Aware AI

Daily and monthly spending limits with intelligent layer fallback. Prevents unexpected API costs with configurable budgets ($1/day embeddings, $5/day LLM default).

Delta Sync

Efficient incremental email fetching using Microsoft Graph delta queries—only syncs new/changed messages.

Modules & Services

MCP Server

Model Context Protocol server exposing 16 email operations as Claude tools. Async stdio communication enabling conversational email management through Claude Code CLI.

Microsoft Provider

Full Microsoft Graph API integration with OAuth 2.0 PKCE flow, automatic token refresh, Fernet encryption (AES-128) for token storage, and delta query sync for efficient incremental fetching.

3-Layer Hybrid Rules Engine

Cost-optimized evaluation: Layer 1 deterministic pattern matching (free, <1ms), Layer 2 semantic embedding search ($0.02/1M tokens, ~100ms), Layer 3 LLM classification ($0.15-3.00/1M tokens, ~500ms). Short-circuit optimization maximizes accuracy while minimizing costs.

Database Layer

PostgreSQL with pgvector for semantic similarity search. 15+ tables including accounts, emails, rules, decisions, VIP senders, embeddings, and AI usage tracking with budget enforcement.

AI Services

Embedding generation with text-embedding-3-small, semantic search with cosine similarity, LLM-powered classification into 14 email categories, and comprehensive cost tracking with daily/monthly budget limits.

Learning System

Records user decisions, detects patterns (3+ similar actions), proposes rules with calculated confidence, and implements progressive automation: <50% ask, 50-79% suggest, 80-99% act & mention, 100% silent.

Admin Dashboard

Next.js admin interface with Prisma ORM for VIP contact management, rule configuration, todo tracking, and AI usage monitoring.

Tech Stack

Languages

Python 3.11+TypeScript

Frameworks

MCP SDKasyncioPydantic 2.0httpxNext.js 16Prisma

Infrastructure

Microsoft Graph APIOpenAI APIAnthropic APINotion API

Data

PostgreSQL 16pgvectorSQLite

Loading project...