헤르메스 에이전트 스킬 시스템 완전 분해: 3계층 메모리와 SQLite FTS5 [3편]

작성자:

TL;DR

  • 헤르메스의 스킬 파일은 YAML 프론트매터 + Markdown 본문으로 구성된 사람이 읽을 수 있는 파일이며, 에이전트가 자동 생성하고 인간이 편집·삭제할 수 있다.
  • 세션 색인에 SQLite FTS5 키워드 검색을 쓰는 이유는 명확하다. 임베딩보다 재현성이 높고 외부 API 의존 없이 로컬 디버깅이 가능하다.
  • 팀 단위에서는 skills 디렉터리를 Git 저장소로 관리하는 것이 스킬 품질 유지의 핵심이다.

시리즈 목차

편 주제
1편 소개 — 무엇이 다른가
2편 설치 가이드
3편 스킬 시스템 완전 분해 (현재 글)
4편 자동화 워크플로우 실전
5편 실무 도입 결론

스킬 파일이란 무엇인가

헤르메스 에이전트가 복잡한 작업(도구 호출 5회 이상)을 마치면, 에이전트 자신이 그 작업을 정리한 Markdown 파일을 생성한다. 이것이 스킬 파일이다.

스킬 파일의 핵심은 단순함이다. 에이전트가 작성하지만 사람이 읽고 수정할 수 있다. Git에 커밋할 수 있다. 팀원 간 공유가 된다. PR 리뷰 대상이 된다.

스킬 파일 구조

스킬 파일은 YAML 프론트매터와 Markdown 본문으로 구성된다.

---
name: postgresql-connection-pool-setup
version: 3
created: 2026-05-10T09:23:00Z
last_used: 2026-05-14T14:07:00Z
use_count: 7
trigger_keywords:
  - postgresql
  - connection pool
  - asyncpg
  - pgbouncer
confidence: 0.87

목적

PostgreSQL 연결 풀 설정 시 발생하는 일반적인 문제 해결
접근법

1. asyncpg 기준 최소 pool_size=5, max_size=20으로 시작
2. PgBouncer 사용 시 transaction 모드 vs session 모드 트레이드오프 확인
3. max_overflow는 트래픽 피크 × 1.5로 계산
경계 케이스


  • too many clients 오류: max_connections 확인 후 PgBouncer 앞단 배치
    • 

  • 연결 누수: asyncpg context manager 미사용 시 발생. async with pool.acquire() as conn: 필수
    • 

  • 타임아웃: command_timeout 기본값 None → 프로덕션에서 30s 명시 권장
    • 



검증된 설정 (FastAPI + asyncpg)

asyncpg.create_pool(dsn, min_size=5, max_size=20, command_timeout=30)

use_count: 7은 이 스킬이 7번 재사용됐다는 뜻이다. 에이전트는 재사용할 때마다 스킬을 업데이트하므로, 자주 쓰이는 스킬일수록 정교해진다.

SQLite FTS5: 임베딩 대신 키워드 검색을 선택한 이유

대부분의 AI 에이전트 메모리 시스템은 임베딩 벡터 유사도 검색을 쓴다. 헤르메스는 SQLite FTS5 기반 키워드 검색을 선택했다.

이 결정은 에이전트 실용성 관점에서 몇 가지 강점을 가진다.

재현성. 임베딩 검색은 같은 쿼리도 모델이 바뀌면 결과가 달라진다. FTS5 키워드 매칭은 입력이 같으면 결과가 같다. 에이전트가 “왜 이 스킬을 로드했는가”를 사람이 이해할 수 있다.

정확성. 에러 메시지나 함수명처럼 정확한 문자열로 검색할 때 임베딩보다 FTS5가 더 정확하다. too many clients라는 에러로 검색하면 의미적으로 유사한 결과가 아니라 그 에러를 다룬 스킬을 찾아낸다.

비용. 외부 임베딩 API가 필요 없다. 스킬이 1,000개가 되어도 로컬 SQLite 연산이다.

