{
  "markdown": "# 🧠 Mecris — Personal LLM Accountability System\n\n> \"A containerized mind palace for living deliberately, acting efficiently, and getting the damn goals done.\"\n\n## What This Is\n\nMecris 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.\n\n**This is not a chatbot.** This is a delegation system that helps you stay accountable to your goals and use your time intentionally.\n\n## Quick Start\n\n> **New to Mecris? No `.env` yet?** Start with the from-zero guide:\n> [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) — database setup, minimal\n> configuration, and your first working narrator in ~10 minutes.\n\n### 🚀 Local-First (Optimized for Ollama)\nMecris is now optimized for fast, local inference on **Ollama (Gemma 4)** with a token-efficient minimal harness (<1.5k context overhead).\n\n```bash\n# Launch the optimized local-first loop\nPYTHONPATH=. .venv/bin/python3 py_harness/main.py\n```\n\n### 🎯 Using Pi (Open-Source Agent)\nThe **Pi coding agent** now drives Mecris as a TypeScript extension—bring your own model (Copilot, Groq, Anthropic, Google, local Ollama).\n\n```bash\n# One-time setup\ncd .pi/extensions/mecris && npm install && cd ../../..\n\n# Launch Pi with Mecris bridge\npi  # Or: pi --provider groq --model llama-3.1-70b-versatile\n\n# In Pi:\n/status          # deterministic five-line report; no model tokens\n/mecris          # richer model-interpreted status\n```\n\nSee [docs/PI_MECRIS_GUIDE.md](docs/PI_MECRIS_GUIDE.md) for detailed configuration, lazy-loading, and troubleshooting.\n\n### ☁️ Standard Setup\nFor detailed setup instructions for different agents, see [docs/SETUP_GUIDE.md](docs/SETUP_GUIDE.md).\n\n```bash\n# 1. Install dependencies, then authenticate\nuv sync           # creates/synchronizes .venv\nbin/mecris login  # activates .venv, sets PYTHONPATH, launches auth\n\n# 2. Configure environment (copy and edit .env.example if needed)\n# Set BEEMINDER_USERNAME, BEEMINDER_AUTH_TOKEN, TWILIO credentials, etc.\n\n# 3. MCP server is embedded (not manually launched)\n# The harness loads it automatically via .mcp.json (command: uv run --project . mcp_server.py --stdio).\n# If you must verify: ./scripts/launch_server.sh (manual fallback)\n./scripts/launch_server.sh\n\n# 4. Test health endpoint\ncurl http://127.0.0.1:8000/health\n```\n\n## Architecture Overview\n\nMecris 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.\n\n```text\n                               ┌─────────────────┐\n                               │   NEON DB       │\n                               │ (Central State) │\n                               └─┬─────────────┬─┘\n                  (Cloud Path)   │             │   (Local Path)\n                ┌────────────────┴──────┐      ▼────────────────┐\n                │   CLOUD HUB (WASM API)│      │   LOCAL MCP    │\n                ├───────────────────────┤      │ (Python / SQL) │\n                │   INACTIVE: FERMYON  │ (deprovisioned; see 2026-06-cloud-easing) │      └──────┬─────────┘\n                │   ACTIVE: AKAMAI     │             │\n                └───────────┬───────────┘             │\n                            │                         │\n           ┌────────────────┴─────────────────────────┴──────────────┐\n           │              THE STANDARD BUS (JSON / WIT)              │\n           └────┬───────────────┬─────────────────┬─────────────┬────┘\n                ▼               ▼                 ▼             ▼\n         ┌────────────┐  ┌─────────────┐  ┌───────────────┐  ┌─────────────┐\n         │ MOBILE GO  │  │ AGENTS/BOTS  │  │ HUMAN / CLI   │  │ CI TRIGGERS │\n         │ (Sensors)  │  │ (Narrators)  │  │ (Gemini/Term) │  │ (GHA/Hooks) │\n         └────────────┘  └─────────────┘  └───────────────┘  └─────────────┘\n```\n\n### Core Components\n\n*   **The Hubs**: Distributed logic centers that manage \"Knowledge\" (Neon DB) and \"Actions\" (Twilio/Beeminder).\n    *   **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.\n    *   **Cloud Hub (Failover/Mobile)**: Hosted on **Akamai (ACTIVE)**. Fermyon is **INACTIVE/deprovisioned** (see `decisions/2026-06-cloud-easing.md`). The cloud path provides high-availability endpoints; the local Python MCP (`mcp_server.py`) is embedded in the harness (`.mcp.json`) and is the primary interactive backend.\n*   **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.\n*   **The Spokes**: Lightweight \"Hosts\" (Mobile, CLI, and Bots) provide sensors and interfaces to the human.\n    *   **Mobile Go**: Android client bridging physical sensors (Google Fit/Health Connect).\n    *   **Agents/Bots**: Gemini and Claude narrators that interpret the state and guide the human.\n    *   **CI Triggers**: GitHub Actions and webhooks that drive periodic cloud synchronization.\n- **Robust startup/shutdown** with process management\n- **Enhanced error handling** and logging\n- **Industry-Leading Toolset**: Features **34 distinct MCP tools**—a larger specialized toolset than even the standard [GitHub MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/github) (which provides 20+).\n\n## Agent Harnesses\n\nMecris can be driven by multiple agent harnesses. Each has different tradeoffs (model choice, context size, local-first vs cloud-first, token efficiency).\n\n| Harness | Model Backend | Local-First? | Token Efficiency | Status | Docs |\n|---|---|---|---|---|---|\n| **Pi (TypeScript extension)** | Any (Copilot, Groq, Anthropic, Google, local) | Optional | ⭐⭐ (5 tools + loader) | ✅ Active (official harness; embedded MCP via .mcp.json) | [docs/PI_MECRIS_GUIDE.md](docs/PI_MECRIS_GUIDE.md) |\n| **Claude Code** | Claude models | ❌ No | ⭐⭐ (all 34 tools) | ✅ Active (explicit mcp__mecris__* permissions in .claude/settings.local.json) | [.mcp.json](.mcp.json) |\n| **Antigravity CLI** | Gemini models | ❌ No | ⭐⭐ (all 34 tools) | ✅ Active (replaced deprecated Gemini 'Google Code') | [.gemini/antigravity-cli/](docs/) |\n| **py_harness** (Ollama) | Ollama (Gemma 4) | ✅ Yes | ⭐⭐⭐ (1.5k core) | ⚠️ Partial (exists; not fully verified in OKF bundle) | [py_harness/README.md](py_harness/README.md) |\n\n**Pick your harness (official: Pi; verified: Claude Code; deprecated: Gemini 'Google Code' → Antigravity):**\n- **Local + fast?** Use `py_harness` (Ollama on your machine)\n- **Multi-model + vendor-agnostic?** Use **Pi** (bring your own model/provider)\n- **Specific vendor?** Use Claude Code (Claude), Gemini CLI (Gemini), or Antigravity (Gemini)\n\nSee [docs/PI_HARNESS_ROADMAP.md](docs/PI_HARNESS_ROADMAP.md) for detailed parity matrix and architectural differences.\n\n**Tool Categories:**\n- **Strategic Context**: `get_narrator_context`, `get_coaching_insight`\n- **Goal Mastery**: `get_beeminder_status`, `trigger_language_sync`, `get_language_velocity_stats`\n- **Physical Accountability**: `get_daily_activity`, `get_weather_report`\n- **Financial Stewardship**: `get_budget_status`, `get_real_anthropic_usage`, `get_unified_cost_status`\n- **System Health**: `get_system_health`, `get_scheduler_queue`, `trigger_reminder_check`\n- **Daily Progress**: `get_daily_aggregate_status` (The Majesty Cake 🍰)\n\n**Key Endpoints:**\n- `GET /health` - Service health and dependency status\n- `GET /narrator/context` - Unified context for Claude narrator\n- `GET /beeminder/status` - Goal portfolio with risk assessment\n- `GET /usage` - Budget status and burn rate analysis\n- `POST /beeminder/alert` - Emergency goal notifications\n- `POST /usage/record` - Track API usage sessions\n\n### 2. Data Source Integrations\n\n#### ✅ Beeminder API - **FULLY TESTED**\n- **Live API integration** with real goal data\n- **Risk classification** (CRITICAL/WARNING/CAUTION/SAFE)\n- **Emergency detection** with urgency levels\n- **Runway analysis** prioritizing urgent goals\n- **No mock data** - verified via comprehensive test suite\n\n#### ✅ Usage Tracking - **PRODUCTION READY**\n- **Neon (Postgres)** for cloud-native persistence and multi-tenant isolation.\n- **Accurate cost calculation** using official Anthropic pricing\n- **Real-time budget tracking** via Anthropic Admin API and Neon.\n- **Alert system** via Twilio for critical budget states\n- **Historical analysis** and burn rate projection\n\n#### ✅ Twilio Alerts - **CONFIGURED**\n- SMS notifications for beemergencies and budget alerts\n- Integrated with background task processing\n- Configurable alert thresholds\n\n#### ✅ Obsidian Integration - **CONFIGURED**\n- File reading capabilities implemented\n- Vault structure parsing in progress\n\n### 3. Server Management Tools ✅ **COMPLETE**\n- **`scripts/launch_server.sh`** - Safe server startup with health checks\n- **`scripts/shutdown_server.sh`** - Graceful shutdown with cleanup\n- **Process management** with PID files and cleanup traps\n- **Health monitoring** with automatic service validation\n\n## Current State\n\n### ✅ Production Ready\n- **MCP Server**: Secure, robust, stdio-integrated\n- **Beeminder Integration**: Live API, comprehensive testing\n- **Budget Tracking**: Real-time via Anthropic Admin API and Neon (Postgres)\n- **Alert System**: Twilio SMS for critical notifications\n- **Coordination**: Distributed leader election across instances\n\n### 🚧 In Progress  \n- **Obsidian Integration**: Vault parsing and goal extraction\n- **Documentation**: Organized into `/docs` directory\n\n### 📋 Next Priorities\n- **Majesty Cake UI** (In Progress): Widget defined in `architecture/beeminder-majesty-cake.md`; Android integration planned per `ROADMAP.md` and `decisions/2026-09-06-cloud-easing.md`.\n- **WASM Brain / Multi-User Twilio** (Future / Planned): WASM brain concept referenced in `docs/architectural_evolution/01_the_bootstrap_era.md` (historical design); multi-user migration planned per `ROADMAP.md`.\n- **Rust Reminder Engine** (Future): Planned per `ROADMAP.md`; currently handled by Python `services/coaching-service.py`.\n\n## Design Principles\n\n1. **Read Before Writing**: No hallucinations, context window is sacred\n2. **Budget Conscious**: Every token costs money\n3. **Warning System**: Professional doomsaying for deadline risks  \n4. **Memory Persistence**: Leave breadcrumbs for future sessions\n5. **Strategic Focus**: Insight and path illumination, not just task completion\n\n## Project Structure\n\n```\nmecris/\n├── README.md                 # This file\n├── CLAUDE.md                 # Core narrator instructions\n├── requirements.txt          # Python dependencies\n├── start_server.py          # Main server entry point\n├── mcp_server.py            # FastAPI application\n├── scripts/                 # Server management scripts\n│   ├── launch_server.sh     # Safe server startup\n│   └── shutdown_server.sh   # Graceful shutdown\n├── tests/                   # Test suites\n│   ├── test_mecris.py       # System integration tests\n│   └── test_beeminder_live.py # Beeminder API tests\n├── logs/                    # Application logs and reports\n├── docs/                    # Technical documentation\n└── [data clients]           # beeminder_client.py, usage_tracker.py, etc.\n```\n\n## Operation Mode\n\nMecris currently operates in **Stdio Mode**, integrated directly with CLI agents (Gemini CLI, Claude Code).\n\n### Running in Stdio Mode\nThe server is invoked automatically by your agent using:\n```bash\npython mcp_stdio_server.py\n```\n\n### Future: Secure SSE Mode\nStandalone FastAPI/SSE mode is currently disabled and will be reintroduced once secured with OIDC authentication.\n\n## Testing\n\n### Run All Tests\n```bash\nsource .venv/bin/activate\nPYTHONPATH=. pytest\n```\n\n### Manual Tool Testing\nYou can test the MCP tools directly via your agent's command interface (e.g., `/get_narrator_context`).\n\n## Configuration\n\nSet these environment variables in your shell or `.env` file:\n\n```bash\n# Beeminder Integration\nBEEMINDER_USERNAME=your_username\nBEEMINDER_AUTH_TOKEN=your_token\n\n# Twilio Alerts  \nTWILIO_ACCOUNT_SID=your_sid\nTWILIO_AUTH_TOKEN=your_token\nTWILIO_FROM_NUMBER=+1234567890\nTWILIO_TO_NUMBER=+1234567890\n\n# Optional Configuration\nDEBUG=false                    # Enable debug logging\nHOST=127.0.0.1                # Server bind address  \nPORT=8000                     # Server port\nLOG_LEVEL=INFO                # Logging level\n```\n\n## Budget Management\n\n### Current Budget: $20.88 remaining (as of April 2026)\n- **Daily burn rate**: Automatically calculated from usage\n- **Budget alerts**: SMS notifications for critical states\n- **Manual updates**: Use `/usage/update_budget` endpoint\n\n### Update Budget\n```bash\ncurl -X POST http://127.0.0.1:8000/usage/update_budget \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"remaining_budget\": 15.50}'\n```\n\n## Documentation\n\n- **`CLAUDE.md`** - Core narrator instructions and context\n- **`CLAUDE_CODE_INTEGRATION.md`** - Integration with Claude Code CLI\n- **`docs/CLAUDE_API_LIMITATIONS.md`** - Budget tracking approach\n- **`docs/`** - Additional technical documentation\n\n## Support\n\nFor issues or questions:\n- Check server logs in `logs/` directory\n- Run health checks to diagnose problems\n- Review test output for integration issues# CI Cache Validation Test\n",
  "bytes": 13440,
  "sha": "5bae6c53179e35ff62e036536e180916c607676b8ed02935ef400f0de1ed110c",
  "repo_slug": "kingdonb/mecris",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_kingdonb_mecris_knowledge_index_md_6dc23cd3/readme"
}