overmind-mcp 2.8.21 → 2.8.22

package/docs/guide_agent_hermes_overmind.md

@@ -0,0 +1,403 @@
+# 🤖 Guide : Créer un Agent Hermes Permanent avec Overmind
+
+> **Pour les débutants** — De zéro à un agent autonome fonctionnel, step by step.
+
+---
+
+## 📖 Table des Matières
+
+1. [Concepts de Base](#-concepts-de-base)
+2. [Architecture 2 Couches](#-architecture-2-couches)
+3. [Hermes Gateway vs Overmind](#-hermes-gateway-vs-overmind)
+4. [Bridge SDK — Wrappers TypeScript](#-bridge-sdk--wrappers-typescript)
+5. [Architecture Dossier Agent](#-architecture-dossier-agent)
+6. [Les 4 Fichiers Cruciaux](#-les-4-fichiers-cruciaux)
+7. [Créer un Agent — Tutorial Complet](#-créer-un-agent--tutorial-complet)
+8. [Configuration Avancée](#-configuration-avancée)
+9. [Skills — Compétences Hermes](#-skills--compétences-hermes)
+10. [MCP Servers — Outils](#-mcp-servers--outils)
+11. [Mémoire — 3 Couches](#-mémoire--3-couches)
+12. [Cron — Agent vs Persistant](#-cron--agent-vs-persistant)
+13. [Workflow Type](#-workflow-type)
+14. [Troubleshooting](#-troubleshooting)
+
+---
+
+## 🧠 Concepts de Base
+
+### Qu'est-ce qu'un Agent Hermes ?
+
+Un **agent Hermes** est une instance isolée d'IA avec :
+- Son propre **system prompt** (SOUL.md)
+- Ses propres **clés API** (.env)
+- Ses propres **skills** (compétences)
+- Sa propre **mémoire locale** (state.db + MEMORY.md)
+- Sa propre **configuration** (modèle, MCP, TTS)
+
+### Qu'est-ce qu'Overmind ?
+
+**Overmind** est l'**encapsuleur** qui gère plusieurs agents :
+- **CRUD agents** (create, config, delete)
+- **Orchestration** (run_agent, run_agents_parallel)
+- **Mémoire locale/agent** (memory_store, memory_search — DB propre par agent)
+- **Mémoire partagée** (cross-agents, transmission inter-agents)
+- **Cron persistant** (survit aux redémarrages)
+- **Agent Control** (status, stream, kill, wait)
+- **Bridge SDK** (wrappers TypeScript)
+
+### Qu'est-ce que le Bridge ?
+
+Le **Bridge** (`bridge/`) est un SDK TypeScript qui wrappe les appels Overmind MCP. Il permet de piloter les agents depuis une app externe (Discord bot, API REST, CLI).
+
+---
+
+## 📐 Architecture 2 Couches
+
+```
+┌──────────────────────────────────────────────────┐
+│                  OVERMIND                         │
+│          L'Encapsuleur / Orchestrator             │
+│                                                   │
+│  CRUD agents • Orchestration • Mémoire partagée   │
+│  Mémoire locale/agent • Cron PERSISTANT • Bridge  │
+│                                                   │
+│  ┌────────────────────────────────────────────┐   │
+│  │           HERMES GATEWAY                    │   │
+│  │        Le Runtime Agent                     │   │
+│  │                                             │   │
+│  │  SOUL.md • Skills • TTS • MCP Client        │   │
+│  │  Mémoire locale • Sessions • Cron agent     │   │
+│  └────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────┘
+```
+
+**Point clé** : Overmind encapsule Hermes. Ce sont 2 couches distinctes.
+
+---
+
+## 🔀 Hermes Gateway vs Overmind
+
+| Fonctionnalité | Hermes Gateway | Overmind |
+|---|---|---|
+| **Persona (SOUL.md)** | ✅ Gère et exécute | — |
+| **Skills** | ✅ Charge et injecte | — |
+| **TTS** | ✅ Exécute la synthèse | — |
+| **MCP Client** | ✅ Se connecte aux serveurs | — |
+| **Mémoire fichiers plats** | ✅ MEMORY.md, USER.md, state.db | — |
+| **Mémoire locale DB** | — | ✅ memory_store/search (DB propre/agent) |
+| **Mémoire partagée** | — | ✅ Cross-agents, include_runs |
+| **Session** | ✅ SQLite par agent | — |
+| **Cron agent-level** | ✅ Session fraîche chaque tick | — |
+| **Terminal/Fichiers** | ✅ Outils d'exécution | — |
+| **Agent CRUD** | — | ✅ create, config, delete |
+| **Orchestration** | — | ✅ run_agent, run_agents_parallel |
+| **Cron PERSISTANT** | — | ✅ Survit aux redémarrages |
+| **Agent Control** | — | ✅ status, stream, kill, wait |
+| **Bridge SDK** | — | ✅ Wrappers TypeScript |
+| **Registre agents** | — | ✅ .overmind/hermes/ |
+
+---
+
+## 🔗 Bridge SDK — Wrappers TypeScript
+
+### Architecture en 3 Couches
+
+```
+App → OverBridgeService → BridgeProxy → Overmind MCP → Hermes Gateway
+```
+
+### Les 5 Fichiers
+
+| Fichier | Rôle | Lignes |
+|---|---|---|
+| `types.ts` | Contrats : `McpResponse`, `AgentResult`, `BridgeConfig`, `SessionState` | ~150 |
+| `utils.ts` | Logger, SSE parsing, retry, validation, formatage Discord | ~170 |
+| `BridgeProxy.ts` | Transport JSON-RPC 2.0 : circuit breaker, 3 couches timeout | ~285 |
+| `OverBridgeService.ts` | API Overmind : `runAgent()`, `memorySearch()`, `runParallel()` | ~284 |
+| `index.ts` | Barrel export | ~46 |
+
+### Ce que le Bridge Wrappe (Overmind uniquement)
+
+```typescript
+// Orchestration (Overmind → lance Hermes)
+bridge.runAgent('agent', 'hermes', 'prompt')
+bridge.runAgentForDiscord('agent', 'hermes', msg, ctx)
+bridge.runParallel([...agents])
+
+// Mémoire partagée (Overmind)
+bridge.memorySearch({ query: 'trading' })
+bridge.memoryStore({ text: 'Décision...', source: 'decision' })
+
+// Agent CRUD (Overmind)
+bridge.listAgents()
+bridge.createAgent('nom', 'hermes', 'prompt')
+
+// Agent Control (Overmind)
+bridge.agentControl({ agentName: 'x', action: 'status' })
+```
+
+### Circuit Breaker + Session Persistante
+
+- **Circuit Breaker** : Closed → Open (5 échecs) → Half-Open → Closed (3 succès)
+- **Session** : auto-persistée dans `SessionState`, `autoResume: true`
+
+---
+
+## 📁 Architecture Dossier Agent
+
+```
+.overmind/hermes/<agent_name>/
+│
+├── .hermes/                         ← HERMES GATEWAY (runtime agent)
+│   ├── SOUL.md                      ← Persona
+│   ├── config.yaml                  ← Modèle + MCP + TTS
+│   ├── .env                         ← Clés API
+│   ├── state.db                     ← Mémoire locale SQLite
+│   ├── skills/                      ← Compétences Hermes
+│   ├── sessions/                    ← Historique sessions
+│   ├── memories/                    ← MEMORY.md + USER.md
+│   ├── cron/                        ← Cron agent-level Hermes
+│   ├── logs/                        ← Logs
+│   └── audio_cache/                 ← TTS
+│
+└── (fichiers de travail)
+
+.overmind/agents/                    ← REGISTRE OVERMIND
+bridge/                             ← SDK OVERMIND (wrappers TypeScript)
+```
+
+---
+
+## 📄 Les 4 Fichiers Cruciaux (Hermes Gateway)
+
+### 1. `SOUL.md` — Le Cerveau
+System prompt. Définit personnalité, règles, comportements.
+
+### 2. `config.yaml` — Configuration Runtime
+Modèle, MCP servers, TTS. Géré par Hermes, configuré via Overmind.
+
+### 3. `.env` — Les Secrets
+Clés API. **JAMAIS de commit Git.**
+
+### 4. `state.db` — Mémoire SQLite
+Historique conversations, sessions, cache. **Géré automatiquement par Hermes.**
+
+---
+
+## 🚀 Créer un Agent — Tutorial
+
+### Via Overmind MCP
+
+```bash
+# 1. Créer (OVERMIND)
+create_agent(name: "mon_agent", runner: "hermes", prompt: "Tu es...")
+
+# 2. Configurer (OVERMIND)
+update_agent_config(name: "mon_agent", model: "glm-5.1",
+  mcpServers: ["memory-server", "discord-server"])
+
+# 3. Clés (OVERMIND)
+update_agent_config(name: "mon_agent", env: { "OPENAI_API_KEY": "sk-..." })
+
+# 4. Lancer (OVERMIND orchestre, HERMES exécute)
+run_agent(runner: "hermes", agentName: "mon_agent", prompt: "Analyse...")
+```
+
+### Via Bridge SDK
+
+```typescript
+import { OverBridgeService } from './bridge/index.js';
+const bridge = new OverBridgeService({ mcpUrl: 'http://localhost:3099/mcp' });
+
+const result = await bridge.runAgent('mon_agent', 'hermes', 'Mon prompt');
+const results = await bridge.runParallel([...]);
+```
+
+---
+
+## ⚙️ Configuration Avancée (Hermes Gateway)
+
+### Multi-Modèles
+```bash
+run_agent(runner: "hermes", agentName: "x", model: "claude-sonnet-4", prompt: "...")
+```
+
+### TTS
+```yaml
+tts:
+  provider: elevenlabs
+  voice: charlie
+  voice_id: IKne3meq5aSn9XLyUdCD
+  model: eleven_multilingual_v2
+```
+
+---
+
+## 🎯 Skills — Compétences Hermes
+
+Skills = fichiers `SKILL.md` chargés par Hermes Gateway.
+
+```
+skills/
+└── catégorie/
+    └── skill/
+        ├── SKILL.md
+        ├── references/
+        ├── scripts/
+        └── templates/
+```
+
+~100+ built-in : `autonomous-ai-agents`, `creative`, `github`, `research`, `devops`...
+
+```bash
+skill_manage(action: "create", name: "mon-skill", content: "...")
+```
+
+---
+
+## 🔌 MCP Servers — Outils des Agents
+
+| Serveur | Port | Fonction |
+|---|---|---|
+| `memory-server` | 3099 | Mémoire locale/agent + partagée Overmind + CRUD agents |
+| `discord-server` | 3141 | Messages, embeds, fichiers Discord |
+| `x-mcp-server` | 3142 | Scraping Twitter/X |
+| `postgresql-server` | 5433 | SQL + Vector search |
+
+---
+
+## 🧠 Mémoire — 3 Couches
+
+### 1. Mémoire Hermes Gateway (fichiers plats, par agent)
+
+Injectée dans le prompt à chaque tour. Gérée par l'agent lui-même via `memory()`.
+
+```bash
+memory(action: "add", target: "memory", content: "Préfère réponses courtes")
+memory(action: "replace", target: "user", old_text: "old", content: "new")
+```
+
+| Fichier | Rôle | Portée |
+|---|---|---|
+| `MEMORY.md` | Notes personnelles de l'agent | 1 agent |
+| `USER.md` | Profil et préférences utilisateur | 1 agent |
+| `state.db` | SQLite (sessions, cache) | 1 agent |
+
+### 2. Mémoire Overmind Locale (DB propre par agent)
+
+**Chaque agent a sa PROPRE base de données Overmind** — isolation complète.
+Les `memory_store` et `memory_search` sont **locale à l'agent** par défaut.
+
+```bash
+# Stockage dans la DB locale de l'agent
+memory_store(text: "Décision : BlockChat v0.2", source: "decision")
+memory_search(query: "BlockChat protocol")
+```
+
+- Chaque agent = sa propre DB vectorielle
+- Recherche sémantique dans les connaissances de l'agent
+- Types : `user`, `agent`, `pattern`, `error`, `decision`
+
+### 3. Mémoire Overmind Partagée (cross-agents)
+
+En plus de sa DB locale, un agent peut accéder à une mémoire **commune** partagée entre tous les agents.
+
+```bash
+# Accès mémoire partagée (cross-agents)
+memory_search(query: "trading strategy", include_runs: true)
+```
+
+- Partagée entre tous les agents de la flotte
+- Inclut l'historique des runs (`include_runs: true`)
+- Permet la transmission de connaissances inter-agents
+
+---
+
+## ⏰ Cron — Agent vs Persistant
+
+### Cron Hermes Gateway (agent-level)
+- Session **fraîche** à chaque tick
+- Même profil, même MCP, pas de contamination
+- Lié au cycle de vie de l'agent
+- Config via `cronjob()` dans l'agent
+
+### Cron Overmind (PERSISTANT)
+- Géré au niveau de l'**encapsuleur**
+- **Survit aux redémarrages** de l'agent ET du gateway
+- Stocké dans le registre Overmind
+- Indépendant du cycle de vie Hermes
+
+```bash
+# Cron Hermes (agent-level)
+cronjob(action: "create", name: "analyse", schedule: "0 9 * * *",
+  prompt: "Analyse crypto...")
+
+# Cron Overmind (persistant)
+# → Configuré via Bridge SDK ou API Overmind
+# → Survit aux redémarrages
+```
+
+---
+
+## 🔄 Workflow Type
+
+### Mono-Agent
+```
+create_agent (OVERMIND) → config (OVERMIND) → run_agent (OVERMIND → HERMES)
+```
+
+### Multi-Agents
+```
+Orchestrateur (OVERMIND)
+  ├─► run_agents_parallel([agent1, agent2, agent3])
+  └─► Consolidate → Discord
+```
+
+### Via Bridge
+```
+App → OverBridgeService → BridgeProxy → Overmind MCP → Hermes Gateway
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### L'agent ne démarre pas
+- Vérifier `SOUL.md` non vide (Hermes)
+- Vérifier `config.yaml` valide (Hermes)
+- Checker `logs/errors.log` (Hermes)
+
+### MCP Server non connecté
+- Vérifier le port dans `config.yaml` (Hermes)
+- Tester `curl http://localhost:PORT/mcp`
+
+### Bridge — Circuit breaker ouvert
+- 5 échecs → circuit open
+- Attendre 30s ou `bridge.healthCheck()`
+
+### Cron perdu après redémarrage
+- Cron Hermes = par session (pas persistant)
+- Cron Overmind = persistant (survit)
+- Vérifier quel niveau de cron est utilisé
+
+### Mémoire pleine
+- `MEMORY.md` / `USER.md` ont des limites
+- `memory(action: "remove")` pour nettoyer
+
+---
+
+## 📊 Checklist Nouvel Agent
+
+- [ ] `create_agent()` (OVERMIND)
+- [ ] `update_agent_config()` — modèle (OVERMIND)
+- [ ] `update_agent_config()` — MCP servers (OVERMIND)
+- [ ] `update_agent_config()` — .env (OVERMIND)
+- [ ] Tester avec `run_agent()` (OVERMIND → HERMES)
+- [ ] Stocker premiers faits en `memory_store()` (OVERMIND)
+- [ ] Configurer Bridge SDK si orchestration externe (OVERMIND)
+
+---
+
+> **Dernière mise à jour** : 30 mai 2026
+> **Auteur** : Sniperbot Analyst (agent Hermes permanent)
+> **Basé sur** : Infrastructure Overmind (encapsuleur) + Hermes Gateway (runtime)