Mercury Agent

Permission-aware. Memory-backed. Always on.

Mercury Agent

Mercury Agent is a soul-driven AI agent that asks before it acts, remembers what matters, and stays reachable from the CLI or Telegram without turning into a black-box automation bot.

View on GitHub See Quick Start
  • 31 built-in tools
  • SQLite + FTS5 memory
  • CLI and Telegram access
  • Daemon mode with crash recovery
This page condenses the public Mercury Agent repository into a faster read for people searching the product by keyword.
Mercury Agent logo mark 
$ npx @cosmicstack/mercury-agent
$ mercury doctor
$ mercury up

Memory: SQLite + FTS5
Channel: CLI / Telegram
Mode: permission-hardened
State: runs 24/7

Quick Start

The shortest path from curiosity to a running Mercury Agent.

The public README starts with a lightweight setup flow: run the package, finish the wizard, and promote it to a background service only when you want the agent to stay up.

Try it now

npx @cosmicstack/mercury-agent

Install globally

npm i -g @cosmicstack/mercury-agent

Keep it running

mercury up

Why Mercury

Mercury is built around restraint, memory, and long-running usefulness.

Most AI agents can read files, run commands, and call tools. Mercury Agent turns those abilities into a safer operating model: approvals before action, persistent user context, a personality you own, and daemon controls that make 24/7 usage practical.

Fast thesis

It treats the operating model as the product.

Instead of presenting tool use as invisible magic, Mercury keeps the loop legible. Setup is quick, permissions are explicit, and the memory layer is not an afterthought.

Reading lens

It is opinionated in the right places.

The public repo highlights shell blocklists, scoped read and write boundaries, token budgets, structured memories, and boot-time services because those are the mechanics that decide whether an agent is usable day after day.

01

Permission-hardened tools

Mercury asks before it acts, blocks dangerous shell patterns, and keeps access scoped instead of assuming blanket authority.

02

Second Brain memory

Preferences, goals, habits, and other structured memories live in SQLite with FTS5 so context can persist beyond a single session.

03

Soul-driven configuration

Personality is defined by markdown files you own, including soul.md, persona.md, taste.md, and heartbeat.md.

04

Token-aware behavior

Daily budgets and an in-chat /budget command keep Mercury aware of resource limits instead of pretending usage does not matter.

05

CLI and Telegram channels

Mercury can start locally, stream replies in the terminal, and optionally open up a Telegram channel for remote access.

06

Daemon mode

mercury up installs the right service model for the platform, starts the agent, and gives you a practical way to keep it online.

How It Works

The loop starts small, then graduates into a durable background agent.

  1. 01

    Run the package or install it globally

    Start with npx @cosmicstack/mercury-agent or add the global mercury command for repeated use.

  2. 02

    Finish the setup wizard

    First run asks for your name, an API key, and optionally a Telegram bot token. The repo positions this as a roughly 30-second step.

  3. 03

    Approve actions instead of trusting blind automation

    Mercury is designed around explicit approvals, pending access, and bounded file or shell behavior instead of silent execution.

  4. 04

    Let the memory layer accumulate useful context

    Structured memory allows recurring preferences, goals, and habits to survive across conversations.

  5. 05

    Promote it to an always-on service

    Use mercury up when you want Mercury to run continuously with crash recovery, service management, and remote reachability.

Commands and Channels

The public command surface is small enough to learn quickly.

Key CLI commands
Command Use
mercury Start the agent in the foreground.
mercury up Install service support and keep the agent running.
mercury doctor Reconfigure keys, name, and settings later.
mercury logs Inspect the daemon when Mercury runs in the background.
mercury telegram list Review Telegram access state and pending users.

CLI first

Mercury starts as a terminal-native tool. Live streaming and local setup keep the first interaction straightforward.

Telegram when remote access matters

Telegram is optional, but it becomes the primary channel once Mercury runs as a daemon without an interactive terminal attached.

Skills extend the base agent

The repo positions Mercury as extensible through community skills and recurring tasks, rather than a frozen bundle of built-ins.

FAQ

Questions people usually have before trying Mercury Agent.

What makes Mercury Agent different from a typical AI CLI?

The core difference is operational discipline: Mercury foregrounds approvals, scoped access, persistent memory, and daily token budgets instead of treating those concerns as optional.

Does Mercury Agent have to run in the foreground?

No. The project includes daemon mode, status and logs commands, and service installation for macOS, Linux, and Windows workflows.

Do I need Telegram to use Mercury Agent?

No. Telegram is optional. The first-run path works from the CLI, and Telegram can be added later if you want a remote channel.

How does Mercury remember context?

The repository describes a SQLite-backed Second Brain with FTS5 full-text search and multiple memory types for preferences, goals, habits, and related context.

What platforms does Mercury support?

The service layer documented in the public repo covers macOS LaunchAgent, Linux systemd user units, and Windows Task Scheduler.

Is this the official Mercury Agent website?

No. This page is an independent explainer built around the public Mercury Agent repository. The GitHub repo remains the source of truth for releases and docs.