Mecris
MCP experiment / accountability coaching
Ask AI about Mecris
Powered by Claude Β· Grounded in docs
I know everything about Mecris. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π§ 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
Mecris is a cloud-coordinated, local-first accountability system. It is designed for maximum resilience: the local MCP server maintains a direct line to the database and can survive a total loss of the cloud APIs.
βββββββββββββββββββ
β NEON DB β
β (Central State) β
βββ¬ββββββββββββββ¬ββ
(Cloud Path) β β (Local Path)
ββββββββββββββββββ΄βββββββ βΌβββββββββββββββββ
β CLOUD HUB (WASM API)β β LOCAL MCP β
βββββββββββββββββββββββββ€ β (Python / SQL) β
β FREE: FERMYON β ββββββββ¬ββββββββββ
β PRO: AKAMAI CRON β β
βββββββββββββ¬ββββββββββββ β
β β
ββββββββββββββββββ΄ββββββββββββββββββββββββββ΄βββββββββββββββ
β THE STANDARD BUS (JSON / WIT) β
ββββββ¬ββββββββββββββββ¬ββββββββββββββββββ¬ββββββββββββββ¬βββββ
βΌ βΌ βΌ βΌ
ββββββββββββββ βββββββββββββββ βββββββββββββββββ βββββββββββββββ
β MOBILE GO β β AGENTS/BOTS β β HUMAN / CLI β β CI TRIGGERS β
β (Sensors) β β (Narrators) β β (Gemini/Term) β β (GHA/Hooks) β
ββββββββββββββ βββββββββββββββ βββββββββββββββββ βββββββββββββββ
Core Components
- The Hubs: Distributed logic centers that manage "Knowledge" (Neon DB) and "Actions" (Twilio/Beeminder).
- Local MCP (Primary): Your local Python server. It bridges local data (Obsidian) and maintains a direct connection to Neon. It is the primary interface for humans and narrators.
- Cloud Hub (Failover/Mobile): Hosted on Fermyon or Akamai. It provides high-availability API endpoints for the Android app and scheduled cron triggers for autonomous nagging.
- The Bus: All components interact via a language-neutral Standard Bus (JSON/WIT), ensuring that your Android app and your terminal see the same reality.
- The Spokes: Lightweight "Hosts" (Mobile, CLI, and Bots) provide sensors and interfaces to the human.
- Mobile Go: Android client bridging physical sensors (Google Fit/Health Connect).
- Agents/Bots: Gemini and Claude narrators that interpret the state and guide the human.
- CI Triggers: GitHub Actions and webhooks that drive periodic cloud synchronization.
- Robust startup/shutdown with process management
- Enhanced error handling and logging
- Industry-Leading Toolset: Features 30 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 statusGET /narrator/context- Unified context for Claude narratorGET /beeminder/status- Goal portfolio with risk assessmentGET /usage- Budget status and burn rate analysisPOST /beeminder/alert- Emergency goal notificationsPOST /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 checksscripts/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
/docsdirectory
π Next Priorities
- Majesty Cake UI: Implement the visual reward widget in the Android app.
- Multi-User Twilio: Migrate Twilio logic to the WASM brain for full multi-tenancy.
- Rust Reminder Engine: Port heuristic logic from Python to Rust/WASM.
Design Principles
- Read Before Writing: No hallucinations, context window is sacred
- Budget Conscious: Every token costs money
- Warning System: Professional doomsaying for deadline risks
- Memory Persistence: Leave breadcrumbs for future sessions
- Strategic Focus: Insight and path illumination, not just task completion
Project Structure
mecris/
βββ README.md # This file
βββ CLAUDE.md # Core narrator instructions
βββ requirements.txt # Python dependencies
βββ start_server.py # Main server entry point
βββ mcp_server.py # FastAPI application
βββ scripts/ # Server management scripts
β βββ launch_server.sh # Safe server startup
β βββ shutdown_server.sh # Graceful shutdown
βββ tests/ # Test suites
β βββ test_mecris.py # System integration tests
β βββ test_beeminder_live.py # Beeminder API tests
βββ logs/ # Application logs and reports
βββ docs/ # Technical documentation
βββ [data clients] # beeminder_client.py, usage_tracker.py, etc.
Operation Mode
Mecris currently operates in Stdio Mode, integrated directly with CLI agents (Gemini CLI, Claude Code).
Running in Stdio Mode
The server is invoked automatically by your agent using:
python mcp_stdio_server.py
Future: Secure SSE Mode
Standalone FastAPI/SSE mode is currently disabled and will be reintroduced once secured with OIDC authentication.
Testing
Run All Tests
source .venv/bin/activate
PYTHONPATH=. pytest
Manual Tool Testing
You can test the MCP tools directly via your agent's command interface (e.g., /get_narrator_context).
Configuration
Set these environment variables in your shell or .env file:
# Beeminder Integration
BEEMINDER_USERNAME=your_username
BEEMINDER_AUTH_TOKEN=your_token
# Twilio Alerts
TWILIO_ACCOUNT_SID=your_sid
TWILIO_AUTH_TOKEN=your_token
TWILIO_FROM_NUMBER=+1234567890
TWILIO_TO_NUMBER=+1234567890
# Optional Configuration
DEBUG=false # Enable debug logging
HOST=127.0.0.1 # Server bind address
PORT=8000 # Server port
LOG_LEVEL=INFO # Logging level
Budget Management
Current Budget: $20.88 remaining (as of April 2026)
- Daily burn rate: Automatically calculated from usage
- Budget alerts: SMS notifications for critical states
- Manual updates: Use
/usage/update_budgetendpoint
Update Budget
curl -X POST http://127.0.0.1:8000/usage/update_budget \
-H "Content-Type: application/json" \
-d '{"remaining_budget": 15.50}'
Documentation
CLAUDE.md- Core narrator instructions and contextCLAUDE_CODE_INTEGRATION.md- Integration with Claude Code CLIdocs/CLAUDE_API_LIMITATIONS.md- Budget tracking approachdocs/- Additional technical documentation
Support
For issues or questions:
- Check server logs in
logs/directory - Run health checks to diagnose problems
- Review test output for integration issues
