🧠 OverMind-MCP

Wrapper multi-agent persistant pour runners IA via MCP. Instanciez et pilotez des agents Hermes, Claude-Code, Gemini-cli, QwenCli, Kilo/Cline, OpenClaw — chacun avec sa propre mémoire, son state, ses skills. Backbone mémoire vectorielle PostgreSQL + pgvector.

Positionnement : OverMind n'est plus un orchestrateur central qui dispatche. C'est une factory à agents persistants : chaque agent créé reçoit son propre profil Hermes, sa propre DB, ses propres skills, et vit tant qu'il est utile. L'intelligence est dans les agents, pas dans le wrapper.

OverMind-MCP instancie des agents IA persistants via le Model Context Protocol. Chaque agent créé = 1 profil Hermes natif + 1 profile.yaml + 1 SOUL.md + 1 state.db — il vit, se souvient, et communique avec ses pairs. Compatible avec Hermes (natif), Claude-Code, Gemini-cli, QwenCli, Kilo/Cline, OpenClaw, et extensible à tout runner CLI.

✨ Fonctionnalités

• 🔌 Multi-Runner : Hermes natif, Claude-Code, Gemini, Kilo, QwenCli, OpenClaw — 1 commande par runner
• 🧠 Mémoire Vectorielle : RAG 4096D via PostgreSQL + pgvector, isolation par agent
• 🏗️ Architecture v3.1 : Profils Hermes canoniques avec profile.yaml, workspace.yaml, state.db
• 🌉 Bridge HTTP JSON-RPC : Communication A2A peer-to-peer entre agents persistants, scénarios, webhooks, sessions multi-tenant
• 🛡️ Anti-Zombie : 1 seul process HTTP partagé, processRegistry avec TTL + cleanup auto
• 📋 14 Outils MCP : run_agent, create_agent, memory_search/store, agent_control, etc.
• 🧠 Mémoire par défaut : tout agent créé via Overmind reçoit automatiquement le MCP memory (3 tools: memory_search/store/runs sur :3099). Pour l'accès complet 14 tools, utiliser overmind explicitement.
• 🅾️ HTTP Singleton : FastMCP httpStream — 1 serveur, tous les agents

🚀 Installation

Globale via NPM (Recommandé)

npm install -g overmind-mcp@latest

Le postinstall crée ~/.overmind/ automatiquement :

~/.overmind/                              ← racine unique
├── .mcp.json                             ← MCP canonique (1 fichier)
├── .env                                  ← secrets globaux
├── bridge/
│   ├── agents.json                       ← registre sessions unifié
│   └── process-registry.json             ← runtime live
└── hermes/                               ← HERMES_HOME (injecté par HermesRunner)
    └── profiles/                         ← SOURCE homes (unique)
        └── <name>/
            ├── config.yaml               ← Hermes config (model, provider)
            ├── SOUL.md                   ← system prompt
            ├── .env                      ← credentials spécifiques
            ├── state.db                  ← state local (SQLite)
            └── skills/                   ← skills personnalisés

Configuration MCP Client

{
  "mcpServers": {
    "overmind": {
      "type": "http",
      "url": "http://localhost:3099/mcp"
    },
    "postgres": {
      "type": "http",
      "url": "http://localhost:5433/mcp"
    }
  }
}

Lancer le serveur

# Foreground (dev)
overmind --transport httpStream --port 3099

# Systemd (prod)
overmind-setup  # installe PostgreSQL + pgvector si absent

🔧 Installation Locale (Dev)

git clone https://github.com/DeamonDev888/overmind-mcp.git
cd overmind-mcp
pnpm install
pnpm run build
pnpm run test

📚 Utilisation

CLI

# Démarrer le serveur MCP
overmind --transport httpStream --port 3099

# Bridge (Discord, SMS, webhooks)
overmind-bridge server --port 3001

# Gestion PostgreSQL
overmind-postgres-mcp up     # docker-compose up
overmind-postgres-mcp status # vérifier l'état

Bibliothèque (ESM)

