헤르메스 에이전트용 Mnemosyne: 로컬 메모리 빠른 시작

Mnemosyne은 Hermes Agent를 위한 로컬 퍼스트(local-first) 메모리 프로바이더입니다. 워킹 메모리, 구조화된 사실, 시간 데이터, 그리고 에피소드적 역사를 로컬 SQLite에 저장하며, 호스팅된 서비스나 필수적인 네트워크 호출 없이도 유독 세밀한 수준의 쓰기(write) 제어를 제공합니다.

그의 가장 유용한 속성은 원시적 기억 품질(raw recall quality)이 아닙니다. 쓰기(write) 패스에 대해 노출하는 제어량의 수준입니다. 대화 자동 저장은 역할별로 제한하거나 완전히 비활성화할 수 있으며, 도구 결과(tool-result) 로깅은 기본적으로 꺼져 있고, 명시적인 기억(remember) 및 잊기(forget) 연산은 항상 사용 가능합니다. 또한 최신 릴리스에서는 컨텍스트 압축 경계(context-compression boundaries) 주위에 셀프 에코(self-echo) 억제가 옵트인(opt-in) 방식으로 추가되었습니다. 이러한 조합 덕분에 모든 대화를 자동으로 영구 지식으로 변환하지 않으면서도 영속적 메모리를 원할 때 합리적인 선택지가 됩니다.

이러한 쓰기 패스 규율이 중요한 이유는 에이전트 메모리가 잘 문서화된 실패 모드가 있기 때문입니다. 모델의 추론 자체가 관찰(observation)인 것처럼 캡처되어 나중에 검색된 후, 그 자체의 더 강한 버전을 정당화하는 데 사용될 수 있습니다. AI 에이전트에서의 자기 강화형 메모리 루프는 해당 실패 모드를 심층적으로 다루며, 이 가이드는 실제로 이를 제한하기 위한 구체적인 Mnemosyne 설정에 초점을 맞춥니다. Mnemosyne이 다른 Hermes 메모리 백엔드와 어떤 위치에 있는지 알고 싶다면 에이전트 메모리 프로바이더 비교를 참고하세요.

1분으로 이해하는 Mnemosyne

전형적인 메모리 프로바이더는 캡처, 추출, 저장, 검색, 그리고 향후 프롬프트에 주입하기까지의 어떤 형태로든 이 기본 루프를 수행합니다. Mnemosyne은 이 기본 루프 주위에 워킹 메모리, 의미적 및 문법적 회상(semantic and lexical recall), 구조화된 사실, 시간 정보, 엔티티 링크, 에피소드 메모리, 통합(consolidation), 정준 사실(canonical facts), 메모리 검증 등 여러 개의 별개의 레이어를 추가합니다. 저장소는 FTS5와 선택적 벡터 검색을 지원하는 로컬 SQLite로, 클라우드 전용 메모리 제품보다 훨씬 더 쉽게 검사할 수 있으며, 단순한 MEMORY.md 파일보다 더 강력한 기능을 제공합니다.

아주 간단히, Hermes 프로바이더 생태계의 다른 것들과 비교하면: Holographic은 더 단순하고 고의적으로 사실 저장소(fact-store) 지향적이며, Hindsight는 하이브리드 검색, 지식 그래프, 성찰(reflection)에 중점을 둡니다. Honcho는 담론 추론(dialectic reasoning)과 함께 피어 및 사용자 모델링에 중점을 두고, Mem0은 자동화된 LLM 기반 사실 추출에 중점을 둡니다. Mnemosyne은 로컬 SQLite 저장소, 하이브리드 회상, 통합, 구조화된 사실, 그리고 유독 세밀한 보존(retention) 제어를 결합합니다. 모든 프로바이더에 대한 인프라 요구 사항과 셀프 호스팅 참고 사항을 포함한 전체적인 분석은 에이전트 메모리 프로바이더 비교에 있습니다.

현재 버전

2026년 9월 기준으로, 안정적인 PyPI 릴리스는 mnemosyne-memory 3.15.1이며, 4.0 브랜치는 프리릴리스(pre-release)로 사용할 수 있습니다. 프로덕션 Hermes 설치의 경우, 4.0의 특정 수정 사항이나 기능이 필요하고 데이터베이스 마이그레이션 및 행동 변화에 대한 테스트를 준비한 것이 아닌 이상, 안정적인 버전부터 시작하는 것이 좋습니다. 설치된 버전을 확인하려면:

