Anima 딥다이브
— "모든 하드웨어에 영혼을" 집안 기기를 협업하는 에이전트로 만드는 Agent OS

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

Anima는 하드웨어 지능화 Agent Runtime이다. (1) 기기를 발견·등록하고 상태를 유지하며 어댑터로 실제 하드웨어를 제어한다, (2) 명시적 선호와 반복 행동에서 장기 기억(Memory)을 학습한다, (3) 환경·의도·기억·스킬 지식을 읽어 행동을 계획하는 LLM Brain을 쓴다, (4) 기기 종류별 도메인 지식을 Skill로 패키징한다, (5) 관찰·디버그·제어·확장을 위한 Dashboard·REST API·CLI를 제공한다. 현재는 샤오미 Mi Home / MIoT 기기를 지원하며, 더 많은 프로토콜이 추가될 예정이다.

2왜 주목받는가

트렌딩 이유 · Home Assistant 등 기존 스마트홈 대비 장점.

스마트홈 소프트웨어 자체는 새롭지 않다 — Home Assistant가 이미 거대한 생태계를 가지고 있다. 그런데도 Anima가 주목받는 이유는, 기존 스마트홈이 "규칙(automation)을 사람이 직접 짜는 도구"에 머물러 있는 지점에서 한 발 더 나아가 "LLM이 도메인 지식과 기억으로 스스로 판단하는 에이전트"를 지향하기 때문이다. 2025~2026년 "Agent + 물리 세계(physical AI)" 흐름을 스마트홈에 정조준한 셈이다.

3기술 스택 전체 지도

백엔드(코어)·프론트엔드(대시보드)·인프라(MQTT/도커) 각각.

① 백엔드 코어 — FastAPI + asyncio 단일 프로세스

Anima의 코어는 "Thin Core(얇은 코어) + MQTT 기기 레이어" 설계로, 단일 asyncio 프로세스 안에서 API·Brain·메모리·스케줄러·이벤트버스가 함께 돈다. 기기 제어는 본질적으로 I/O 바운드(네트워크·기기 응답 대기)라 동기 스레드 대신 비동기로 짜였다.

② 프론트엔드 — React + Vite 대시보드

③ 인프라 · 빌드 · 데이터

4아키텍처 심화 분석

신호 입력 → Brain 계획 → Skill 결정 → Adapter 실행 → 검증 → 학습.

전체 런타임 루프 한눈에

Anima의 흐름은 사용자 요청 · 기기 발견 · 센서 업데이트 · 예약 작업 · 기기 액션이라는 신호로 시작된다. 신호가 Anima Core에 들어오면, Brain이 기기 상태 + Memory + Skill 컨텍스트를 합쳐 이해·계획한다. 실행 단계에서 Skill이 결정을 구조화된 액션으로 바꾸고, Adapter가 그 액션을 구체적 하드웨어 프로토콜(MIoT 등)에 매핑해 실제 제어와 피드백 기록을 완성한다. 그 결과는 다시 History/Memory로 흘러 다음 결정을 개선한다.

핵심 설계 패턴 1 — Skill: 기기 지능의 최소 단위

Anima에서 Skill은 단순 함수나 프롬프트 한 줄이 아니다. 기기 도메인 지식을 담은 폴더 단위 패키지다. 구조는 다음과 같다.

skills/system/humidifier/
├── SKILL.md          # 메타데이터: 지원 기기·동작 규칙(프런트매터 YAML)
├── references/
│   ├── knowledge.md  # 도메인 지식(쾌적 습도 범위·계절 요인·에어컨 상호작용)
│   ├── decide.md     # 단일 결정 프롬프트
│   └── learn.md      # 장기 학습 프롬프트
└── scripts/
    └── actions.py    # 구조화 액션 실행 진입점

기본 제공 시스템 스킬은 다음과 같고, skills/custom/에 자신만의 스킬을 추가할 수 있다.

핵심 설계 패턴 2 — Memory: 증거 기반 3계층 장기 기억

매 요청마다 모든 이력을 LLM에 욱여넣으면 토큰이 폭발한다. Anima는 기억을 L1(핵심 정체성) · L2(기억 디렉토리) · L3(상세) 3계층으로 나눠, "필요할 때만 깊이 읽는다."

핵심은 "Planner는 기억이 무엇이 있는지(목차)만 먼저 알고, 실제 기기 Skill을 실행할 때 비로소 상세를 로드"한다는 점이다. 또한 기억은 그냥 저장되지 않고 증거(evidence)와 상태(status)를 갖는다.

