cosmicstack-labs/mercury-agent

Mercury — A “Soul‑Driven” AI Agent

What it is – Mercury is a locally‑run, permission‑hardened AI assistant that you can talk to from the command line, a web dashboard, or Telegram. It talks to large‑language‑model providers (OpenAI, Anthropic, DeepSeek, Ollama, etc.) and can read/write files, run shell commands, fetch URLs, manage Git, schedule tasks, and more. All actions are gated behind an explicit permission model, and the agent keeps a persistent, searchable “second‑brain” memory on your machine.

---

Core ideas

Idea	How Mercury implements it
Permission‑hardened tools	Every built‑in tool (file, shell, git, web, etc.) is blocked by default for dangerous operations (e.g., sudo, rm -rf /). You choose Ask Me (prompt before each action) or Allow All for the whole session.
Second‑brain memory	SQLite + FTS5 stores extracted facts in ten typed categories (identity, goal, habit …). After each conversation Mercury auto‑extracts a few high‑confidence facts, consolidates them hourly, and injects the top‑5 relevant memories into the LLM context.
Soul‑driven personality	Your own markdown files (soul.md, persona.md, taste.md, heartbeat.md) define the agent’s character, keeping the “personality” out of any corporate service.
Token‑aware budgeting	A daily token budget is tracked; when usage exceeds 70 % Mercury automatically shortens replies. You can view, reset, or override the budget with /budget commands.
Always‑on daemon	mercury up installs a per‑user system service (LaunchAgent, systemd user unit, or Windows Task Scheduler) that restarts on crash and can start at boot. In daemon mode Telegram becomes the primary chat channel.
Extensible skills	Community‑contributed “skills” (mini‑agents) follow the Agent Skills spec and can be installed with a single command (mercury skills install …). Skills appear as additional tools and can be scheduled or invoked from chat.

---

Quick start (no Node.js needed)

# macOS / Linux – download a self‑contained binary
curl -fsSL https://mercuryagent.sh/install.sh | sh

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

The installer drops a mercury executable in ~/.local/bin (or the Windows equivalent). The first run launches a wizard to set your name, LLM provider API keys, and optional Telegram pairing.

If you already have Node 20+, you can also run:

npx @cosmicstack/mercury-agent   # one‑off execution
npm i -g @cosmicstack/mercury-agent && mercury   # global install

---

Main command‑line interface

Command	What it does
mercury / mercury start	Launch the interactive Ink TUI chat session.
mercury up	Install the per‑user service (if needed) and start the background daemon.
mercury stop / restart / status / logs	Manage the daemon.
mercury doctor	Re‑run the setup wizard or inspect configuration.
mercury telegram …	Pair, approve, or manage Telegram users (admin vs. member roles).
mercury skills …	Search, view, install, update, or remove community skills.
mercury upgrade	Pull the latest release (binary or npm).

During a chat you can type slash commands that do not consume LLM tokens, e.g.:

• /tools – list the currently loaded tools
• /budget – show daily token usage
• /memory – browse the second‑brain
• /code agent <task> – spawn a sub‑agent to work on a coding job in the background
• /tasks – list scheduled jobs

---

Web dashboard & Kanban boards

Running mercury doctor can enable a local web UI at http://127.0.0.1:6174. It provides:

• Chat with server‑sent‑events streaming
• Visual Kanban boards where each card can be processed automatically by Mercury
• A view of the second‑brain memory graph
• A lightweight IDE‑like workspace for code‑editing tasks

The dashboard is protected by a default credential (mercury / Mercury@123) and binds to localhost only.

---

Extending Mercury

1. Skills – Packages that describe a toolset and a markdown SKILL.md. Install with mercury skills install <category>/<slug>. Skills are stored under ~/.mercury/skills/ and loaded on the next start.
2. Providers – Add any OpenAI‑compatible endpoint in ~/.mercury/mercury.yaml. Mercury will try them in order and fall back automatically.
3. Custom tools – Because the core is built on the Vercel AI SDK and a simple tool‑dispatch loop, developers can add new TypeScript modules that expose a run function and register them in the config.

---

Installation from source

git clone https://github.com/cosmicstack-labs/mercury-agent.git
cd mercury-agent
npm install               # Node ≥ 20
npm run build             # produces dist/ bundle
npm start                 # run from source

For a truly standalone binary (no Node runtime required for end users) the repo uses Bun:

npm run build:bin          # creates platform‑specific executables in release/

The release layout contains separate binaries for macOS (arm64 & x64), Linux (arm64 & x64) and Windows, plus a tarball of the web UI and SHA‑256 checksums.

---

License & safety

• License: MIT (see LICENSE).
• Security model: All potentially destructive actions are blocked by a shell blocklist and require explicit user approval. The agent never sends your local files or command output to any remote service unless you invoke a tool that does so (e.g., fetch_url).
• Data locality: All memory, logs, and configuration live under ~/.mercury/ on your machine; no cloud storage is used unless you configure a remote LLM provider.

---

Who might find this useful?

• Developers who want a personal AI assistant that can edit code, run builds, or manage git without granting it unrestricted shell access.
• Knowledge‑workers who like a searchable, auto‑curated “second brain” that lives entirely on their laptop.
• Teams that need a self‑hosted, permission‑aware bot for Telegram or a private web UI.

---

Bottom line: Mercury is a full‑featured, locally‑run AI agent that emphasizes safety (permission prompts, token budgeting), persistence (SQLite‑backed memory and Kanban boards), and extensibility (community skills, multi‑provider fallback). It can be used instantly via a single‑line installer or built from source for deeper customization.