hermes mnemosyne version

Hermes에 Mnemosyne 설치하기

표준 로컬 설치를 사용했다면 먼저 Hermes 자신의 가상 환경을 활성화하세요:

source ~/.hermes/hermes-agent/venv/bin/activate

로컬 임베딩(嵌入) 지원이 필요하면, 임베딩 엑스트라(extra)와 Hermes 플러그인 래퍼를 포함하여 핵심 패키지를 설치하세요:

python -m pip install \
  "mnemosyne-memory[embeddings]" \
  mnemosyne-hermes

그 다음 플러그인을 등록합니다:

mnemosyne-hermes install

기존 플러그인 등록을 대체하는 경우:

mnemosyne-hermes install --force

프로바이더를 활성화하고 게이트웨이를 재시작합니다:

hermes config set memory.provider mnemosyne
hermes gateway restart

다음으로 확인합니다:

hermes memory status

기대되는 출력은 다음과 유사합니다:

Provider: mnemosyne

Plugin: installed
Status: available

Docker 및 영구 서버 설치

Hermes가 영구적인 Docker나 이미지 기반 배포 안에서 실행된다면, 컨테이너의 재빌드 가능한 Python 환경이 아닌 마운트된 Hermes 홈의 보조 가상 환경(side virtual environment)에 설치하여 이미지 재빌드 시 플러그인이 유지되도록 하세요:

export HERMES_HOME=/opt/data
VENV="$HERMES_HOME/.mnemosyne/venv"
python3 -m venv "$VENV"
"$VENV/bin/python" -m pip install --upgrade "mnemosyne-memory[embeddings]" mnemosyne-hermes
"$VENV/bin/mnemosyne-hermes" install --mode wrapper --python "$VENV/bin/python"
hermes config set memory.provider mnemosyne

보조 venv는 실행 중인 Hermes 게이트웨이와 동일한 Python major/minor 버전을 사용해야 하며, PATH의 무관한 python3을 가리키지 마세요. 이후 실제 컨테이너나 서비스를 재시작하고 "$VENV/bin/mnemosyne-hermes" status와 hermes memory status로 확인하세요.

Hermes 메모리 툴셋 전체를 비활성화하지 마세요

두 개념을 구분하십시오: Hermes 자체 내장 메모리(MEMORY.md / USER.md, Hermes Agent 메모리 시스템에서 완전히 다루어짐)와 외부 프로바이더(Mnemosyne). 외부 프로바이더를 구성할 때 hermes tools disable memory를 함부로 실행하지 마십시오. Hermes 버전에 따라, 해당 명령은 외부 메모리 프로바이더 도구도 숨길 수 있습니다. 아래에 표시된 것처럼 프로바이더 구성을 대신 사용하세요.

기본 상태 및 검사

hermes memory status
hermes mnemosyne stats
hermes mnemosyne stats --global
hermes mnemosyne inspect "query"

이동 가능한 백업을 내보냅니다:

hermes mnemosyne export \
  --output ~/mnemosyne-backup.json

백킹 데이터베이스는 일반적으로 ~/.hermes/mnemosyne/data/mnemosyne.db 아래에 위치합니다. SQLite이므로 표준 도구를 사용하여 검사와 백업이 직관적입니다. 이 가이드 전반에 걸쳐 언급된 나머지 게이트웨이, 세션, 진단 명령어에 대해 Hermes Agent CLI 치트시트는 --help 출력을 파헤치는 것보다 더 빠른 참고 자료입니다.

기본 보존(retention) 정책은 주의를 기울여야 합니다

이해해야 할 첫 번째 제어는 sync_roles입니다. 현재 Mnemosyne 기본값은 초기 릴리스보다 이미 더 보수적입니다 — 자동 Hermes 동기화는 사용자 턴(user turns)과 어시스턴트 턴(assistant turns) 양쪽이 아니라 사용자 턴으로만 기본적으로 설정되어 있습니다 — 하지만 엄격한 명시적 전용(explicit-only) 보존을 위해 턴 자동 저장을 완전히 비활성화하는 것은 추가 단계에 가치가 있습니다. ~/.hermes/config.yaml을 편집합니다:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

