Mercury Agent: a soul-driven CLI agent that asks before it acts
Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI or Telegram.
At a glance
- What is it?
- Mercury is a TypeScript AI agent from Cosmic Stack that runs from the CLI, Telegram or Web, ships 31 built-in tools, and gates every shell command behind a permission mode. Here is what the README and repository actually specify, and where the gaps are.
- Who is it for?
- Adopt Mercury if you want a long-running personal agent whose tool calls are gated by an explicit permission mode and whose memory lives in a SQLite file you can inspect. Skip it if you need a hosted control plane with an admin console, or if you are looking for an enterprise support contract: the README documents no such thing, and the related searches for a login portal, support number or agent locator do not match anything in the repository.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 27, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The problem Mercury Agent targets: an agent that touches your machine silently
Most agent frameworks give the model a shell tool and a file tool and let it run. Mercury's README frames the opposite position in one line: "Mercury asks first, and remembers what matters." That is the whole pitch. The project is aimed at a single operator who wants an assistant living on their own machine or VPS, reachable from a terminal and from Telegram, with a record of what it did and a gate in front of destructive commands.
The target user is not a platform team. It is one engineer, or a small group, running a personal agent 24/7. The README lists the pieces that support that shape of use: 31 built-in tools, Kanban boards, extensible skills, and a SQLite-backed Second Brain. The package description in package.json repeats the same framing, so the positioning is consistent between the README and the published metadata.
Where this differs from a general agent library is the assumption of persistence. A daemon, a boot service, cron scheduling and heartbeat monitoring only make sense if the agent is expected to outlive the terminal session that started it. That assumption drives most of the design decisions below, including the ones that are inconvenient.
How Mercury Agent works: soul files, a SQLite Second Brain and a permission gate
Three mechanisms are visible in the repository and the README, and they are separable.
The first is the soul. Personality is defined by markdown files the user owns: soul.md, persona.md, taste.md and heartbeat.md. These are plain files, not a prompt template compiled into the binary, which means the agent's character is editable without rebuilding anything. The README calls this "soul-driven" and contrasts it with a "corporate wrapper". That is marketing language, but the underlying claim is checkable: the files are yours and they are markdown.
The second is memory. The Second Brain is described as persistent, structured memory on SQLite with FTS5 full-text search, 10 memory types, auto-extraction, conflict resolution and auto-consolidation. FTS5 is a real SQLite extension, and using it means memory retrieval is a local query rather than a vector call to a hosted service. The trade-off is that retrieval quality depends on keyword and full-text matching rather than embeddings, and the README does not describe a hybrid or vector path. For a personal agent that mostly needs to recall stated preferences and goals, that is a reasonable fit. For a corpus where the user and the agent use different vocabulary for the same thing, full-text search will miss.
The third is the permission layer. The README lists a shell blocklist (sudo, rm -rf /, and similar commands "never execute"), folder-level read and write scoping, a pending approval flow, and a per-session choice between Ask Me and Allow All. The permission mode is asked before chat starts, which means the gate is a session-level decision rather than a per-call prompt. That is a real design choice with a real consequence: in Allow All mode the blocklist and folder scoping are the only remaining protections, and the README does not describe a per-command confirmation inside that mode.
Installing Mercury Agent and running a first session
The README gives three install paths. The standalone binary needs no Node.js:
curl -fsSL https://mercuryagent.sh/install.sh | shOn Windows the equivalent is a PowerShell one-liner:
irm https://mercuryagent.sh/install.ps1 | iexIf Node.js 20 or newer is already present, npm works instead. Running without installing is the quickest check:
npx @cosmicstack/mercury-agentOr install the package globally, which puts a mercury binary on your path:
npm i -g @cosmicstack/mercury-agent
mercuryAccording to the README, the first run triggers a setup wizard that asks for a name, a provider, and optionally Telegram. After setup, Mercury opens the Ink TUI startup screen and asks you to pick a permission mode, Ask Me or Allow All, before chat starts. That is the point where you should choose deliberately rather than by habit.
Reconfiguration is handled by a separate command, and there is a platform diagnostics flag if the daemon or terminal behaves oddly:
mercury doctor
mercury doctor --platformProvider credentials come from environment variables. The repository ships a .env.example that documents the full set, including MERCURY_NAME, MERCURY_OWNER, and per-provider keys such as OPENAI_API_KEY, ANTHROPIC_API_KEY and DEEPSEEK_API_KEY. If you want a local model with no API key, the example file shows OLLAMA_LOCAL_BASE_URL pointing at http://127.0.0.1:11434/api with OLLAMA_LOCAL_ENABLED=false, so enabling it is an explicit edit on your side. Note that the README's install instructions and the .env.example are two different configuration surfaces; the README does not explain how they interact, and a reader who sets both could reasonably be unsure which wins.
Running Mercury Agent as a daemon and reaching it from Telegram
The persistent mode is one command:
mercury upThe README states that this installs the system service if it is not already installed, starts the background daemon, and ensures Mercury is running. If the process is already up, it reports the PID instead. The supporting commands are mercury restart, mercury stop, mercury start -d, mercury logs and mercury status.
The service layer is platform-specific and the README is explicit about the mechanism for each: a LaunchAgent under ~/Library/LaunchAgents/ on macOS, a systemd user unit under ~/.config/systemd/user/ on Linux, and Task Scheduler via schtasks on Windows. None require admin rights, though the README notes that Linux needs linger enabled for start-on-boot. That detail matters: without linger, a user unit stops when the session ends, and the agent is not actually 24/7.
Crash recovery is built in, with automatic restart and exponential backoff capped at 10 restarts per minute. That cap is the honest part of the design. A crash loop will not be masked indefinitely; it will hit the ceiling and stop restarting, which is the behaviour you want but also the behaviour you need to monitor.
The README states plainly that in daemon mode Telegram becomes the primary channel because CLI is log-only with no terminal for input. Telegram access is not open by default. Users are approved through an explicit command set: mercury telegram list, approve, reject, remove, promote, demote and reset. The promote and demote commands imply a two-tier model of admins and members, though the README does not describe what an admin can do that a member cannot.
Where Mercury Agent gets in the way
The permission model is a session-level choice, not a per-action prompt. If you pick Allow All, the README's protections reduce to the shell blocklist and folder scoping. A blocklist is a denylist, and denylists are bypassable in principle: the README names sudo and rm -rf / as examples of what never executes, but it does not claim the list is exhaustive, and no denylist of shell strings can be. If your threat model includes a model that is actively trying to work around restrictions, this is not the tool for that.
The memory layer is full-text, not semantic. FTS5 is fast and local, but it matches tokens. A user who says "I hate long meetings" and later asks the agent about "calendar preferences" is relying on the auto-extraction and consolidation logic to have already normalized that into a retrievable memory type, and the README does not document how well that holds up.
Configuration is split across the setup wizard, mercury doctor, and a .env file with a long provider list. The .env.example alone covers OpenAI, Anthropic, DeepSeek, Grok, Atlas Cloud, AI/ML API, Ollama Cloud, Ollama Local, a generic OpenAI-compatible slot, and two MiMo variants. That is a lot of surface for a personal agent, and the README does not state a precedence order between wizard-written config and environment variables.
Finally, the related searches for this project include phrases like "mercury agent login portal", "mercury agent support number" and "mercury agent near me". None of those map to anything in the repository. There is no hosted portal, no support line, and no physical presence. Anyone arriving with that expectation is looking at a different kind of product than the one described here.
Mercury Agent compared with a hosted assistant like Hermes
The obvious comparison, and one people search for directly, is Mercury against Hermes. The difference is architectural rather than feature-level.
Hermes-style hosted assistants run the agent loop on someone else's infrastructure. You get a web interface, the provider keys are managed for you, and the machine the tools touch is a sandbox the vendor controls. Setup is an account, not an install.
Mercury inverts that. The agent process runs on your machine, the memory is a SQLite file on your disk, the soul is markdown you edit, and the API keys are environment variables you supply. The tools operate on your real filesystem, which is precisely why the permission layer exists at all. In a hosted sandbox you do not need a shell blocklist; on your own laptop you do.
The cost of that inversion is operational. You install a daemon, you enable linger on Linux, you approve Telegram users one by one, and you watch for the restart ceiling. The benefit is that nothing about the agent's state is outside your reach. If that trade does not appeal, a hosted assistant is the better fit and Mercury is the wrong tool.
Licence, upgrades and the maintenance cost of a self-hosted agent
The licence is MIT, per both the repository metadata and the LICENSE file at the top level. MIT permits commercial use, modification and redistribution with the copyright notice preserved. That is a permissive arrangement and it means you can fork the project if the upstream direction stops suiting you. It says nothing about the provider terms you accept when you plug in an API key, and those are separate agreements you should read on their own.
Upgrades have a dedicated command, mercury upgrade, which the README describes as upgrading to the latest version. Release history shows a steady cadence: v1.2.3 on 2026-09-08, v1.2.2 on 2026-08-10, and v1.1.13 on 2026-06-18. The last push to the repository was on 2026-09-09, so the project is current as of this writing. Note that package.json declares version 1.2.7 while the README's badge and "Current Stable" line say v1.2.3, so the README lags the package. Verify which version you actually have with mercury status rather than trusting the README banner.
The real maintenance cost is not the upgrade command. It is the daemon. A self-hosted agent that starts on boot, restarts on crash, and holds API keys needs a machine that stays on, and it needs you to read mercury logs when the restart ceiling is reached. The README documents mercury logs and mercury status for exactly that purpose but does not document alerting when the daemon stops. That gap is yours to fill.
Editorial conclusion
Adopt Mercury if you want a long-running personal agent whose tool calls are gated by an explicit permission mode and whose memory lives in a SQLite file you can inspect. Skip it if you need a hosted control plane with an admin console, or if you are looking for an enterprise support contract: the README documents no such thing, and the related searches for a login portal, support number or agent locator do not match anything in the repository. Before committing, verify three things yourself: that your chosen provider key works through mercury doctor, that the daemon survives a reboot on your platform via mercury service status, and that the shell blocklist plus folder scoping match the directories you actually care about.
Frequently asked questions
What is Mercury AI Agent?
It is a TypeScript AI agent from Cosmic Stack that runs from the CLI, Telegram or Web, with 31 built-in tools, a SQLite-backed Second Brain memory, and a permission layer that gates shell and file access. The README describes it as soul-driven, meaning its personality comes from markdown files you own.
What are Mercury's powers and abilities?
The README lists 31 built-in tools, Kanban boards, extensible skills based on the Agent Skills specification, persistent memory with FTS5 search across 10 memory types, daily token budgets, live token streaming, and daemon mode with cron scheduling and heartbeat monitoring. Telegram access is controlled through a set of approve, reject, promote and demote commands.
what is mercury agent
The package is published as @cosmicstack/mercury-agent and installs either as a standalone binary through a shell script or through npm with Node.js 20 or newer. Its distinguishing feature is that it asks for a permission mode, Ask Me or Allow All, before chat starts.
mercury agent vs hermes
Mercury runs the agent loop on your own machine, with memory in a local SQLite file and API keys in your environment, while a hosted assistant like Hermes runs the loop on vendor infrastructure. That is why Mercury ships a shell blocklist and folder scoping and a hosted assistant does not need one.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/cosmicstack-labs-mercury-agent)