mercury-agent

Introduzione

Agente AI "soul-driven" con strumenti con permessi rafforzati, budget di token e accesso multi-canale.

Ricorda ciò che conta. Chiede prima di agire. Funziona 24/7 da CLI o Telegram. 31 strumenti integrati, skill estensibili, memoria "Second Brain" basata su SQLite.

🔖 Versione Stabile Corrente: v1.1.6

---

Avvio Rapido

npx @cosmicstack/mercury-agent

Oppure installa globalmente:

npm i -g @cosmicstack/mercury-agent
mercury

La prima esecuzione avvia l'assistente di configurazione (nome, provider, Telegram opzionale). Dopo la configurazione, Mercury apre la schermata di avvio Ink TUI e chiede la modalità di permesso (Chiedimi o Consenti Tutto) prima che inizi la chat.

Per riconfigurare in seguito (cambiare chiavi, nome, impostazioni):

mercury doctor
mercury doctor --platform

Perché Mercury?

Ogni agente AI può leggere file, eseguire comandi e recuperare URL. La maggior parte lo fa silenziosamente. Mercury chiede prima — e ricorda ciò che conta.

• Permessi rinforzati — Blacklist della shell (sudo, rm -rf /, ecc. non vengono mai eseguiti). Scoping di lettura/scrittura a livello di cartella. Flusso di approvazione in sospeso. "Chiedimi" o "Consenti Tutto" per sessione. Nessuna sorpresa.
• Second Brain — Memoria persistente e strutturata con SQLite + ricerca full-text FTS5. 10 tipi di memoria, estrazione automatica, risoluzione dei conflitti, consolidamento automatico. Mercury apprende le tue preferenze, obiettivi e abitudini senza immissione manuale.
• Soul-driven — Personalità definita da file markdown di tua proprietà (soul.md, persona.md, taste.md, heartbeat.md). Nessun wrapper aziendale.
• Token-aware — Applicazione del budget giornaliero. Auto-conciso quando supera il 70%. Comando /budget per controllare, resettare o ignorare.
• Streaming in tempo reale — Streaming di token in tempo reale su CLI con salvataggio/ripristino del cursore e re-rendering markdown. Streaming Telegram con messaggi di stato modificabili.
• Sempre attivo — Esecuzione come demone in background su qualsiasi sistema operativo. Riavvio automatico in caso di crash. Avvio all'accensione. Pianificazione Cron, monitoraggio heartbeat e notifiche proattive.
• Estensibile — Installa skill della community con un solo comando. Pianifica skill come attività ricorrenti. Basato sulla specifica Agent Skills.

Mercury ora seeda una skill web-search di default alla prima esecuzione in ~/.mercury/skills/web-search/SKILL.md.

Modalità Demone

Un comando per rendere Mercury persistente:

mercury up

Questo installa il servizio di sistema (se non installato), avvia il demone in background e assicura che Mercury sia in esecuzione. Usa questo come comando principale.

Se Mercury è già in esecuzione, mercury up si limita a confermarlo e mostra il PID.

Altri comandi del demone

mercury restart      # Riavvia il processo in background
mercury stop         # Ferma il processo in background
mercury start -d     # Avvia in background (senza installazione del servizio)
mercury logs         # Visualizza i log recenti del demone
mercury status       # Mostra se il demone è in esecuzione

La modalità demone include il ripristino automatico in caso di crash — se il processo si blocca, si riavvia automaticamente con un backoff esponenziale (fino a 10 riavvii al minuto).

