Soul-driven. Token-efficient. Always on.

Your personal AI agent with 31 built-in tools, skill system, multi-agent orchestration, Spotify integration, GitHub companion, and hardened permissions. Runs 24/7 from your terminal or Telegram.

Get StartedSee it in actionRead Docs
npm i -g @cosmicstack/mercury-agent && mercury
terminal

Built Different

Not another chatbot. An orchestrator that works for you.

☿

Soul-Driven Identity

Mercury isn't a blank slate. Its personality is defined by markdown soul files — soul.md, persona.md, taste.md, heartbeat.md — that you control.

⚡

Token-Efficient

Daily token budgets with enforcement. Only soul + persona injected per request (~400 tokens). Progressive skill loading. Auto-concise when budget exceeds 70%.

♾

Always On

Background daemon by default. Cron scheduling, delayed tasks, and a heartbeat system. Auto-starts on boot, auto-restarts on crash.

📡

Multi-Channel

CLI with readline and arrow-key menus. Telegram with typing indicators, HTML formatting, file uploads, and private 1:1 access.

🤖

Sub-Agents

Spawn parallel AI agents for concurrent tasks. Mercury orchestrates — research, code, and review run simultaneously. Non-blocking: keep chatting while agents work.

🎵

Spotify Integration

Native Spotify control through conversation. Play music, manage playlists, DJ on your devices. Search, like, queue — all through natural language.

🧩

Skill System

Install community skills with a single command. Skills auto-load into context, get elevated permissions, and can be scheduled as recurring tasks.

🛡

Permission Hardened

Folder-level read/write scoping. Command blocklist. Pending approval flow. Ask Me or Allow All mode per session.

🧠 Second Brain

Most AI agents forget everything when you close the chat. Mercury remembers — automatically, privately, and with surgical precision.

Learns Automatically

After each conversation, Mercury extracts facts about you — your preferences, goals, projects, habits, relationships, and decisions.

Recalls What Matters

Only memories relevant to the current conversation are injected — up to 5 facts within a 900-character budget.

Resolves Conflicts

When Mercury detects a contradiction, the higher-confidence memory wins. No stale data.

10 Memory Types

Identity, preference, goal, project, habit, decision, constraint, relationship, episode, and reflection — each scored by confidence, importance, and durability.

Auto-Consolidation

Every hour Mercury synthesizes a profile summary and generates reflections from patterns it detects.

You Stay in Control

/memory gives you overview, search, pause, and clear. All data stays on your machine in SQLite — nothing leaves.

Up and Running in 60 Seconds

1

Install

npm i -g @cosmicstack/mercury-agent

Or use npx @cosmicstack/mercury-agent — no install needed.

2

Setup

mercury

First run triggers the onboarding wizard. Choose providers, validate keys, pick your default model, optionally pair Telegram.

3

Run

mercury start

Mercury wakes up, loads your soul files, restores scheduled tasks, and runs as a background daemon.

See It Work

A real Mercury session — tool calls, streaming, files, and scheduling.

mercury

31 Built-In Tools

Plus extensible skills, scheduling, and memory.

📂 Filesystem

  • read_file — Read file contents
  • write_file — Write to existing file
  • create_file — Create new files (+ dirs)
  • edit_file — Search & replace text
  • list_dir — List directory contents
  • delete_file — Delete a file
  • send_file — Send file to user
  • approve_scope — Request directory access

💬 Messaging

  • send_message — Send a message to approved Telegram recipients

🐚 Shell

  • run_command — Execute shell commands
  • cd — Change working directory
  • approve_command — Permanently approve a command

📦 Git

  • git_status — Working tree status
  • git_diff — Show file changes
  • git_log — Commit history
  • git_add — Stage files
  • git_commit — Create commits
  • git_push — Push to remote

🐙 GitHub

  • create_pr — Create pull requests
  • review_pr — Review PRs + post comments
  • list_issues — List & filter issues
  • create_issue — Create new issues
  • github_api — Raw API access
  • Co-authored-by on every commit

