overmind-mcp 2.2.4 → 2.3.0

package/docs/docs/README_POSTGRES_INTEGRATION.md

@@ -0,0 +1,229 @@
+# 🔗 PostgreSQL Integration Guide
+
+Guide complet pour intégrer et utiliser PostgreSQL avec l'extension pgvector dans OverMind MCP.
+
+## 📋 Table des matières
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Utilisation](#utilisation)
+- [Performance](#performance)
+- [Dépannage](#dépannage)
+
+## 🚀 Installation
+
+### Via Docker (Recommandé)
+
+L'installation automatique est gérée par les scripts d'installation :
+
+```bash
+# Windows
+bin/install-overmind-windows.bat
+
+# Linux/macOS
+bin/install-overmind-unix.sh
+```
+
+Le script crée automatiquement :
+- Container Docker `overmind-postgres-pgvector`
+- Extension pgvector (4096 dimensions)
+- Base de données `overmind_memory`
+- Tables et index nécessaires
+
+### Manuelle
+
+Si vous préférez installer PostgreSQL manuellement :
+
+```bash
+# Installer PostgreSQL
+sudo apt-get install postgresql postgresql-contrib
+
+# Installer l'extension pgvector
+# Suivre les instructions sur : https://github.com/pgvector/pgvector
+```
+
+## ⚙️ Configuration
+
+### Variables d'environnement
+
+Créer ou modifier `.env` :
+
+```bash
+# PostgreSQL
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=your_secure_password
+POSTGRES_DB=overmind_memory
+
+# OverMind Memory (optionnel)
+OVERMIND_MEMORY_TYPE=postgres
+```
+
+### Vérification
+
+Tester la connexion :
+
+```bash
+docker exec overmind-postgres-pgvector psql -U postgres -c "SELECT extname FROM pg_extension WHERE extname = 'vector';"
+```
+
+Doit retourner : `vector`
+
+## 🎯 Utilisation
+
+### Avec OverMind MCP
+
+Les outils MCP suivants utilisent PostgreSQL :
+
+#### 1. **memory_search** - Recherche sémantique
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "memory_search",
+    "arguments": {
+      "query": "agents IA performants",
+      "agentName": "my_agent",
+      "limit": 5
+    }
+  }
+}
+```
+
+#### 2. **memory_store** - Stocker des connaissances
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "memory_store",
+    "arguments": {
+      "text": "Les agents GLM-5.1 sont très performants",
+      "source": "user"
+    }
+  }
+}
+```
+
+#### 3. **MCP_PG_VECTOR** - Requêtes SQL directes
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "MCP_PG_VECTOR",
+    "arguments": {
+      "sql": "SELECT * FROM agents_metadata LIMIT 10"
+    }
+  }
+}
+```
+
+### Via CLI OverMind
+
+```bash
+# Rechercher dans la mémoire
+overmind memory_search "agents performants" --agent my_agent
+
+# Stocker une information
+overmind memory_store "Nouveau conseil de test" --source user
+
+# Voir les statistiques
+overmind pgvector_stats --table embeddings
+```
+
+## 📊 Performance
+
+### Recherche vectorielle
+
+#### Spécifications
+- **Dimensions** : 4096 (Qwen 8B embeddings)
+- **Index** : HNSW (Hierarchical Navigable Small World)
+- **Distance** : Cosine similarity
+
+#### Benchmark
+
+```bash
+# Test de performance
+overmind intelligent_search "test query" --table embeddings --topK 10
+```
+
+### Optimisations
+
+1. **Index HNSW** - Recherche approximative ultra-rapide
+2. **Cache embeddings** - Réduit les calculs répétitifs
+3. **Recherche hybride** - Combine texte et vecteur pour meilleurs résultats
+
+## 🔧 Dépannage
+
+### Problèmes courants
+
+#### Erreur "extension vector does not exist"
+```bash
+# Créer l'extension
+docker exec overmind-postgres-pgvector psql -U postgres -c "CREATE EXTENSION vector;"
+```
+
+#### Erreur "connection refused"
+```bash
+# Vérifier que PostgreSQL tourne
+docker ps | grep overmind-postgres
+
+# Vérifier les ports
+netstat -an | grep 5432
+```
+
+#### Performance lente
+```bash
+# Vérifier les statistiques
+overmind pgvector_stats --table embeddings
+
+# Recréer les index si nécessaire
+overmind manage_vectors --action optimize --table embeddings
+```
+
+## 📚 Documentation avancée
+
+### Schéma de la base
+
+```sql
+-- Tables principales
+agents_metadata      -- Métadonnées des agents
+conversations          -- Historique des conversations
+embeddings            -- Vecteurs pour recherche sémantique
+agent_knowledge       -- Connaissances des agents
+```
+
+### Recherche hybride
+
+Combiner recherche textuelle et vectorielle :
+
+```sql
+SELECT
+    id,
+    content,
+    embedding <=> '[...]' AS vector_distance,
+    ts_rank(content_fts, query) AS text_rank
+FROM embeddings
+WHERE content_fts @@ query
+ORDER BY vector_distance ASC
+LIMIT 10;
+```
+
+## 🚀 Bonnes pratiques
+
+1. **Backup régulier** : `docker exec overmind-postgres pg_dump -U postgres overmind_memory > backup.sql`
+2. **Monitoring** : Utiliser Grafana dashboard pour surveiller les performances
+3. **Maintenance** : `overmind manage_vectors --action optimize --table embeddings` hebdomadairement
+
+---
+
+**Pour plus d'informations** :
+- Guide principal : `../README.md`
+- Docker : `../docker/README.md`
+- Scripts DB : `../db/README.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overmind-mcp",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "preferGlobal": true,
   "description": "Orchestrateur universel agents IA multi-modeles via MCP. Inclut le protocole 'Custom-Nickname' pour identifier vos agents avec des surnoms originaux (The Chaos Prophet, Shadow Sniper, etc.), l'isolation mémoire (Private Memory Context) et le support pour QwenCli et Nous Hermes. Installation automatique des dépendances Docker (PostgreSQL, pgvector) inclus.",
   "type": "module",
