mecris

🧠 Mecris — Personal LLM Accountability System

"A containerized mind palace for living deliberately, acting efficiently, and getting the damn goals done."

What This Is

Mecris is a persistent cognitive agent system that extends Claude's narrative thread beyond single sessions. It's designed to help maintain focus, track progress, and provide strategic insight by integrating with your personal data sources.

This is not a chatbot. This is a delegation system that helps you stay accountable to your goals and use your time intentionally.

Quick Start

For detailed setup instructions for different agents, see docs/SETUP_GUIDE.md.

# 1. Install dependencies using uv
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

# 2. Configure environment (copy and edit .env.example if needed)
# Set BEEMINDER_USERNAME, BEEMINDER_AUTH_TOKEN, TWILIO credentials, etc.

# 3. Launch the MCP server
./scripts/launch_server.sh

# 4. Test health endpoint
curl http://127.0.0.1:8000/health

Architecture Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude Code   │◄──►│  FastAPI MCP     │◄──►│  Data Sources   │
│   (Narrator)    │    │   Server         │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │                         │
                              ▼                         ├─ Obsidian Vault
                       ┌──────────────┐                 ├─ Beeminder API  ✅
                       │   Twilio     │                 ├─ Claude Monitor ✅
                       │   Alerts     │                 └─ Usage Tracker  ✅
                       └──────────────┘

Core Components

1. FastAPI MCP Server ✅ PRODUCTION READY

• Health endpoint with service status monitoring
• Secure localhost binding (127.0.0.1 only)
• Robust startup/shutdown with process management
• Enhanced error handling and logging
• Industry-Leading Toolset: Features 29 distinct MCP tools—a larger specialized toolset than even the standard GitHub MCP server (which provides 20+).

Key Tool Categories:

• Strategic Context: get_narrator_context, get_coaching_insight
• Goal Mastery: get_beeminder_status, trigger_language_sync, get_language_velocity_stats
• Physical Accountability: get_daily_activity, get_weather_report
• Financial Stewardship: get_budget_status, get_real_anthropic_usage, get_unified_cost_status
• System Health: get_system_health, get_scheduler_queue, trigger_reminder_check
• Daily Progress: get_daily_aggregate_status (The Majesty Cake 🍰)

Key Endpoints:

• GET /health - Service health and dependency status
• GET /narrator/context - Unified context for Claude narrator
• GET /beeminder/status - Goal portfolio with risk assessment
• GET /usage - Budget status and burn rate analysis
• POST /beeminder/alert - Emergency goal notifications
• POST /usage/record - Track API usage sessions

2. Data Source Integrations

✅ Beeminder API - FULLY TESTED

• Live API integration with real goal data
• Risk classification (CRITICAL/WARNING/CAUTION/SAFE)
• Emergency detection with urgency levels
• Runway analysis prioritizing urgent goals
• No mock data - verified via comprehensive test suite

✅ Usage Tracking - PRODUCTION READY

• Neon (Postgres) for cloud-native persistence and multi-tenant isolation.
• Accurate cost calculation using official Anthropic pricing
• Real-time budget tracking via Anthropic Admin API and Neon.
• Alert system via Twilio for critical budget states
• Historical analysis and burn rate projection

✅ Twilio Alerts - CONFIGURED

• SMS notifications for beemergencies and budget alerts
• Integrated with background task processing
• Configurable alert thresholds

✅ Obsidian Integration - CONFIGURED

• File reading capabilities implemented
• Vault structure parsing in progress

3. Server Management Tools ✅ COMPLETE

• scripts/launch_server.sh - Safe server startup with health checks
• scripts/shutdown_server.sh - Graceful shutdown with cleanup
• Process management with PID files and cleanup traps
• Health monitoring with automatic service validation

Current State

✅ Production Ready

• MCP Server: Secure, robust, stdio-integrated
• Beeminder Integration: Live API, comprehensive testing
• Budget Tracking: Real-time via Anthropic Admin API and Neon (Postgres)
• Alert System: Twilio SMS for critical notifications
• Coordination: Distributed leader election across instances

🚧 In Progress

• Obsidian Integration: Vault parsing and goal extraction
• Documentation: Organized into /docs directory