# 헤르메스 내부 스킬 검색 흐름
작업 요청: "asyncpg 연결 풀 타임아웃 설정"
FTS5 쿼리:
  SELECT * FROM skills
  WHERE skills MATCH 'asyncpg AND (connection OR pool OR timeout)'
  ORDER BY rank
→ postgresql-connection-pool-setup.md 로드
→ 처음부터 추론하지 않고 스킬 기반으로 바로 답변

3계층 메모리의 역할 분담

graph LR
    A[작업 요청] --> B[Honcho 사용자 모델]
    B --> |스택 선호도\n축약어 패턴| C[컨텍스트 보강]
    A --> D[SQLite FTS5\n세션 색인]
    D --> |관련 과거 세션| C
    C --> E[스킬 파일 검색]
    E --> |최적 스킬 로드| F[에이전트 실행]
    F --> G{도구 호출 5회+?}
    G -- Yes --> H[새 스킬 파일 생성/업데이트]
    H --> E
    G -- No --> I[응답 반환]

Honcho 사용자 모델은 특히 중요하다. 예를 들어 사용자가 Python 코드를 작성할 때 항상 type hint를 붙이는 패턴을 보이면, 이후 코드 생성 작업에서 에이전트가 자동으로 type hint를 포함한다. 명시적으로 요청하지 않아도 된다.

팀 단위 스킬 관리 전략

스킬 파일이 Markdown이라는 점이 팀 워크플로우와 잘 맞는다.

Git 기반 스킬 저장소:

# 팀 스킬 저장소 생성
mkdir team-hermes-skills && cd team-hermes-skills
git init
# 헤르메스 config에서 skills 디렉터리를 저장소 경로로 지정
# ~/.hermes/config.yml
skills:
  directory: /path/to/team-hermes-skills
  auto_generate: true

스킬 품질 관리 체크리스트:

에이전트가 자동 생성한 스킬을 그대로 신뢰하지 않는다. 정기적으로 아래를 확인한다.

1. confidence 점수가 0.7 미만인 스킬은 사람이 검토
2. use_count가 0인 스킬은 1개월 후 삭제 검토
3. 경계 케이스가 비어있는 스킬은 보강 필요
4. deprecated API를 참조하는 스킬은 즉시 업데이트

중요한 한계: 스킬 품질은 LLM의 자기관찰 능력 수준이다. 에이전트가 작업을 잘못 이해하고 스킬을 작성하면, 그 잘못된 스킬이 다음 작업에 영향을 준다. 자동 생성된 스킬을 주기적으로 사람이 검토하는 프로세스가 없으면 기술 부채처럼 쌓일 수 있다.

스킬 직접 작성

에이전트 자동 생성을 기다리지 않고 팀이 직접 스킬 파일을 작성할 수 있다. 토스·카카오처럼 특정 도메인 지식이 많은 팀에서 효과적이다.

---
name: internal-api-auth-pattern
version: 1
created: 2026-05-15T00:00:00Z
trigger_keywords:
  - internal api
  - service auth
  - mtls
confidence: 1.0

목적

사내 서비스 간 인증 패턴 (mTLS 기반)
접근법

1. 서비스 계정 인증서는 /etc/ssl/internal/ 경로에 마운트
2. 모든 내부 API 호출은 X-Service-Token 헤더 필수
3. 타임아웃: 연결 2s, 읽기 10s 표준
경계 케이스


  • 인증서 만료: cert-manager 자동 갱신 정책 확인
    • 

  • 개발 환경: SKIP_MTLS=true 환경 변수로 우회 (프로덕션 절대 금지)
    •

사내 특수 패턴을 스킬로 미리 작성해두면, 신규 팀원이 에이전트를 사용할 때부터 팀 컨벤션이 반영된 답변을 받는다.

다음 편 예고

4편에서는 스킬 시스템을 토대로 실제 자동화 워크플로우를 구축한다.

  • 크론 스케줄링으로 정기 리포트 자동화
  • 서브에이전트 병렬 실행
  • CI/CD 파이프라인 통합
  • GitHub Actions 연동

참고 자료

댓글 남기기