🎵 Spotify

  • spotify_search — Search tracks, artists, albums, playlists
  • spotify_play — Play on your devices
  • spotify_pause/next/previous — Playback controls
  • spotify_now_playing — What's playing + progress bar
  • spotify_devices — List & select devices
  • spotify_like/top_tracks/playlists — Library access
  • spotify_volume/shuffle/repeat/queue — Full player control

🤖 Sub-Agents

  • delegate_task — Spawn parallel AI agents
  • list_agents — Monitor running agents
  • stop_agent — Halt a specific agent
  • /agents — See all agents + status
  • /halt — Emergency stop all agents
  • File locks for concurrent safety
  • Auto-concurrency from CPU/RAM

🧩 Skills

  • install_skill — Install from URL or content
  • list_skills — Show installed skills
  • use_skill — Invoke a skill

⏰ Scheduler

  • schedule_task — Cron or one-shot tasks
  • list_scheduled_tasks — View all tasks
  • cancel_scheduled_task — Cancel a task

📊 System

  • budget_status — Check token budget

🧠 Memory

  • Short-term — Recent conversation per channel
  • Long-term — Auto-extracted facts with dedup
  • Episodic — Timestamped interaction log

Honest Comparison

We built Mercury because nothing else did all of this.

FeatureMercuryOpen InterpreterClaude Code
Soul / Persona System4 markdown filesCustom instructionsCLAUDE.md
Token BudgetDaily budget + override——
Multi-ChannelCLI + Telegram + moreAllAll
Sub-AgentsParallel AI workers, non-blocking——
Spotify IntegrationNative playback + DJ mode——
Skill SystemInstall, invoke, schedule——
Cron + Delayed SchedulingPersisted, auto-restore——
Permission HardeningBlocklist + scope + approvalConfirmation promptsPermission prompts
GitHub CompanionPRs, issues, co-authored commits——
Proactive NotificationsHeartbeat + task alerts——
Auto Fact ExtractionWith dedup——
Provider FallbackAuto with last-successfulManual configAnthropic only
File Upload (Telegram)Auto type detection——
Streaming OutputReal-time text streamReal-time text streamReal-time text stream
Headless / 24-7Built-in——
LanguageTypeScript / Node.jsPythonTypeScript / Node.js
Open SourceMITLGPL-2.1Source-available

Under the Hood

Minimal runtime, maximum capability.

Core
TypeScript + Node.js 18+
ESM, tsup build, SQLite-backed second brain
AI SDK
Vercel AI SDK v6
streamText + generateText, 10-step agentic loop
Sub-Agents
Same-process async coroutines
Parallel task delegation, file locks, resource-aware concurrency
Spotify
Native Web API integration
OAuth2 auth, 14 tools, DJ mode skill, Premium + free support
Providers
DeepSeek · OpenAI · Anthropic · Grok · Ollama Cloud · Ollama Local
Validated onboarding, model discovery, and fallback with last-successful tracking
Memory
JSONL + SQLite
Short-term, long-term, episodic + second brain
Telegram
grammY
Long polling, pairing codes, CLI-managed access requests, broadcasts, file uploads
Runtime Data
~/.mercury/
Config, soul, memory, permissions, skills, schedules — all in your home dir

Supported Providers

Pick one or stack them all. Mercury falls back automatically.

DeepSeek

Default provider. Cost-effective with strong reasoning.

OpenAI

GPT-4o-mini, GPT-4o, o3. Industry standard.

Anthropic

Claude Sonnet, Haiku, Opus. Nuanced reasoning.

Grok (xAI)

xAI's models. OpenAI-compatible endpoint.

Ollama Cloud

Remote Ollama models via API. No local setup.

Ollama Local

On your machine. Zero API cost, fully private.

More providers on the way — Google Gemini, Mistral, and others. Mercury's OpenAI-compatible architecture also supports custom endpoints.

Ready to Deploy Your Agent?

npm i -g @cosmicstack/mercury-agent && mercury

That's it. 60 seconds to your own AI agent with GitHub companion.

GitHub →Report an Issue →