mercury-agent: 행동 전에 묻고 중요한 것을 기억하는 상시 구동 개인 AI 에이전트

9bow · 6월 29, 2026, 9:30오전

mercury-agent 소개

파일을 읽고, 명령을 실행하고, URL을 가져오는 일은 이제 대부분의 AI 에이전트가 할 수 있습니다. 문제는 그 대부분이 사용자에게 묻지 않고 조용히 실행한다는 점, 그리고 대화가 끝나면 방금 알게 된 사용자의 맥락을 잊어버린다는 점입니다. 개인용 에이전트를 상시 띄워 두고 쓰려면 이 두 가지가 특히 불편하게 다가옵니다.

mercury-agent(Mercury)는 이 두 지점을 정면으로 다루는 오픈소스 개인 AI 에이전트입니다. 행동하기 전에 먼저 승인을 묻고, 중요한 것을 구조화된 기억으로 남기는 것을 기본 동작으로 삼습니다. TypeScript로 작성되었고, CLI와 웹 대시보드, 텔레그램(Telegram)까지 세 개 채널에서 24시간 구동할 수 있으며, 권한이 제한된 31개의 내장 도구와 토큰 예산을 한데 묶어 제공합니다.

Mercury는 자신을 "기업용 래퍼가 아닌, 사용자가 소유한 마크다운 파일로 성격이 정의되는 영혼 기반(soul-driven) 에이전트" 로 소개합니다. 성격은 soul.md, persona.md, taste.md, heartbeat.md 같은 파일로 사용자가 직접 정의하고, 기억은 SQLite 기반의 세컨드 브레인(Second Brain)에 쌓이며, 토큰 사용량은 일일 예산으로 통제됩니다. 본 게시물에서는 Mercury의 핵심 설계와 설치·사용법을 정리합니다.

mercury-agent의 핵심 특징

Mercury가 다른 에이전트와 구분되는 지점은 "묻고 기억한다"는 두 축을 중심으로 정리됩니다. 주요 특징은 다음과 같습니다.

권한 강화(Permission-hardened): 셸 차단 목록으로 sudo, rm -rf / 같은 명령은 아예 실행되지 않게 막고, 폴더 단위로 읽기·쓰기 범위를 한정합니다. 실행 전에 승인을 기다리는 흐름이 있으며, 세션마다 Ask Me(매번 확인)와 Allow All(모두 허용) 모드를 고를 수 있습니다.
세컨드 브레인(Second Brain): SQLite와 FTS5 전문 검색(full-text search)을 결합한 영속적이고 구조화된 기억입니다. 10가지 기억 유형, 자동 추출, 충돌 해결, 자동 통합을 갖춰, 수동 입력 없이도 사용자의 선호와 목표, 습관을 학습합니다.
토큰 예산(Token-aware): 일일 토큰 예산을 강제하고, 사용량이 70%를 넘으면 자동으로 답변을 간결하게 줄입니다. /budget 명령으로 확인·초기화·재설정할 수 있습니다.
상시 구동(Always-on): 어떤 OS에서도 백그라운드 데몬으로 돌아가고, 크래시가 나면 자동으로 재시작합니다. 부팅 시 시작, 크론(cron) 스케줄링, 하트비트 모니터링, 선제적 알림을 지원합니다.
확장 가능한 스킬(Extensible): Agent Skills 명세를 따르는 스킬을 명령 한 줄로 설치하고, 반복 작업으로 예약할 수 있습니다.
멀티 에이전트 오케스트레이션(Multi-agent orchestration): 여러 하위 에이전트를 격리된 컨텍스트에서 병렬로 띄워 작업을 동시에 처리하고, 리더-라이터 파일 잠금으로 동시 쓰기 충돌을 막습니다. 최대 동시 실행 수는 CPU와 RAM에 맞춰 자동으로 정해집니다.

이 특징들은 따로 노는 기능이 아니라, "권한을 확인하고 → 도구를 실행하고 → 결과를 기억에 남긴다"는 하나의 흐름으로 이어집니다.

mercury-agent의 권한 모델과 세컨드 브레인

Mercury의 권한 모델은 "조용히 실행하지 않는다"는 원칙을 코드 수준에서 구현합니다. 셸 도구에는 차단 목록이 있어 위험한 명령은 실행 단계에서 거부되고, 파일 시스템 접근은 폴더 단위 범위로 좁혀집니다. 승인 대기(pending approval) 흐름을 통해, 에이전트가 새로운 작업을 시도할 때 사용자가 허용 여부를 결정할 수 있습니다. 채팅 중에는 /permissions 명령으로 Ask Me와 Allow All 사이를 오갈 수 있습니다.

기억은 세컨드 브레인이라는 이름의 SQLite 데이터베이스에 저장됩니다. FTS5 전문 검색으로 과거 대화를 찾을 수 있고, 10가지 기억 유형과 자동 추출·충돌 해결·자동 통합 기능이 더해져, 사용자가 일일이 메모를 남기지 않아도 선호와 습관이 누적됩니다. 대화 중에는 /memory 명령으로 저장된 기억을 보고 관리할 수 있습니다.

mercury-agent의 상시 데몬과 멀티채널

