ShenSeanChen/waku-agent

해결하는 문제

Waku는 현대 에이전트가 어떻게 작동하는지 읽기 쉬운 투명한 블루프린트로 설계된 로컬 우선 개인용 AI 어시스턴트입니다. 복잡하고 '블랙박스' 형태의 에이전트 프레임워크를 대체하여, 사용자가 전체 에이전트 루프, 메모리 시스템, 평가 허브를 소유하고 이해할 수 있는 간단하고 읽기 쉬운 코드베이스를 제공합니다.

작동 방식

에이전트 루프

핵심은 약 95줄의 순수한 Python 루프로, 추론-행동-관찰 사이클을 따릅니다. LLM이 요청에 대해 추론하고, 필요 시 도구를 호출하며, 결과를 관찰한 후 최종 응답이 생성될 때까지 반복합니다.

메모리의 세 가지 기둥

메모리는 로컬 SQLite 데이터베이스(state.db)에 저장되며, 인간이 읽기 쉬운 MEMORY.md 파일에도 미러링됩니다. 세 가지 유형으로 구성됩니다:

• 의미적(Semantic): 지속적인 사실과 사용자 프로필.
• 에피소딕(Episodic): 날짜가 붙은 사건과 과거 대화.
• 절차적(Procedural): 기술과 '어떻게 하는지'에 대한 지침.

검색 게이트웨이

관련 없는 메모리가 답변을 왜곡하거나 지연을 유발하는 것을 방지하기 위해, '검색 게이트웨이'(작고 저렴한 모델)가 실제로 메모리 검색이 필요한지 판단한 후 데이터베이스에 접근합니다.

그래프 워크플로우

특정 구조가 필요한 작업에는 Waku가 그래프 워크플로우를 사용합니다. 이는 병렬 실행과 결정론적 라우팅을 가능하게 하며, 예를 들어 간단한 '고마워요' 메시지는 작은 모델로, 복잡한 작업은 전체 에이전트 루프로 라우팅할 수 있습니다.

LLM-Ops 및 평가

시스템에는 결정론적 테스트(올바른 도구가 실행되었는가?)와 LLM이 판단하는 테스트(응답이 유용했는가?)를 분리한 내장 평가 허브가 포함되어 있습니다. 모든 턴은 디버깅을 위해 JSONL 파일로 추적됩니다.

대상 사용자

• 무거운 프레임워크에 의존하지 않고 개인용 AI 어시스턴트를 구축하거나 이해하고 싶은 개발자.
• 로컬 우선 메모리와 에이전트 루프 엔지니어링을 구현하고 싶은 AI 엔지니어.
• 자신의 도구(캘린더, 메일, 텔레그램 등)와 통합 가능한 개인 정보 보호 중심의 로컬 우선 어시스턴트를 원하는 사용자.

주요 특징

• 로컬 우선: 메모리는 사용자가 소유하는 단일 SQLite 파일입니다.
• 시각적 대시보드: 에이전트의 추론, 도구 호출, 메모리 업데이트를 실시간으로 모니터링할 수 있는 로컬 웹 코크피트.
• 다중 제공자 지원: 간단한 어댑터를 통해 Anthropic, OpenAI, Gemini, DeepSeek 등과 호환됩니다.
• 투명한 아키텍처: 시스템의 모든 구성 요소가 코드 내 읽기 쉬운 파일에 직접 매핑됩니다.
• 통합 평가: 결정론적 평가와 판단 평가를 사용하는 내장 릴리스 게이트웨이가 있습니다.