SemaClaw: 하네스 엔지니어링을 통한 범용 개인용 AI 에이전트로의 진전

모델 자체의 성능 개선을 넘어 에이전트를 감싸는 인프라 구조인 하네스 엔지니어링의 중요성을 입증했다. 복잡한 다단계 작업을 안정적으로 수행하고 사용자의 지식을 지속적으로 축적하는 오픈소스 프레임워크를 통해 실용적인 개인용 AI 비서 구현의 기틀을 마련했다.

기존의 AI 에이전트는 주로 단일 ReAct 루프 내에서 작동하며, 대화가 길어질수록 컨텍스트 윈도우가 가득 차서 이전의 제약 조건이나 결정을 잊어버리는 '기억 상실' 문제에 직면한다. 이는 Transformer 아키텍처의 Self-Attention이 모든 토큰을 동일하게 처리하려다 보니 발생하는 한계로, 중요한 정보가 노이즈에 묻히는 현상을 초래한다.

SemaClaw는 이를 해결하기 위해 운영체제의 페이징 기법과 유사한 '하네스(Harness)' 계층을 도입한다. 핵심 아이디어는 컨텍스트를 단순히 쌓아두는 버퍼가 아니라 관리해야 할 자원으로 취급하는 것이다. 컨텍스트가 일정 수준(75%)에 도달하면 중요 정보를 요약하여 압축하고, 나머지는 외부 저장소로 밀어내어 모델의 주의 집중력을 유지시킨다.

또한, 복잡한 작업 시 LLM이 즉흥적으로 다음 행동을 결정하게 두지 않고, 먼저 전체 작업의 인과 관계를 담은 그래프(DAG)를 설계하게 한 뒤 시스템이 이를 순차적으로 집행하게 한다. 이는 딥러닝의 추론 유연성을 유지하면서도 소프트웨어 공학의 예측 가능성을 결합하여 에이전트의 신뢰도를 높이는 원리이다.

SemaClaw는 이벤트 기반의 에이전트 런타임인 sema-code-core와 그 위의 애플리케이션 하네스 계층으로 구성된 2계층 구조를 가진다. 런타임은 세션 초기화, 도구 호출, 컨텍스트 업데이트 등 모든 상태 변화를 정형화된 이벤트로 처리하여 외부 시스템과의 결합도를 낮춘다.

컨텍스트 관리는 세 가지 소스를 동적으로 주입한다. Working Memory는 현재 세션의 대화 이력을 담당하며, 용량 초과 시 요약 모델을 통해 압축된다. External Memory는 과거 세션의 기록을 벡터 검색과 키워드 검색이 결합된 하이브리드 방식으로 추출한다. Structured Context Injection은 에이전트의 고정된 정체성(Soul)과 현재 작업 환경(Workspace) 정보를 명확히 구분하여 주입한다.

오케스트레이션은 DAG Teams 방식을 사용한다. 관리자 에이전트가 create_parent 함수를 호출하여 작업 목표와 하위 작업 배열을 전달하면, 시스템은 [작업 간 의존성 확인 → 순환 참조 검사 → 가용 에이전트 매칭] 과정을 거쳐 실행 계획을 확정한다. 이후 DispatchBridge 스케줄러가 300ms 주기로 상태를 확인하며 의존성이 해결된 작업을 순차적으로 실행한다.

LangChain의 Terminal Bench 2.0 실험 결과, 모델을 고정시킨 상태에서 하네스 구성만 개선했을 때 작업 완료율이 52.8%에서 66.5%로 13.7%포인트 향상되었다. 이는 에이전트의 성능이 모델 자체의 지능만큼이나 이를 보조하는 시스템 구조에 크게 의존함을 보여준다.

컨텍스트 압축 메커니즘은 컨텍스트 윈도우의 75% 지점에서 작동하며, 8,000토큰의 여유 버퍼를 유지함으로써 긴 대화에서도 추론 품질 저하를 방지했다. 요약 모델이 실패할 경우를 대비해 이력을 50%로 강제 절단하는 폴백 메커니즘을 갖추어 시스템 안정성을 확보했다.

외부 메모리 검색 시 Vector 검색과 FTS5 키워드 검색을 결합한 하이브리드 방식을 적용하여, 단순 벡터 유사도만 사용했을 때보다 전문 용어나 고유 명사에 대한 재현율(Recall)을 높였다. 특히 두 경로 모두에서 발견된 문서에 0.7과 0.3의 가중치를 부여해 합산하는 방식을 통해 검색 정확도를 최적화했다.

SemaClaw의 핵심은 '하네스 엔지니어링'으로, 모델 외부에서 실행 제어와 데이터 흐름을 규제하는 인프라 설계에 집중한다. 아키텍처는 Anthropic의 Model Context Protocol(MCP)을 준수하여 도구 생태계의 호환성을 확보했다.

권한 관리 시스템인 PermissionBridge는 전역 싱글톤 인스턴스로 작동하며, 모든 에이전트 세션의 승인 요청을 고유 식별자(Request ID)로 멀티플렉싱한다. 이는 다수의 에이전트가 동시에 승인을 기다려도 세션 컨텍스트가 섞이지 않게 하며, 사용자가 응답할 때까지 실행을 일시 중단(Pause)했다가 재개(Resume)하는 상태 보존 기능을 제공한다.

메모리 시스템은 '지식 침전(Knowledge Sedimentation)' 개념을 구현한다. 단순 로그 적재가 아니라, 에이전트가 작업 중 얻은 통찰을 YAML 프론트매터가 포함된 Markdown 파일로 구조화하여 저장한다. 이 파일들은 데이터베이스가 아닌 로컬 파일 시스템에 직접 저장되어 버전 관리와 사용자 직접 편집이 용이하도록 설계되었다.

현재 구현은 주로 CLI와 웹 UI에 집중되어 있어 메시징 플랫폼이나 음성 인터페이스와의 통합이 미흡하다. 또한 Claude Code의 최신 확장 모델과 완전히 동기화되지 않아 사용자 정의 훅(Hook) 통합이 불완전하며, 위키 지식 베이스와 세션 메모리 간의 통합 검색 기능이 아직 구현되지 않은 상태이다.