<p align="center">
<img src="https://raw.githubusercontent.com/Rustam-Z/hamroh/HEAD/assets/hamroh-logo.jpg" alt="hamroh" width="700">
</p>
<p align="center">
<b>hamroh</b>는 Telegram에서 자신만의 지속형 AI 동반자를 실행하기 위한 프레임워크입니다. 사용자가 완전히 소유하고, 제어하며, 확장할 수 있고, 사용자로부터 학습하는 동반자입니다.
</p>
실시간 체험: 실행 중인 인스턴스는 @rustamz_workshop Telegram 그룹에서 확인할 수 있습니다. 설치하기 전에 Luna라는 hamroh 기반 어시스턴트에게 메시지를 보내 작동 방식을 확인해 보세요.
hamroh는 사용자의 Telegram 내에 지속형 AI 어시스턴트를 실행합니다. 단순한 챗봇이 아니라, 메모리를 가지고 있고, 예약된 작업을 수행하며, 상황을 모니터링할 수 있고, 연결하는 모든 도구(tool)로 확장될 수 있는 에이전트입니다.
사용자는 모든 것을 소유합니다: 메모리 파일, 스킬 플레이북, MCP 연결, 로그, 토큰. 어떤 것도 제3자 제품을 통해 라우팅되지 않습니다. 사용자는 이 AI가 내린 모든 결정을 읽고 DM(Direct Message)을 통해 모든 규칙을 변경할 수 있습니다.
기본적으로 다음 기능을 제공합니다:
- 그룹 채팅에 머무르며 유용한 말이 있을 때 대화에 참여합니다.
- *자기 성찰(self-reflection)*을 실행하여 잘못된 부분을 검토하고 승인을 위한 새로운 규칙을 제안합니다.
- 메시지에 응답하는 동시에 백그라운드 서브 에이전트에서 예약된 연구 작업을 실행합니다.
- 파일 기반 메모리를 통해 재시작 시에도 컨텍스트를 기억합니다.
확장성이 뛰어납니다: MCP(Micro-Connection Protocol)를 추가하여 GitHub, Jira, 이메일, 캘린더 등 모든 것과 연결할 수 있습니다. 스킬을 추가하고 사용자 지정 도구를 구축하세요.
노트북이나 소형 VPS에서 실행됩니다.
목표는 Jarvis와 같습니다. 사용자와 함께 살아가며, 중요한 것을 모니터링하고, 사용자 대신 행동하는 AI입니다. hamroh가 그 기반이 됩니다.
Quickstart (3 minutes)
어디서 실행해야 할지 모른다면 Hetzner나 Contabo를 추천합니다.
필수 준비 사항:
- Docker compose 설치
- Claude Code CLI 설치
- 사용 중인 기기에서 Claude 인증 토큰 생성:
claude setup-token (브라우저가 열리며, Claude 구독 또는 API로 작동합니다). 이 명령어는 sk-ant-oat01-...으로 시작하는 토큰을 출력하며, 이를 아래의 .env 파일에 붙여넣어야 합니다. 이는 모든 OS(Linux, macOS, Windows)에서 봇 로그인 역할을 합니다.
Linux에서 실행하는 방법
git clone https://github.com/Rustam-Z/hamroh && cd hamroh
cp .env.example .env && nano .env
...
봇에게 다이렉트 메시지(DM)를 보내세요. 답장이 올 것입니다.
Docker가 없나요?
Python 3.11 이상과 Claude Code CLI(claude --version)가 필요합니다.
uv sync --extra dev
uv run python -m hamroh
uv run python -m hamroh.scripts.trace --follow
설정 (Configuration)
이 README는 개요(high-level intro)입니다. 더 깊은 자료는 docs/에 있습니다. 여기에는 전체 기술 매뉴얼, 배포 워크스루, 도구 참조, 그리고 hamroh가 기반으로 하는 시스템들이 포함되어 있습니다. docs/README.md부터 시작하세요.
기본적으로는 메시징(messaging), 메모리(memory), 알림(reminders), 웹(web), 비전(vision) 기능을 제공합니다. 셸 접근(shell access)이 필요하신가요? 코드 편집 기능이 필요한가요? GitHub, Jira, Notion, Slack 등 다른 MCP 서버를 플러그인으로 연결할 수 있습니다. 동일한 단일 진입점 패턴을 사용하며, stdio 또는 인증 헤더를 포함하는 원격 HTTP/SSE 방식을 지원합니다.
사용자 정의 (Customization)
설정 파일 외에도, 파일을 추가하여 봇 기능을 확장할 수 있습니다. 대부분의 경우 Python 지식이 필요하지 않습니다:
- Skills —
skills/<name>/SKILL.md에 플레이북을 추가하면 봇이 자체적으로 읽습니다. docs
- MCPs & tools — 플러그인(plugins.json)에 어떤 도구, 스킬, MCP가 포함되는지 보여주는 기능 표면입니다 (
stdio 또는 원격 HTTP/SSE). 자격 증명은 ${VAR}를 통해 .env에서 가져옵니다. docs/tools.md를 읽어보세요. docs/documentation.md.
- Extensions — 봇 자체의 Python 도구와 소유자용
/commands입니다. 이는 plugins.json에 이름이 지정된 ext/ 패키지로 해당 봇의 리포지토리에 보관됩니다. 프레임워크는 건드리지 않습니다. docs/tools.md.
- Reminders — 봇과 함께 제공되는 사용자 정의 반복 알림은
default-reminders.json에 있습니다. docs.
- Memory notes — 봇의 메모는
memories/ 아래에 존재합니다 (예: memories/notes/references.md). 봇은 이를 읽고, 검색하고, 작성하며, 사용자도 직접 관리할 수 있습니다. 전체 경로(memories/...)로 지정되고 git 추적되므로, 재시작에도 메모가 유지되며 커밋할 수 있습니다. memories/README.md
- Persona & rules —
prompts/project.md를 편집하여 시스템 프롬프트를 확장합니다. 이는 제공되는 prompts/system.md에 추가됩니다. 봇 이름, 언어, 내부 규칙(house rules), 소유자별 지침 등이 포함되며, 제공되는 prompts/system.md에 추가됩니다.
- Access — 누가 봇에게 DM을 보내거나 그룹에서 사용할 수 있는지 (핫 리로드되어 재시작할 필요가 없습니다). docs/documentation.md.
.env 비밀값 — Telegram 봇 토큰, 소유자 ID, 그리고 plugins.json 항목이 ${VAR}를 통해 참조하는 모든 자격 증명(예시 파일의 GitLab / GitHub 항목에서 패턴을 확인할 수 있습니다).
더 자세한 내용은 docs/documentation.md에서 확인하세요.
Telegram @BotFather 설정
- 그룹에 봇 추가를 원하지 않는 경우 '그룹 허용(Allow groups)' 비활성화
- 봇이 다른 봇의 메시지를 볼 수 있도록 '봇 간 통신(Bot to bot communication)' 활성화
hamroh가 할 수 있는 것
빠른 개요 — 모든 도구별 표면(인수, 제한 사항, 레일)은 docs/tools.md에서 확인할 수 있습니다.
- 통신 및 미디어: 전송(/), 답장(/), 수정(/), 삭제(/), 반응, 투표; HTML과 LaTeX를 PNG로 렌더링; 수신 사진(비전), 텍스트 기반 문서, PDF 읽기.
- 메모리: 전체 경로로 지정되는 영구적인 마크다운 (목록/검색/읽기/쓰기/추가), 파일당 64 KiB, 쓰기 전 읽기, 재시작 후에도 유지. 하나의 저장소: 봇이 읽고, 검색하고, 쓰고, 추가하는 git 추적
memories/... 폴더 — 그리고 사용자가 커밋하고 관리할 수 있습니다. memories/README.md를 참조하세요.
- 검색 및 기록: 웹 검색 / 가져오기 (내부 URL 없음) 및 채팅 데이터베이스에 대한 읽기 전용 SQL SELECT 실행.
- 브라우저:
WebFetch가 도달할 수 없는 페이지의 실제 헤드리스 Chromium을 구동합니다 — 탐색, 클릭, 채우기, 읽기, 스크린샷, 다운로드. 기본적으로 활성화되어 있습니다.
- 스케줄링: 일회성 + 크론 알림, 그리고
default-reminders.json에 있는 git 추적 사용자 지정 알림. 매일 자체 반성(기본 활성화)을 통해 승인을 위한 지속 가능한 규칙을 제안합니다.
- 기술 및 자가 편집:
skills/ 아래의 운영자 관리 플레이북; 봇은 prompts/project.md에 규칙을 추가할 수 있습니다 (소유자 전용).
- 선택적 활성화(Opt-in): 셸, 코드 편집, 서브 에이전트 — 기본적으로 모두 비활성화되어 있으며,
plugins.json에서 토글합니다. 외부 MCP 서버도 같은 방식으로 플러그인 할 수 있습니다.
- 할 수 없는 것: 이미지 생성; 음성, 비디오, 스티커, GIF 전송/읽기; 그룹 관리; 통화 연결.
아키텍처
Telegram → Engine (buffer + debounce) → Claude worker → claude process
│ │
▼ ▼
...
- **Telegram 리스너(listener)**는 메시지를 읽고, 이를 SQLite에 저장한 다음 전달합니다.
- **엔진(Engine)**은 근접하게 도착하는 메시지들을 묶습니다. 만약 Claude가 답변을 작성하는 도중에 새로운 메시지가 도착하면, 그것은 실행 중인 턴(turn)에 주입됩니다.
- **Claude 워커(worker)**는
claude 서브프로세스를 실행하고 충돌 시 재시작합니다.
- **MCP 서버(server)**는 hamroh/tools/의 모든 도구를 자동으로 로드합니다.
엔진은 한 번에 하나의 턴을 처리합니다. 채팅 A에서 긴 작업을 수행하면, 그것이 끝날 때까지 채팅 B가 지연됩니다. 한 사용자에게는 괜찮지만, 바쁜 환경에서는 채팅 그룹별로 별도의 봇을 실행해야 합니다.
시스템 프롬프트(system prompt)는 두 개의 파일로 구성됩니다: prompts/system.md (일반적인 hamroh 동작, 기본 제공)와 prompts/project.md (사용자 오버레이 — gitignore됨, prompts/project.md.example에서 복사).
보안(Security)
이 봇은 외부에 노출되며, 보안 모델은 희망에 의존하는 것이 아니라 코드 내에서 강제됩니다 — 전체 레일 목록은 Security model을 참조하고, 도구별 표면적(surface)은 docs/tools.md를 참조하세요.
기여(Contributing)
이슈 및 PR 환영합니다.
더 큰 변경 사항에 앞서 아키텍처 심층 분석: docs/documentation.md.
라이선스(License)
MIT. LICENSE를 참조하세요.