핵심 설계 패턴 3 — Adapter: 얇은 하드웨어 추상화

Adapter는 Anima의 구조화된 액션을 실제 기기 프로토콜 호출로 변환한다. 인터페이스가 매우 작아서(BaseAdapter 추상클래스) 새 프로토콜을 붙이기 쉽다.

class BaseAdapter(abc.ABC):
    @abc.abstractmethod
    async def discover(self) -> list[Device]:
        """네트워크를 스캔해 발견한 기기 목록 반환"""

    @abc.abstractmethod
    async def subscribe(self, device: Device) -> None:
        """기기 상태 변화 모니터링 시작"""

    @abc.abstractmethod
    async def execute(self, device_id, action, params) -> ActionResult:
        """기기에 제어 명령 실행"""

5디렉토리 구조 해부

코어·어댑터·스킬·대시보드가 명확히 분리된 모노레포.

6학습 포인트 (기술별)

하드웨어 Agent OS 아키텍처에서 무엇을 배우나.

A. LangGraph로 짜는 Planner / Executor 흐름

Anima는 "LLM을 한 번 호출하고 끝"이 아니라, 상태를 가진 그래프(StateGraph)로 다단계 추론"을 짜는 살아 있는 예제다. engine.py의 BrainCycleState(TypedDict)를 보면 devices·environment_state·lightweight_skills·planner_output·plan_items·execution_results가 그래프 노드를 거치며 채워진다. "컨텍스트 구성 → 계획 → 실행 → 검증"을 노드로 분리하면 각 단계를 따로 테스트·교체할 수 있다.

B. "지식을 코드 밖으로" — 파일 기반 Skill 시스템

가장 배울 점은 기기 정책을 Brain이나 Adapter에 하드코딩하지 않고 SKILL.md + 프롬프트 파일로 외부화한 설계다. 새 기기 = 폴더 하나 추가. 이는 Anthropic의 "Agent Skills" 패턴(SKILL.md + references + scripts)을 스마트홈에 적용한 것으로, "변하는 부분(도메인 지식)은 데이터/문서로, 안 변하는 부분(로딩·실행 엔진)만 코드로"의 모범 사례다.

C. 토큰 예산을 지키는 계층형 메모리

L1/L2/L3 설계는 "LLM 컨텍스트는 비싸고 유한하다"는 현실을 정면으로 다룬다. 핵심 트릭은 get_planner_context()가 "기억의 목차(L2)만" 주고, get_skill_context(device_type)가 실제 실행 직전에야 상세(L3)를 로드하는 지연 로딩(lazy loading)이다. RAG·에이전트 메모리를 설계할 때 그대로 쓸 수 있는 패턴이다.

D. 증거 기반 신념(belief) 모델 — candidate→confirmed

기억에 positive/negative_evidence와 candidate/confirmed/rejected/stale 상태를 둔 것은 "한 번 본 걸 곧장 사실로 믿지 않는다"는 자세다. 확정(confirmed)된 기억만 결정에 쓰는 보수성은, 환각·과잉 일반화를 막는 에이전트 설계의 핵심 원칙이다. 추천 시스템·사용자 모델링에도 동일하게 응용된다.

E. 얇은 추상화 인터페이스 설계

BaseAdapter가 discover/subscribe/execute 단 3개 메서드인 것은 "플러그인 인터페이스는 작을수록 확장하기 쉽다"는 교훈이다. 인터페이스가 비대해지면 새 어댑터를 붙이는 비용이 커진다. 좋은 추상화 경계를 찾는 연습 대상으로 훌륭하다.

7하드웨어 / 시스템 요구사항

설치는 가볍지만, 실제 기기 제어에는 별도 조건이 붙는다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 가상 어댑터를 쓰면 실제 기기 없이도 대부분 가능.

9관련 기술 심화 학습 로드맵

6주 코스 — 비동기 백엔드부터 에이전트 메모리·하드웨어 통합까지.

10핵심 키워드 사전

본문·소스에 나온 용어 빠른 참조.

11참고 링크

• GitHub: Fullive-AI/Anima
• 설계 문서: 레포 내 docs/plans/design.md · ARCHITECTURE_GUARDRAILS.md · AGENT.md
• 핵심 개념: LangGraph 문서 · FastAPI 문서
• 하드웨어: python-miio (MIoT) · MQTT · Eclipse Mosquitto
• 비교 대상: Home Assistant (전통적 스마트홈 자동화 생태계)
• 도구: uv · pnpm