An open-source AI assistant that remembers every conversation, evolves its own code, and runs on your machine.
Website · Docs · Blog · Quick Start · Video Walkthrough
Mobile
Most AI assistants are stateless — every conversation starts from scratch. Edward is different:
- Persistent memory — Hybrid vector + keyword retrieval across every conversation. Edward knows your name, your preferences, your projects.
- Proactive awareness — The heartbeat system monitors iMessage, Calendar, and Mail, then briefs you on what you missed.
- Self-evolution — Edward can propose, test, and deploy improvements to its own codebase via Claude Code.
- Multi-agent orchestration — Spawns worker agents that run tasks in parallel while you're away.
- Self-hosted — Runs on your machine. Your data never leaves your hardware.
| Long-Term Memory | Hybrid vector + keyword recall | Scheduled Events | One-time & cron recurring |
| Multi-Channel Messaging | iMessage, SMS, WhatsApp | Code Execution | Python, JS, SQL, Shell sandboxes |
| Apple Services | Calendar, Mail, Reminders, Notes | Web Search | Brave Search + page extraction |
| Document Store | Semantic search over saved docs | Custom MCP Servers | Self-serve install at runtime |
| Multi-Agent Orchestrator | Spawns parallel worker agents | Self-Evolution | Proposes, tests, and deploys its own upgrades |
| Push Notifications | Web Push via VAPID | File Storage | Persistent files with tags |
git clone https://github.com/ben4mn/meet-edward.git && cd meet-edward
./setup.sh # Installs PostgreSQL, pgvector, Python & Node deps
./restart.sh # Starts backend (:8000) + frontend (:3000)Add your Anthropic API key to .env — that's the only required variable. Open localhost:3000 and set a password on first visit.
Prerequisites: macOS, Homebrew, Python 3.11+, Node.js 18+, Anthropic API key
Frontend (Next.js :3000) → Backend (FastAPI :8000) → PostgreSQL (:5432)
↓
LangGraph Agent
(preprocess → retrieve
memory → respond →
extract memory)
↓
Claude API (Anthropic)
The backend runs natively on macOS (not in Docker) to support iMessage, AppleScript, and the scheduled event scheduler.
Edward is built for macOS, where it integrates with iMessage, Calendar, Mail, and other Apple services. On Windows (via WSL) or Linux, the core assistant — memory, chat, scheduling, code execution, orchestration, and evolution — works fully. See the Platform Support docs for details.
Background Systems
| System | Description |
|---|---|
| Heartbeat | Monitors iMessage, Calendar, and Mail; triages by urgency |
| Memory Reflection | Post-turn enrichment via related memory queries |
| Deep Retrieval | Pre-turn multi-query search for complex conversations |
| Memory Consolidation | Hourly clustering of related memories |
| Search Tags | Auto-generated keywords for conversation search |
Configuration
Copy .env.example to .env and configure:
| Variable | Required | Description |
|---|---|---|
ANTHROPIC_API_KEY |
Yes | Claude API key |
BRAVE_SEARCH_API_KEY |
No | Enables web search |
TWILIO_ACCOUNT_SID / AUTH_TOKEN / PHONE_NUMBER |
No | SMS & WhatsApp messaging |
MCP_APPLE_ENABLED |
No | Apple Services (Calendar, Mail, etc.) |
VAPID_PUBLIC_KEY / PRIVATE_KEY |
No | Browser push notifications |
JWT_SECRET_KEY |
No | Auth secret (auto-generates if unset) |
GITHUB_TOKEN |
No | MCP server search via GitHub API |
HTML_HOSTING_API_KEY |
No | HTML page hosting |
See .env.example for the full list.
./setup.sh # First-time setup (PostgreSQL, dependencies, .env)
./restart.sh # Restart both frontend and backend
./restart.sh frontend # Restart only frontend
./restart.sh backend # Restart only backendLogs: /tmp/edward-backend.log and /tmp/edward-frontend.log
- Documentation — Architecture, setup guides, and feature deep-dives
- Blog — Articles on AI memory, self-evolution, and building Edward
Contributions welcome! See CONTRIBUTING.md for development setup and guidelines. Open an issue first to discuss what you'd like to change.
