cosmicstack-labs/mercury-agent

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI or Telegram.

Mercury — "영혼에 이끌린" AI 에이전트

무엇인가요 – Mercury는 로컬에서 실행되며 권한이 엄격히 제어되는 AI 어시스턴트입니다. CLI, 웹 대시보드, 또는 Telegram에서 대화할 수 있습니다. 대규모 언어 모델 제공자(OpenAI, Anthropic, DeepSeek, Ollama 등)와 통신하며 파일 읽기/쓰기, 쉘 명령 실행, URL 가져오기, Git 관리, 작업 스케줄링 등이 가능합니다. 모든 작업은 명시적인 권한 모델로 제한되며, 에이전트는 사용자의 기계에 지속적이고 검색 가능한 "제2의 뇌" 메모리를 유지합니다.

핵심 아이디어

아이디어	Mercury가 어떻게 구현하는가
권한이 엄격히 제어된 도구	파일, 쉘, Git, 웹 등 모든 내장 도구는 위험한 작업(예: `sudo`, `rm -rf /`)에 대해 기본적으로 차단됩니다. 각 작업 전에 프롬프트를 묻는 "물어보기" 또는 세션 전체에 대해 "모두 허용"을 선택할 수 있습니다.
제2의 뇌 메모리	SQLite + FTS5는 추출된 사실을 10개 유형(정체성, 목표, 습관 등)으로 저장합니다. 대화마다 고신뢰도의 사실을 자동 추출하고, 시간당 통합하며, LLM 컨텍스트에 상위 5개 관련 기억을 삽입합니다.
영혼에 이끌린 성격	사용자의 마크다운 파일(`soul.md`, `persona.md`, `taste.md`, `heartbeat.md`)이 에이전트의 성격을 정의하며, 기업 서비스에 의존하지 않고 "성격"을 유지합니다.
토큰 인식 예산 관리	일일 토큰 예산을 추적하며, 사용량이 70 %를 초과하면 자동으로 응답을 단축합니다. `/budget` 명령어로 예산을 확인, 재설정, 오버라이드할 수 있습니다.
항상 실행되는 데몬	`mercury up`은 사용자 단위 시스템 서비스(LaunchAgent, systemd 사용자 단위, Windows 작업 스케줄러)를 설치하고, 충돌 시 재시작하며 부팅 시 자동 시작할 수 있습니다. 데몬 모드에서는 Telegram이 주요 채팅 채널이 됩니다.
확장 가능한 스킬	커뮤니티 기여 스킬(미니에이전트)은 Agent Skills 사양을 따르며, 단일 명령어(`mercury skills install …`)로 설치 가능합니다. 스킬은 추가 도구로 나타나며, 채팅에서 호출하거나 스케줄링할 수 있습니다.

빠른 시작 (Node.js 필요 없음)

# macOS / Linux – 자체 포함형 바이너리 다운로드
curl -fsSL https://mercuryagent.sh/install.sh | sh

# Windows PowerShell
irm https://mercuryagent.sh/install.ps1 | iex

설치 프로그램은 ~/.local/bin (또는 Windows 동등 위치)에 mercury 실행 파일을 배치합니다. 첫 실행 시 이름, LLM 제공자 API 키, 선택적 Telegram 페어링을 설정하는 마법사가 실행됩니다.

Node 20+가 이미 설치되어 있다면 다음도 실행 가능합니다:

npx @cosmicstack/mercury-agent   # 일회성 실행
npm i -g @cosmicstack/mercury-agent && mercury   # 글로벌 설치

주요 명령줄 인터페이스

명령어	기능
`mercury` / `mercury start`	인터랙티브한 Ink TUI 채팅 세션 시작.
`mercury up`	필요 시 사용자 단위 서비스 설치 후 백그라운드 데몬 시작.
`mercury stop / restart / status / logs`	데몬 관리.
`mercury doctor`	설정 마법사 재실행 또는 구성 확인.
`mercury telegram …`	Telegram 사용자 페어링, 승인, 관리(관리자 vs. 멤버 권한).
`mercury skills …`	커뮤니티 스킬 검색, 보기, 설치, 업데이트, 제거.
`mercury upgrade`	최신 릴리스(바이너리 또는 npm) 가져오기.