@@ -25,8 +25,8 @@
     "README.md",
     "docs",
     "scripts",
-    "install-overmind-windows.bat",
-    "install-overmind-unix.sh"
+    "bin",
+    ".mcp.json.example"
   ],
   "scripts": {
     "build": "tsc",
@@ -116,8 +116,8 @@
     "pino-pretty": "^13.1.3",
     "pino-roll": "^2.2.0",
     "tinyglobby": "^0.2.16",
-    "zod": "^4.3.6",
-    "tslib": "^2.8.1"
+    "tslib": "^2.0.0",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
     "tslib": "^2.0.0"

package/scripts/auto-install.mjs

@@ -136,13 +136,13 @@ async function setupInfrastructure() {
   const exportersUrl = 'https://raw.githubusercontent.com/DeamonDev888/overmind-mcp/main/docker-compose.exporters.yml';
 
   try {
-    const composeData = runCommand(`curl -sL ${composeUrl}`);
+    const composeData = runCommand(`curl -sL --max-time 30 ${composeUrl}`);
     if (composeData) {
       writeFileSync(join(INSTALL_DIR, 'docker-compose.yml'), composeData);
       console.log('✅ docker-compose.yml téléchargé');
     }
 
-    const exportersData = runCommand(`curl -sL ${exportersUrl}`);
+    const exportersData = runCommand(`curl -sL --max-time 30 ${exportersUrl}`);
     if (exportersData) {
       writeFileSync(join(INSTALL_DIR, 'docker-compose.exporters.yml'), exportersData);
       console.log('✅ docker-compose.exporters.yml téléchargé');
@@ -190,12 +190,12 @@ async function validateServices() {
   console.log('');
 
   const services = [
-    { name: 'PostgreSQL', filter: 'postgres', check: 'pg_isready' },
-    { name: 'RabbitMQ', filter: 'rabbitmq', check: null },
-    { name: 'Temporal', filter: 'temporal', check: null },
-    { name: 'Prometheus', filter: 'prometheus', check: null },
-    { name: 'Grafana', filter: 'grafana', check: null },
-    { name: 'Jaeger', filter: 'jaeger', check: null },
+    { name: 'PostgreSQL', filter: 'overmind-postgres-pgvector', check: 'pg_isready' },
+    { name: 'RabbitMQ', filter: 'overmind-rabbitmq', check: null },
+    { name: 'Temporal', filter: 'overmind-temporal', check: null },
+    { name: 'Prometheus', filter: 'overmind-prometheus', check: null },
+    { name: 'Grafana', filter: 'overmind-grafana', check: null },
+    { name: 'Jaeger', filter: 'overmind-jaeger', check: null },
   ];
 
   let allRunning = true;

package/scripts/postgres-manager.mjs

@@ -173,7 +173,7 @@ function showHelp() {
   console.log('║  Usage:                                                        ║');
   console.log('║    overmind-postgres up          Démarrer PostgreSQL           ║');
   console.log('║    overmind-postgres down        Arrêter PostgreSQL            ║');
-  console.log('║    overmind-postgres status     Vérifier l''état               ║');
+  console.log('║    overmind-postgres status     Verifier l\'etat               ║');
   console.log('║    overmind-postgres logs      Voir les logs en temps réel   ║');
   console.log('║    overmind-postgres reset     Réinitialiser (⚠️  données)    ║');
   console.log('║                                                                ║');

package/scripts/postinstall.mjs

@@ -201,14 +201,14 @@ async function setupConfigFiles() {
 
   try {
     // Télécharger .env.example
-    const envExampleData = runCommand(`curl -sL ${envExampleUrl}`);
+    const envExampleData = runCommand(`curl -sL --max-time 30 ${envExampleUrl}`);
     if (envExampleData) {
       writeFileSync(join(INSTALL_DIR, '.env.example'), envExampleData);
       log(COLORS.green, '✅ .env.example téléchargé');
     }
 
     // Télécharger .mcp.json.example
-    const mcpExampleData = runCommand(`curl -sL ${mcpExampleUrl}`);
+    const mcpExampleData = runCommand(`curl -sL --max-time 30 ${mcpExampleUrl}`);
     if (mcpExampleData) {
       writeFileSync(join(INSTALL_DIR, '.mcp.json.example'), mcpExampleData);
       log(COLORS.green, '✅ .mcp.json.example téléchargé');

package/scripts/setup.mjs

@@ -175,11 +175,11 @@ async function installPostgreSQL() {
     execSync('docker pull pgvector/pgvector:pg16', { stdio: 'inherit' });
 
     console.log('🚀 Démarrage container PostgreSQL...');
-    const runCommand = `docker run -d --name postgres-pgvector \\
+    const runCommand = `docker run -d --name overmind-postgres-pgvector \\
       -p 5432:5432 \\
       -e POSTGRES_PASSWORD=overmind_temp_password_change_me \\
       -e POSTGRES_USER=postgres \\
-      -v postgres_data:/var/lib/postgresql/data \\
+      -v overmind_postgres_data:/var/lib/postgresql/data \\
       --restart unless-stopped \\
       pgvector/pgvector:pg16`;
 
@@ -192,7 +192,7 @@ async function installPostgreSQL() {
     // Verify pgvector
     console.log('🔍 Vérification pgvector...');
     await runCommandAsync(
-      'docker exec postgres-pgvector psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS vector;"',
+      'docker exec overmind-postgres-pgvector psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS vector;"',
       'Activation pgvector'
     );
 
@@ -268,13 +268,16 @@ async function startDockerServices() {
 async function createOvermindDatabase() {
   logSection('CRÉATION BASE OVERMIND');
 
-  // Import and run setup-overmind-db.mjs
   const setupDbPath = join(__dirname, 'setup-overmind-db.mjs');
+  const destDbDir = INSTALL_DIR;
+  const destDbPath = join(destDbDir, 'setup-overmind-db.mjs');
 
   try {
+    if (!existsSync(destDbDir)) {
+      mkdirSync(destDbDir, { recursive: true });
+    }
     copyFileSync(setupDbPath, destDbPath);
 
-    // Run it
     await runCommandAsync(
       `node "${destDbPath}"`,
       'Initialisation DB OverMind'