Mercury Agent: A Permission-Hardened AI Assistant That Runs 24/7 from CLI or Telegram

What Mercury Agent Solves and Who It's For

Mercury Agent addresses a common complaint about AI agents: they can read files, run commands, and fetch URLs, but they often do so without asking. The README states that Mercury 'asks first' and 'remembers what matters.' This targets users who want an always-on assistant that can act autonomously but with guardrails. The intended audience includes developers and power users who want a personal AI that runs 24/7 from CLI or Telegram, manages tasks via Kanban boards, and stores preferences in a searchable memory. It is not a library or a framework; it is a standalone agent you install and converse with. The 'soul-driven' branding means personality is defined by markdown files you own, such as soul.md and persona.md, which appeals to users who want a customizable agent without a corporate wrapper. In short, it is for individuals who want a proactive assistant with memory and permission controls, not for teams building multi-user AI products.

Core Mechanism: Permission Gates, Token Budgets, and SQLite Memory

Mercury's architecture centers on three mechanisms visible in the README. First, permission-hardened tools: a shell blocklist prevents commands like sudo and rm -rf / from ever executing. Folder-level read/write scoping restricts what the agent can access. The agent presents a pending approval flow, and you choose a session mode: 'Ask Me' or 'Allow All.' Second, token budgets: a daily budget is enforced, and the agent automatically becomes concise when usage exceeds 70%. You can check, reset, or override with the /budget command. Third, Second Brain memory: SQLite with FTS5 full-text search stores ten types of memories, with auto-extraction, conflict resolution, and auto-consolidation. This is not a vector database; it is a structured relational store. The agent learns preferences and goals without manual entry. These mechanisms work together: the memory informs the soul, the permission gates control actions, and the budget prevents runaway costs. The design is pragmatic, but the effectiveness hinges on how well the blocklist and scoping cover edge cases.

Installation and Configuration: Commands from the README

The README offers several install paths. For a one-liner without Node.js, on macOS or Linux run: curl -fsSL https://mercuryagent.sh/install.sh | sh. On Windows, use PowerShell: irm https://mercuryagent.sh/install.ps1 | iex. If you have Node.js 20+, you can run npx @cosmicstack/mercury-agent or install globally with npm i -g @cosmicstack/mercury-agent and then run mercury. First run triggers a setup wizard asking for your name, provider, and optional Telegram. After setup, the Ink TUI startup screen appears and asks for your permission mode before chat. To reconfigure later, use mercury doctor or mercury doctor --platform for diagnostics. For daemon mode, mercury up installs a system service and starts the background process. The service uses LaunchAgent on macOS, systemd user unit on Linux, and Task Scheduler on Windows, none requiring admin. Other daemon commands include restart, stop, start -d, logs, and status. In daemon mode, Telegram becomes the primary channel because there is no terminal for input. This is a key constraint: if you run it as a service, you must interact via Telegram or the CLI becomes log-only.

Limitations and Failure Modes: What the README Doesn't Say

Several limitations are evident from the material. First, the permission system is only as good as its blocklist and folder scoping. The README lists sudo and rm -rf / as blocked, but it does not enumerate the full blocklist or explain how folder scoping is configured. A determined user could find commands that slip through, especially if the agent has write access to sensitive directories. Second, the token budget enforcement is automatic, but the 'auto-concise when over 70%' behavior might truncate important responses. There is no mention of a hard stop, only conciseness, so a long conversation could still exceed the budget if overridden. Third, daemon mode's reliance on Telegram means you must trust Telegram as a control channel. The README includes a Telegram user approval system with pairing codes and admin roles, which adds security, but it also means your agent is reachable via a third-party service. Fourth, the README does not document how the agent handles concurrent requests or queueing, which could be a problem if you send multiple commands while it is busy. Finally, there is no mention of offline capability; the agent depends on an LLM provider, so if the provider is down, the agent is inert. These gaps suggest you should test the permission enforcement in a sandbox before granting broad access.

Extensibility and Skills: The Agent Skills Specification

Mercury supports extensible skills based on the Agent Skills specification from agentskills.io. The README notes that on first run, it seeds a default web-search skill in ~/.mercury/skills/web-search/SKILL.md. You can install community skills with a single command and schedule them as recurring tasks. This is a notable differentiator: instead of a monolithic agent, you can add capabilities as discrete skills. The specification likely defines a standard format for skill metadata and execution, which means skills are portable across agents that support the spec. However, the README does not detail the installation command syntax or how to author your own skill. You would need to consult the spec or the repository's docs. The presence of a skills directory in the user's home suggests that skills are plain files, possibly markdown with embedded scripts, but this is not confirmed. For users who want to extend Mercury, this is an entry point, but the learning curve depends on the spec's maturity. If you are not interested in skills, the built-in 31 tools may suffice, but the exact list is not given.

Comparison with a Generic Agent Framework: Different Approach

A real alternative to Mercury is a framework like LangChain or a similar agent library where you build your own agent with custom tools and memory. The key difference in approach is that frameworks give you full control over the loop: you define tools, memory, and permission logic yourself. Mercury, by contrast, is a turnkey agent with a fixed architecture. With a framework, you can implement fine-grained permission policies, such as per-tool allowlists or context-dependent approvals, but you must write that logic. Mercury gives you a session-level 'Ask Me' or 'Allow All' toggle, which is coarser. A framework also lets you choose any vector store or database for memory; Mercury is locked to SQLite with FTS5. For a developer who wants to integrate an agent into an existing product, a framework is more flexible. For an individual who wants a working agent without coding, Mercury is more direct. The trade-off is between control and convenience. Mercury's permission-hardening is a feature you would have to build yourself in a framework, and you would likely not get the same level of polish in a weekend.

Maintenance and Upgrade Costs, and License Implications

The project is under active development, with recent releases including v1.2.3 in September 2026. The README mentions an upgrade command: mercury upgrade, which suggests a built-in mechanism to fetch the latest version. This lowers the maintenance burden compared to manual updates. However, upgrading could introduce breaking changes, especially given the rapid release cadence (v1.1.13 in June 2026, v1.2.2 in August, v1.2.3 in September). The changelog is not included, so you cannot assess what changed between versions. The license is MIT, which is permissive: you can use, modify, and distribute the code with attribution. This is a positive for adoption, but it also means there is no warranty or support guarantee. The project has a homepage at mercuryagent.sh, which may host documentation, but the README is the primary source. For long-term use, you should monitor the repository for breaking changes and test upgrades in a non-production environment. The daemon mode's auto-restart with exponential backoff (up to 10 restarts per minute) is a built-in resilience feature, but it does not protect against data corruption in the SQLite memory. Regular backups of the ~/.mercury directory are advisable, though the README does not mention backup tooling.

Editorial conclusion

Adopt Mercury Agent if you need an always-on AI assistant with explicit permission gates, token budgets, and persistent memory, and you are comfortable managing a daemon and Telegram as your primary interface. Skip it if you prefer a purely interactive terminal experience or need deep customization beyond the provided skills and config. Before adopting, verify that the permission enforcement matches your threat model, test the shell blocklist and folder scoping on your own commands, and confirm the npm package or binary matches the version in the README. Also check the Node.js 20+ requirement if you go the npm route. The project is MIT-licensed, which is permissive, but you should review the actual license file for any disclaimers. Ultimately, Mercury's appeal is its balance of autonomy and restraint, but that balance only holds if you trust its enforcement and are willing to run it as a service.

Official sources

1. cosmicstack-labs/mercury-agent on GitHub
2. License: MIT
3. Project website
4. README
5. Releases