빈 리스트는 sync_turn()이 일반 대화 턴을 자동으로 저장하지 않음을 의미합니다. 명시적인 mnemosyne_remember 연산은 여전히 작동합니다 — 정상적인 대화가 자동으로 메모리로 흘러들어가는 것은 멈추지만, 명시적인 “이것을 기억해” 요청은 여전히 Mnemosyne에 도달합니다.

자동 도구 결과 로깅 비활성화

Mnemosyne는 도구 실행을 메모리로 로깅할 수도 있습니다. 보수적인 설정을 위해, ~/.hermes/.env에서 이를 비활성화한 상태로 두세요:

MNEMOSYNE_LOG_TOOLS=0

이미 이것이 기본값이지만, 명시적으로 설정함으로써 기본값에 대한 가정 대신 정책을 문서화합니다. 이후 Hermes를 재시작하세요:

hermes gateway restart

sync_roles: []와 MNEMOSYNE_LOG_TOOLS=0을 함께 사용하면, 두 가지 주요 자동 쓰기 경로(대화 자동 저장 및 도구 결과 자동 저장) 모두 꺼집니다.

자동 회상(recall) 유지

자동 쓰기를 비활성화한다고 해서 회상을 비활성화할 필요는 없습니다. 유용한 정책은 자동 보존을 끄면서 자동 회상, 명시적 기억, 명시적 잊기는 모두 켜두는 것입니다. 메모리는 읽기 쉽게, 쓰기 어렵게 만들어야 하며, 이는 “모든 것을 캡처하고 나중에 정리하자"는 기본값과 거의 반대되는 것입니다.

영구적인 에이전트 지침 추가

프로바이더 구성은 프로바이더 수준의 자동 캡처를 막지만, 모델은 여전히 자신의 이니셔티브에 따라 명시적인 쓰기 도구를 호출하기로 결정할 수 있습니다. SOUL.md에 명시적인 정책을 추가하세요:

## 장기 기억 정책

Mnemosyne은 장기 기억 프로바이더입니다.

사용자가 명시적으로 요청하지 않는 한 Mnemosyne에 아무것도 쓰지 마십시오.
기억, 저장, 보존, 또는 정보를 보관하라는 요청.

정보가 향후 세션에 유용할 수 있지만 사용자가 명시적으로 기억해 달라고 요청하지
않았다면, mnemosyne_remember 또는 다른 Mnemosyne 쓰기 도구를 호출하기 전에
허가를 요청하세요.

자체 추론, 가정, 요약, 해석, 결론, 또는 추론된 선호도를 기반으로 영구적인
메모리를 만들지 마십시오.

도구 출력을 기반으로 영구적인 메모리를 만들지 마십시오, 사용자가 명시적으로
그 결과를 기억해 달라고 요청한 경우가 아닌 이상.

승인된 메모리를 저장할 때, 사용자가 실제로 진술한 내용을 보존하세요.
추론된 컨텍스트나 결론으로 꾸며내지 마십시오.

Mnemosyne 메모리를 읽고 회상하는 것은 허가를 요청하지 않아도 허용됩니다.

게이트웨이를 재시작하고 이후 새로운 세션을 시작하세요:

hermes gateway restart

/new

이는 모델이 강제하는 정책이며, 경계가 딱딱한 권한 경계는 아닙니다 — 이는 위의 프로바이더 수준 구성을 대체하는 것이 아니라 보완하는 것입니다.

memory.write_approval은 어떨까요?

Hermes는 내장 MEMORY.md / USER.md 쓰기에 대해 memory.write_approval: true를 지원하며, Mnemosyne은 최신 릴리스에서 명시적인 쓰기에 대한 자체 프로바이더 전용 스테이징(staging)을 구현했습니다. 이것은 희망적이지만, 진지하게 받아들여야 할 아키텍처상의 주의 사항이 있습니다: Hermes는 아직 모든 외부 메모리 프로바이더에 대해 균일하고 프로바이더 중립적인 승인 계약을 노출하지 않으며, Mnemosyne의 pending/apply 구현은 공유 표준의 일부가 아니라 프로바이더 전용입니다. 구성 키가 존재한다고 해서 승인이 올바르게 작동한다고 가정하지 마십시오 — 사용 중인 정확한 Hermes 및 Mnemosyne 버전에 대해 테스트하세요. 프로바이더 독립적 승인이 성숙할 때까지, sync_roles: [], MNEMOSYNE_LOG_TOOLS=0, 그리고 위의 명시적 쓰기 SOUL.md 정책을 결합하면 신뢰할 수 있는 기반을 제공하며, 승인 경로에 의존하려는 경우 별도로 테스트합니다.

