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. 31 built-in tools, Kanban boards, extensible skills, SQLite-backed Second Brain memory.

🔖 Current Stable: v1.1.13

English | 简体中文

---

Quick Start

One-liner install (no Node.js required) — downloads the latest standalone binary for your OS:

# macOS / Linux
curl -fsSL https://mercuryagent.sh/install.sh | sh

# Windows
irm https://mercuryagent.sh/install.ps1 | iex

Or via npm if you already have Node.js 20+:

npx @cosmicstack/mercury-agent

Or install the npm package globally:

npm i -g @cosmicstack/mercury-agent
mercury

First run triggers the setup wizard (name, provider, optional Telegram). After setup, Mercury opens the Ink TUI startup screen and asks for your permission mode (Ask Me or Allow All) before chat starts.

To reconfigure later (change keys, name, settings):

mercury doctor
mercury doctor --platform

Why Mercury?

Every AI agent can read files, run commands, and fetch URLs. Most do it silently. Mercury asks first — and remembers what matters.

• Permission-hardened — Shell blocklist (sudo, rm -rf /, etc. never execute). Folder-level read/write scoping. Pending approval flow. Ask Me or Allow All per session. No surprises.
• Second Brain — Persistent, structured memory with SQLite + FTS5 full-text search. 10 memory types, auto-extraction, conflict resolution, auto-consolidation. Mercury learns your preferences, goals, and habits without manual entry.
• Soul-driven — Personality defined by markdown files you own (soul.md, persona.md, taste.md, heartbeat.md). No corporate wrapper.
• Token-aware — Daily budget enforcement. Auto-concise when over 70%. /budget command to check, reset, or override.
• Live streaming — Real-time token streaming on CLI with cursor-save/restore and markdown re-rendering. Telegram streaming with editable status messages.
• Always on — Run as a background daemon on any OS. Auto-restarts on crash. Starts on boot. Cron scheduling, heartbeat monitoring, and proactive notifications.
• Extensible — Install community skills with a single command. Schedule skills as recurring tasks. Based on the Agent Skills specification.

Mercury now seeds a default web-search skill on first run in ~/.mercury/skills/web-search/SKILL.md.

Daemon Mode

One command to make Mercury persistent:

mercury up

This installs the system service (if not installed), starts the background daemon, and ensures Mercury is running. Use this as your go-to command.

If Mercury is already running, mercury up just confirms it and shows the PID.

Other daemon commands

mercury restart      # Restart the background process
mercury stop         # Stop the background process
mercury start -d     # Start in background (without service install)
mercury logs         # View recent daemon logs
mercury status       # Show if daemon is running

Daemon mode includes built-in crash recovery — if the process crashes, it restarts automatically with exponential backoff (up to 10 restarts per minute).

System Service (auto-start on boot)

mercury up installs this automatically. You can also manage it directly:

mercury service install

mercury service status     # Check if service is running
mercury service uninstall  # Remove the system service

In daemon mode, Telegram becomes your primary channel — CLI is log-only since there's no terminal for input.

CLI Commands

In-Chat Commands

Type these during a conversation — they don't consume API tokens. Work on both CLI and Telegram.

Built-in Tools

Installing Skills

Mercury can pull community-contributed skills from the registry at skills.mercuryagent.sh (126+ skills, no auth required).

mercury skills search prompt                  # search the registry
mercury skills browse ai-ml                   # browse by category
mercury skills view ai-ml/prompt-engineering  # render SKILL.md in the terminal
mercury skills view ai-ml/prompt-engineering --web   # open the registry page
mercury skills install ai-ml/prompt-engineering      # install to ~/.mercury/skills/
mercury skills list                           # show installed skills
mercury skills update                         # refresh all installed skills
mercury skills remove ai-ml/prompt-engineering
mercury skills doctor                         # check install root + registry

Installed skills land at ~/.mercury/skills/<category>/<slug>/SKILL.md and are picked up by the agent on the next boot — they're treated identically to built-in skills.

Review before you ship. Skills are community-contributed and unaudited. Run mercury skills view <id> before installing.

Overrides: --registry <url> (or MERCURY_SKILLS_REGISTRY) for self-hosted registries, MERCURY_SKILLS_INSTALL_ROOT for an alternate install path, --json for machine-readable output.

