{"id":48209830,"url":"https://github.com/smouj/alchemical-agent-ecosystem","last_synced_at":"2026-04-04T18:47:15.128Z","repository":{"id":340264456,"uuid":"1165247975","full_name":"smouj/alchemical-agent-ecosystem","owner":"smouj","description":"🧙Unified local-first multi-agent platform (self-hosted, zero paid APIs)","archived":false,"fork":false,"pushed_at":"2026-02-24T05:51:12.000Z","size":84,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T08:08:42.161Z","etag":null,"topics":["ai-agent","automation","caddy","docker-compose","local-first","multi-agent","ollama","openclaw","self-hosted","skill-agent"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smouj.png","metadata":{"files":{"readme":"README.es.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T01:09:44.000Z","updated_at":"2026-02-24T05:51:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/smouj/alchemical-agent-ecosystem","commit_stats":null,"previous_names":["smouj/alchemical-agent-ecosystem"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/smouj/alchemical-agent-ecosystem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Falchemical-agent-ecosystem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Falchemical-agent-ecosystem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Falchemical-agent-ecosystem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Falchemical-agent-ecosystem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smouj","download_url":"https://codeload.github.com/smouj/alchemical-agent-ecosystem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smouj%2Falchemical-agent-ecosystem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31409470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","automation","caddy","docker-compose","local-first","multi-agent","ollama","openclaw","self-hosted","skill-agent"],"created_at":"2026-04-04T18:47:14.099Z","updated_at":"2026-04-04T18:47:15.112Z","avatar_url":"https://github.com/smouj.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003c!-- Sigilo del ecosistema --\u003e\n\u003cimg src=\"./assets/branding/variants/logo-horizontal.svg\" alt=\"Alchemical Agent Ecosystem\" width=\"780\" /\u003e\n\n# ⚗️ Alchemical Agent Ecosystem v2.0\n\n### *Magnum Opus*\n\n[![Versión](https://img.shields.io/badge/versión-2.0--magnum--opus-D4AF37?style=for-the-badge\u0026logo=flask\u0026logoColor=white)](https://github.com/smouj/alchemical-agent-ecosystem)\n[![Licencia](https://img.shields.io/github/license/smouj/alchemical-agent-ecosystem?style=for-the-badge\u0026color=16a34a)](LICENSE)\n[![Último commit](https://img.shields.io/github/last-commit/smouj/alchemical-agent-ecosystem?style=for-the-badge)](https://github.com/smouj/alchemical-agent-ecosystem/commits/main)\n[![CI](https://img.shields.io/github/actions/workflow/status/smouj/alchemical-agent-ecosystem/ci.yml?style=for-the-badge\u0026label=CI\u0026logo=github)](https://github.com/smouj/alchemical-agent-ecosystem/actions/workflows/ci.yml)\n[![Next.js](https://img.shields.io/badge/Next.js-15-black?style=for-the-badge\u0026logo=next.js)](https://nextjs.org)\n[![FastAPI](https://img.shields.io/badge/FastAPI-gateway-009688?style=for-the-badge\u0026logo=fastapi\u0026logoColor=white)](https://fastapi.tiangolo.com)\n[![KiloCode AI](https://img.shields.io/badge/KiloCode_AI-4B0082?style=for-the-badge\u0026logoColor=white)](https://kilo.ai)\n[![Auto-alojado](https://img.shields.io/badge/auto--alojado-100%25-8b5cf6?style=for-the-badge\u0026logo=homeassistant\u0026logoColor=white)](https://github.com/smouj/alchemical-agent-ecosystem)\n[![APIs de pago](https://img.shields.io/badge/Datos_Locales-100%25-dc2626?style=for-the-badge)](https://github.com/smouj/alchemical-agent-ecosystem)\n[![SSE](https://img.shields.io/badge/realtime-SSE-06b6d4?style=for-the-badge)](https://github.com/smouj/alchemical-agent-ecosystem)\n[![RBAC](https://img.shields.io/badge/auth-RBAC_%2B_API_Keys-16a34a?style=for-the-badge)](https://github.com/smouj/alchemical-agent-ecosystem)\n\n---\n\n\u003ca href=\"./README.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/Language-English-1f6feb?style=for-the-badge\" alt=\"English\"\u003e\u003c/a\u003e\n\u0026nbsp;\n\u003cstrong\u003e\u003cimg src=\"https://img.shields.io/badge/Idioma-Español-c92a2a?style=for-the-badge\" alt=\"Español\"\u003e\u003c/strong\u003e\n\n---\n\n[![Typing SVG](https://readme-typing-svg.demolab.com?font=Cinzel\u0026size=21\u0026duration=3000\u0026pause=800\u0026color=D4AF37\u0026center=true\u0026vCenter=true\u0026width=780\u0026lines=Donde+la+Inteligencia+se+Forja%2C+No+se+Compra.;Plataforma+multi-agente+local-first+y+soberana.;Siete+servicios.+Una+arquitectura+sin+concesiones.;C%C3%ADrculos+Alqu%C3%ADmicos%3A+agentes+que+se+auto-forman.;Datos+locales.+IA+v%C3%ADa+KiloCode.+Tier+gratuito+disponible.;El+Opus+M%C3%A1ximo+de+la+automatizaci%C3%B3n+propia.)](https://github.com/smouj/alchemical-agent-ecosystem)\n\n\u003c/div\u003e\n\n---\n\n## ✦ La Gran Transmutación\n\nExiste un sueño antiguo en la alquimia: convertir la materia bruta en oro puro mediante el conocimiento, la disciplina y el fuego correcto. El **Alchemical Agent Ecosystem** es ese sueño convertido en software.\n\nNo es un envoltorio de ChatGPT. No es una interfaz para la API de otro. Es una **plataforma multi-agente de filosofía local-first**, forjada desde el primer principio: que la inteligencia artificial verdaderamente poderosa no debería depender de infraestructura ajena para tus datos, ni de costos impredecibles, ni de la benevolencia de ninguna corporación.\n\nAquí, en tu propia infraestructura, conviven:\n\n- Un **dashboard visual** (`Agent Node Studio`) donde los agentes se componen como circuitos alquímicos — arrastrando nodos, trazando flujos, observando en tiempo real cómo el pensamiento se propaga de capa en capa.\n- Un **gateway inteligente** que enruta, autentica, recuerda y orquesta sin descanso, actuando como límite de política entre el mundo exterior y el núcleo de ejecución.\n- **Diez servicios de ejecución** nombrados como fuerzas elementales — `velktharion`, `synapsara`, `kryonexus`, `noctumbra-mail`, `temporaeth`, `vaeloryn-conclave`, `ignivox`, `auralith`, `resonvyr`, `fluxenrath` — cada uno con su dominio, sus capacidades y su lugar en la Gran Obra.\n- **Memoria jerárquica** que no olvida: Redis para el instante, ChromaDB para la semántica, agentes resumen para la continuidad a largo plazo.\n- **Modelos invocados a través de KiloCode AI Gateway** — Claude, Gemini, MiniMax, y más — sin almacenar ni un solo dato tuyo en servidores externos.\n- **Círculos Alquímicos**: equipos de agentes que se auto-forman, colaboran en paralelo y producen resultados que ningún agente solitario podría alcanzar.\n\n\u003e *\"Solve et Coagula\"* — disuelve lo complejo en partes comprensibles, y después coaguélalo en una obra mayor. Eso es exactamente lo que hace este ecosistema con tus tareas de automatización.\n\nEl **Magnum Opus** no es la versión final. Es la primera versión que merece ese nombre.\n\n---\n\n## 🖼️ Capturas de Pantalla — Diseño 2026\n\n\u003e **✨ Nuevo Sistema de Diseño Alquímico 2026**: Negro profundo (#050505), acentos dorados líquidos (#d4af37) y cobre, paneles glassmorphism con bordes holográficos, y animaciones butter-smooth con framer-motion.\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e💬 Chat del Caldero — Interacción Multi-Agente\u003c/strong\u003e\u003cbr/\u003e\n  \u003cem\u003eStreaming SSE en tiempo real con efectos de brillo etéreo\u003c/em\u003e\u003cbr/\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/smouj/alchemical-agent-ecosystem/main/assets/screenshots/dashboard-chat.svg\" width=\"100%\" alt=\"Alchemical Dashboard - Chat View\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🧩 Agent Node Studio — Constructor Visual de Flujos\u003c/strong\u003e\u003cbr/\u003e\n  \u003cem\u003eCanvas React Flow con nodos alquímicos personalizados y conexiones animadas\u003c/em\u003e\u003cbr/\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/smouj/alchemical-agent-ecosystem/main/assets/screenshots/dashboard-nodes.svg\" width=\"100%\" alt=\"Alchemical Dashboard - Node Studio\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🤖 Runtime de Agentes — Estado de Agentes en Vivo\u003c/strong\u003e\u003cbr/\u003e\n  \u003cem\u003eMétricas en tiempo real con animaciones de pulso e indicadores de estado\u003c/em\u003e\u003cbr/\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/smouj/alchemical-agent-ecosystem/main/assets/screenshots/dashboard-agents.svg\" width=\"100%\" alt=\"Alchemical Dashboard - Agents View\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e📜 Logs \u0026 Telemetría — Streaming de Logs en Tiempo Real\u003c/strong\u003e\u003cbr/\u003e\n  \u003cem\u003eMonitor de logs con SSE y resaltado de sintaxis\u003c/em\u003e\u003cbr/\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/smouj/alchemical-agent-ecosystem/main/assets/screenshots/dashboard-logs.svg\" width=\"100%\" alt=\"Alchemical Dashboard - Logs Monitor\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🛠️ Administración — Operaciones del Sistema\u003c/strong\u003e\u003cbr/\u003e\n  \u003cem\u003ePanel de configuración con navegación jerárquica\u003c/em\u003e\u003cbr/\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/smouj/alchemical-agent-ecosystem/main/assets/screenshots/dashboard-admin.svg\" width=\"100%\" alt=\"Alchemical Dashboard - Admin Panel\" /\u003e\n\u003c/p\u003e\n\n### 🎨 Características del Sistema de Diseño\n\n- **Paneles Glassmorphism**: Backdrop-blur con bordes etéreos\n- **Gradientes Dorados Líquidos**: Gradientes CSS @property animados\n- **Efectos Holográficos**: Bordes giratorios animados y pulsos de brillo\n- **Framer Motion 12**: Transiciones de página, micro-interacciones, animaciones escalonadas\n- **Tailwind CSS v4**: Motor Oxide con tokens de color alquímicos personalizados\n- **Integración React Flow**: Tipos de nodos personalizados con mini-mapa y controles\n- **PWA Ready**: Manifest.json con colores de tema e iconos\n\n---\n\n## 🚀 Inicio Rápido (El Ritual de 5 Minutos)\n\n### Prerrequisitos\n\nAntes de invocar la Gran Obra, asegúrate de tener los elementos en orden:\n\n| Elemento | Versión mínima | Propósito |\n|---|---|---|\n| `Docker` + `Docker Compose` | 24+ | El crisol que contiene todo |\n| `Node.js` | 20 LTS | Alimenta el dashboard |\n| `Python` | 3.11+ | Motor del gateway y los servicios |\n| `KILO_API_KEY` | — | Clave de [kilo.ai](https://kilo.ai) (tier gratuito disponible) |\n| RAM libre | 8 GB mínimo | Los agentes necesitan espacio para pensar |\n\n### Paso 1 — Clona el repositorio\n\n```bash\ngit clone https://github.com/smouj/alchemical-agent-ecosystem.git\ncd alchemical-agent-ecosystem\n```\n\n### Paso 2 — Ejecuta el asistente de instalación\n\n```bash\n./install.sh --wizard\n```\n\nEl asistente te guiará por la configuración inicial y generará tu archivo `.env` con valores sensatos para uso local.\n\nSi prefieres hacerlo manualmente, copia el ejemplo y edita lo que necesites:\n\n```bash\ncp .env.example .env\nnano .env  # o tu editor favorito\n```\n\nLas variables esenciales:\n\n```dotenv\n# ── Identidad del ecosistema ──────────────────────────────────\nECOSYSTEM_SECRET_KEY=\"cambia-esto-por-algo-fuerte\"\n\n# ── Base de datos ─────────────────────────────────────────────\nPOSTGRES_DB=alchemical\nPOSTGRES_USER=alchemist\nPOSTGRES_PASSWORD=gran_obra_secreta\n\n# ── Redis ─────────────────────────────────────────────────────\nREDIS_URL=redis://redis:6379/0\n\n# ── KiloCode AI Gateway ───────────────────────────────────────\nKILO_BASE_URL=https://api.kilo.ai/api/gateway\nKILO_API_KEY=tu-clave-de-kilo-ai\nKILO_DEFAULT_MODEL=anthropic/claude-sonnet-4.5\n\n# ── Conectores (opcionales — déjalos vacíos si no los usas) ───\nTELEGRAM_BOT_TOKEN=\nDISCORD_BOT_TOKEN=\n```\n\n### Paso 3 — Levanta el crisol\n\n```bash\n./scripts/alchemical up-fast\n```\n\nO directamente con Docker Compose:\n\n```bash\ndocker compose up -d\n```\n\nEste comando inicia simultáneamente: PostgreSQL con `pgvector`, Redis, ChromaDB, el gateway FastAPI, los diez servicios de ejecución y el dashboard Next.js.\n\n### Paso 4 — Verifica que todo respira\n\n```bash\ncurl -fsS http://localhost/gateway/health\n```\n\nUna respuesta `200 OK` con el estado de cada componente confirma que la transmutación fue exitosa.\n\n### Paso 5 — Abre el portal\n\n| Interfaz | URL |\n|---|---|\n| Dashboard (modo runtime) | `http://localhost` |\n| Dashboard (modo dev) | `http://localhost:3000` |\n| Gateway API Docs | `http://localhost/gateway/docs` |\n| ChromaDB | `http://localhost:8001` |\n\nEl `Agent Node Studio` te recibirá. Crea tu primer agente. Observa cómo piensa.\n\n\u003e **Modo desarrollo del dashboard:**\n\u003e ```bash\n\u003e cd apps/alchemical-dashboard\n\u003e npm run dev\n\u003e # → http://localhost:3000\n\u003e ```\n\n---\n\n## 🌌 Arquitectura – Los Siete Círculos\n\nLa arquitectura refleja la cosmología alquímica: capas concéntricas donde cada círculo purifica y eleva lo que recibe del anterior. El gateway es la frontera sagrada — nada entra ni sale sin pasar por él.\n\n### Vista general del sistema\n\n```mermaid\nflowchart TB\n  subgraph Edge[\"🌐 Capa de Borde\"]\n    CADDY[\"Caddy :80 / :443\\nReverse Proxy\"]\n  end\n\n  subgraph UX[\"🖥️ Control Plane\"]\n    OP[\"Operador\"]\n    DASH[\"Dashboard Next.js 15\\nAgent Node Studio\\n:3000\"]\n  end\n\n  subgraph Core[\"⚙️ Núcleo de Orquestación\"]\n    GW[\"Gateway FastAPI\\nAuth · Routing · Policy\\n:8000\"]\n    DB[(\"PostgreSQL\\n+ pgvector\")]\n    EV[(\"Eventos / Jobs\\nChat / Usage\")]\n    AUTH[\"RBAC + API Keys\"]\n    SSE[\"SSE Observabilidad\\nTiempo Real\"]\n  end\n\n  subgraph Diez[\"🧪 Los Diez Círculos — Servicios de Ejecución\"]\n    S1[\"⚔️ velktharion :7401\\nOrquestador y director\"]\n    S2[\"🧠 synapsara :7402\\nMeta-razonamiento y coordinación\"]\n    S3[\"❄️ kryonexus :7403\\nDatos y análisis\"]\n    S4[\"✉️ noctumbra-mail :7404\\nComunicaciones y notificaciones\"]\n    S5[\"🌊 temporaeth :7405\\nRazonamiento temporal\"]\n    S6[\"🏛️ vaeloryn-conclave :7406\\nConsejo y deliberación\"]\n    S7[\"🔥 ignivox :7407\\nConstructor e ingeniero\"]\n    S8[\"🎵 auralith :7408\\nAudio y habla\"]\n    S9[\"🔊 resonvyr :7409\\nLenguaje y retórica\"]\n    S10[\"⚡ fluxenrath :7410\\nWeb y recuperación\"]\n  end\n\n  subgraph Modelos[\"🤖 Capa de Modelos\"]\n    KILO[\"KiloCode AI Gateway\\nClaude · Gemini · MiniMax · y más\\n(api.kilo.ai)\"]\n  end\n\n  subgraph Persistencia[\"💾 Capa de Persistencia\"]\n    RED[(\"Redis\\nCache · Sesiones\")]\n    CHR[(\"ChromaDB\\nVector Store\")]\n  end\n\n  OP --\u003e DASH\n  CADDY --\u003e DASH\n  CADDY --\u003e GW\n  DASH --\u003e|\"REST / WebSocket / SSE\"| GW\n  GW --\u003e AUTH\n  GW --\u003e SSE\n  GW --\u003e DB\n  GW --\u003e EV\n  GW --\u003e RED\n  GW --\u003e CHR\n  GW --\u003e|\"dispatch con política\"| S1 \u0026 S2 \u0026 S3 \u0026 S4 \u0026 S5 \u0026 S6 \u0026 S7 \u0026 S8 \u0026 S9 \u0026 S10\n  S1 \u0026 S2 \u0026 S3 \u0026 S4 \u0026 S5 \u0026 S6 \u0026 S7 \u0026 S8 \u0026 S9 \u0026 S10 --\u003e KILO\n  S1 \u0026 S2 \u0026 S3 \u0026 S4 \u0026 S5 \u0026 S6 \u0026 S7 \u0026 S8 \u0026 S9 \u0026 S10 --\u003e RED\n  S1 \u0026 S2 \u0026 S3 \u0026 S4 \u0026 S5 \u0026 S6 \u0026 S7 \u0026 S8 \u0026 S9 \u0026 S10 --\u003e CHR\n```\n\n### Flujo de una tarea orquestada\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor U as Operador\n  participant UI as Agent Node Studio\n  participant GW as Gateway\n  participant SY as synapsara (orquestador)\n  participant AG as Agentes del Círculo\n  participant KL as KiloCode AI Gateway\n  participant MEM as Memoria Jerárquica\n\n  U-\u003e\u003eUI: Define tarea en el canvas visual\n  UI-\u003e\u003eGW: POST /api/v1/tasks {workflow_graph}\n  GW-\u003e\u003eGW: Valida RBAC + API key + límites\n  GW-\u003e\u003eSY: Despacha grafo de trabajo\n  SY-\u003e\u003eMEM: Consulta contexto histórico relevante\n  MEM--\u003e\u003eSY: Devuelve memoria semántica + resúmenes\n  SY-\u003e\u003eAG: Distribuye sub-tareas en paralelo\n  loop Ejecución del Círculo Alquímico\n    AG-\u003e\u003eKL: Solicita inferencia vía KiloCode AI\n    KL--\u003e\u003eAG: Respuesta del modelo\n    AG-\u003e\u003eMEM: Actualiza memoria episódica\n    AG--\u003e\u003eSY: Entrega resultado parcial vía SSE\n    SY--\u003e\u003eUI: Stream de progreso en tiempo real\n  end\n  SY-\u003e\u003eSY: Consolida y valida resultados\n  SY--\u003e\u003eGW: Resultado final\n  GW--\u003e\u003eUI: Respuesta enriquecida con metadata\n  UI--\u003e\u003eU: Visualización del resultado\n```\n\n### Funcionamiento del agente de proyecto\n\n```mermaid\nflowchart LR\n  I[\"Petición del operador\"] --\u003e A[\"Auth + política gateway\"]\n  A --\u003e B[\"Lookup en registry de agentes\"]\n  B --\u003e C[\"Resolución target_service\"]\n  C --\u003e D[\"Ejecución del servicio\"]\n  D --\u003e E[\"Persistencia: resultado + uso + evento + chat\"]\n  E --\u003e F[\"Actualización SSE en dashboard\"]\n```\n\n### Topología de puertos\n\n| Puerto | Servicio | Capa |\n|---|---|---|\n| `:80` / `:443` | Caddy (reverse proxy) | Borde |\n| `:3000` | Dashboard Next.js | Control Plane |\n| `:8000` | Gateway FastAPI | Núcleo |\n| `:8001` | ChromaDB UI | Persistencia |\n| `:7401` | velktharion | Ejecución |\n| `:7402` | synapsara | Ejecución |\n| `:7403` | kryonexus | Ejecución |\n| `:7404` | noctumbra-mail | Ejecución |\n| `:7405` | temporaeth | Ejecución |\n| `:7406` | vaeloryn-conclave | Ejecución |\n| `:7407` | ignivox | Ejecución |\n| `:7408` | auralith | Ejecución |\n| `:7409` | resonvyr | Ejecución |\n| `:7410` | fluxenrath | Ejecución |\n\n---\n\n## ✨ Matriz de Capacidades\n\n\u003cdiv align=\"center\"\u003e\n\n| Capacidad | Descripción | Estado |\n|---|---|:---:|\n| **Agent Node Studio** | Constructor visual de flujos con nodos arrastrables y etiquetas de skills/tools | ✅ |\n| **Orquestación LangGraph** | Grafos de agentes con estado persistente entre ejecuciones | ✅ |\n| **Círculos Alquímicos** | Equipos de agentes auto-formados con roles dinámicos | ✅ |\n| **Chat directo** | Hilo compartido, ask directo, metadatos thinking/repo/auto-edit | ✅ |\n| **Roundtable multi-agente** | Varios agentes deliberan sobre una misma tarea | ✅ |\n| **Control de agentes** | Start/stop/restart, ping dispatch, estado runtime en tiempo real | ✅ |\n| **Memoria jerárquica** | Redis (instante) + ChromaDB (semántica) + agentes resumen | ✅ |\n| **LLMs vía KiloCode AI** | Claude, Gemini, MiniMax, y más modelos compatibles (tier gratuito disponible) | ✅ |\n| **Visión multi-modal** | Análisis de imágenes vía KiloCode (claude-3-haiku vision, gemini-flash) | ✅ |\n| **Transcripción de audio** | Modelos de audio vía KiloCode (whisper y equivalentes disponibles) | ✅ |\n| **RBAC + API Keys** | Control de acceso por roles y claves programáticas | ✅ |\n| **SSE observabilidad** | Stream en tiempo real de chat, eventos, usage y logs | ✅ |\n| **OpenTelemetry** | Trazas distribuidas, métricas y logs unificados | ✅ |\n| **Conector Telegram** | Pipeline inbound/outbound, agentes accesibles desde Telegram | ✅ |\n| **Conector Discord** | Pipeline inbound/outbound, integración nativa con Discord | ✅ |\n| **pgvector** | Búsqueda semántica sobre PostgreSQL sin servicios externos | ✅ |\n| **Sistema de plugins** | Extiende cualquier servicio con capacidades propias | ✅ |\n| **Higiene GitHub project** | Ritual integrado de sincronización y snapshots automáticos | ✅ |\n| **Datos 100% locales** | PostgreSQL, Redis, ChromaDB — todos en tu infraestructura | ✅ |\n| **Tier gratuito de IA** | Modelos gratuitos disponibles vía KiloCode (minimax/minimax-m2.5:free, etc.) | ✅ |\n\n\u003c/div\u003e\n\n---\n\n## 🧠 El Modelo de Agentes\n\nEl dashboard carga **agentes lógicos reales desde el gateway** — no skills estáticas ni mocks. Cada agente es una entidad con ciclo de vida completo y presencia runtime.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    CICLO VITAL DEL AGENTE                   │\n│                                                             │\n│   [Invocación]                                              │\n│        │                                                    │\n│        ▼                                                    │\n│   [Percepción] ←── texto · imagen · audio · datos           │\n│        │                                                    │\n│        ▼                                                    │\n│   [Recuperación de Memoria] ←── Redis + ChromaDB + resúmen  │\n│        │                                                    │\n│        ▼                                                    │\n│   [Razonamiento] ←── KiloCode AI Gateway                    │\n│        │                                                    │\n│        ▼                                                    │\n│   [Planificación de Acciones]                               │\n│        │                                                    │\n│        ├──► Delegar a sub-agente                            │\n│        ├──► Invocar herramienta / plugin                    │\n│        ├──► Escribir en memoria                             │\n│        └──► Emitir resultado vía SSE                        │\n│                                                             │\n│   [Actualización de Estado] ──► Persistido en PostgreSQL    │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Anatomía de un agente\n\nCada agente en el registry expone:\n\n| Campo | Descripción |\n|---|---|\n| `name` | Nombre único dentro del ecosistema |\n| `role` | Arquetipo funcional (orquestador, ejecutor, sensor, etc.) |\n| `model` | Modelo KiloCode AI asignado (puede diferir por agente) |\n| `target_service` | Servicio de ejecución que lo aloja (`synapsara`, `fluxenrath`…) |\n| `skills[]` | Lista de habilidades declaradas |\n| `tools[]` | Herramientas y plugins disponibles |\n| `runtime_state` | Estado actual: idle / running / error |\n| `latency_ms` | Latencia media de las últimas N invocaciones |\n\n### Definición de un agente (YAML)\n\n```yaml\n# agents/analista-mercado.yaml\nname: \"Analista de Mercado\"\nversion: \"1.0\"\nrole: executor\ntarget_service: fluxenrath\n\nmodel:\n  provider: kilo\n  name: anthropic/claude-sonnet-4.5\n  temperature: 0.3\n  context_window: 8192\n\nmemory:\n  short_term: redis          # Conversación activa\n  long_term: chromadb        # Conocimiento semántico\n  episodic: postgresql       # Historial de ejecuciones\n\ntools:\n  - web_search\n  - file_reader\n  - data_analyzer\n\nskills:\n  - análisis financiero\n  - síntesis de informes\n  - detección de tendencias\n\nsystem_prompt: |\n  Eres un analista financiero especializado en mercados emergentes.\n  Siempre citas tus fuentes. Expresas la incertidumbre cuando existe.\n  Hablas en español formal a menos que se te indique lo contrario.\n\ncircle_role: executor\nmax_concurrent_tasks: 3\n```\n\n---\n\n## 🔮 Círculos Alquímicos\n\nLos **Círculos Alquímicos** son la innovación central del ecosistema. Mientras que los sistemas tradicionales asignan tareas a agentes individuales en secuencia, los Círculos permiten que **grupos de agentes se auto-organicen** en torno a un objetivo complejo, trabajando en paralelo con roles dinámicos.\n\nEl nombre evoca los círculos de la alquimia medieval — estructuras donde cada posición tiene un papel preciso y el conjunto es inmensamente más poderoso que la suma de sus partes.\n\n### Anatomía de un Círculo\n\n```\n        ╔════════════════════════════════════╗\n        ║     CÍRCULO ALQUÍMICO ACTIVO       ║\n        ║                                   ║\n        ║  ┌─────────────────────────────┐  ║\n        ║  │    Maestro Orquestador      │  ║  ← synapsara define el plan\n        ║  │  (synapsara + Claude)       │  ║\n        ║  └─────────────┬───────────────┘  ║\n        ║                │                  ║\n        ║    ┌───────────┼──────────┐       ║\n        ║    ▼           ▼          ▼       ║\n        ║ [Recolector][Analista][Redactor]  ║  ← agentes especializados\n        ║    │           │          │       ║\n        ║    └───────────┴──────────┘       ║\n        ║                │                  ║\n        ║  ┌─────────────▼───────────────┐  ║\n        ║  │     Agente de Memoria       │  ║  ← consolida y archiva\n        ║  │  (kryonexus + ChromaDB)     │  ║\n        ║  └─────────────────────────────┘  ║\n        ╚════════════════════════════════════╝\n```\n\n### Ciclo de vida de un Círculo\n\n```\nCONVOCACIÓN → DISTRIBUCIÓN → TRABAJO EN PARALELO → CONSOLIDACIÓN → DISOLUCIÓN\n     │               │                │                   │              │\n  synapsara      Asigna roles     Cada agente         synapsara      Estado final\n  recibe el      dinámicos        ejecuta en          une todos      guardado en\n  objetivo       según la tarea   su servicio         los hilos      PostgreSQL\n```\n\n### Invocar un Círculo por API\n\n```python\nimport httpx\n\nasync def invocar_circulo():\n    async with httpx.AsyncClient() as client:\n        respuesta = await client.post(\n            \"http://localhost/gateway/api/v1/circles\",\n            headers={\"X-API-Key\": \"tu-clave-aqui\"},\n            json={\n                \"nombre\": \"Investigación de Competencia\",\n                \"objetivo\": \"\"\"\n                    Analiza los últimos 3 meses de actividad pública\n                    de nuestros 5 competidores principales y produce\n                    un informe ejecutivo con hallazgos y recomendaciones.\n                \"\"\",\n                \"agentes\": {\n                    \"orquestador\": \"synapsara\",\n                    \"ejecutores\": [\"fluxenrath\", \"resonvyr\"],\n                    \"memoria\": \"kryonexus\",\n                    \"comunicacion\": \"noctumbra-mail\"\n                },\n                \"config\": {\n                    \"modelo_base\": \"anthropic/claude-sonnet-4.5\",\n                    \"max_iteraciones\": 10,\n                    \"tiempo_limite_seg\": 300\n                }\n            }\n        )\n        return respuesta.json()\n```\n\n---\n\n## 💾 Arquitectura de Memoria\n\nLa memoria es lo que separa un agente que *procesa* de un agente que *aprende*. El ecosistema implementa tres capas complementarias que trabajan en concierto:\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                     PIRÁMIDE DE MEMORIA                      │\n│                                                              │\n│    ▲ ABSTRACTO / DURADERO                                    │\n│    │                                                         │\n│    │  ┌────────────────────────────────────────────┐        │\n│    │  │          RESÚMENES NARRATIVOS               │  PG    │\n│    │  │  Agentes especializados sintetizan           │        │\n│    │  │  semanas de trabajo en narrativas            │        │\n│    │  │  estructuradas y recuperables por contexto   │        │\n│    │  └────────────────────────────────────────────┘        │\n│    │                                                         │\n│    │  ┌────────────────────────────────────────────┐        │\n│    │  │          MEMORIA SEMÁNTICA                  │ Chroma │\n│    │  │  Embeddings vectoriales de documentos,       │        │\n│    │  │  conversaciones y resultados pasados.        │        │\n│    │  │  Búsqueda por similitud semántica (pgvector) │        │\n│    │  └────────────────────────────────────────────┘        │\n│    │                                                         │\n│    │  ┌────────────────────────────────────────────┐        │\n│    │  │          MEMORIA DE TRABAJO                 │ Redis  │\n│    │  │  Contexto de la sesión activa, estado del   │        │\n│    │  │  agente, caché de prompts, cola inmediata    │        │\n│    │  └────────────────────────────────────────────┘        │\n│    │                                                         │\n│    ▼ CONCRETO / EFÍMERO                                      │\n└──────────────────────────────────────────────────────────────┘\n```\n\n### Búsqueda semántica con pgvector\n\n```sql\n-- Encuentra los 5 documentos más similares a una consulta\nSELECT\n    d.id,\n    d.titulo,\n    d.contenido,\n    1 - (d.embedding \u003c=\u003e $1) AS similitud\nFROM documentos d\nWHERE d.agente_id = $2\n  AND d.fecha_creacion \u003e NOW() - INTERVAL '30 days'\nORDER BY d.embedding \u003c=\u003e $1\nLIMIT 5;\n```\n\nEl gateway abstrae las tres capas en una sola interfaz: los agentes preguntan por contexto y la capa correcta responde, sin que el agente necesite saber de dónde viene la información.\n\n---\n\n## 🧩 Sistema de Plugins\n\nCada servicio puede extenderse mediante plugins. Un plugin es una unidad autocontenida que le da a un agente una nueva **capacidad** sin modificar el código del núcleo.\n\n### Estructura de un plugin\n\n```\nplugins/\n└── mi-empresa/\n    └── mi-plugin/\n        ├── plugin.yaml          # Manifiesto y metadatos\n        ├── handler.py           # Lógica de ejecución\n        ├── schema.json          # Esquema de entrada/salida\n        ├── requirements.txt     # Dependencias propias\n        └── README.md\n```\n\n### Manifiesto del plugin (`plugin.yaml`)\n\n```yaml\nname: analizador-financiero\nvendor: mi-empresa\nversion: \"1.0.0\"\ndescription: \"Análisis de métricas financieras sobre datos locales\"\n\ncompatible_services:\n  - fluxenrath\n  - synapsara\n\ninputs:\n  ticker:\n    type: string\n    required: true\n  periodo:\n    type: string\n    enum: [\"1d\", \"1w\", \"1m\", \"1y\"]\n    default: \"1d\"\n\noutputs:\n  precio: float\n  volumen: integer\n  resumen: string\n```\n\n### Instalar y activar un plugin\n\n```bash\n# Instala el plugin en el servicio objetivo\n./scripts/alchemical plugin install ./plugins/mi-empresa/mi-plugin --service fluxenrath\n\n# Verifica que está activo\n./scripts/alchemical plugin list --service fluxenrath\n```\n\n### Plugins oficiales incluidos\n\n| Plugin | Función |\n|---|---|\n| `core/web-search` | Búsqueda web local (SearXNG) |\n| `core/file-reader` | Lee y procesa archivos del sistema |\n| `core/code-executor` | Ejecuta código Python en sandbox |\n| `core/data-analyzer` | Análisis estadístico y visualización |\n\n---\n\n## 📡 Conectores\n\nLos conectores llevan el ecosistema hacia donde tus usuarios ya están, sin exponer el gateway directamente al exterior.\n\n### Telegram\n\n```bash\n# Activa el conector en docker-compose\ndocker compose --profile telegram up -d telegram-connector\n```\n\n```python\n# connectors/telegram/config.py\nTELEGRAM_CONFIG = {\n    \"bot_token\": os.getenv(\"TELEGRAM_BOT_TOKEN\"),\n    \"allowed_users\": [123456789],          # IDs de Telegram autorizados\n    \"default_agent\": \"synapsara\",\n    \"streaming\": True,                     # Muestra el razonamiento del agente\n    \"commands\": {\n        \"/analiza\": \"circle:analisis\",\n        \"/redacta\": \"agent:redactor\",\n    }\n}\n```\n\n### Discord\n\n```bash\n# Activa el conector\ndocker compose --profile discord up -d discord-connector\n```\n\n```python\n# connectors/discord/config.py\nDISCORD_CONFIG = {\n    \"token\": os.getenv(\"DISCORD_BOT_TOKEN\"),\n    \"channels\": {\n        \"agentes-ia\":  \"agent:synapsara\",\n        \"análisis\":    \"circle:analisis-financiero\",\n    },\n    # Los roles de Discord se mapean al RBAC interno\n    \"role_mapping\": {\n        \"Administrador\": \"admin\",\n        \"Analista\":      \"power_user\",\n        \"@everyone\":     \"viewer\"\n    }\n}\n```\n\n### API REST directa\n\n```bash\n# Ejecutar un agente\ncurl -X POST http://localhost/gateway/api/v1/agents/synapsara/run \\\n  -H \"X-API-Key: tu-clave\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"input\": \"Resume las noticias tecnológicas de esta semana\"}'\n\n# Convocar un Círculo Alquímico\ncurl -X POST http://localhost/gateway/api/v1/circles \\\n  -H \"X-API-Key: tu-clave\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"objetivo\": \"...\", \"agentes\": {...}}'\n\n# Suscribirse al stream SSE de una tarea\ncurl -N http://localhost/gateway/api/v1/tasks/abc123/stream \\\n  -H \"X-API-Key: tu-clave\"\n```\n\nEl ecosistema soporta futuros adaptadores de canal mediante una arquitectura de conectores normalizada — el inbound/outbound de cada red social se implementa como un adapter independiente.\n\n---\n\n## 📊 Tabla Comparativa\n\n¿Por qué forjar tu propia inteligencia cuando podrías simplemente comprarla? Porque lo que se compra puede retirarse, encarecerse, censurarse o vigilarse.\n\n\u003cdiv align=\"center\"\u003e\n\n| Característica | **Magnum Opus** | Plataforma Cloud Típica | Demo Chat-Only |\n|---|:---:|:---:|:---:|\n| Costo mensual | **$0 (tier gratuito)** | $50–$500+ | $0 (limitado) |\n| Modelos de IA | ✅ KiloCode AI (Claude, Gemini, MiniMax) | ❌ Solo los suyos | ⚠️ Parcial |\n| Los datos salen de tu red | **Nunca** | Siempre | Depende |\n| Memoria jerárquica | ✅ 3 capas | ⚠️ Básica | ❌ |\n| Círculos multi-agente | ✅ Auto-formados | ⚠️ Manual | ❌ |\n| Constructor visual | ✅ Node Studio | ✅ | ❌ |\n| Roundtable multi-agente | ✅ | ⚠️ | ❌ |\n| Datos 100% locales | ✅ PostgreSQL/Redis/ChromaDB local | ❌ | ⚠️ |\n| Multi-modal (visión + audio) | ✅ vía KiloCode | ✅ (de pago) | ❌ |\n| SSE tiempo real | ✅ Streams endurecidos | ⚠️ Básica | ❌ |\n| Higiene operativa integrada | ✅ | ❌ | ❌ |\n| RBAC granular | ✅ | ✅ | ⚠️ |\n| Frontera de política (gateway) | ✅ Dedicada | ⚠️ UI mezclada | ❌ |\n| Soberanía de datos | ✅ **Total** | ❌ | ⚠️ |\n\n\u003c/div\u003e\n\n---\n\n## 📁 Estructura del Repositorio\n\n```\nalchemical-agent-ecosystem/\n│\n├── 📂 .github/                      # Workflows CI/CD y project automation\n│   ├── workflows/\n│   │   ├── ci.yml                   # Pipeline de integración continua\n│   │   ├── release.yml              # Gestión de releases\n│   │   └── sync-project-status.yml  # Sincronización del estado del proyecto\n│   └── ISSUE_TEMPLATE/\n│\n├── 📂 apps/\n│   └── alchemical-dashboard/        # Agent Node Studio (Next.js 15 · React 19)\n│       ├── app/                     # App Router\n│       │   ├── (auth)/              # Rutas de autenticación\n│       │   ├── studio/              # Constructor visual de agentes\n│       │   ├── circles/             # Gestión de Círculos Alquímicos\n│       │   ├── memory/              # Inspector de memoria\n│       │   └── observability/       # Dashboard de métricas y trazas\n│       ├── components/\n│       │   ├── node-editor/         # Canvas de nodos (drag \u0026 drop)\n│       │   ├── agent-cards/         # Tarjetas de estado runtime\n│       │   └── sse-feed/            # Componentes de stream en tiempo real\n│       └── lib/\n│           ├── api-client.ts        # Cliente tipado para el gateway\n│           └── sse-hooks.ts         # Hooks React para SSE\n│\n├── 📂 gateway/                      # Gateway FastAPI (auth · routing · policy)\n│   ├── routers/\n│   │   ├── agents.py                # Endpoints de agentes\n│   │   ├── circles.py               # Endpoints de Círculos\n│   │   ├── memory.py                # API de memoria unificada\n│   │   ├── chat.py                  # Endpoints de chat y roundtable\n│   │   └── observability.py         # Métricas, trazas y usage\n│   ├── services/\n│   │   ├── orchestrator.py          # Motor LangGraph\n│   │   ├── memory_broker.py         # Abstracción de las tres capas\n│   │   └── auth.py                  # RBAC y API keys\n│   ├── models/                      # Modelos SQLAlchemy + Pydantic\n│   └── main.py                      # Punto de entrada FastAPI\n│\n├── 📂 services/                     # Los Diez Círculos\n│   ├── velktharion/   # :7401 — Orquestador y director\n│   ├── synapsara/     # :7402 — Meta-razonamiento y coordinación\n│   ├── kryonexus/     # :7403 — Datos y análisis\n│   ├── noctumbra-mail/ # :7404 — Email y notificaciones\n│   ├── temporaeth/    # :7405 — Razonamiento temporal\n│   ├── vaeloryn-conclave/ # :7406 — Consejo y deliberación\n│   ├── ignivox/       # :7407 — Constructor e ingeniero\n│   ├── auralith/      # :7408 — Audio y habla\n│   ├── resonvyr/      # :7409 — Lenguaje y retórica\n│   └── fluxenrath/    # :7410 — Web y recuperación\n│\n├── 📂 connectors/                   # Integraciones externas\n│   ├── telegram/                    # Pipeline inbound/outbound Telegram\n│   └── discord/                     # Pipeline inbound/outbound Discord\n│\n├── 📂 infra/\n│   ├── caddy/                       # Reverse proxy (caddy.json / Caddyfile)\n│   └── scripts/                     # Implementación del instalador\n│\n├── 📂 ops/                          # Scripts de operación y higiene\n│   ├── project-tidy.sh              # Limpieza y ordenamiento del proyecto\n│   ├── ritual-sync.sh               # Sincronización con GitHub Project\n│   └── snapshots/                   # Snapshots automáticos del estado\n│\n├── 📂 docs/                         # El Grimorio (documentación técnica)\n│   ├── README.md                    # Índice de documentación\n│   ├── INSTALLATION.md              # Instalación y arranque detallado\n│   ├── CLI_REFERENCE.md             # Catálogo completo de comandos\n│   ├── ARCHITECTURE.md              # Arquitectura extendida y ADRs\n│   ├── API_REFERENCE.md             # Referencia de endpoints\n│   ├── OPERATIONS_RUNBOOK.md        # Operación day-2\n│   └── PROJECT_STATUS.md            # Snapshot autosincronizado\n│\n├── 📂 scripts/                      # CLI helpers\n│   └── alchemical                   # Comando principal del ecosistema\n│\n├── 📂 assets/                       # Branding y recursos visuales\n│   └── branding/variants/\n│       └── logo-horizontal.svg\n│\n├── 📂 tests/                        # Suite de pruebas\n│   ├── unit/\n│   ├── integration/\n│   └── e2e/\n│\n├── 📂 workspace/                    # Espacio de trabajo de agentes (runtime)\n│\n├── docker-compose.yml               # Orquestación completa del ecosistema\n├── install.sh                       # Asistente de instalación interactivo\n├── .env.example                     # Variables de entorno documentadas\n└── README.es.md                     # Este grimorio\n```\n\n---\n\n## 📚 El Grimorio (Documentación)\n\nLa documentación completa vive en `/docs` y está organizada como un grimorio técnico: por tema y profundidad creciente.\n\n| Sección | Ruta | Contenido |\n|---|---|---|\n| **Índice** | `docs/README.md` | Mapa completo de la documentación |\n| **Instalación** | `docs/INSTALLATION.md` | Instalación, configuración y primer arranque |\n| **Referencia CLI** | `docs/CLI_REFERENCE.md` | Catálogo completo de comandos `alchemical` |\n| **Arquitectura** | `docs/ARCHITECTURE.md` | Arquitectura extendida y decisiones de diseño |\n| **API Reference** | `docs/API_REFERENCE.md` | Referencia completa de endpoints |\n| **Operaciones** | `docs/OPERATIONS_RUNBOOK.md` | Runbook para operación day-2 |\n| **Estado del proyecto** | `docs/PROJECT_STATUS.md` | Snapshot autosincronizado con GitHub |\n\n```bash\n# Accede a la documentación vía API (si tienes mkdocs activo)\ndocker compose --profile docs up -d\n# → http://localhost:8080\n```\n\n---\n\n## 🔄 El Ritual Diario (Operaciones)\n\n### Comandos esenciales\n\n```bash\n# ── Ciclo de vida del ecosistema ──────────────────────────────\n./scripts/alchemical up-fast       # Levanta todo en modo rápido\n./scripts/alchemical up            # Levanta con health checks completos\n./scripts/alchemical down          # Detiene preservando los datos\n./scripts/alchemical restart       # Reinicia sin perder estado\n./scripts/alchemical update-safe   # Actualización sin downtime\n\n# ── Estado y salud ────────────────────────────────────────────\n./scripts/alchemical status        # Estado de todos los contenedores\n./scripts/alchemical health        # Chequeo de salud profundo con detalle\n./scripts/alchemical logs          # Logs de todos los servicios\n./scripts/alchemical logs synapsara  # Logs de un servicio específico\n\n# ── Agentes y círculos ────────────────────────────────────────\n./scripts/alchemical agent list    # Lista todos los agentes registrados\n./scripts/alchemical circle list   # Lista los círculos activos\n./scripts/alchemical circle stop abc123  # Detiene un círculo por ID\n\n# ── Memoria ───────────────────────────────────────────────────\n./scripts/alchemical memory stats  # Estadísticas de uso de cada capa\n./scripts/alchemical memory backup # Exporta snapshot completo de memoria\n\n# ── Modelos ───────────────────────────────────────────────────\n./scripts/alchemical models list   # Lista modelos disponibles en KiloCode\n./scripts/alchemical models pull anthropic/claude-sonnet-4.5  # Configura un modelo\n\n# ── Higiene del proyecto ──────────────────────────────────────\n./ops/project-tidy.sh              # Limpieza y ordenamiento\n./ops/ritual-sync.sh               # Sincroniza estado con GitHub Project\n```\n\n### Actualización segura\n\n```bash\n# En producción — actualización progresiva sin downtime\ngit pull --rebase origin main\n./scripts/alchemical update-safe\n\n# O paso a paso si necesitas control total\ngit pull --rebase origin main\ndocker compose pull\ndocker compose up -d --no-deps --build gateway\n# Repite para cada servicio en el orden deseado\n```\n\n### Respaldo y restauración\n\n```bash\n# Respalda base de datos, vectores y configuración\n./scripts/alchemical backup\n# → backups/magnum-opus-20260227-1430.tar.gz\n\n# Restaura desde un backup\n./scripts/alchemical restore FILE=backups/magnum-opus-20260227-1430.tar.gz\n```\n\n### Monitoreo con OpenTelemetry\n\n```bash\n# Activa el stack de observabilidad\ndocker compose --profile observability up -d\n\n# Accesos:\n# Jaeger (trazas):   http://localhost:16686\n# Prometheus:        http://localhost:9090\n# Grafana:           http://localhost:3001\n```\n\n---\n\n## 🏆 ¿Por Qué Magnum Opus?\n\nEn la tradición alquímica, el **Magnum Opus** — la Gran Obra — era el proceso de perfeccionamiento máximo. No era un producto terminado, sino un camino: un compromiso con la excelencia continua, con la transmutación de lo ordinario en extraordinario.\n\nEsta versión lleva ese nombre porque representa un punto de inflexión genuino.\n\n**Antes de esta versión,** el ecosistema era una colección de servicios potentes pero desconectados. Los agentes operaban en silos. La memoria se evaporaba entre sesiones. La observabilidad era superficial. El onboarding exigía conocimiento profundo de toda la arquitectura.\n\n**Con Magnum Opus:**\n\n- Los **Círculos Alquímicos** hacen posible la colaboración genuinamente emergente entre agentes — no scripted, sino adaptativa, con roles que nacen del objetivo.\n- La **memoria jerárquica** da continuidad real: un agente recuerda lo que aprendió hace semanas y lo aplica hoy sin que le recuerdes nada.\n- El **Agent Node Studio** democratiza la creación de flujos complejos sin necesidad de escribir código — el pensamiento se diseña visualmente.\n- Los **streams SSE endurecidos** convierten la observabilidad en algo tangible: ves pensar al agente, en tiempo real.\n- La **arquitectura de diez servicios** refleja una separación de responsabilidades diseñada para crecer sin acoplamiento ni fragilidad.\n\nY sobre todo: sigue siendo **tuyo**. Cero dependencia de APIs externas para tus datos. Cero telemetría hacia terceros. Cero sorpresas en la factura al final del mes. La inferencia de IA corre a través de [KiloCode AI Gateway](https://kilo.ai) — con tier gratuito disponible — mientras que todos tus datos viven en tu base de datos local, el conocimiento que construyes permanece contigo para siempre.\n\n\u003e *\"El alquimista no busca el oro del mercado. Busca el oro de la comprensión.\"*\n\nLa próxima transmutación ya está en proceso. Consulta el [ROADMAP.md](ROADMAP.md) para ver adónde va la Gran Obra.\n\n---\n\n## 🤝 Contribuir\n\nEl ecosistema crece con cada alquimista que aporta su conocimiento:\n\n1. Lee [CONTRIBUTING.md](CONTRIBUTING.md) — el código de honor del taller.\n2. Abre un Issue antes de trabajar en cambios grandes — la Gran Obra se coordina.\n3. Sigue los estándares del proyecto: `ruff` (Python), `biome` (TypeScript), tests obligatorios.\n4. Cada PR necesita descripción clara, pruebas, y el pipeline CI en verde.\n\n---\n\n## 📄 Licencia\n\nDistribuido bajo la **Licencia MIT**. Consulta [`LICENSE`](LICENSE) para los términos completos.\n\nLa sabiduría es libre. Úsala bien.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n---\n\n### ⚗️ *Solve et Coagula*\n\n**Alchemical Agent Ecosystem v2.0 — Magnum Opus**\n\n*Datos forjados en local. IA potenciada por KiloCode. Sin nubes ajenas para tus datos.*\n\n[![GitHub Stars](https://img.shields.io/github/stars/smouj/alchemical-agent-ecosystem?style=social)](https://github.com/smouj/alchemical-agent-ecosystem)\n[![Forks](https://img.shields.io/github/forks/smouj/alchemical-agent-ecosystem?style=social)](https://github.com/smouj/alchemical-agent-ecosystem/fork)\n[![Issues](https://img.shields.io/github/issues/smouj/alchemical-agent-ecosystem)](https://github.com/smouj/alchemical-agent-ecosystem/issues)\n\n---\n\n\u003csub\u003eHecho con ☿ · Mercurio, Azufre y Sal · en algún taller sin ventanas\u003c/sub\u003e\n\n\u003csub\u003e© 2026 Alchemical Agent Ecosystem — Licencia MIT — La sabiduría es libre\u003c/sub\u003e\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmouj%2Falchemical-agent-ecosystem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmouj%2Falchemical-agent-ecosystem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmouj%2Falchemical-agent-ecosystem/lists"}