Technical deep-dive documentation for all 55 systems powering Marcus's AI agent coordination platform.
Marcus is built on 55 interconnected systems that enable AI agents to collaborate autonomously. Each system is documented with implementation details, APIs, and integration patterns.
| System Category | Files | Description |
|---|---|---|
| Core Intelligence | 01, 07, 17, 23, 27, 44 | Memory, AI engine, learning, task intelligence, recommendations, task classifier |
| Agent Coordination | 21, 26, 03, 12 | Agent management, worker support, context sharing, communication |
| Project Management | 16, 04, 24, 25, 53 | Project control, Kanban integration, analysis, reporting, workflow management |
| Development & Analysis | 42, 43 | Code analysis, API systems |
| Data & Storage | 10, 32, 13, 19 | Persistence, models, cost tracking, NLP processing |
| Security & Compliance | 51 | Security systems, access control, threat detection |
| Quality & Testing | 18, 30, 11, 29 | QA systems, testing framework, monitoring, detection |
| Infrastructure | 08, 09, 06, 14, 15 | Error handling, events, MCP server, isolation, service registry |
| Operations | 22, 20, 28, 31 | Operational modes, pipelines, configuration, resilience |
| Visualization | 05, 02 | UI systems, logging and visualization |
Multi-tier cognitive memory (Working, Episodic, Semantic, Procedural) that enables learning and context retention across projects.
Hybrid AI decision-making system combining multiple AI providers with context-aware prompt engineering.
Continuous learning from project outcomes, pattern recognition, and performance optimization.
Intelligent task analysis, dependency inference, and automatic task breakdown.
AI-powered recommendations for task assignment, technology choices, and workflow optimization.
Intelligent task categorization, priority scoring, and agent matching using ML and NLP.
Core agent lifecycle management, registration, assignment, and the work-loop protocol. (What earlier docs called "Communication Hub" is folded in here — there is no separate inter-agent message bus; coordination happens on the board.)
Tools and utilities that help AI agents work more effectively with context and error recovery.
Intelligent context sharing between agents and automatic dependency resolution.
High-level project creation, tracking, and completion management.
Multi-provider Kanban board integration. SQLite (default, zero-setup) plus Planka, GitHub Projects, and Linear.
Project analytics, performance metrics, and insight generation.
AI-powered task breakdown into manageable subtasks with clear interfaces and shared conventions.
Repository analysis, language detection, complexity assessment, and security scanning for agent-generated code.
Comprehensive security framework including authentication, threat detection, and workspace isolation.
Data storage abstraction supporting multiple backends (SQLite, JSON, PostgreSQL).
Data models for tasks, agents, projects, and system entities.
API usage monitoring and cost optimization across AI providers.
Natural language processing for task analysis and context extraction.
Automated quality checks, code review, and deployment validation.
Comprehensive testing infrastructure for all Marcus components.
Real-time system monitoring, health checks, and alerting.
Anomaly detection, error pattern recognition, and preventive measures.
Comprehensive error handling with automatic recovery and escalation.
Publish/subscribe system for loose coupling and scalability.
Model Context Protocol server implementation for AI agent integration.
Secure isolation between agents and projects.
Dynamic service discovery and health management.
Different operation modes (development, staging, production) with appropriate configurations.
Dynamic configuration system with environment-based overrides.
Fault tolerance, circuit breakers, and graceful degradation.
Real-time dashboards and project visualization tools. The active visualization product is Cato, which reads board state directly.
Comprehensive logging infrastructure with multiple output formats.
- Start with Core Intelligence systems to understand how Marcus thinks
- Review Agent Coordination to understand agent workflows
- Check Infrastructure systems for integration patterns
- Review MCP Server (06) for API integration
- Check Error Framework (08) for proper error handling
- Study Configuration Management (28) for setup
- Understand Event-Driven Architecture (09) for loose coupling
- Review Service Registry (15) for service discovery
- Check Testing Framework (30) for validation
- Study Monitoring Systems (11) for observability
- Review Resilience (31) for fault tolerance
- Check Pipeline Systems (20) for deployment
graph TD
A[01-Memory] --> B[07-AI Engine]
B --> C[17-Learning]
C --> D[27-Recommendations]
E[21-Agent Coord] --> F[26-Worker Support]
F --> G[03-Context System]
G --> H[12-Communication]
I[16-Project Mgmt] --> J[04-Kanban]
J --> K[24-Analysis]
K --> L[25-Reports]
M[08-Error Framework] --> N[09-Events]
N --> O[06-MCP Server]
O --> P[15-Service Registry]
- 55 Total Systems documented
- 6 Core Intelligence systems for AI decision-making and classification
- 4 Agent Coordination systems for workflow management
- 2 Development & Analysis systems for code quality and API integration
- 1 Security & Compliance system for comprehensive security
- 7 Project Management systems including workflow orchestration and task decomposition
- 5 Infrastructure systems for reliability and scalability
- 4 Quality & Testing systems for reliability
- Rest: Data storage, operations, and visualization systems
When modifying systems:
- Update the relevant system documentation
- Update this README if adding/removing systems
- Update interdependency diagrams if changing relationships
- Add integration examples for new APIs
- Document breaking changes clearly
- All systems follow Event-Driven Architecture principles
- Error Framework provides consistent error handling across systems
- Configuration Management allows per-environment customization
- Testing Framework ensures all systems maintain quality standards
- MCP Server exposes unified API regardless of internal complexity
Each system is designed to be independently testable, scalable, and maintainable while contributing to Marcus's overall AI agent coordination capabilities.