import { runAgent, AgentManager } from 'overmind-mcp';

// Créer un agent Hermes
const manager = new AgentManager();
await manager.createAgent({
  name: 'analyst',
  runner: 'hermes',
  prompt: 'Tu es un analyste financier.',
  model: 'MiniMax-M3',
});

// Lancer une mission
const { content, isError } = await runAgent({
  runner: 'hermes',
  agentName: 'analyst',
  prompt: 'Analyse BTCUSDT',
  autoResume: true,
});

Outils MCP (14)

| Outil | Description | |-------|-------------| | run_agent | Lance un agent (Hermes/Claude/Kilo/etc.) | | run_agents_parallel | Lance N agents en parallèle | | create_agent | Crée un profil Hermes + SOUL.md + profile.yaml | | list_agents | Liste tous les agents (Hermes + Claude) | | delete_agent | Supprime un agent | | update_agent_config | Modifie model, provider, credentials, SOUL.md | | get_agent_configs | Affiche config.yaml + SOUL.md d'un agent | | memory_search | Recherche vectorielle (pgvector) | | memory_store | Stocke un souvenir (avec embedding auto) | | memory_runs | Historique des exécutions | | create_prompt / edit_prompt | Gestion des prompts Claude | | agent_control | Status, stream, kill, wait | | config_example | Exemple de configuration |

📂 Structure du Projet

overmind-mcp/
├── src/
│   ├── bin/                # Entrypoints CLI (cli.ts, overmind-bridge.ts)
│   ├── bridge/             # Bridge HTTP JSON-RPC + scénarios + webhooks
│   ├── lib/                # Config, logger, sessions, processRegistry
│   ├── memory/             # Provider PostgreSQL + pgvector
│   ├── services/           # Runners: Hermes, Claude, Gemini, Kilo, etc.
│   ├── tools/              # 14 outils MCP (1 fichier par tool)
│   └── __tests__/          # Tests unitaires (vitest)
├── scripts/                # setup, postgres-manager, postinstall, migration
├── bin/                    # Launchers (bat, sh, launch.cjs)
├── docs/                   # Documentation + site web GitHub Pages
└── assets/                 # Images et ressources

🛡️ Anti-Zombie Architecture

1 seul serveur HTTP FastMCP partagé par tous les agents. Le processRegistry traque les PIDs avec TTL automatique (1h) et cleanup background (5min).

Agent 1 ──┐
Agent 2 ──┼──→ Overmind MCP :3099 (1 process FastMCP)
Agent 3 ──┘
         └──→ PostgreSQL :5433 (pgvector)

🗺️ Roadmap v4.0 — Wrapper Multi-Agent Persistant

OverMind pivote d'orchestrateur central → wrapper factory à agents persistants. Chaque agent créé est autonome (profil, state, mémoire, skills), pas un slot dans un pool global.

État actuel (v3.7.0) — wrapper déjà opérationnel :

• ✅ Agents Hermes = profils natifs (config.yaml, SOUL.md, state.db, skills/)
• ✅ Pool de credentials géré par Hermes (rotation round-robin, rate-limit aware)
• ✅ Bridge HTTP par agent (ports 3101+) — peer-to-peer A2A, pas de dispatch central
• ✅ Hermes Gateway natif (port 8642) — HTTP+SSE, routing via X-Hermes-Profile

Plan de migration v4.0 — voir docs/MIGRATION_V4_WRAPPER.md pour le détail complet :

• Phase 1a — Suppression du dispatcher/YOLO_CONFIG (obligatoire, ~300 LOC)
• Phase 2 — Support Kanban OPTIONNEL (opt-in via OVERMIND_KANBAN_ENABLED=1)
• Phase 3 — Chaque agent = son propre bridge (peer-to-peer, plus de central)
• Phase 4 — Mémoire par-profile (au lieu de pgvector central)
• Phase 1b — Suppression historique Kanban (seulement si inutilisé après 1 release)

Projet propulsé par DeaMoN888 — 2026