OpenClaw·Hermes 마이그레이션 (1/13) — 현행 구조 인벤토리: 마이그레이션 전 스냅샷

-

단일 페르소나 + 백엔드 역할 분리, 4-tier 메모리, 크론·LaunchAgent·스크립트 레이어링 — 1인 AI 시스템이 실제로 어떤 부품들로 구성되는지 해부한다.

이 글이 전달하는 것

  • 단일 대화 페르소나 + 다중 백엔드 에이전트로 역할을 분리하는 설계 패턴
  • 크론 / macOS LaunchAgent / 스크립트 레이어를 어떤 기준으로 나누는지
  • 메모리를 Identity / Curated / Project / Episode 4-tier로 쪼개 토큰과 회상 품질을 동시에 잡는 구조
  • oMLX 기반 하이브리드 검색(임베딩 + 키워드 + MMR + temporal decay)의 실제 구성값
  • 마이그레이션 관점에서 "재사용 가능한 자산"과 "해당 플랫폼에 종속된 자산"을 가르는 기준

오픈클로는 Claude Code 기반 1인 AI 시스템으로 출발해 현재 다수의 에이전트, 다수의 스케줄러 / 데몬, 다수의 운영 스크립트, 여러 스킬, 4-tier 메모리로 구성되어 있다. 헤르메스(Hermes) 베이스로의 이관 결정을 앞두고 현행 자산을 한 번에 조감하기 위해 인벤토리를 정리한다. 같은 구조를 만들거나 참고하려는 사람이 어느 레이어에 어떤 역할이 붙는지 그대로 가져갈 수 있도록 구성했다.

1. 에이전트 레이어 — 단일 페르소나 + 역할 분리

에이전트는 여러 개이고, 사용자가 대화하는 인터페이스는 mir 하나로 고정한다. 나머지는 전부 백엔드 역할로 분리된다. 이 구조는 (a) 대화 맥락 하나만 유지하면서 (b) 무거운 작업은 전용 에이전트로 위임해 모델·프롬프트를 독립적으로 튜닝할 수 있게 한다.

에이전트 모델 역할
mir gpt-5.4 (high) 유일 대화 인터페이스, 라우팅
monitor omlx gemma-4 시스템 상태 감시
researcher gemini-3.1-flash-lite 웹 리서치, AutoSearch Deep, Scrapling
communicator gpt-5.4 (medium) 글쓰기
orchestrator gpt-5.3-codex 코딩 + CLI, 서브에이전트/스킬 팩토리
google gemini-3.1-flash-lite Google Workspace API
reviewer gemini-3.1-flash-lite 월간 메모리 리뷰
memory-runner omlx gemma-4 bank/ 파일 I/O
memory-manager gemini-2.5-flash Reflect 의미 판단
telegram-ops gemini-3.1-flash-lite 텔레그램 송신
planner mir 상속 (subagent) PRD/기획

모델 선택 기준

  • 판단 무거움 / 라우팅: GPT-5.4 high
  • 코딩·CLI: GPT-5.3 codex
  • 경량 처리 (리서치, 송신, 리뷰): Gemini 3.1 Flash Lite
  • 로컬 보안(네트워크로 내보내지 않음): oMLX gemma-4 26b

판단 비용과 보안 경계, 두 축만으로 모델이 결정된다. 대화 인터페이스를 한 에이전트에 고정하면 모델 이질성이 사용자 경험에 노출되지 않는다는 점이 핵심이다.

2. 자동화 레이어 — Cron

스케줄된 배치 작업은 크론에 올린다. 작업은 크게 두 축이다.

name schedule agent
ai-research-scan 09:00 researcher
reddit-scan 15분/6시간 researcher
reflect-orchestrate 03:00 memory-manager
memory-micro-cycle 7,37분/매시간 mir
daily-summary 22:40 mir
self-review-scan 22:05 mir
self-review-apply 22:12 mir
self-review-fix 10분/22~23시 mir
monthly-memory-review 매월 1일 09:00 reviewer

작동 원리

  • 메모리 사이클: 03:00 Reflect(의미 병합·정리), 매시간 7분·37분에 micro-cycle(짧은 주기 정리). 사용자가 입력하지 않는 시간대에 bank/와 memory/를 정합시킨다.
  • 셀프 리뷰: 22:05 스캔 → 22:12 적용 → 22~23시 fix 루프. 하루 끝에 규칙 위반·드리프트를 자기 수정한다.