Also installable from:

• Web dashboard — http://127.0.0.1:6174/skills has a registry installer (paste category/slug) and a URL installer side by side.
• Telegram — /skills, /skills search <q>, /skills view <id>, /skills install <id> (admin-only). Every result includes the registry URL so you can review before installing.

See the Skills reference for the full command surface, frontmatter spec, and API endpoints.

Web Dashboard

Mercury includes a built-in web UI at http://127.0.0.1:6174:

mercury doctor   # Enable web during setup

Or set in ~/.mercury/mercury.yaml:

web:
  enabled: true
  port: 6174

Features: Chat with SSE streaming, Kanban boards, Second Brain visualization, Workspace IDE, provider/skill/permission/schedule management, usage tracking, dark/light theme.

Default credentials: mercury / Mercury@123. Binds to localhost only.

Kanban Boards

Persistent task boards with agent execution. Create boards, add cards, and let Mercury process them autonomously.

• Cards — title, description, status (todo/doing/done/blocked), priority, labels, comments, attachments, dependencies
• Smart execution — Mercury processes cards sequentially, updating status and leaving result comments
• Cascade execution — process dependent cards in dependency order
• Token budget — per-card token tracking with auto-pause when exhausted
• Storage — SQLite with per-board context, variables, and instructions

Access via Web Dashboard or API (/api/boards/*).

Channels

Workspace/Coding Shortcuts (CLI)

• Ctrl+P → switch to Plan mode
• Ctrl+X → switch to Execute mode
• Esc or Ctrl+Q → exit workspace to general chat
• Ctrl+V → toggle progress view (/view is fallback when terminal intercepts Ctrl+V)

Spotify UI Notes (CLI)

• Spotify deck supports keyboard shortcuts: N next, P previous, +/- volume, Z now playing.
• Inline album art is optional and safe-gated:
  • Enable with MERCURY_SPOTIFY_ART=1
  • Currently renders only in local iTerm sessions
  • Automatically falls back to text-only UI in SSH/mobile/light terminals

Telegram Access

Mercury uses an organization access model with admins and members.

• First-time setup: Send /start to your bot, receive a pairing code, enter it in the CLI with mercury telegram approve <code>. You become the first admin.
• Additional users: Send /start to request access. Admins approve or reject from the CLI.
• Roles: Admins can approve/reject requests, promote/demote users, and reset access. Members can chat with Mercury.
• Reset: Admins can send /unpair in Telegram or run mercury telegram reset in the CLI to clear all access and start fresh.
• Private chats only — group messages are always ignored.

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

Scheduler

• Recurring: schedule_task with cron expressions (0 9 * * * for daily at 9am)
• One-shot: schedule_task with delay_seconds (e.g. 15 seconds)
• Tasks persist to ~/.mercury/schedules.yaml and restore on restart
• Responses route back to the channel where the task was created

Second Brain

Mercury builds a structured, persistent memory that grows with every conversation. Enabled by default, it automatically extracts, stores, and recalls facts about you.

• 10 memory types — identity, preference, goal, project, habit, decision, constraint, relationship, episode, reflection
• Automatic extraction — after each conversation, Mercury pulls 0–3 facts with confidence, importance, and durability scores
• Relevant recall — before each message, the top 5 matching memories (900-char budget) are injected into context
• Auto-consolidation — every 60 min, Mercury builds a profile summary, active-state summary, and generates reflections from patterns
• Conflict resolution — opposing memories are resolved by confidence (higher wins) or recency (newer wins)
• Auto-pruning — active-scope memories stale after 21 days; inferred memories decay; low-confidence durable memories dismissed after 120 days
• User controls — /memory for overview, search, pause, resume, and clear
• Disable — SECOND_BRAIN_ENABLED=false env var or memory.secondBrain.enabled: false in config

All data stays on your machine in ~/.mercury/memory/second-brain/second-brain.db (SQLite + FTS5). No cloud.

Configuration

All runtime data lives in ~/.mercury/ — not in your project directory.

Provider Fallback

Configure multiple LLM providers. Mercury tries them in order and falls back automatically:

When a provider fails, Mercury automatically tries the next one. It remembers the last successful provider and starts there on the next request.

More providers incoming — Google Gemini, Mistral, and others are on the roadmap. Mercury's OpenAI-compatible architecture also supports custom endpoints via base URL configuration.

Architecture

• TypeScript + Node.js 18+ — ESM, tsup build
• Vercel AI SDK v4 — generateText + streamText, 10-step agentic loop, provider fallback
• grammY — Telegram bot with typing indicators, editable streaming, and file uploads
• SQLite + FTS5 — Second brain with full-text search, conflict resolution, auto-consolidation
• JSONL — Short-term, long-term, and episodic conversation memory
• Daemon manager — Background spawn + PID file + watchdog crash recovery
• System services — macOS LaunchAgent, Linux systemd, Windows Task Scheduler

Build From Source

You can build Mercury yourself from source — either the standard Node bundle (for npm link / local development) or a standalone executable that bundles the entire runtime, so end-users don't need Node.js installed at all.

Prerequisites

• Node.js ≥ 20 (for the build toolchain)
• Bun ≥ 1.3 (only required for standalone binaries; install with curl -fsSL https://bun.sh/install | bash)

Standard build (ESM bundle)

git clone https://github.com/cosmicstack-labs/mercury-agent.git
cd mercury-agent
npm install
npm run build           # builds dist/ via tsup + post-build (UI, static assets)
npm start               # node dist/index.js

Standalone executable (no Node.js required for end users)

Mercury can be compiled into a single self-contained binary using bun build --compile. The resulting file embeds the Bun runtime and the full Mercury bundle.

npm run build:bin            # host platform only
npm run build:bin:all        # clean release: all 5 targets plus web archive and checksums
npm run build:bin:force      # rebuild (overwrite existing binary for the same version)
npm run build:bin:all:force  # replace an existing release directory, then rebuild all targets
node scripts/verify-standalone-release.cjs  # verify an already-built publishable release

Output is versioned so older builds are never overwritten:

release/
├── latest                       → symlink to most-recent version
├── v1.1.9/
│   ├── mercury-macos-arm64
│   ├── mercury-macos-x64
│   ├── mercury-linux-x64
│   ├── mercury-linux-arm64
│   ├── mercury-win-x64.exe
│   ├── web.tar.gz
│   └── checksums.txt            (SHA-256 for downloadable binaries and web.tar.gz)
├── smoke/v1.2.0/                (host-only local builds; never publish)
└── v1.2.0/ …

The version is read from package.json. Host-only smoke builds are isolated from publishable releases. build:bin:all refuses to reuse a non-empty version directory; use build:bin:all:force to delete and recreate it so assets from different revisions cannot be mixed.

Cross-compilation: Bun produces the JavaScript binaries for every target from a single host. Native addons such as better-sqlite3 still require target-compatible packaging. sql.js is used by a narrow web API fallback; it is not a general substitute for all better-sqlite3-backed features.

macOS Gatekeeper: unsigned binaries trigger a warning on first launch. For distribution, sign with codesign --sign "Developer ID" release/v<version>/mercury-macos-arm64 and notarize.

License

MIT © Cosmic Stack

---

Disclaimer

This is AI - it can break sometimes, please use this at your own risk.

---

Contributing

We're open to contributions! Mercury is built to evolve, and we welcome help from the community. Whether it's fixing a bug, adding a tool, improving memory, or refining the soul — all quality contributions are appreciated.

🎯 Agentic Expertise — Must-Have for Contributors

Mercury isn't just another open-source project — it's a soul-driven agent that runs 24/7, manages permissions, remembers context, and interacts across channels. If you're contributing, you must think like an agent builder, not just a library contributor. These are non-negotiable principles every contributor should internalize:

Code Quality — Dos

Code Quality — Don'ts

Getting Started

1. Fork the repo
2. Run npm install
3. Make your changes
4. Run npm run build to verify it compiles
5. Test with mercury locally
6. Open a PR with a clear description of what you changed and why

PR Guidelines

• Keep PRs focused — one feature/fix per PR
• Include before/after behavior in the description
• Tag related issues if applicable
• Be responsive to review feedback

Need Help?

Open an issue or reach out at mercury@cosmicstack.org. We're friendly.

---

Community

1. Discord — Join the Mercury Agent Discord for real-time chat, support, and community discussions.