앱·라이브러리
Rust 에이전트 하네스와 타입 있는 임베딩 API. 데스크톱 앱과 CLI·TUI 호스트가 같은 코어를 서로 다른 방식으로 사용한다.
왜 LLM 단독으로는 부족하고, 왜 메모리 트리가 필요한가.
2024~2026년 사이 ChatGPT·Claude·Gemini는 점점 똑똑해졌지만, "내 일상을 진짜로 이해하고 대신 일해주는" 에이전트는 여전히 부족했다. 이메일·노션·슬랙·캘린더가 다 흩어져 있고, 모델은 매 대화마다 컨텍스트를 처음부터 다시 배워야 했기 때문이다.
해법은 LLM을 둘러싸는 "외골격(harness)"이다. 도구 호출, 외부 데이터 자동 수집, 장기 기억, 모델 라우팅, UI까지 책임지는 운영 레이어. OpenHuman은 이 외골격을 데스크톱 네이티브 앱으로 끝까지 밀어붙인 첫 사례다.
openhuman-core(Rust)가 하네스를 맡고, Tauri 앱이 UI를 맡는다.≤3k 토큰 청크로 잘라 계층적으로 요약해 만드는 트리. 상위 노드는 자식 노드들의 요약. LLM이 "최근 이메일 요약" 요청 시 트리 상단만 읽고, 필요하면 자식으로 내려간다. Karpathy의 obsidian-wiki 트윗을 코드화한 결과.한 문장으로 줄이면.
현재 README는 앱 사용 경로와 자체 프로그램에 코어를 내장하는 경로를 함께 소개한다. 공통 runtime을 재사용하면서 에이전트별 도구·작업 디렉터리·접근 권한을 나누는 구조가 핵심 학습 대상이다.
아래 초기 소개의 메모리·마스코트 경험과 현재 코어 구조를 구분한다. 재검토한 모듈 경계와 개발 조건은 3·4·5·7절에 반영했다.
시대적 배경 + 경쟁 우위.
기존 에이전트(Hermes, OpenClaw 등)는 사용자를 학습하는 데 며칠~몇 주가 걸렸다. 매일 대화하며 선호도를 알아내야 했기 때문. OpenHuman은 OAuth 한 번으로 118+ 서비스를 한꺼번에 흡수해 이 콜드 스타트 시간을 분 단위로 단축한다.
또 하나 — "BYOK(Bring Your Own Key) 지옥" 탈출. 보통 에이전트는 OpenAI·Anthropic·ElevenLabs 키를 각각 발급받아야 했지만, OpenHuman은 구독 하나 + 자동 모델 라우팅(reasoning/fast/vision)으로 끝낸다. Karpathy가 X에 올린 "obsidian-style wiki + memory tree" 워크플로우를 실제 작동하는 데스크톱 앱으로 구현한 첫 사례라는 점이 화제의 핵심.
| 비교 항목 | Claude Cowork | OpenClaw / Hermes | OpenHuman |
|---|---|---|---|
| 오픈소스 | 독점 | MIT | GPL-3.0 |
| 시작 난이도 | 데스크톱+CLI | 터미널 우선 | 클린 UI, 수 분 내 |
| 비용 | 구독+애드온 | BYO 모델 키 | 구독 1 + TokenJuice 압축 |
| 메모리 | 채팅 스코프 | 플러그인/자가학습 | Memory Tree + Obsidian 미러 |
| 통합 수 | 소수 | BYO | 118+ OAuth 빌트인 |
| 오토페치 | 없음 | 없음 | 20분 주기 자동 |
| 모델 라우팅 | 단일 | 수동 | 빌트인 (reasoning/fast/vision) |
| 네이티브 도구 | 코드만 | 코드만 | 코드+검색+스크래핑+음성+Meet |
새로 산 스마트폰을 떠올려보라. 처음 며칠은 자동완성이 멍청하고, 추천 앱도 엉터리다. AI 에이전트도 똑같았다 — 너를 모르니까. OpenHuman은 그 며칠을 OAuth 한 클릭으로 압축한다. 마치 새 폰에 백업을 통째로 복원하는 것과 같다.
2026-10-31의 고정 소스는 Rust 라이브러리와 데스크톱·CLI·TUI 호스트를 분리한 모노레포다. 루트 Cargo workspace 버전은 0.64.20, edition은 2021, 라이선스 선언은 GPL-3.0-only다.
| 계층 | 실제 위치·역할 |
|---|---|
| 핵심 라이브러리 | crates/openhuman-core: 도메인 로직·runtime·도구, 라이브러리 이름 openhuman_core |
| 임베딩 | openhuman-embed: Runtime·Agent·Core의 타입 있는 인터페이스 |
| 호스팅 연결 | openhuman-tinyhumans: backend transport·로그인·세션 소유권 |
| 통신 | openhuman-rpc: JSON-RPC envelope·client·server·session store |
| 클라이언트 | openhuman-cli·openhuman-tui; 데스크톱 openhuman-app은 별도 Cargo workspace |
| 화면 | app/: React 19·Vite·Tauri 2·Zustand와 Redux 계열 의존성 |
루트 package.json은 pnpm 10.10.0을 고정한다. app/package.json의 Node 조건은 24 이상이다. 예전 루트 src/ 중심 구조와 다른 위치이므로 아래 새 맵을 기준으로 소스를 찾는다.
core → embed → tinyhumans → rpc → app / cli / tui 도메인·도구 타입 facade hosted 연결 통신·세션 사용자 진입점
이 화살표는 낮은 계층에서 높은 계층으로 쌓이는 구조를 뜻한다. 루트 Cargo.toml은 호스트가 rpc를 의존하고 core가 TinyHumans SDK를 직접 의존하지 않도록 경계를 설명한다. 데스크톱 앱은 코어를 프로세스 안에 연결하며, app/package.json의 core:stage는 sidecar가 제거되어 no-op이라고 명시한다. Docker의 7788 서버를 모든 데스크톱 실행의 필수 별도 프로세스로 그리면 현재 구조와 맞지 않는다.
openhuman-embed/src/lib.rs에서 호스트가 코어를 호출할 때는 구체적 Core와 하위 facade를 쓰고, 코어가 호스트 기능을 호출할 때는 주입된 trait port를 쓴다. 기능이 컴파일에서 빠지면 accessor 자체가 없고, runtime DomainSet에서 꺼졌다면 Unavailable을 반환한다. 설정 실패와 기능 미제공을 구분하는 설계를 배울 수 있다.
Runtime은 공통 초기화를 소유하고 Agent마다 MCP·스킬·작업 디렉터리·접근 수준·공급자를 달리 구성한다. README의 성능 수치는 제작자의 공개 벤치마크 조건에 따른 주장이다. 가격·동시 실행 규모를 임의의 하드웨어에 보장하는 사양으로 사용하지 않는다.
openhuman/ ├── crates/ │ ├── openhuman-core/ # 순수 핵심 라이브러리 │ ├── openhuman-embed/ # 타입 있는 임베딩 API │ ├── openhuman-tinyhumans/ # hosted backend 연결 │ ├── openhuman-rpc/ # 프로토콜·서버·세션 저장 │ ├── openhuman-cli/ # openhuman-core 바이너리·개발 bins │ ├── openhuman-tui/ # 터미널 클라이언트 │ ├── openhuman-modules-linked/ │ └── openhuman-app/ # 독립 lockfile·target을 쓰는 데스크톱 ├── app/ # React·Vite 화면, 모바일 Tauri 경로 ├── packages/ # 공유 패키지·PTT 플러그인 ├── vendor/ # 함께 고정한 모듈·의존 소스 ├── docs/ # 문서·Gitbook 원본 ├── scripts/ # 개발·배포·검증 보조 도구 ├── Cargo.toml # root workspace와 patch 경로 ├── rust-toolchain.toml # Rust 1.99.1 └── docker-compose.yml # 헤드리스 서버·두 영속 볼륨
app은 root Cargo workspace에서 제외되어 GTK·WebKit·Tauri를 루트 전용 검사에서 분리한다. 외부 패키지를 임의 버전으로 바꾸기 전에 patch 테이블과 vendor 경로가 공유하는 trait·wire 타입을 먼저 확인한다.
기술 영역마다 무엇을 가져갈지.
parking_lot/once_cell로 동시성 처리실습: 작은 RPC 서버를 Axum으로 만들고 SQLite에 메모를 저장하는 토이 프로젝트 → Tokio mpsc 채널로 백그라운드 워커 추가
@tauri-apps/api 사용법실습: Tauri로 로컬 파일 검색 앱 만들기 — Rust에서 ripgrep 같은 검색, TS에서 결과 표시
실습: 자기 노션 페이지를 export → 청크 분할 → OpenAI 임베딩 → 트리 노드별로 GPT-4o-mini로 요약 → SQLite 저장
실습: Gmail OAuth → 최근 50개 메일 가져와 GPT로 분류하는 미니 에이전트
실습: Whisper로 회의 녹음을 로컬에서 트랜스크립트 → 요약 → Notion에 자동 업로드
실습: 자신의 사이드 프로젝트 컨테이너에 같은 패턴 적용해 변조 못 하는 컨테이너 만들기
데스크톱 배포 파일은 macOS dmg, Windows msi·exe, Linux deb·AppImage를 제공한다. 하드웨어 최소값을 제작자 벤치마크로 대신 추정하지 않는다.
| 환경 | 고정 소스에서 확인한 조건 |
|---|---|
| Rust 개발 | rust-toolchain.toml: 1.99.1, rustfmt·clippy |
| 화면 개발 | Node >=24.0.0, 루트 pnpm 10.10.0 |
| Docker 코어 | 7788, mem_limit 기본 4g·CPU 기본 2.0. 앱 최소 RAM과는 다른 컨테이너 제한 |
| 영속 경로 | workspace와 projects의 두 named volume |
| RPC 접속 | .env의 BACKEND_URL·OPENHUMAN_CORE_TOKEN을 배포 전에 설정 |
Compose는 read_only·no-new-privileges·cap_drop ALL을 사용하되 볼륨 소유권 보정과 권한 하향을 위해 CHOWN·SETUID·SETGID를 다시 허용한다. “모든 capability가 제거됐다”는 설명과 구분한다. 설치 파일과 필요한 모델·서비스를 준비할 디스크·네트워크 용량은 선택 기능에 따라 달라진다.
난이도별 실습 — Easy → Hard.
1) 설치 스크립트(curl ... | bash)로 OpenHuman 띄우기 2) Gmail OAuth 연결 3) "지난 일주일 이메일 요약해줘" 명령 4) 메모리 트리가 어떻게 SQLite에 쌓이는지 sqlite3 CLI로 직접 들여다보기
배우는 것: 메모리 트리 구조 직관, OAuth 흐름 체험, SQLite 스키마
1) OpenHuman이 생성한 Obsidian 호환 볼트를 Obsidian 앱으로 열기 2) 어떤 노드가 어떤 데이터에서 생성됐는지 추적 3) 백링크 구조와 그래프 뷰로 시각화 4) 직접 노드를 편집하면 OpenHuman이 어떻게 반응하는지 관찰
배우는 것: 계층적 요약 트리의 시각적 이해, 데이터 주권 의미
1) Python으로 HTML → Markdown 변환기 작성 2) "긴 URL 단축 + 비-ASCII 제거 + 표 보존" 룰 적용 3) tiktoken으로 토큰 카운트 측정 4) 압축률 표로 정리 (원본 vs 변환 후)
배우는 것: 토큰 비용 절감 실전 감각, 정규식·파서 설계
1) Tauri 앱 생성, 항상 떠 있는 작은 캐릭터 윈도우 2) always-on-top + 투명 배경 + 무프레임 윈도우 설정 3) Rust에서 시스템 알림 감지 → IPC로 TS에 전달 → 캐릭터가 손 흔들기 4) 트레이 메뉴로 토글
배우는 것: Tauri IPC, 데스크톱 OS API, 윈도우 매니지먼트
1) 임의의 마크다운 코퍼스 입력 2) ≤3k 토큰 청크 분할 + 임베딩 + 클러스터링 3) 각 클러스터를 LLM에 요약시켜 부모 노드 생성 (재귀) 4) SQLite에 트리 저장 + Obsidian용 .md 미러링 5) "이 트리에서 X에 대한 정보 찾아줘" 쿼리 모드 — top-down 탐색 알고리즘
배우는 것: 진짜 어드밴스드 RAG, 계층적 메모리 알고리즘, RAPTOR 논문 구현
1) Puppeteer/Playwright로 Meet에 자동 입장 2) 시스템 오디오 캡처 → Whisper로 STT 3) LLM이 발화 응답 생성 4) ElevenLabs TTS로 회의에 발화 5) 윤리·동의 문제도 함께 고민 (참가자 고지 필수)
배우는 것: 멀티모달 에이전트, 실시간 오디오 파이프라인, 컴퓨터 제어, AI 윤리
주차별로 따라가면 전체 스택 마스터.
The Rust Book 1~10장, tokio.rs/tokio/tutorial로 비동기. cargo new로 echo TCP 서버 만들기
Axum 0.8 튜토리얼로 RPC 서버 구축. rusqlite로 메모 저장. OpenHuman의 crates/openhuman-cli/ 패턴 따라하기
공식 Tauri 튜토리얼. Rust 함수를 TS에서 호출하는 IPC 명령 5개 작성. 시스템 트레이, 글로벌 단축키
OpenAI API + Google OAuth로 "내 캘린더 요약기" 만들기. Refresh token 처리, scope 설계
OpenAI text-embedding-3 + Chroma/Qdrant. 청크 사이즈 실험(500/1500/3000 토큰)으로 검색 품질 비교
RAPTOR 논문, Karpathy의 obsidian-wiki 트윗 정독. 자체 Memory Tree 토이 구현
whisper-rs로 로컬 STT. enigo로 마우스 자동화. ElevenLabs TTS 호출
위 모든 걸 합쳐 자신의 "1인용 AI 에이전트" 만들기. README + 데모 영상 작성 후 GitHub 공개
자주 마주칠 단어들.
.md + 백링크). OpenHuman은 메모리 트리를 이 형식으로 미러링.공식 · 영감 · 학습 리소스.
2026-10-31 고정 커밋 218d35f4b96b의 workspace·타입 facade·앱 manifest·Compose를 대조했다.
curl ... | bash로 띄우고 Gmail 1개만 먼저 연결. 첫 오토페치(20분)가 끝날 때까지 기다리기. 이 시간이 콜드 스타트의 종착점.sqlite3 ~/.openhuman/memory.db로 직접 들어가 SELECT * FROM nodes LIMIT 20; — 트리 노드가 어떻게 부모/자식 관계로 저장되는지 눈으로 확인.docker-compose.yml로 :7788 코어만 띄워보기. read_only·cap_drop 옵션이 빠지면 어떻게 되는지 일부러 망가뜨려 보기 — 프로덕션 보안의 감 잡기.