Huy's Wiki

Mercury Agent — Soul-Driven AI Agent by CosmicStack Labs

Properties2
descriptionPermission-hardened AI agent with second brain memory, token budgets, daemon mode, multi-channel access (CLI/Telegram/Web), and 30+ built-in tools. Node.js/standalone binary, 126+ community skills.
tagsai-agent, cosmosstack, open-source, permission-hardened, second-brain, daemon, telegram, skills

2 min read

Mercury Agent

By: CosmicStack Labs GitHub: cosmicstack-labs/mercury-agent npm: @cosmicstack/mercury-agent Stable: v1.1.9 License: Open source

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Remembers what matters. Asks before it acts. Runs 24/7 from CLI, Telegram, or Web.

Quick Start

# One-liner (no Node.js required)
curl -fsSL https://mercuryagent.sh/install.sh | sh
 
# Or via npm
npx @cosmicstack/mercury-agent

First run → setup wizard (name, provider, Telegram optional) → Ink TUI startup screen → choose permission mode → chat.

Key Features

Permission-Hardened

  • Shell blocklist (sudo, rm -rf / etc. never execute)
  • Folder-level read/write scoping
  • Pending approval flow
  • 2 modes: Ask Me (default) or Allow All per session

Second Brain Memory

  • Persistent SQLite + FTS5 full-text search
  • 10 memory types, auto-extraction, conflict resolution, auto-consolidation
  • Mercury learns preferences, goals, and habits without manual entry

Soul-Driven

  • Personality defined by markdown files you own:
    • soul.md — core identity
    • persona.md — communication style
    • taste.md — preferences
    • heartbeat.md — proactive behavior patterns
  • No corporate wrapper

Token-Aware

  • Daily budget enforcement
  • Auto-concise when over 70%
  • /budget command to check, reset, override

Daemon Mode

mercury up    # Install service + start daemon + ensure running
  • Auto-restarts on crash (exponential backoff, up to 10/min)
  • Starts on boot via LaunchAgent (macOS), systemd user unit (Linux), Task Scheduler (Windows)
  • No admin required

31 Built-in Tools

CategoryTools
Filesystemread_file, write_file, create_file, edit_file, list_dir, delete_file, send_file, approve_scope
Shellrun_command, cd, approve_command
Messagingsend_message
Gitgit_status, git_diff, git_log, git_add, git_commit, git_push
Webfetch_url
Skillsinstall_skill, list_skills, use_skill
Schedulerschedule_task, list_scheduled_tasks, cancel_scheduled_task
Systembudget_status

Channels

  • CLI — Ink TUI with real-time token streaming, cursor-save/restore, markdown re-rendering
  • Telegram — Editable status messages, multi-user with approve/reject/promote/demote
  • Web — Browser interface

Skills

126+ community skills in the registry. Install with one command:

# In-chat
/install_skill <name>

Skills follow the Agent Skills specification. Default skill: web-search on first run.

CLI Commands

CommandDescription
mercury / mercury startStart in foreground
mercury upInstall service + start daemon
mercury start -dBackground daemon mode
mercury restart / stopDaemon lifecycle
mercury logsView daemon logs
mercury doctorReconfigure setup
mercury setupRe-run setup wizard
mercury statusConfig + daemon status
mercury upgradeUpgrade to latest
mercury telegram list/approve/reject/remove/promote/demoteTelegram user management

In-Chat Commands

/help, /status, /tools, /skills, /stream, /budget, /permissions, /view, /code agent <task>, /tasks, /memory, /unpair

Architecture

  • TypeScript/Node.js 20+
  • Standalone binary option (no Node.js required)
  • Cross-platform: macOS, Linux, Windows
  • Open source with AGENTS.md for LLM-assisted development

Graph View