APEX v2 — Autonomous Local-First Agent

Agente autónomo con LLM local (Ollama), diseñado para superar las fallas conocidas de frameworks como OpenClaw, AutoGPT y BabyAGI.

Qué corrige respecto a la competencia

Problema reportado	Solución APEX v2
OpenClaw ignoró STOP y borró semanas de correos	STOP se honra en cada iteración del loop (/stop/:sessionId)
Skills maliciosas en ClawHub (824 detectadas)	Sin skills externas; tool registry local y auditable
30k instancias expuestas sin auth	APEX_API_KEY opcional con verificación en middleware
Token blow-up (envío de todo el historial)	Scratchpad con trimming + Memory Pointer Pattern
AutoGPT bucles infinitos	Detector de repetición de tool+args + APEX_MAX_STEPS
BabyAGI pierde foco del objetivo	Objetivo inyectado en cada prompt + reflexión estructurada
Hallucination silenciosa	Critic con JSON verdict + refinamiento
Tool timeouts bloquean al agente	AbortController + APEX_TOOL_TIMEOUT_MS por tool
Context window overflow	Outputs > N chars se guardan como artifact y se referencian
Fallas silenciosas de LLM	Circuit breaker + reintentos con backoff

Arquitectura

                ┌─────────────────────────────────────────────────┐
                │                   apps/web (UI)                  │
                │  Live trace SSE · Stop · Modo · Memoria reciente │
                └──────────────────────┬──────────────────────────┘
                                       │  /run/stream · /stop · /memory
                ┌──────────────────────▼──────────────────────────┐
                │              apps/api (Express)                  │
                │  SSE · JSON · API key opcional · rate limits     │
                └──────────────────────┬──────────────────────────┘
                                       │
              ┌────────────────────────┼──────────────────────────┐
              │                        │                          │
 ┌────────────▼───────────┐ ┌──────────▼──────────┐ ┌─────────────▼──────────┐
 │ runtime/react_loop.js  │ │ agents/ (classic)   │ │ memory/store.js        │
 │ Think → Act → Observe  │ │ planner→exec→critic │ │ Scratchpad + LTM JSONL │
 │ loop-detect · budget   │ │                     │ │ Artifact pointer       │
 └────────────┬───────────┘ └─────────────────────┘ └────────────────────────┘
              │
   ┌──────────▼────────────┐   ┌────────────────┐   ┌─────────────┐
   │ tools/ (FS, shell,    │◄──┤ safety/guard   │──►│ llm.js      │
   │  http, memory, finish)│   │ allowlist+stop │   │ Ollama+retry│
   └───────────────────────┘   └────────────────┘   └─────────────┘

Modos

• Autónomo (default) — ReAct loop: el agente razona, llama herramientas, observa y repite hasta agent.finish o MAX_STEPS.
• Clásico — planner → executor → critic → retry-si-improve. Retro-compatible con v1.

Herramientas incluidas

• fs.read, fs.write, fs.list — sandboxed en data/workspace
• shell.exec — allowlist estricta + patrones peligrosos bloqueados
• http.get — solo http/https, con timeout
• memory.search — consulta sesiones pasadas
• artifact.save — Memory Pointer Pattern para outputs grandes
• agent.finish — señal de terminación

Requisitos

• Node 18+ (Docker usa 20)
• Ollama con llama3

ollama pull llama3

Ejecutar local

cd apex-startup
npm install
npm run dev
# luego abrir apps/web/index.html

Ejecutar con Docker

docker-compose up --build

• API: http://localhost:4001
• UI: http://localhost:3000

Endpoints

Método	Ruta	Descripción
GET	/health	Estado + reachability de Ollama + breaker
GET	/tools	Catálogo de herramientas
POST	/run	Ejecutar (modo: autonomous | classic)
GET	/run/stream?objective=...	SSE del loop autónomo
POST	/stop/:sessionId	STOP honrado en la próxima iteración
GET	/memory/recent	Últimas 20 sesiones
GET	/memory/search?q=...	Búsqueda léxica en LTM

Variables de entorno

Variable	Default	Descripción
OLLAMA_HOST	http://localhost:11434	Endpoint de Ollama
APEX_MODEL	llama3	Modelo a usar
APEX_MAX_STEPS	12	Pasos máximos en loop autónomo
APEX_LLM_TIMEOUT_MS	120000	Timeout por llamada al LLM
APEX_LLM_RETRIES	2	Reintentos con backoff
APEX_TOOL_TIMEOUT_MS	20000	Timeout por tool
APEX_ALLOWED_SHELL	lista segura	Comandos permitidos (csv)
APEX_DATA_DIR	./data	Ruta para LTM + artifacts
APEX_API_KEY	(vacío = auth off)	Si se setea, exige x-api-key

Seguridad por defecto

• Comandos destructivos (rm -rf, format, shutdown, mkfs, dd, curl|sh) bloqueados siempre
• Path traversal bloqueado en FS tools
• Artifact storage separado del contexto del LLM
• STOP inmediato — inspirado en el incidente OpenClaw de Summer Yue (feb 2026)

Roadmap

• Vector memory (FAISS/Qdrant) opcional
• Multi-agent validation (segundo crítico)
• Plugins firmados (no como ClawHub)
• Telemetría OTEL
• Frontend con gráfico del árbol de decisiones