셀프 에코 억제 활성화

현재 Mnemosyne은 선택적 셀프 에코 억제도 제공합니다:

MNEMOSYNE_SELF_ECHO_ENABLED=1

이를 ~/.hermes/.env에 넣고, 재시작하세요:

hermes gateway restart

셀프 에코 억제는 특별히 컨텍스트 압축 경계를 표적으로 합니다 — 그 목적은 프로바이더가 방금 생성한 메모리가 독립적인 컨텍스트인 것처럼 에이전트에 즉시 되먹힘(feedback)되는 경우를 줄이는 것입니다. 이는 의도적으로 최선을 다하여(best-effort) 수행되며, 쓰기 필터링을 대체하지 않습니다: 쓰기 제어는 의심스러운 메모리가 처음부터 들어오지 못하게 막고, 셀프 에코 제어는 최근의 프로바이더 출력이 즉시 다시 튀어 나오지 못하게 막습니다. 둘 다 중요하며, 어느 것도 다른 것을 대체하지 않습니다.

보수적인 Mnemosyne 구성

부품들을 모아 보면, 셀프 호스팅된 개인 엔지니어링 에이전트에 대한 시작 구성은 다음과 같습니다. ~/.hermes/config.yaml에:

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

~/.hermes/.env에:

MNEMOSYNE_LOG_TOOLS=0
MNEMOSYNE_SELF_ECHO_ENABLED=1

그리고 SOUL.md에, 최소한:

사용자가 명시적으로 요청할 때만 장기 기억을 저장하세요.
명시적인 허가 없이 모델 생성된 결론이나 도구 출력을 영구적인 메모리로
격상하지 마십시오.

일반 대화가 보존되지 않는지 테스트하기

먼저 기준(베이스라인) 개수를 확인하세요:

hermes mnemosyne stats

새로운 Hermes 세션을 시작하고, 에이전트에게 기억하라고 요청하지 않고 단순한 사실적 진술을 하세요, 예를 들어:

PurpleOtter uses port 48123.

그 후, 그것에 대해 검색하세요:

hermes mnemosyne inspect "PurpleOtter"

기대치: Results for 'PurpleOtter': 0. 또한 hermes mnemosyne stats를 다시 확인하세요 — 그 일반 턴 때문에 워킹 메모리 개수가 증가해서는 안 됩니다.

명시적 메모리 테스트

이제 같은 종류의 진술을 하지만, 명시적으로 보존을 요청하세요:

Remember that BlueKoala uses port 17321.

검사하고, 새 세션을 시작하여 다시 요청하세요:

hermes mnemosyne inspect "BlueKoala"

/new

What port does BlueKoala use?

Hermes는 값을 올바르게 검색해야 합니다 — 이 테스트 쌍은 쓰기 패스 정책(요청 없이는 아무것도 들어오지 않음)과 검색 메커니즘(들어온 것은 신뢰할 수 있게 다시 나옴)를 격리합니다.

도구 로깅 테스트

MNEMOSYNE_LOG_TOOLS=0이 설정된 상태에서, Hermes에게 독특하고 고유한 명령을 실행하도록 요청하세요:

Use the terminal tool to run:
echo tool-canary-834729

그 다음 카너리(canary) 문자열에 대해 검색하세요:

hermes mnemosyne inspect "tool-canary-834729"

기대치: 0 results. 이는 환경 변수가 모든 곳에서 준수된다고 단순히 믿는 것보다 훨씬 더 강력한 테스트입니다.

데이터베이스 검사

저장이 SQLite이므로, 내부 스키마는 직접 검사할 수 있습니다:

sqlite3 ~/.hermes/mnemosyne/data/mnemosyne.db '.tables'

