# juandiegohernandezangarita13-png/mmae-agent architecture

> Architecture diagram of the GitHub repository juandiegohernandezangarita13-png/mmae-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juandiegohernandezangarita13-png/mmae-agent
- Repository: https://github.com/juandiegohernandezangarita13-png/mmae-agent

## Overview

MMAE/JEV is a local and distributed autonomous-agent platform. Its documented core workflow accepts a goal through an interface, protects exact literals, creates a macro plan, expands it into a detailed action, then executes and reflects on tool results. JEV adds a broader agent runtime, skills, memory, verification, multimodal tools, and desktop/remote interfaces. Edges follow README statements or references in excerpted/indexed files; unsampled subsystem wiring is omitted or marked unverified.

Main entry points: [`jev/core/agent.py`](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/agent.py) (JEV agent), [`jev/tools/base.py`](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/tools/base.py) (Tool registry), [`core/micro_engine.py`](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/micro_engine.py) (Micro engine), [`core/planner.py`](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/planner.py) (Task planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_desktop["Desktop app<br/>[app.py]"]
  node_telegram["Telegram bot<br/>[telegram_bot.py]"]
end

subgraph group_reason["Agent reasoning"]
  node_agent["JEV agent<br/>[agent.py]"]
  node_bypass["Literal bypass<br/>[bypass.py]"]
  node_macro["Macro engine<br/>[macro_engine.py]"]
  node_planner["Task planner<br/>[planner.py]"]
  node_micro["Micro engine<br/>[micro_engine.py]"]
  node_reflection["Reflection loop<br/>[reflection_loop.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_runtime["Execution and skills"]
  node_tools["Tool registry<br/>[base.py]"]
  node_skills["Skill manager<br/>[manager.py]"]
  node_executor["Muse executor"]
  node_sandbox["Command sandbox<br/>[sandbox.py]"]
end

subgraph group_state["Memory and improvement"]
  node_memory[("Agent memory<br/>[memory.py]")]
  node_evolution["Self improvement"]
  node_finetune["Fine-tuning<br/>[finetune_engine.py]"]
end

subgraph group_extensions["Specialized capabilities"]
  node_claude["Claude Code bridge"]
  node_vision["Vision engine<br/>[vision_engine.py]"]
  node_image["Image generator<br/>[image_generator.py]"]
  node_sidecar["Web sidecar"]
  node_jevservice["Claude Code service"]
end

node_user(("User"))

node_user -->|"submits goal"| node_cli
node_user -->|"submits goal"| node_desktop
node_user -->|"submits goal"| node_telegram
node_cli -.->|"invokes"| node_agent
node_desktop -->|"invokes"| node_agent
node_telegram -.->|"invokes"| node_agent
node_agent -->|"plans tasks"| node_planner
node_agent -->|"queries"| node_llm
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"uses memory"| node_memory
node_agent -.->|"reflects"| node_reflection
node_agent -->|"delegates improvement"| node_evolution
node_agent -->|"uses skills"| node_skills
node_agent -.->|"uses vision"| node_vision
node_agent -.->|"uses image tools"| node_image
node_agent -.->|"delegates coding"| node_claude
node_agent -->|"connects UI"| node_sidecar
node_bypass -->|"shields literals"| node_macro
node_macro -->|"structures task"| node_planner
node_planner -->|"provides subtasks"| node_micro
node_bypass -->|"restores literals"| node_micro
node_micro -->|"fallback queries"| node_llm
node_micro -->|"emits tool actions"| node_tools
node_tools -.->|"executes action"| node_executor
node_executor -->|"validates commands"| node_sandbox
node_skills -->|"adapts skills"| node_tools
node_claude -->|"forwards requests"| node_jevservice
node_finetune -.->|"exposes tool"| node_tools

click node_cli "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/main.py"
click node_desktop "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/app.py"
click node_telegram "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/interfaces/telegram_bot.py"
click node_agent "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/agent.py"
click node_bypass "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/utils/bypass.py"
click node_macro "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/macro_engine.py"
click node_planner "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/planner.py"
click node_micro "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/micro_engine.py"
click node_reflection "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/reflection_loop.py"
click node_llm "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/llm_client.py"
click node_tools "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/tools/base.py"
click node_skills "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/skills/manager.py"
click node_executor "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/muse/execution_engine.py"
click node_sandbox "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/sandbox.py"
click node_memory "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/memory.py"
click node_evolution "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/self_evolving_agent.py"
click node_finetune "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/learning/finetune_engine.py"
click node_claude "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/claude_code_bridge.py"
click node_vision "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/vision_engine.py"
click node_image "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/image_generator.py"
click node_sidecar "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/ui/web_sidecar_server.py"
click node_jevservice "https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/claude_code_service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_desktop,node_telegram,node_user toneBlue
class node_agent,node_bypass,node_macro,node_planner,node_micro,node_reflection,node_llm toneAmber
class node_tools,node_skills,node_executor,node_sandbox toneMint
class node_memory,node_evolution,node_finetune toneRose
class node_claude,node_vision,node_image,node_sidecar,node_jevservice toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/main.py): `main.py`
- [Desktop app](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/app.py): `app.py`
- [Telegram bot](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/interfaces/telegram_bot.py): `jev/interfaces/telegram_bot.py`

### Agent reasoning

- [JEV agent](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/agent.py): `jev/core/agent.py`
- [Literal bypass](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/utils/bypass.py): `utils/bypass.py`
- [Macro engine](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/macro_engine.py): `core/macro_engine.py`
- [Task planner](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/planner.py): `core/planner.py`
- [Micro engine](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/micro_engine.py): `core/micro_engine.py`
- [Reflection loop](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/core/reflection_loop.py): `core/reflection_loop.py`
- [LLM client](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/llm_client.py): `jev/core/llm_client.py`

### Execution and skills

- [Tool registry](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/tools/base.py): `jev/tools/base.py`
- [Skill manager](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/skills/manager.py): `jev/skills/manager.py`
- [Muse executor](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/muse/execution_engine.py): `jev/core/muse/execution_engine.py`
- [Command sandbox](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/sandbox.py): `jev/core/sandbox.py`

### Memory and improvement

- [Agent memory](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/memory.py): `jev/core/memory.py`
- [Self improvement](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/self_evolving_agent.py): `jev/core/self_evolving_agent.py`
- [Fine-tuning](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/learning/finetune_engine.py): `jev/learning/finetune_engine.py`

### Specialized capabilities

- [Claude Code bridge](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/claude_code_bridge.py): `jev/core/claude_code_bridge.py`
- [Vision engine](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/vision_engine.py): `jev/core/vision_engine.py`
- [Image generator](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/image_generator.py): `jev/core/image_generator.py`
- [Web sidecar](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/ui/web_sidecar_server.py): `jev/ui/web_sidecar_server.py`
- [Claude Code service](https://github.com/juandiegohernandezangarita13-png/mmae-agent/blob/main/jev/core/claude_code_service.py): `jev/core/claude_code_service.py`

### Other components

- **User**

## Connections

- User → CLI: submits goal
- User → Desktop app: submits goal
- User → Telegram bot: submits goal
- CLI → JEV agent: invokes
- Desktop app → JEV agent: invokes (evidence: `app.py`)
- Telegram bot → JEV agent: invokes
- JEV agent → Task planner: plans tasks (evidence: `jev/core/agent.py`)
- JEV agent → LLM client: queries (evidence: `jev/core/agent.py`)
- JEV agent → Tool registry: dispatches tools (evidence: `jev/core/agent.py`)
- JEV agent → Agent memory: uses memory (evidence: `jev/core/agent.py`)
- JEV agent → Reflection loop: reflects
- JEV agent → Self improvement: delegates improvement (evidence: `jev/core/agent.py`)
- JEV agent → Skill manager: uses skills (evidence: `jev/core/agent.py`)
- JEV agent → Vision engine: uses vision
- JEV agent → Image generator: uses image tools
- JEV agent → Claude Code bridge: delegates coding
- JEV agent → Web sidecar: connects UI (evidence: `app.py`)
- Literal bypass → Macro engine: shields literals (evidence: `core/macro_engine.py`)
- Macro engine → Task planner: structures task
- Task planner → Micro engine: provides subtasks
- Literal bypass → Micro engine: restores literals (evidence: `core/micro_engine.py`)
- Micro engine → LLM client: fallback queries (evidence: `core/micro_engine.py`)
- Micro engine → Tool registry: emits tool actions
- Tool registry → Muse executor: executes action
- Muse executor → Command sandbox: validates commands (evidence: `jev/core/muse/execution_engine.py`)
- Skill manager → Tool registry: adapts skills (evidence: `jev/skills/manager.py`)
- Claude Code bridge → Claude Code service: forwards requests (evidence: `jev/core/claude_code_bridge.py`)
- Fine-tuning → Tool registry: exposes tool (evidence: `jev/learning/finetune_engine.py`)