Mercury는 한 번의 명령으로 상시 구동 상태가 됩니다. mercury up 은 시스템 서비스를 설치하고 백그라운드 데몬을 시작하며, 이미 실행 중이면 PID를 확인해 줍니다. 데몬은 크래시 복구를 내장해, 프로세스가 죽으면 지수 백오프(exponential backoff)로 자동 재시작합니다(분당 최대 10회).

부팅 시 자동 시작을 위한 시스템 서비스는 플랫폼별로 다르게 등록되며, 모두 관리자 권한 없이 설정됩니다.

플랫폼	방식	관리자 권한
macOS	LaunchAgent	불필요
Linux	systemd 사용자 유닛	불필요(부팅 시작은 linger 설정)
Windows	작업 스케줄러(Task Scheduler)	불필요

데몬 모드에서는 입력을 받을 터미널이 없으므로 텔레그램이 주 채널이 되고, CLI는 로그 전용이 됩니다. 이 밖에 http://127.0.0.1:6174 에서 동작하는 내장 웹 대시보드로도 에이전트와 스킬을 관리할 수 있으며, 대시보드에서는 칸반(Kanban) 보드와 세컨드 브레인 시각화, 파일 탐색기와 git 패널을 갖춘 워크스페이스 IDE를 함께 제공합니다.

mercury-agent의 멀티 에이전트와 오토파일럿

Mercury는 하나의 작업을 통째로 붙들고 있는 대신, 여러 하위 에이전트를 격리된 컨텍스트 창에서 병렬로 실행합니다. 에이전트들이 같은 파일을 동시에 건드리지 않도록 리더-라이터 잠금을 두고, 동시 실행 가능한 에이전트 수는 머신의 CPU와 RAM에 맞춰 자동으로 정해집니다. 하위 에이전트가 작업하는 동안에도 사용자는 계속 대화할 수 있고, 작업이 끝나면 알림을 받습니다.

오토파일럿(Autopilot)은 에이전트가 "열심히 일하는 중"인지 "제자리를 맴도는 중"인지를 구분하는 루프 감지 장치입니다. 파라미터 다양성과 성공률을 함께 보고 세 가지로 판정합니다.

생산적(Productive): 파라미터 다양성과 성공률이 모두 높으면 멈추지 않고 계속 진행합니다.
의심스러움(Suspicious): 반복이 어느 정도 감지되면 Allow All 모드에서는 모델이 스스로 진척도를 점검하고, Ask Me 모드에서는 사용자에게 묻습니다.
막힘(Stuck): 다양성이 낮고 실패율이 높으면 현재 실행 경로를 자동으로 중단합니다.

mercury-agent의 제공자 폴백

Mercury는 여러 LLM 제공자를 한꺼번에 설정해 두고 순서대로 시도하며, 한 제공자가 실패하면 자동으로 다음으로 넘어갑니다. 마지막으로 성공한 제공자를 기억해 다음 요청에서 그곳부터 시작합니다.

제공자	기본 모델	비고
DeepSeek	deepseek-chat	기본값, 비용 효율적
OpenAI	gpt-4o-mini	GPT-4o, o3 등
Anthropic	claude-sonnet-4	Claude Sonnet/Haiku/Opus
Grok (xAI)	grok-4	OpenAI 호환 엔드포인트
Ollama Cloud	gpt-oss:120b	API로 원격 Ollama 사용
Ollama Local	gpt-oss:20b	로컬 인스턴스, 키 불필요

API 키 대신 브라우저 OAuth로 인증하는 ChatGPT Plus/Pro 구독과 GitHub Copilot 구독도 제공자로 쓸 수 있고, 세션 도중에 /models use 로 모델을 바꿀 수 있습니다.

mercury-agent 설치 및 사용법

Node.js 없이 단독 실행 바이너리를 내려받거나, Node.js 20 이상 환경에서 npm으로 설치할 수 있습니다.

# macOS / Linux: 최신 단독 실행 바이너리 설치 (Node.js 불필요)
curl -fsSL https://mercuryagent.sh/install.sh | sh

# 또는 Node.js 20+ 환경에서 npm 전역 설치
npm i -g @cosmicstack/mercury-agent
mercury

첫 실행 시 이름과 제공자, 선택적으로 텔레그램을 설정하는 마법사가 뜨고, 채팅 시작 전에 권한 모드(Ask Me 또는 Allow All)를 먼저 묻습니다. 상시 구동과 스킬 설치는 다음과 같이 사용합니다.

mercury up                                     # 시스템 서비스 설치 + 데몬 시작
mercury skills search prompt                   # 스킬 레지스트리 검색
mercury skills install ai-ml/prompt-engineering  # 스킬 설치
mercury skills list                            # 설치된 스킬 목록

설치된 스킬은 ~/.mercury/skills/<category>/<slug>/SKILL.md 에 자리 잡고, 다음 부팅에서 내장 스킬과 동일하게 인식됩니다. 다만 레지스트리의 스킬은 커뮤니티 기여물이라 감사를 거치지 않으므로, 설치 전에 mercury skills view <id> 로 내용을 확인하라고 안내합니다.

mercury-agent의 라이선스

mercury-agent는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

mercury-agent 공식 홈페이지

mercury-agent 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~