채팅 중에는 LLM 토큰을 소비하지 않는 슬래시 명령어를 사용할 수 있습니다. 예:

/tools – 현재 로드된 도구 목록
/budget – 일일 토큰 사용량 표시
/memory – 제2의 뇌 탐색
/code agent <task> – 백그라운드에서 코딩 작업을 처리하는 서브에이전트 생성
/tasks – 스케줄된 작업 목록

웹 대시보드 및 칸반 보드

mercury doctor를 실행하면 http://127.0.0.1:6174에 로컬 웹 UI가 활성화됩니다. 제공 기능:

서버 전송 이벤트 스트리밍을 통한 채팅
Mercury가 자동으로 처리할 수 있는 카드가 있는 시각적 칸반 보드
제2의 뇌 메모리 그래프 보기
코드 편집 작업용 가벼운 IDE 스타일 워크스페이스

대시보드는 기본 인증 정보(mercury / Mercury@123)로 보호되며, localhost에만 바인딩됩니다.

Mercury 확장하기

스킬 – 도구 세트와 마크다운 SKILL.md를 설명하는 패키지. mercury skills install <category>/<slug>로 설치. 스킬은 ~/.mercury/skills/에 저장되며 다음 시작 시 로드됩니다.
프로바이더 – ~/.mercury/mercury.yaml에 OpenAI 호환 엔드포인트를 추가. Mercury는 순서대로 시도하고 자동으로 백업합니다.
사용자 정의 도구 – 코어는 Vercel AI SDK와 간단한 도구 디스패치 루프로 구성되어 있어, run 함수를 노출하는 새로운 TypeScript 모듈을 추가하고 설정 파일에 등록할 수 있습니다.

소스에서 설치하기

git clone https://github.com/cosmicstack-labs/mercury-agent.git
cd mercury-agent
npm install               # Node ≥ 20
npm run build             # dist/ 번들 생성
npm start                 # 소스에서 실행

엔드유저에게 Node 런타임이 필요하지 않은 완전히 독립된 바이너리(노드 런타임 없이)를 생성하려면, 이 리포지토리는 Bun을 사용합니다:

npm run build:bin          # 플랫폼별 실행 파일을 release/에 생성

릴리스 레이아웃에는 macOS(arm64 & x64), Linux(arm64 & x64), Windows용 별도 바이너리와 웹 UI의 tarball, SHA‑256 체크섬이 포함됩니다.

라이선스 및 안전성

라이선스: MIT (LICENSE 참조).
보안 모델: 잠재적으로 파괴적인 작업은 쉘 블록리스트로 차단되며, 명시적인 사용자 승인이 필요합니다. 에이전트는 fetch_url과 같은 도구를 호출하지 않는 한, 로컬 파일이나 명령 출력을 원격 서비스에 전송하지 않습니다.
데이터 로컬성: 모든 메모리, 로그, 구성은 사용자의 기계에 있는 ~/.mercury/에 저장되며, 원격 LLM 제공자 설정을 제외하고는 클라우드 스토리지 사용하지 않습니다.

누구에게 유용할까?

제한 없는 쉘 접근 권한 없이 코드 편집, 빌드 실행, Git 관리가 가능한 개인용 AI 어시스턴트를 원하는 개발자.
로컬에 완전히 저장되며 검색 가능하고 자동 정리되는 "제2의 뇌"를 선호하는 지식 종사자.
Telegram 또는 사내 웹 UI용 자체 호스팅, 권한 인식 봇이 필요한 팀.

결론: Mercury는 안전성(권한 프롬프트, 토큰 예산), 지속성(SQLite 기반 메모리와 칸반 보드), 확장성(커뮤니티 스킬, 다중 프로바이더 백업)을 중시하는 완전 기능의 로컬 AI 에이전트입니다. 단일 라인 설치 스크립트로 즉시 사용 가능하거나, 소스에서 빌드하여 더 깊은 커스터마이징도 가능합니다.