# Hermes

세션 체크포인트, 자동 캡처 및 지속적인 프로젝트 메모리를 지원하는 PyPI의 네이티브 메모리 플러그인을 통해 Hermes Agent를 연결합니다.

- Canonical: https://docs.xmemo.dev/ko/docs/connect/hermes
- Locale: ko-KR
- Content-Locale: ko-KR
- Canonical-Content-Digest: bc9df4e1a62a317f42328c5fb35b354a1666ef85ea9f18ff6c96dbf5dccbdd9f
- Edition-Digest: c291f0b536ade5af326e7056bbed2582c6d0a4bba17488fef752adb6b8198f4e
- Source-Revision: sha256:c1c2001f12dcea28dab430debe91620cc57ef3d7fced5162a27e2afa3fe87072

## 대상 독자 및 구체적 인터페이스

이 가이드는 Hermes Agent를 XMemo 영구 메모리에 연결합니다. Hermes는 PyPI에서 유지 관리되는 네이티브 메모리 플러그인 패키지 hermes-xmemo (버전 1.1.3)를 통해 통합되며 활성 리포지토리 yonro/hermes-xmemo-plugin @ 30fe1bc20a (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md)에 고정되어 있습니다. 보관된 리포지토리 yonro/xmemo-hermes-plugin @ eb47797a08은 레거시 마이그레이션 참조용일 뿐이며 모든 신규 설치에는 hermes-xmemo를 사용합니다.

## 사전 요구 사항

연결하기 전에 다음 런타임 종속성 및 도구가 준비되어 있는지 확인합니다:

- Hermes Agent CLI 및 런타임 설치 (Python 3.10+).
- Python 패키지 설치 관리자 (pip).
- https://xmemo.dev의 유효한 XMemo 계정.
- HTTPS를 통한 https://xmemo.dev/mcp 네트워크 액세스.

## 설치

공식 Hermes 플러그인 마켓에서 Hermes XMemo 제공자를 설치합니다. Hermes 버전에서 플러그인 마켓 명령을 지원하지 않는 경우 고정된 PyPI 대체 방식을 사용하십시오.

```bash
hermes plugins install xmemo

# Fallback for older Hermes versions
pip install hermes-xmemo
hermes memory setup xmemo
```

## 인증 및 자격 증명 구성

환경 변수 또는 Hermes 구성을 사용하여 인증을 구성합니다. 버전 관리에 일반 베어러 토큰을 절대 커밋하지 마십시오:

- 환경 변수 (권장): Hermes를 시작하는 셸 또는 환경에서 XMEMO_KEY를 설정합니다 (export XMEMO_KEY='<your-xmemo-token>').
- Hermes 설정 마법사: hermes memory setup xmemo를 실행하면 자격 증명을 묻는 메시지가 표시되고 ~/.hermes/config.yaml이 구성됩니다.
- 구성 확인: ~/.hermes/config.yaml에 memory.provider가 xmemo로 설정되어 있는지 확인합니다.

## 로드 및 재시작 동작

데몬 재시작 또는 세션 다시 로드 절차는 hermes-xmemo 플러그인 README (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md)에 명시적으로 설명되어 있지 않습니다. Hermes Agent 호스트 문서를 참조하거나 활성 Hermes 터미널 세션을 다시 시작하십시오.

## 연결 확인 (읽기 전용)

지속적인 데이터를 작성하기 전에 읽기 전용 회상 요청으로 연결 상태를 확인합니다. 이 확인은 메모리 상태를 수정하지 않습니다:

- 확인: 테스트 Hermes 세션을 시작하고 기존 프로젝트 컨텍스트에 대해 읽기 전용 활성 회상 쿼리를 실행합니다.
- 성공 신호: Hermes가 승인된 워크스페이스에서 유효한 Reference 및 Location 필드가 포함된 구조화된 메모리 결과를 반환합니다.

## 첫 번째 유용한 작업: 합성 메모리 수명 주기

메모리 지속성, 상태 비저장 세션 전환, 출처 귀속 회상 및 수정을 확인합니다:

- 1. 합성 사실 저장: 프로젝트 규칙 ("Hermes demo conventions: UTC logging with ISO 8601 timestamps.")을 "projects/demo-hermes/conventions"에 저장합니다.
- 2. 상태 비저장 전환: 현재 Hermes 대화를 종료하고 새 세션을 시작합니다.
- 3. 출처 귀속 회상: "demo conventions timestamp format"을 쿼리합니다. 반환된 Reference 및 Location을 확인합니다.
- 4. 메모리 수정: 업데이트된 서식 지정 규칙을 지정하여 update_memory를 통해 기억된 규칙을 업데이트합니다.
- 5. 선택적 정리: 온보딩 확인이 완료되면 데모 규칙을 소프트 삭제 (forget)합니다.

## 자동 캡처 및 중복 방지

Hermes Agent는 실행 경계를 넘어 자동 컨텍스트 캡처를 제공합니다:

- 세션 체크포인트: ~/.hermes/config.yaml에서 활성화된 경우 Hermes는 세션 경계 마일스톤에서 세션 요약 및 주요 결정을 캡처합니다.
- 중복 방지: 내장된 콘텐츠 해시 중복 제거를 통해 반복적인 실행 루프 중에 동일한 사실과 결정이 반복해서 기록되지 않도록 합니다.
- 범위 경계: 캡처된 모든 메모리는 인증된 사용자의 워크스페이스 및 활성 프로젝트 범위로 엄격하게 격리됩니다.

## 제공자 충돌 및 스토리지 경계

런타임 격리 및 스토리지 소유권의 이해:

- 제공자 충돌: ~/.hermes/config.yaml에서 여러 메모리 제공자를 동시에 활성화하지 마십시오. 중복되는 제공자를 실행하면 스플릿 브레인 회상이 발생합니다.
- 스토리지 소유권: 모든 영구 메모리는 사용자가 소유한 XMemo 클라우드 백엔드에 있습니다. Hermes는 세션 응답성을 위한 단기 로컬 캐시만 유지합니다.
- 오프라인 및 재생 제한: 일시적인 네트워크 중단은 제한된 로컬 쓰기 버퍼에 의해 처리됩니다. 버퍼 제한 또는 토큰 만료에 도달하면 오프라인 쓰기가 실패하며 커밋되지 않은 작업은 다시 연결될 때까지 다른 에이전트에 복제되지 않습니다.

## 복구, 업데이트 및 제거

Hermes의 문제 해결, 업데이트 및 제거 절차:

- 복구 (401 invalid_token): 현재 셸 환경 또는 Hermes 구성에서 XMEMO_KEY가 설정되어 있는지 확인합니다.
- 업데이트: 플러그인 업데이트 명령은 hermes-xmemo 플러그인 README (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md)에 설명되어 있지 않습니다. pip install --upgrade hermes-xmemo를 실행하거나 Hermes 호스트 문서를 참조하십시오.
- 제거 (README 292행): Hermes에서 메모리 제공자를 비활성화하려면 문서화된 제거 명령을 실행합니다: hermes config set memory.provider "".
- 제거와 원격 삭제의 비교: 로컬 제공자를 비활성화해도 저장된 원격 메모리가 삭제되거나 API 자격 증명이 해지되지 않습니다. 메모리를 삭제하거나 키를 해지하려면 https://xmemo.dev/me를 이용하십시오.

```bash
hermes config set memory.provider ""
```