[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-676":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":24,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":29,"readmeContent":30,"aiSummary":31,"trendingCount":15,"starSnapshotCount":15,"syncStatus":32,"lastSyncTime":33,"discoverSource":34},676,"mercury-agent","cosmicstack-labs\u002Fmercury-agent","cosmicstack-labs","Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24\u002F7 from CLI or Telegram.","https:\u002F\u002Fmercury.cosmicstack.org\u002F",null,"TypeScript",2611,270,13,0,42,108,493,126,29.3,"MIT License",false,"main",true,[26,27,28],"ai-agent","ai-assistant","llm","2026-06-12 02:00:17","\u003Cp align=\"center\">\n  \u003Cpicture>\n    \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs\u002Fimg\u002Fcard-dark.png\">\n    \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"docs\u002Fimg\u002Fcard-light.png\">\n    \u003Cimg alt=\"Mercury — Soul-Driven AI Agent\" src=\"docs\u002Fimg\u002Fcard-light.png\" width=\"600\">\n  \u003C\u002Fpicture>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access.\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  Remembers what matters. Asks before it acts. Runs 24\u002F7 from CLI or Telegram. 31 built-in tools, extensible skills, SQLite-backed Second Brain memory.\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@cosmicstack\u002Fmercury-agent\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@cosmicstack\u002Fmercury-agent\" alt=\"npm\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fcosmicstack-labs\u002Fmercury-agent\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fcosmicstack-labs\u002Fmercury-agent\" alt=\"license\">\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fnodejs.org\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnode\u002Fv\u002F@cosmicstack\u002Fmercury-agent\" alt=\"node\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>🔖 Current Stable: v1.1.6\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  English | \u003Ca href=\"README.zh-CN.md\">简体中文\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## Quick Start\n\n```bash\nnpx @cosmicstack\u002Fmercury-agent\n```\n\nOr install globally:\n\n```bash\nnpm i -g @cosmicstack\u002Fmercury-agent\nmercury\n```\n\nFirst 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.\n\nTo reconfigure later (change keys, name, settings):\n\n```bash\nmercury doctor\nmercury doctor --platform\n```\n\n## Why Mercury?\n\nEvery AI agent can read files, run commands, and fetch URLs. Most do it silently. **Mercury asks first — and remembers what matters.**\n\n- **Permission-hardened** — Shell blocklist (`sudo`, `rm -rf \u002F`, etc. never execute). Folder-level read\u002Fwrite scoping. Pending approval flow. Ask Me or Allow All per session. No surprises.\n- **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.\n- **Soul-driven** — Personality defined by markdown files you own (`soul.md`, `persona.md`, `taste.md`, `heartbeat.md`). No corporate wrapper.\n- **Token-aware** — Daily budget enforcement. Auto-concise when over 70%. `\u002Fbudget` command to check, reset, or override.\n- **Live streaming** — Real-time token streaming on CLI with cursor-save\u002Frestore and markdown re-rendering. Telegram streaming with editable status messages.\n- **Always on** — Run as a background daemon on any OS. Auto-restarts on crash. Starts on boot. Cron scheduling, heartbeat monitoring, and proactive notifications.\n- **Extensible** — Install community skills with a single command. Schedule skills as recurring tasks. Based on the [Agent Skills](https:\u002F\u002Fagentskills.io) specification.\n\nMercury now seeds a default `web-search` skill on first run in `~\u002F.mercury\u002Fskills\u002Fweb-search\u002FSKILL.md`.\n\n## Daemon Mode\n\n**One command to make Mercury persistent:**\n\n```bash\nmercury up\n```\n\nThis installs the system service (if not installed), starts the background daemon, and ensures Mercury is running. Use this as your go-to command.\n\nIf Mercury is already running, `mercury up` just confirms it and shows the PID.\n\n### Other daemon commands\n\n```bash\nmercury restart      # Restart the background process\nmercury stop         # Stop the background process\nmercury start -d     # Start in background (without service install)\nmercury logs         # View recent daemon logs\nmercury status       # Show if daemon is running\n```\n\nDaemon mode includes built-in crash recovery — if the process crashes, it restarts automatically with exponential backoff (up to 10 restarts per minute).\n\n### System Service (auto-start on boot)\n\n`mercury up` installs this automatically. You can also manage it directly:\n\n```bash\nmercury service install\n```\n\n| Platform | Method | Requires Admin |\n|----------|--------|---------------|\n| **macOS** | LaunchAgent (`~\u002FLibrary\u002FLaunchAgents\u002F`) | No |\n| **Linux** | systemd user unit (`~\u002F.config\u002Fsystemd\u002Fuser\u002F`) | No (linger for boot) |\n| **Windows** | Task Scheduler (`schtasks`) | No |\n\n```bash\nmercury service status     # Check if service is running\nmercury service uninstall  # Remove the system service\n```\n\nIn daemon mode, Telegram becomes your primary channel — CLI is log-only since there's no terminal for input.\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `mercury up` | **Recommended.** Install service + start daemon + ensure running |\n| `mercury` | Start the agent (same as `mercury start`) |\n| `mercury start` | Start in foreground |\n| `mercury start -d` | Start in background (daemon mode) |\n| `mercury restart` | Restart the background process |\n| `mercury stop` | Stop a background process |\n| `mercury logs` | View recent daemon logs |\n| `mercury doctor` | Reconfigure setup (name, providers, channels, permissions defaults) |\n| `mercury doctor --platform` | Show cross-platform terminal\u002Fdaemon compatibility diagnostics |\n| `mercury setup` | Re-run the setup wizard |\n| `mercury status` | Show config and daemon status |\n| `mercury help` | Show full manual |\n| `mercury upgrade` | Upgrade to latest version |\n| `mercury telegram list` | List approved and pending Telegram users |\n| `mercury telegram approve \u003Ccode\\|id>` | Approve a pairing code or pending request |\n| `mercury telegram reject \u003Cid>` | Reject a pending Telegram access request |\n| `mercury telegram remove \u003Cid>` | Remove an approved Telegram user |\n| `mercury telegram promote \u003Cid>` | Promote a Telegram member to admin |\n| `mercury telegram demote \u003Cid>` | Demote a Telegram admin to member |\n| `mercury telegram reset` | Clear all Telegram access and start fresh |\n| `mercury service install` | Install as system service (auto-start on boot) |\n| `mercury service uninstall` | Uninstall system service |\n| `mercury service status` | Show system service status |\n| `mercury --verbose` | Start with debug logging |\n\n## In-Chat Commands\n\nType these during a conversation — they don't consume API tokens. Work on both CLI and Telegram.\n\n| Command | Description |\n|---------|-------------|\n| `\u002Fhelp` | Show the full manual |\n| `\u002Fstatus` | Show agent config, budget, and usage |\n| `\u002Ftools` | List all loaded tools |\n| `\u002Fskills` | List installed skills |\n| `\u002Fstream` | Toggle Telegram text streaming |\n| `\u002Fstream off` | Disable streaming (single message) |\n| `\u002Fbudget` | Show token budget status |\n| `\u002Fbudget override` | Override budget for one request |\n| `\u002Fbudget reset` | Reset usage to zero |\n| `\u002Fbudget set \u003Cn>` | Change daily token budget |\n| `\u002Fpermissions` | Change permission mode (Ask Me \u002F Allow All) |\n| `\u002Fview` | Toggle progress view (balanced\u002Fdetailed) |\n| `\u002Fview balanced` | Set compact progress view |\n| `\u002Fview detailed` | Set full progress view |\n| `\u002Fcode agent \u003Ctask>` | Delegate a coding task to a sub-agent in background |\n| `\u002Fws exit` | Exit workspace IDE mode back to general chat |\n| `\u002Ftasks` | List scheduled tasks |\n| `\u002Fmemory` | View and manage second brain memory |\n| `\u002Funpair` | Telegram: reset all access |\n\n## Built-in Tools\n\n| Category | Tools |\n|----------|-------|\n| **Filesystem** | `read_file`, `write_file`, `create_file`, `edit_file`, `list_dir`, `delete_file`, `send_file`, `approve_scope` |\n| **Shell** | `run_command`, `cd`, `approve_command` |\n| **Messaging** | `send_message` |\n| **Git** | `git_status`, `git_diff`, `git_log`, `git_add`, `git_commit`, `git_push` |\n| **Web** | `fetch_url` |\n| **Skills** | `install_skill`, `list_skills`, `use_skill` |\n| **Scheduler** | `schedule_task`, `list_scheduled_tasks`, `cancel_scheduled_task` |\n| **System** | `budget_status` |\n\n## Channels\n\n| Channel | Features |\n|---------|----------|\n| **CLI** | Ink TUI, startup permission mode picker, interactive permission prompts (arrow keys + Enter; Y\u002FN\u002FA shortcuts), progress views (balanced\u002Fdetailed), real-time streaming |\n| **Telegram** | HTML formatting, editable streaming messages, file uploads, typing indicators, multi-user access with admin\u002Fmember roles |\n\n### Workspace\u002FCoding Shortcuts (CLI)\n\n- `Ctrl+P` → switch to Plan mode\n- `Ctrl+X` → switch to Execute mode\n- `Esc` or `Ctrl+Q` → exit workspace to general chat\n- `Ctrl+V` → toggle progress view (`\u002Fview` is fallback when terminal intercepts Ctrl+V)\n\n### Spotify UI Notes (CLI)\n\n- Spotify deck supports keyboard shortcuts: `N` next, `P` previous, `+\u002F-` volume, `Z` now playing.\n- Inline album art is optional and safe-gated:\n  - Enable with `MERCURY_SPOTIFY_ART=1`\n  - Currently renders only in local iTerm sessions\n  - Automatically falls back to text-only UI in SSH\u002Fmobile\u002Flight terminals\n\n### Telegram Access\n\nMercury uses an **organization access model** with admins and members.\n\n- **First-time setup:** Send `\u002Fstart` to your bot, receive a pairing code, enter it in the CLI with `mercury telegram approve \u003Ccode>`. You become the first admin.\n- **Additional users:** Send `\u002Fstart` to request access. Admins approve or reject from the CLI.\n- **Roles:** Admins can approve\u002Freject requests, promote\u002Fdemote users, and reset access. Members can chat with Mercury.\n- **Reset:** Admins can send `\u002Funpair` in Telegram or run `mercury telegram reset` in the CLI to clear all access and start fresh.\n- Private chats only — group messages are always ignored.\n\nCLI commands: `mercury telegram list|approve|reject|remove|promote|demote|reset`\n\n## Scheduler\n\n- **Recurring**: `schedule_task` with cron expressions (`0 9 * * *` for daily at 9am)\n- **One-shot**: `schedule_task` with `delay_seconds` (e.g. 15 seconds)\n- Tasks persist to `~\u002F.mercury\u002Fschedules.yaml` and restore on restart\n- Responses route back to the channel where the task was created\n\n## Second Brain\n\nMercury builds a structured, persistent memory that grows with every conversation. Enabled by default, it automatically extracts, stores, and recalls facts about you.\n\n- **10 memory types** — identity, preference, goal, project, habit, decision, constraint, relationship, episode, reflection\n- **Automatic extraction** — after each conversation, Mercury pulls 0–3 facts with confidence, importance, and durability scores\n- **Relevant recall** — before each message, the top 5 matching memories (900-char budget) are injected into context\n- **Auto-consolidation** — every 60 min, Mercury builds a profile summary, active-state summary, and generates reflections from patterns\n- **Conflict resolution** — opposing memories are resolved by confidence (higher wins) or recency (newer wins)\n- **Auto-pruning** — active-scope memories stale after 21 days; inferred memories decay; low-confidence durable memories dismissed after 120 days\n- **User controls** — `\u002Fmemory` for overview, search, pause, resume, and clear\n- **Disable** — `SECOND_BRAIN_ENABLED=false` env var or `memory.secondBrain.enabled: false` in config\n\nAll data stays on your machine in `~\u002F.mercury\u002Fmemory\u002Fsecond-brain\u002Fsecond-brain.db` (SQLite + FTS5). No cloud.\n\n## Configuration\n\nAll runtime data lives in `~\u002F.mercury\u002F` — not in your project directory.\n\n| Path | Purpose |\n|------|---------|\n| `~\u002F.mercury\u002Fmercury.yaml` | Main config (providers, channels, budget) |\n| `~\u002F.mercury\u002F.env` | API keys and tokens (loaded alongside project .env) |\n| `~\u002F.mercury\u002Fsoul\u002F*.md` | Agent personality (soul, persona, taste, heartbeat) |\n| `~\u002F.mercury\u002Fpermissions.yaml` | Capabilities and approval rules |\n| `~\u002F.mercury\u002Fskills\u002F` | Installed skills |\n| `~\u002F.mercury\u002Fschedules.yaml` | Scheduled tasks |\n| `~\u002F.mercury\u002Ftoken-usage.json` | Daily token usage tracking |\n| `~\u002F.mercury\u002Fmemory\u002Fshort-term\u002F` | Per-conversation JSON files |\n| `~\u002F.mercury\u002Fmemory\u002Flong-term\u002F` | Auto-extracted facts (JSONL) |\n| `~\u002F.mercury\u002Fmemory\u002Fepisodic\u002F` | Timestamped event log (JSONL) |\n| `~\u002F.mercury\u002Fmemory\u002Fsecond-brain\u002F` | Structured memory database (SQLite + FTS5) |\n| `~\u002F.mercury\u002Fdaemon.pid` | Background process PID |\n| `~\u002F.mercury\u002Fdaemon.log` | Daemon mode logs |\n\n## Provider Fallback\n\nConfigure multiple LLM providers. Mercury tries them in order and falls back automatically:\n\n| Provider | Default Model | API Key | Notes |\n|----------|--------------|---------|-------|\n| **DeepSeek** | deepseek-chat | `DEEPSEEK_API_KEY` | Default, cost-effective |\n| **OpenAI** | gpt-4o-mini | `OPENAI_API_KEY` | GPT-4o, o3, etc. |\n| **Anthropic** | claude-sonnet-4 | `ANTHROPIC_API_KEY` | Claude Sonnet, Haiku, Opus |\n| **Grok (xAI)** | grok-4 | `GROK_API_KEY` | OpenAI-compatible endpoint |\n| **Ollama Cloud** | gpt-oss:120b | `OLLAMA_CLOUD_API_KEY` | Remote Ollama via API |\n| **Ollama Local** | gpt-oss:20b | No key needed | Local Ollama instance |\n\nWhen a provider fails, Mercury automatically tries the next one. It remembers the last successful provider and starts there on the next request.\n\n> **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.\n\n## Architecture\n\n- **TypeScript + Node.js 18+** — ESM, tsup build\n- **Vercel AI SDK v4** — `generateText` + `streamText`, 10-step agentic loop, provider fallback\n- **grammY** — Telegram bot with typing indicators, editable streaming, and file uploads\n- **SQLite + FTS5** — Second brain with full-text search, conflict resolution, auto-consolidation\n- **JSONL** — Short-term, long-term, and episodic conversation memory\n- **Daemon manager** — Background spawn + PID file + watchdog crash recovery\n- **System services** — macOS LaunchAgent, Linux systemd, Windows Task Scheduler\n\n## License\n\nMIT © [Cosmic Stack](https:\u002F\u002Fgithub.com\u002Fcosmicstack-labs)\n\n---\n\n## Disclaimer\n\n**This is AI - it can break sometimes, please use this at your own risk.**\n\n---\n\n## Contributing\n\nWe'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.\n\n### 🎯 Agentic Expertise — Must-Have for Contributors\n\nMercury isn't just another open-source project — it's a **soul-driven agent** that runs 24\u002F7, 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:\n\n| Principle | What It Means |\n|-----------|---------------|\n| 🧠 **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. |\n| 🔐 **Permission-first** | Every action that touches the outside world (files, shell, network, git) must go through the permission system. Never assume approval. |\n| 💾 **Memory-aware** | If your feature generates facts about the user, consider hooking into the Second Brain. If it reads user data, check memory first. |\n| 📏 **Token-conscious** | Mercury has a daily token budget. Logging, verbose outputs, and large context dumps burn tokens fast. Keep it lean. |\n| 🔌 **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. |\n| 🔁 **Graceful degradation** | If a provider fails, a tool errors, or a file doesn't exist — Mercury should recover, not crash. Always handle edge cases. |\n| 📋 **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. |\n| 🧪 **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. |\n\n### Code Quality — Dos\n\n| Do | Why |\n|----|-----|\n| ✅ Write clean, readable TypeScript with explicit types | Mercury's codebase is type-safe — keep it that way |\n| ✅ Add JSDoc comments on public functions and tools | Helps other contributors and the agent understand intent |\n| ✅ Keep functions small and single-purpose | Easier to test, review, and reason about |\n| ✅ Use async\u002Fawait over raw promises | Consistent error handling and readability |\n| ✅ Write tests for new tools and memory features | Reliability matters for a 24\u002F7 agent |\n| ✅ Follow the existing project structure (`src\u002Ftools\u002F`, `src\u002Fmemory\u002F`, `src\u002Fchannels\u002F`) | Keeps the codebase navigable |\n| ✅ Use the Agent Skills spec for new skill-based features | Ensures compatibility with the skills ecosystem |\n| ✅ Document breaking changes in PR descriptions | Helps maintainers version properly |\n\n### Code Quality — Don'ts\n\n| Don't | Why |\n|-------|-----|\n| ❌ Don't add dependencies without discussion | Mercury is lean — every dep adds surface area |\n| ❌ Don't hardcode API keys, tokens, or paths | Use config\u002Fenv vars like the rest of the codebase |\n| ❌ Don't bypass the permission system | Tools must ask before acting — that's Mercury's core promise |\n| ❌ Don't introduce sync\u002Fblocking I\u002FO in hot paths | Mercury is async-first for a reason |\n| ❌ Don't commit large binary files or secrets | Use `.gitignore` and env files |\n| ❌ Don't change the soul\u002Fpersona system without discussion | It's the heart of Mercury — changes need care |\n| ❌ Don't submit untested Telegram or daemon changes | These are hard to debug post-merge |\n| ❌ Don't ignore the token budget system | Every tool should be mindful of token consumption |\n\n### Getting Started\n\n1. Fork the repo\n2. Run `npm install`\n3. Make your changes\n4. Run `npm run build` to verify it compiles\n5. Test with `mercury` locally\n6. Open a PR with a clear description of what you changed and why\n\n### PR Guidelines\n\n- Keep PRs focused — one feature\u002Ffix per PR\n- Include before\u002Fafter behavior in the description\n- Tag related issues if applicable\n- Be responsive to review feedback\n\n### Need Help?\n\nOpen an issue or reach out at [mercury@cosmicstack.org](mailto:mercury@cosmicstack.org). We're friendly.\n\n---\n\n## Community\n\n1. **Discord** — [Join the Mercury Agent Discord](https:\u002F\u002Fdiscord.gg\u002F5emMpMJy5J) for real-time chat, support, and community discussions.\n","Mercury Agent 是一个具有权限强化工具、令牌预算和多渠道访问的灵魂驱动AI代理，支持24\u002F7运行于命令行或Telegram。其核心功能包括权限硬化的安全措施（如黑名单阻止危险命令）、基于SQLite的持久化记忆系统（支持全文搜索与自动提取）、个性化的灵魂定义文件以及每日令牌预算管理。这些特性使得Mercury能够在确保安全性的同时，学习并适应用户的偏好和习惯。适用于需要长期运行且对安全性有较高要求的个人助手场景，特别是在开发者希望为其项目添加智能辅助功能时尤为适用。",2,"2026-06-11 02:38:34","CREATED_QUERY"]