mercury-agent-deployment

# Mercury Agent Deployment > Skill by [ara.so](https://ara.so) — AI Agent Skills collection. Mercury is a soul-driven AI agent framework with permission-hardened tools, token budgets, multi-channel access (CLI + Telegram), persistent memory (Second Brain), and 24/7 daemon mode. It runs TypeScript-based agents with 31 built-in tools, extensible skills, and SQLite-backed memory. ## Installation ### Quick Start (npx) ```bash npx @cosmicstack/mercury-agent ``` ### Global Installation ```bash npm i -g @cosmicstack/mercury-agent mercury ``` First run triggers setup wizard for: - Agent name - LLM provider (OpenAI, Anthropic, etc.) - Optional Telegram bot integration - Permission defaults ## Core Commands ### Daemon & Service Management ```bash # Recommended: install service + start daemon mercury up # Start in foreground mercury start # Start as background daemon mercury start -d # Daemon control mercury restart mercury stop mercury logs mercury status # System service (auto-start on boot) mercury service install mercury service status mercury service uninstall ``` ### Configuration ```bash # Reconfigure setup mercury doctor # Platform diagnostics mercury doctor --platform # Re-run setup wizard mercury setup # Check status mercury status # Upgrade to latest mercury upgrade ``` ### Telegram Access Management ```bash # List all users mercury telegram list # Approve pairing code or pending request mercury telegram approve <code|id> # Reject pending request mercury telegram reject <id> # Remove approved user mercury telegram remove <id> # Role management mercury telegram promote <id> mercury telegram demote <id> # Reset all access mercury telegram reset ``` ## Configuration Files All runtime data in `~/.mercury/`: ``` ~/.mercury/ ├── mercury.yaml # Main config ├── .env # API keys ├── permissions.yaml # Tool capabilities ├── token-usage.json # Budget tracking ├── schedules.yaml # Scheduled tasks ├── soul/ # Personality files │ ├── soul.md │ ├── persona.md │ ├── taste.md │ └── heartbeat.md ├── skills/ # Installed skills ├── memory/ │ ├── short-term/ # Conversation JSON │ ├── long-term/ # Extracted facts (JSONL) │ ├── episodic/ # Event log (JSONL) │ └── second-brain/ # SQLite + FTS5 └── logs/ ``` ### Example mercury.yaml ```yaml agentName: Mercury soul: path: ~/.mercury/soul providers: - type: openai model: gpt-4o apiKeyEnv: OPENAI_API_KEY - type: anthropic model: claude-3-5-sonnet-20241022 apiKeyEnv: ANTHROPIC_API_KEY channels: telegram: enabled: true tokenEnv: TELEGRAM_BOT_TOKEN persistence: ~/.mercury/telegram.json permissions: defaultMode: ask filesystem: read: ask write: ask delete: ask shell: execute: ask blocklist: - sudo - rm -rf / - mkfs - dd if= budget: daily: 200000 warningThreshold: 0.7 memory: secondBrain: enabled: true dbPath: ~/.mercury/memory/second-brain/second-brain.db ``` ### Example .env ```bash # LLM Providers OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... # Telegram TELEGRAM_BOT_TOKEN=123456:ABC-DEF... # Optional: Spotify (for music control tools) SPOTIFY_CLIENT_ID=... SPOTIFY_CLIENT_SECRET=... # Optional: Enable inline album art (iTerm only) MERCURY_SPOTIFY_ART=1 # Optional: Disable Second Brain SECOND_BRAIN_ENABLED=false ``` ## In-Chat Commands These work in both CLI and Telegram without consuming tokens: ```bash /help # Show manual /status # Config, budget, usage /tools # List loaded tools /skills # List installed skills /budget # Token budget status /budget override # Override budget once /budget reset # Reset usage to zero /budget set <n> # Change daily limit /permissions # Toggle Ask Me / Allow All /view # Toggle balanced/detailed progress /stream # Toggle Telegram streaming /code agent <task> # Delegate coding task to sub-agent /ws exit # Exit workspace IDE mode /tasks # List scheduled tasks /memory # View/manage Second Brain /unpair # Telegram: reset access ``` ## Built-in Tools ### Filesystem Tools ```typescript // Mercury auto-requests permission for file operations // Example conversation: // User: "Read package.json" // Mercury uses: read_file // Approve folder scope for batch operations // User: "Read all TypeScript files in src/" // Mercury prompts: approve_scope for src/ // File operations read_file({ path: "package.json" }) write_file({ path: "config.json", content: "{...}" }) create_file({ path: "new.ts", content: "export ..." }) edit_file({ path: "app.ts", operations: [...] }) list_dir({ path: "src/" }) delete_file({ path: "temp.txt" }) send_file({ path: "report.pdf" }) // Telegram only ``` ### Shell Tools ```typescript // Blocklist prevents dangerous commands // Blocked: sudo, rm -rf /, mkfs, dd if=, etc. run_command({ command: "npm install" }) cd({ path: "/path/to/project" }) approve_command({ command: "git push" }) // Pre-approve ``` ### Git Tools ```typescript git_status() git_diff({ staged: true }) git_log({ limit: 10 }) git_add({ files: ["src/app.ts"] }) git_commit({ message: "feat: add feature" }) git_push() ``` ### Web Tools ```typescript fetch_url({ url: "https://api.example.com/data" }) ``` ### Messaging Tools ```typescript // Send proactive messages send_message({ channel: "telegram", content: "Build complete!" }) ``` ### Scheduler Tools ```typescript // Recurring task (cron syntax) schedule_task({ name: "morning-standup", cron: "0 9 * * *", // 9am daily task: "Send standup reminder" }) // One-shot delayed task schedule_task({ name: "reminder", delay_seconds: 900, // 15 minutes task: "Check deployment status" }) list_scheduled_tasks() cancel_scheduled_task({ name: "morning-standup" }) ``` ### Skill Management Tools ```typescript // Install community skill install_skill({ name: "web-search" }) // List installed list_skills() // Execute skill use_skill({ name: "web-search", query: "latest TypeScript features" }) ``` ## Creating Custom Skills Skills are markdown files in `~/.mercury/skills/<skill-name>/SKILL.md`: ### Example: GitHub Integration Skill ```bash mkdir -p ~/.mercury/skills/github-pr-review ``` `~/.mercury/skills/github-pr-review/SKILL.md`: ```markdown --- name: github-pr-review description: Review GitHub pull requests and provide feedback triggers: - "review this pull request" - "check github pr" - "analyze code changes" --- # GitHub PR Review Skill ## Prerequisites ```bash # Install GitHub CLI brew install gh # macOS # or: sudo apt install gh # Linux # Authenticate gh auth login ``` ## Usage When user requests PR review: 1. Fetch PR diff: `gh pr diff <number>` 2. Analyze changes for: - Code quality - Security issues - Breaking changes - Test coverage 3. Post review: `gh pr review <number> --comment -b "feedback"` ## Example Flow ```bash # Get PR list gh pr list # Get diff gh pr diff 123 # Review with approval gh pr review 123 --approve -b "LGTM! Great work on error handling." # Request changes gh pr review 123 --request-changes -b "Please add tests for the new endpoint." ``` ## Best Practices - Always check CI status before review - Look for security vulnerabilities in dependencies - Verify backward compatibility - Check for adequate test coverage ``` ### Install Custom Skill ```bash # Mercury auto-detects skills in ~/.mercury/skills/ # Or install programmatically: mercury # Start agent # In chat: # User: "Install the github-pr-review skill" # Mercury uses: install_skill ``` ## Second Brain Memory System Mercury's persistent memory system with automatic extraction and recall. ### Memory Types 1. **identity** — Core facts about user (name, role, location) 2. **preference** — User preferences (tools, coding style, communication) 3. **goal** — Objectives and targets 4. **project** — Active projects and context 5. **habit** — Recurring patterns and routines 6. **decision** — Important choices made 7. **constraint** — Limitations and boundaries 8. **relationship** — People and connections 9. **episode** — Significant events 10. **reflection** — Patterns and insights ### Memory Lifecycle ```typescript // Automatic after each conversation: // 1. Extract 0-3 facts with confidence/importance/durability scores // 2. Store in SQLite with FTS5 full-text search // 3. Auto-consolidation every 60 minutes // 4. Conflict resolution (higher confidence wins) // 5. Auto-pruning (stale after 21 days for active-scope) ``` ### Memory Commands ```bash # In-chat memory management /memory # Show overview /memory search AI # Search memories /memory pause # Pause extraction /memory resume # Resume extraction /memory clear # Clear all memories # Disable Second Brain entirely # In .env: SECOND_BRAIN_ENABLED=false # Or in mercury.yaml: memory: secondBrain: enabled: false ``` ### Memory Data Structure ```typescript // ~/.mercury/memory/second-brain/second-brain.db (SQLite) // Tables: // - memories: id, type, content, confidence, importance, durability // - memories_fts: FTS5 index for full-text search // - consolidations: profile summaries, active state, reflections // Example memory record: { type: "preference", content: "User prefers TypeScript over JavaScript for new projects", confidence: 0.95, importance: 0.8, durability: "durable", // or "transient" scope: "active", // or "background" extractedAt: "2026-05-16T10:30:00Z", lastAccessedAt: "2026-05-16T10:30:00Z" } ``` ## Permission System ### Permission Modes ```bash # Ask Me: Prompt for each tool use # Allow All: Auto-approve all tools # Toggle in-chat: /permissions # Or configure default in mercury.yaml: permissions: defaultMode: ask # or: allow ``` ### Permission Configuration `~/.mercury/permissions.yaml`: ```yaml filesystem: read: ask # ask, allow, deny write: ask delete: ask scopes: - path: ~/projects/safe-dir read: allow write: allow shell: execute: ask blocklist: - sudo - rm -rf / - mkfs - dd if= - "> /dev/" allowlist: - npm - git - node messaging: send: allow git: read: allow # status, diff, log write: ask # commit, push web: fetch: ask ``` ### Scope Approval ```bash # User: "Update all TypeScript files in src/ to use strict mode" # Mercury prompts: # ┌─────────────────────────────────────────┐ # │ Approve folder scope? │ # │ Path: ~/project/src │ # │ Read: allow │ # │ Write: allow │ # │ → Yes No Allow All │ # └─────────────────────────────────────────┘ # Keyboard shortcuts: # Y - Yes (approve this scope) # N - No (deny) # A - Allow All (switch to Allow All mode) # Arrow keys + Enter ``` ## Telegram Integration ### Bot Setup 1. Create bot with [@BotFather](https://t.me/botfather) 2. Get token from BotFather 3. Add to `~/.mercury/.env`: ```bash TELEGRAM_BOT_TOKEN=123456:ABC-DEF... ``` 4. Enable in `mercury.yaml`: ```yaml channels: telegram: enabled: true tokenEnv: TELEGRAM_BOT_TOKEN persistence: ~/.mercury/telegram.json ``` ### First-Time Pairing ```bash # 1. Start Mercury mercury up # 2. In Telegram, send to your bot: /start # 3. Bot responds with pairing code: TG-ABC123 # 4. In CLI, approve: mercury telegram approve TG-ABC123 # You're now the first admin! ``` ### Multi-User Access ```bash # Admin workflow: # 1. New user sends /start to bot