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.9
English | ็ฎไฝไธญๆ
--- ## Quick Start **One-liner install (no Node.js required)** โ downloads the latest standalone binary for your OS: ```bash # macOS / Linux curl -fsSL https://mercuryagent.sh/install.sh | sh ``` ```powershell # Windows irm https://mercuryagent.sh/install.ps1 | iex ``` Or via npm if you already have Node.js 20+: ```bash npx @cosmicstack/mercury-agent ``` Or install the npm package globally: ```bash 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): ```bash 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](https://agentskills.io) 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:** ```bash 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 ```bash 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: ```bash mercury service install ``` | Platform | Method | Requires Admin | |----------|--------|---------------| | **macOS** | LaunchAgent (`~/Library/LaunchAgents/`) | No | | **Linux** | systemd user unit (`~/.config/systemd/user/`) | No (linger for boot) | | **Windows** | Task Scheduler (`schtasks`) | No | ```bash 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 | Command | Description | |---------|-------------| | `mercury up` | **Recommended.** Install service + start daemon + ensure running | | `mercury` | Start the agent (same as `mercury start`) | | `mercury start` | Start in foreground | | `mercury start -d` | Start in background (daemon mode) | | `mercury restart` | Restart the background process | | `mercury stop` | Stop a background process | | `mercury logs` | View recent daemon logs | | `mercury doctor` | Reconfigure setup (name, providers, channels, permissions defaults) | | `mercury doctor --platform` | Show cross-platform terminal/daemon compatibility diagnostics | | `mercury setup` | Re-run the setup wizard | | `mercury status` | Show config and daemon status | | `mercury help` | Show full manual | | `mercury upgrade` | Upgrade to latest version | | `mercury telegram list` | List approved and pending Telegram users | | `mercury telegram approve`, `/skills view`, `/skills install ` (admin-only). Every result includes the registry URL so you can review before installing. See the [Skills reference](https://mercuryagent.sh/docs/reference/skills) 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`: ```bash mercury doctor # Enable web during setup ``` Or set in `~/.mercury/mercury.yaml`: ```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 | Channel | Features | |---------|----------| | **CLI** | Ink TUI, startup permission mode picker, interactive permission prompts (arrow keys + Enter; Y/N/A shortcuts), progress views (balanced/detailed), real-time streaming | | **Web** | React SPA dashboard, chat with SSE streaming, Kanban boards, Second Brain visualization, Workspace IDE, dark/light theme | | **Telegram** | HTML formatting, editable streaming messages, file uploads, typing indicators, multi-user access with admin/member roles | ### 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 `. 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. | Path | Purpose | |------|---------| | `~/.mercury/mercury.yaml` | Main config (providers, channels, budget) | | `~/.mercury/.env` | API keys and tokens (loaded alongside project .env) | | `~/.mercury/soul/*.md` | Agent personality (soul, persona, taste, heartbeat) | | `~/.mercury/permissions.yaml` | Capabilities and approval rules | | `~/.mercury/skills/` | Installed skills | | `~/.mercury/schedules.yaml` | Scheduled tasks | | `~/.mercury/token-usage.json` | Daily token usage tracking | | `~/.mercury/memory/short-term/` | Per-conversation JSON files | | `~/.mercury/memory/long-term/` | Auto-extracted facts (JSONL) | | `~/.mercury/memory/episodic/` | Timestamped event log (JSONL) | | `~/.mercury/memory/second-brain/` | Structured memory database (SQLite + FTS5) | | `~/.mercury/daemon.pid` | Background process PID | | `~/.mercury/daemon.log` | Daemon mode logs | | `~/.mercury/boards.db` | Kanban boards database (SQLite) | ## Provider Fallback Configure multiple LLM providers. Mercury tries them in order and falls back automatically: | Provider | Default Model | API Key | Notes | |----------|--------------|---------|-------| | **DeepSeek** | deepseek-chat | `DEEPSEEK_API_KEY` | Default, cost-effective | | **OpenAI** | gpt-4o-mini | `OPENAI_API_KEY` | GPT-4o, o3, etc. | | **Anthropic** | claude-sonnet-4 | `ANTHROPIC_API_KEY` | Claude Sonnet, Haiku, Opus | | **Grok (xAI)** | grok-4 | `GROK_API_KEY` | OpenAI-compatible endpoint | | **Ollama Cloud** | gpt-oss:120b | `OLLAMA_CLOUD_API_KEY` | Remote Ollama via API | | **Ollama Local** | gpt-oss:20b | No key needed | Local Ollama instance | 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](https://bun.sh) โฅ 1.3** (only required for standalone binaries; install with `curl -fsSL https://bun.sh/install | bash`) ### Standard build (ESM bundle) ```bash 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. ```bash npm run build:bin # host platform only npm run build:bin:all # all 5 targets (macOS arm64/x64, Linux x64/arm64, Windows x64) npm run build:bin:force # rebuild (overwrite existing binary for the same version) npm run build:bin:all:force # rebuild all targets ``` 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 โ โโโ checksums.txt (SHA-256 for every binary) โโโ v1.2.0/ โฆ ``` The version is read from `package.json` โ bump it before building to produce a fresh folder. Re-running for the same version skips already-built targets unless `--force` is passed. **Cross-compilation**: Bun produces binaries for every target from a single host. Native modules (`better-sqlite3`) can't cross-compile, but Mercury gracefully falls back to `sql.js` (pure JS + wasm) so the cross-compiled binaries still work end-to-end. **macOS Gatekeeper**: unsigned binaries trigger a warning on first launch. For distribution, sign with `codesign --sign "Developer ID" release/v/mercury-macos-arm64` and notarize. ## License MIT ยฉ [Cosmic Stack](https://github.com/cosmicstack-labs) --- ## 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: | Principle | What It Means | |-----------|---------------| | ๐ง **Think in loops** | Mercury operates in a 10-step agentic loop. Your tool or feature will be called multiple times per conversation. Make it idempotent where possible. | | ๐ **Permission-first** | Every action that touches the outside world (files, shell, network, git) must go through the permission system. Never assume approval. | | ๐พ **Memory-aware** | If your feature generates facts about the user, consider hooking into the Second Brain. If it reads user data, check memory first. | | ๐ **Token-conscious** | Mercury has a daily token budget. Logging, verbose outputs, and large context dumps burn tokens fast. Keep it lean. | | ๐ **Channel-agnostic** | Tools should work identically on CLI and Telegram. Don't assume a terminal, a keyboard, or even a human on the other end. | | ๐ **Graceful degradation** | If a provider fails, a tool errors, or a file doesn't exist โ Mercury should recover, not crash. Always handle edge cases. | | ๐ **Self-documenting** | Your tool's name and description are what Mercury reads to decide when to use it. Make them clear, specific, and action-oriented. | | ๐งช **Test the loop, not just the function** | A tool that works in isolation may fail in the agentic loop (e.g., returns too much data, blocks the next step). Test end-to-end. | ### Code Quality โ Dos | Do | Why | |----|-----| | โ Write clean, readable TypeScript with explicit types | Mercury's codebase is type-safe โ keep it that way | | โ Add JSDoc comments on public functions and tools | Helps other contributors and the agent understand intent | | โ Keep functions small and single-purpose | Easier to test, review, and reason about | | โ Use async/await over raw promises | Consistent error handling and readability | | โ Write tests for new tools and memory features | Reliability matters for a 24/7 agent | | โ Follow the existing project structure (`src/tools/`, `src/memory/`, `src/channels/`) | Keeps the codebase navigable | | โ Use the Agent Skills spec for new skill-based features | Ensures compatibility with the skills ecosystem | | โ Document breaking changes in PR descriptions | Helps maintainers version properly | ### Code Quality โ Don'ts | Don't | Why | |-------|-----| | โ Don't add dependencies without discussion | Mercury is lean โ every dep adds surface area | | โ Don't hardcode API keys, tokens, or paths | Use config/env vars like the rest of the codebase | | โ Don't bypass the permission system | Tools must ask before acting โ that's Mercury's core promise | | โ Don't introduce sync/blocking I/O in hot paths | Mercury is async-first for a reason | | โ Don't commit large binary files or secrets | Use `.gitignore` and env files | | โ Don't change the soul/persona system without discussion | It's the heart of Mercury โ changes need care | | โ Don't submit untested Telegram or daemon changes | These are hard to debug post-merge | | โ Don't ignore the token budget system | Every tool should be mindful of token consumption | ### 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](mailto:mercury@cosmicstack.org). We're friendly. --- ## Community 1. **Discord** โ [Join the Mercury Agent Discord](https://discord.gg/5emMpMJy5J) for real-time chat, support, and community discussions.