크론 레이어는 "사람이 잠든 사이에 시스템이 스스로 정리·교정한다"는 원칙이 구현되는 곳이다.

3. 데몬 레이어 — macOS LaunchAgent

크론이 시간 기반이라면 LaunchAgent는 프로세스 기반이다. 살아 있어야 하는 것들이 여기 들어간다. 대표적인 데몬은 다음과 같다.

  • ai.openclaw.gateway — Gateway 데몬 (포트 18789)
  • ai.openclaw.update-check — 자동 업데이트
  • com.openclaw.omlx — oMLX 서버 (gemma-4 26b)
  • com.openclaw.omlx-proxy — oMLX 프록시
  • com.openclaw.daily-audit — 05:00 일일 감사 (Phase A~E)
  • com.claude-agent.watchdog — 세션 워치독
  • com.claude-agent.autostart — 자동 시작

oMLX 서버와 프록시가 로컬 임베딩·추론 인프라를 구성한다. 외부 API로 내보내고 싶지 않은 데이터는 반드시 이 두 엔드포인트를 경유한다. 로컬 추론을 붙이고 싶다면 "서버 + 프록시 + 프록시를 가리키는 라우팅 설정" 세트가 최소 단위다.

4. 실행 레이어 — 운영 스크립트

가장 양이 많은 영역이고, 기능별 카테고리가 명확하다.

메모리 파이프라인

  • retain-extract.py / retain-merge.py — Retain 태그 추출/병합
  • recall-tree.py / recall-match.py — Topic-Cued Recall
  • recall-cleanup.py — TTL 정리
  • confidence-decay.py — opinions confidence 감쇠
  • topics-validate.py / topics-expand.py — topic 일관성
  • session-cleanup.py / session-archive.py — 세션 라이프사이클
  • user-pattern-stage.py — U-tag 변증법(관찰→가설→검증)
  • bank-lint.py / bank-size-watch.py — bank/ 검증
  • entity-audit.py — entities/ stale 감지
  • memory-micro-cycle.py — 30분 주기 오케스트레이터
  • decision-prepare.py / decision-apply.py — LLM 의사결정 큐
  • memory-warning-report.py / memory-optimize.py
  • memory-archive.sh — memory/ → archived/

Heartbeat

  • heartbeat-router.sh / heartbeat-update.sh / heartbeat-tick.py / heartbeat-health.py
  • proactive-exception-alerts.py
  • check-quotas.sh
  • gws-check.sh — Gmail/Calendar 빠른 체크

Self-Review

  • self-review-prescan.py / self-review-apply.py / self-review-fix.py
  • skill-candidate-stage.py

Daily Audit

  • daily-audit.sh / docs-snapshot.sh / release-check.sh / docs-update-ai.sh
  • agent-linter.sh / config-drift.sh / cron-analytics.sh / session-audit.sh / reflect-trace.py

외부 통합

  • scrape.py — Scrapling + playwright + curl_cffi (Cloudflare 우회)
  • gws-wrapper.sh — Google Workspace CLI
  • omlx-serve.sh — oMLX 데몬

Hooks (.claude/settings)

  • PostToolUse: JSON 검증, AgentLinter, DOC_SYNC, debug 경고
  • PreToolUse(git commit): DOC_SYNC gate, AgentLinter
  • SessionStart / SessionEnd / PreCompact

스크립트는 한 작업 = 한 파일 원칙으로 쪼개져 있다. 크론/LaunchAgent/훅이 이 스크립트를 엔트리로 호출한다. 즉 상위 레이어는 "언제/왜"를 결정하고 스크립트는 "무엇을"만 수행한다.

5. 인터페이스 레이어 — Skill

슬래시 명령 형태의 스킬은 사용자가 직접 호출하는 엔트리포인트다.

  • 일반: brainstorming, writing-plans, verification, deep-interview, code-review, testing, git-commit, project-doctor, self-audit
  • OpenClaw 전용: oc-config, oc-agent, oc-channel, oc-skill, oc-memory, oc-doctor, oc-deploy, oc-backup