버전에 따라 working_memory, episodic_memory, facts, consolidated_facts, gists, graph_edges, memoria_facts, memory_embeddings와 같은 테이블을 볼 수 있습니다. 이것은 삭제를 테스트할 때 중요합니다 — 메모리 시스템은 워킹 메모리 행을 성공적으로 제거하되, 파생된 사실, gist, 또는 그래프 객체를 남겨둘 수 있습니다. Mnemosyne은 고아된 파생 레코드에 관여하는 실제 버그가 이 영역에서 있었고, 최신 릴리스는 삭제와 진단을 모두 이에 따라 더 엄격하게 만들었습니다. 현재 스키마를 완전히 이해하지 않는 한, SQLite 행을 수동으로 삭제하기보다 프로바이더가 지원하는 삭제 및 doctor/repair 경로를 선호하세요.

세션 범위 워킹 메모리 삭제

한 가지 미묘한 점: Mnemosyne 워킹 메모리는 세션 범위일 수 있으므로, scope = session인 행은 default 세션에서 작동하는 독립적인 삭제 작업에 의해 표시되지 않을 수 있습니다. 디버깅 중에는 범위를 직접 검사하세요:

SELECT id, session_id, scope, content
FROM working_memory;

프로바이더 또는 API는 세션 로컬 레코드를 변경하기 위해 올바른 세션 범위를 필요로 합니다 — 이는 원시 SQL 편집보다 지원되는 관리 도구를 선호해야 하는 또 다른 이유입니다.

통합(Consolidation): sleep()에 서두르지 마세요

Mnemosyne은 워킹 메모리를 더 긴 수명의 표현으로 통합할 수 있으며, 이는 유용하지만 변경(mutating) 작업입니다. 공격적인 자동 통합을 활성화하기 전에, 실제로 캡처되는 것을 검사하고, 일반 턴이 의도치 않게 메모리에 들어오지 않는지 확인하고, 삭제를 끝에서 끝까지 검증하며, 데이터베이스를 백업하세요. 그런 다음 다음을 실험해 보세요:

hermes mnemosyne sleep

최근 Mnemosyne 변경 사항은 충돌 처리를 더 보수적으로 만들었습니다 — 의미적 유사성만으로는 한 메모리가 다른 메모리를 무효화해야 한다는 것을 더 이상 증명하지 않으며, 이는 AI 에이전트에서의 자기 강화형 메모리 루프에서 다룬 대로 영구적인 에이전트 메모리 시스템이 나아가야 할 정확한 방향입니다.

업그레이드 전 백업

중요한 변경 사항을 수행하기 전에 이동 가능한 내보내기를 생성하세요:

hermes mnemosyne export \
  --output ~/mnemosyne-backup.json

중요한 설치의 경우, 주요 업그레이드 전에 로컬 데이터베이스 또는 데이터 디렉토리를 복사해 두세요. Mnemosyne 4.x는 현재 프리릴리스 라인이며, 따라서 메이저 버전 업그레이드는 루틴 패치 업데이트보다 더 많은 주의가 필요합니다.

최종 권장 설정

모든 것을 기억하는 것보다 메모리의 정확성이 더 중요한 장기 실행 Hermes 설치의 경우, 영구적인 구성은 다음과 같습니다: Mnemosyne 로컬 저장소 켜기, 자동 회상 켜기, 대화 자동 저장 끄기, 어시스턴트 메시지 자동 저장 끄기, 도구 결과 로깅 끄기, 명시적 기억 및 잊기 켜기, 셀프 에코 억제 켜기, 세션 검색 켜기, 그리고 승인 경로가 테스트된 후에는 민감한 쓰기에 대한 인간 검토를 원하는 것입니다. 이렇게 하면 Mnemosyne은 트랜스크립트 아카이브가 아니라 큐레이팅된(long-term curated) 장기 기억 저장소로 주로 기능하게 됩니다 — 목표는 Hermes가 한 모든 것을 기억하게 만드는 것이 아니라, 다음 세션이 시작될 때 여전히 참일 것들을 기억하게 만드는 것입니다. 다른 프로바이더나 보존 정책을 가진 여러 프로파일을 실행하는 경우, Hermes Agent 프로덕션 설정는 일관성을 유지하기 위한 프로파일 수준의 배선을 다룹니다.