Servizio di sistema (avvio automatico all'accensione)

mercury up lo installa automaticamente. Puoi anche gestirlo direttamente:

mercury service install

mercury service status     # Controlla se il servizio è in esecuzione
mercury service uninstall  # Rimuovi il servizio di sistema

In modalità demone, Telegram diventa il tuo canale principale — la CLI è solo per i log, poiché non c'è un terminale per l'input.

Comandi CLI

Comandi in Chat

Digita questi comandi durante una conversazione — non consumano token API. Funzionano sia su CLI che su Telegram.

Strumenti Integrati

Canali

Scorciatoie Workspace/Codifica (CLI)

• Ctrl+P → passa alla modalità Piano
• Ctrl+X → passa alla modalità Esegui
• Esc o Ctrl+Q → esci dallo workspace e torna alla chat generale
• Ctrl+V → attiva/disattiva la vista progressi (/view è un fallback quando il terminale intercetta Ctrl+V)

Note sull'interfaccia Spotify (CLI)

• Il deck Spotify supporta scorciatoie da tastiera: N successivo, P precedente, +/- volume, Z in riproduzione.
• L'album art inline è opzionale e protetta:
  • Abilita con MERCURY_SPOTIFY_ART=1
  • Attualmente si rende solo nelle sessioni iTerm locali
  • Ricade automaticamente sull'interfaccia solo testo in SSH/mobile/terminali leggeri

Accesso Telegram

Mercury utilizza un modello di accesso basato sull'organizzazione con amministratori e membri.

• Configurazione iniziale: Invia /start al tuo bot, ricevi un codice di accoppiamento, inseriscilo nella CLI con mercury telegram approve <code>. Diventi il primo amministratore.
• Utenti aggiuntivi: Invia /start per richiedere l'accesso. Gli amministratori approvano o rifiutano dalla CLI.
• Ruoli: Gli amministratori possono approvare/rifiutare richieste, promuovere/retrocedere utenti e resettare l'accesso. I membri possono chattare con Mercury.
• Reset: Gli amministratori possono inviare /unpair in Telegram o eseguire mercury telegram reset nella CLI per cancellare tutti gli accessi e ricominciare.
• Solo chat private — i messaggi di gruppo vengono sempre ignorati.

Comandi CLI: mercury telegram list|approve|reject|remove|promote|demote|reset

Scheduler

• Ricorrente: schedule_task con espressioni cron (0 9 * * * per ogni giorno alle 9 del mattino)
• Singola esecuzione: schedule_task con delay_seconds (es. 15 secondi)
• Le attività persistono in ~/.mercury/schedules.yaml e vengono ripristinate al riavvio
• Le risposte vengono reindirizzate al canale dove è stata creata l'attività

Second Brain

Mercury costruisce una memoria strutturata e persistente che cresce con ogni conversazione. Abilitato per impostazione predefinita, estrae, archivia e richiama automaticamente fatti su di te.

• 10 tipi di memoria — identità, preferenza, obiettivo, progetto, abitudine, decisione, vincolo, relazione, episodio, riflessione
• Estrazione automatica — dopo ogni conversazione, Mercury estrae 0–3 fatti con punteggi di confidenza, importanza e durabilità
• Richiamo pertinente — prima di ogni messaggio, i primi 5 ricordi corrispondenti (budget di 900 caratteri) vengono iniettati nel contesto
• Consolidamento automatico — ogni 60 minuti, Mercury costruisce un riepilogo del profilo, un riepilogo dello stato attivo e genera riflessioni da pattern
• Risoluzione dei conflitti — i ricordi opposti vengono risolti per confidenza (vince il più alto) o per recenza (vince il più recente)
• Auto-pulizia — i ricordi con ambito attivo diventano obsoleti dopo 21 giorni; i ricordi inferiti decadono; i ricordi durevoli a bassa confidenza vengono scartati dopo 120 giorni
• Controlli utente — /memory per panoramica, ricerca, pausa, ripristino e cancellazione
• Disabilita — variabile d'ambiente SECOND_BRAIN_ENABLED=false o memory.secondBrain.enabled: false nella configurazione

Tutti i dati rimangono sulla tua macchina in ~/.mercury/memory/second-brain/second-brain.db (SQLite + FTS5). Nessun cloud.

Configurazione

Tutti i dati di runtime vivono in ~/.mercury/ — non nella tua directory di progetto.

Fallback del Provider

Configura più provider LLM. Mercury li prova nell'ordine e ricade automaticamente:

Quando un provider fallisce, Mercury prova automaticamente il successivo. Ricorda l'ultimo provider funzionante e ripartsce da lì alla richiesta successiva.

Altri provider in arrivo — Google Gemini, Mistral e altri sono nella roadmap. L'architettura compatibile OpenAI di Mercury supporta anche endpoint personalizzati tramite la configurazione dell'URL base.

Architettura

• TypeScript + Node.js 18+ — ESM, build tsup
• Vercel AI SDK v4 — generateText + streamText, loop agentico a 10 passi, fallback provider
• grammY — Bot Telegram con indicatori di digitazione, streaming modificabile e caricamento file
• SQLite + FTS5 — Second brain con ricerca full-text, risoluzione dei conflitti, consolidamento automatico
• JSONL — Memoria conversazionale a breve, lungo termine ed episodica
• Daemon manager — Avvio in background + file PID + recupero crash watchdog
• Servizi di sistema — macOS LaunchAgent, Linux systemd, Windows Task Scheduler

Licenza

MIT © Cosmic Stack

---

Disclaimer

Questo è AI - a volte può bloccarsi, si prega di usarlo a proprio rischio.

---

Contributi

Siamo aperti ai contributi! Mercury è costruito per evolvere e accogliamo con favore l'aiuto della community. Che si tratti di correggere un bug, aggiungere uno strumento, ...