이관 관점의 분류

  • 일반 스킬은 플랫폼 독립 — 다른 하네스로 그대로 이식 가능.
  • oc-* 계열은 오픈클로 내부 구조(에이전트 구성, 채널 라우팅, bank/ 스키마)에 묶여 있어 재설계 대상.

이 이분법이 마이그레이션 스코프의 1차 필터가 된다.

6. 메모리 구조 — v0.6 4-tier

핵심 설계이자 가장 신중히 옮겨야 할 자산이다. 토큰 예산과 회상 품질을 분리해 다루기 위해 4개 층으로 쪼갠다.

  • Identity: MEMORY.md (600 토큰) — 항상 컨텍스트 선두에 들어가는 정체성
  • Curated: bank/ (world / experience / opinions / patterns / _changelog / _conflict_log / _map / index / topics)
  • Project: bank/entities/
  • Episode: memory/ (일일 로그)

검색 스택

  • 임베딩: oMLX bge-m3-mlx-fp16
  • 하이브리드: 벡터 0.7 / 키워드 0.3
  • 재랭크: MMR
  • 시간 보정: temporalDecay 30일

Reflect

  • 다단계 Phase 파이프라인
  • U-tag 변증법 (관찰 → 가설 → 검증)

설계 원리

  • Identity는 "항상 들어간다" → 600 토큰으로 하드캡.
  • Curated는 "질문 맥락에 따라 검색" → 벡터+키워드+MMR로 다양성 확보, temporal decay로 최신성 가중.
  • Episode는 "원천 로그" → 대부분 직접 읽지 않고 Reflect가 Curated로 승격.
  • Project는 엔티티 단위 격리 → 엔티티별 stale 감지(entity-audit) 가능.

이 4-tier는 "컨텍스트에 넣을 것 / 검색해 꺼낼 것 / 승격 대상 / 원천" 4개 역할을 물리적으로 분리한 것이다. 역할이 섞이면 토큰이 낭비되거나 회상이 노이즈로 오염된다.

7. 채널 라우팅

알림을 목적별로 쪼갠다.

  • Discord 주채널 (1487837031420792832): reflect, self-review 전부
  • Telegram Forum 토픽: General / Server / Bot / Research / Memory / Heartbeat

한 채널에 이벤트가 전부 몰리면 노이즈가 되어 알림을 무시하게 된다. 토픽 단위로 쪼개 두면 "무엇을 놓치면 안 되는가"를 채널 선택만으로 결정할 수 있다. 이 라우팅 컨셉 자체는 플랫폼에 종속되지 않는 설계라 이관해도 유지될 가능성이 크다.

한계와 적용 범위

  • 레이어 수 자체가 복잡성이다: 에이전트 / 크론 / LaunchAgent / 스크립트 / 훅 / 스킬로 나뉘는 다층 구조는 혼자 유지 가능한 상한선에 가깝다. 규모가 더 커지면 레이어를 합쳐야 한다.
  • oMLX 로컬 추론은 macOS Apple Silicon 전제: 동일 구조를 다른 OS에서 구현하려면 로컬 추론 스택을 교체해야 한다.
  • 크론·LaunchAgent 조합은 macOS 의존: 리눅스로 옮길 경우 systemd timer + unit으로 1:1 치환 가능하지만, 스케줄러가 바뀌면 셀프 리뷰 루프의 실패 복구 동작도 함께 재검증해야 한다.
  • 재사용 가능 영역 vs 종속 영역: 역할 분리 원칙·4-tier 메모리·채널 라우팅·일반 스킬은 이식 가능. oc-* 스킬·Gateway 데몬·훅 구성은 하네스마다 재설계가 필요하다.

열린 질문

  • 4-tier 메모리를 더 줄일 수 있는가 — Identity + Curated 2-tier로 합치면 무엇을 잃는가.
  • 단일 페르소나 + 백엔드 분리 구조에서 페르소나를 N개로 늘릴 때 라우팅 비용은 어떻게 증가하는가.
  • 헤르메스 베이스에서 어느 자산을 그대로, 어느 자산을 재설계, 어느 자산을 폐기할지 — 분류 기준은 "플랫폼 종속성"인가 "설계 부채"인가.

시리즈 전체 안내: 시리즈 목차

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »