The AI brain β LLM integrations, memory systems, agent orchestration, and tool handlers.
INDEX.md β Master navigation for the entire MasterClaw ecosystem
- WHATSNEW.md β Latest features and improvements
- LICENSE β MIT License
- CONTRIBUTING β How to contribute
- CODE_OF_CONDUCT β Community standards
- ROADMAP β Future development plans
- Makefile β Cross-repo orchestration (run
make help) - CHEATSHEET.md β Quick reference for mc commands
- Issue Templates β Bug reports, features, questions
- PR Template β Pull request guidelines
# Install dependencies
pip install -r requirements.txt
# Configure
cp .env.example .env
# Edit .env with your API keys
# Run
python -m masterclaw_coreMasterClaw Core provides interactive API documentation:
| Documentation | URL | Description |
|---|---|---|
| Swagger UI | http://localhost:8000/docs |
Interactive API explorer with "Try it out" feature |
| ReDoc | http://localhost:8000/redoc |
Clean, responsive API reference documentation |
| OpenAPI Schema | http://localhost:8000/openapi.json |
Raw OpenAPI 3.0 specification |
- Navigate to
http://localhost:8000/docs - Browse available endpoints by category
- Click "Try it out" to test endpoints directly from the browser
- View request/response schemas and example payloads
GET /healthGET /health/securityReturns security configuration status:
status: "secure" or "insecure"environment: Current environment (development/production)issues_count: Number of security issues detectedrecommendations_count: Number of configuration recommendations
GET /metricsReturns Prometheus-formatted metrics for monitoring:
masterclaw_http_requests_total- Total HTTP requests by method, endpoint, statusmasterclaw_http_request_duration_seconds- Request latency histogrammasterclaw_chat_requests_total- Chat requests by provider and modelmasterclaw_chat_tokens_total- Token usage countermasterclaw_memory_operations_total- Memory operations by type and statusmasterclaw_memory_search_duration_seconds- Memory search latencymasterclaw_active_sessions- Gauge of active sessionsmasterclaw_memory_entries_total- Gauge of total memory entriesmasterclaw_llm_requests_total- LLM API requests by providermasterclaw_llm_request_duration_seconds- LLM request latency
POST /v1/chat
{
"message": "Hello, MasterClaw!",
"session_id": "abc123",
"provider": "openai",
"model": "gpt-4",
"use_memory": true
}# Search memories
POST /v1/memory/search
{
"query": "backup strategy",
"top_k": 5
}
# Add memory
POST /v1/memory/add
{
"content": "Remember to backup daily",
"metadata": {"priority": "high"},
"source": "user_instruction"
}
# Get memory
GET /v1/memory/{memory_id}
# Delete memory
DELETE /v1/memory/{memory_id}# List all sessions
GET /v1/sessions?limit=100&active_since_hours=24
# Get session chat history
GET /v1/sessions/{session_id}?limit=50
# Delete a session and all its messages
DELETE /v1/sessions/{session_id}
# Get session statistics
GET /v1/sessions/stats/summarySystem maintenance operations for administration:
# Get maintenance status
GET /v1/maintenance/status?retention_days=30
# Run maintenance tasks
POST /v1/maintenance/run
{
"task": "health_history_cleanup",
"days": 30,
"dry_run": false
}Available Tasks:
health_history_cleanup- Remove old health history recordscache_clear- Clear the response cachesession_cleanup- Remove old sessionsmemory_optimize- Optimize memory storeall- Run all maintenance tasks
Features:
- Dry-run mode for safe previews
- Configurable retention period
- Detailed results for each task
- Maintenance recommendations
Response caching management:
# Get cache statistics
GET /cache/stats
# Get cache health
GET /cache/health
# Clear all cached responses
POST /cache/clearReal-time log streaming and retrieval:
# Stream logs (SSE)
POST /v1/logs/stream
{
"service": "core",
"level": "INFO",
"search": "error",
"follow": true
}
# Get recent logs
GET /v1/logs?service=core&level=ERROR&since=1h&limit=100Access Rex's personal context files programmatically:
# Get projects
GET /v1/context/projects?status=active&priority=high
# Get goals
GET /v1/context/goals?status=active
# Get people
GET /v1/context/people?role=developer
# Get knowledge entries
GET /v1/context/knowledge?category=technology
# Get preferences
GET /v1/context/preferences?category=communication
# Search across all context
GET /v1/context/search?query=masterclaw
# Get context summary
GET /v1/context/summaryUse Cases:
- Personalized responses based on Rex's preferences
- Query active projects and goals
- Knowledge base lookups
- People and relationship context
The MasterClaw CLI (mc) provides convenient access to maintenance operations:
# Check maintenance status
mc api-maintenance status
# Run maintenance with dry-run preview
mc api-maintenance run --task health_history_cleanup --dry-run
# Actually run maintenance
mc api-maintenance run --task all --days 30
# List available tasks
mc api-maintenance tasksmasterclaw_core/
βββ __init__.py # Package info
βββ __main__.py # Entry point
βββ main.py # FastAPI app
βββ config.py # Settings with validation
βββ models.py # Pydantic models
βββ llm.py # LLM router (OpenAI, Anthropic)
βββ memory.py # Memory store (Chroma, JSON)
βββ cache.py # Response caching (Redis/Memory)
βββ health_history.py # Health tracking and analytics
βββ audit_logger.py # Security audit logging
βββ context_manager.py # Rex-deus context integration
Configuration is validated on startup with security checks:
| Variable | Default | Description | Validation |
|---|---|---|---|
OPENAI_API_KEY |
- | OpenAI API key | - |
ANTHROPIC_API_KEY |
- | Anthropic API key | - |
DEFAULT_MODEL |
gpt-4 | Default LLM model | - |
MEMORY_BACKEND |
chroma | Memory backend | Must be: chroma, json |
CHROMA_PERSIST_DIR |
./data/chroma | ChromaDB directory | - |
PORT |
8000 | API port | 1-65535 |
RATE_LIMIT_PER_MINUTE |
60 | Rate limit per IP | 1-10000 |
CORS_ORIGINS |
["*"] | Allowed CORS origins | Valid URLs; warns if "*" in production |
SESSION_TIMEOUT |
3600 | Session timeout (seconds) | 60-604800 (7 days) |
LOG_LEVEL |
info | Logging level | debug, info, warning, error, critical |
CACHE_ENABLED |
true | Enable response caching | true/false |
CACHE_BACKEND |
memory | Cache backend | memory, redis |
CACHE_DEFAULT_TTL |
300 | Default cache TTL (seconds) | 0-86400 |
CACHE_MAX_SIZE |
1000 | Max entries in memory cache | 100-100000 |
CACHE_REDIS_URL |
- | Redis connection URL | Valid redis:// URL |
ENVIRONMENT |
development | Environment name | development, production |
The configuration system includes security validators:
- PORT: Must be a valid port number (1-65535)
- RATE_LIMIT_PER_MINUTE: Must be reasonable (1-10000)
- CORS_ORIGINS: Warns if
*is used in production; validates URL format - SESSION_TIMEOUT: Must be between 1 minute and 7 days
- LOG_LEVEL: Must be a standard log level
- MEMORY_BACKEND: Must be a supported backend
On startup in production mode, security issues are logged as warnings.
Set NODE_ENV=production or ENV=production to enable production security checks.
# Build
docker build -t masterclaw-core .
# Run
docker run -p 8000:8000 --env-file .env masterclaw-core# Run all tests
pytest
# Run with coverage
pytest --cov=masterclaw_core
# Run specific test file
pytest tests/test_config.py -v
# Run API integration tests
pytest tests/test_api.py -v# 1. Clone and setup
git clone https://github.com/TheMasterClaw/masterclaw-core.git
cd masterclaw-core
pip install -r requirements.txt
# 2. Configure environment
cp .env.example .env
# Edit .env with your API keys
# 3. Run the API
python -m masterclaw_core
# 4. In another terminal, use the CLI
mc api-maintenance status
mc statusMasterClaw Core integrates with other components of the ecosystem:
| Component | Integration | Purpose |
|---|---|---|
| masterclaw-tools | CLI commands | Remote administration via mc |
| masterclaw-infrastructure | Docker Compose | Deployment and orchestration |
| level100-studios | Design system | UI components for interfaces |
| rex-deus | Context API | Personal context and preferences |
The MasterClaw CLI (mc) provides comprehensive system administration:
| Command | Description |
|---|---|
mc status |
Dashboard-style service status monitoring |
mc health |
Detailed health monitoring with history and trends |
mc doctor |
System diagnostics and recommendations |
mc logs |
View and stream logs from services |
mc api-maintenance |
Remote maintenance operations |
mc whoami |
User context and system information |
mc workflow |
Workflow automation |
mc terraform |
Infrastructure management |
The design system now includes 20+ production-ready components:
Layout & Navigation:
Divider- Visual content separatorsBreadcrumbs- Navigation path indicatorsTabs- Tabbed content interfaceAccordion- Collapsible content sections
Data Display:
Table- Tabular data display with sortingStat- Statistics and metrics displayTimeline- Chronological eventsProgress- Progress barsSkeleton- Loading placeholders
Input & Selection:
Button- Action buttonsInput- Text input fieldsSelect- Dropdown selectionSwitch- Toggle switchesRadio- Single-select optionsCheckbox- Multi-select options
Feedback & Status:
Alert- Important messages and notificationsToast- Notification toastsSpinner- Loading indicatorsBadge- Status indicators and labelsChip- Labels, tags, and filtersEmptyState- Empty list/page states
Utility:
Modal- Dialog and overlay componentTooltip- Hover information tooltipsAvatar- User/profile avatarsKbd- Keyboard key representationsCode- Inline code and code blocks
Core API Endpoints:
- Chat with memory integration
- Memory store (search, add, delete, update)
- Session management
- Bulk operations (memory, sessions)
- Maintenance operations
- Real-time log streaming (SSE)
- Health monitoring and history
- Security health checks
- Prometheus metrics
- Cache management
New Bulk Operations:
POST /v1/memory/bulk-delete- Batch delete memoriesPOST /v1/memory/bulk-update- Batch update metadataPOST /v1/sessions/batch-archive- Archive sessionsGET /v1/memory/stats/bulk- Memory statisticsGET /v1/sessions/stats/batch- Session statistics
The brain behind the claw. πΎ