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

Mnemosyne은 Hermes Agent를 위한 로컬 우선(local-first) 기억(memory) 제공자(provider)로, 작업 기억(working memory), 구조화된 사실(structured facts), 시계열 데이터(temporal data), 그리고 에피소드적 히스토리(episodic history)를 로컬 SQLite에 저장합니다. 호스팅된 서비스도, 필수적인 네트워크 호출도 없으며, 비정상적으로 세밀한(write) 제어 권한을 제공합니다.

가장 유용한 특성은 원시적인 검색(recall) 품질이 아닙니다. 쓰기(write) 경로에 대해 얼마나 많은 제어 권한을 노출하느냐에 있습니다. 대화 자동 저장은 역할별로 제한하거나 완전히 비활성화할 수 있고, 도구 결과(tool-result) 로깅은 기본적으로 꺼져 있으며, 명시적인 remember와 forget 연산은 항상 사용 가능합니다. 그리고 최신 릴리스에서는 컨텍스트 압축 경계 주위에 opt-in self-echo 억제가 추가되었습니다. 이러한 조합은 영속적인 기억이 필요하지만, 모든 대화를 자동으로 영구적 지식으로 변환하고 싶지 않은 합리적인 선택지를 만들어 줍니다.

이러한 쓰기 경로 규율이 중요한 이유는 에이전트 기억에 잘 문서화된 실패 모드가 있기 때문입니다. 모델의 추론(inference)이 캡처되어 나중에 관찰(observation)인 것처럼 검색되어, 자기 자신을 더 강한 버전으로 정당화하는 데 사용될 수 있습니다. AI 에이전트에서의 자기 강화형 기억 루프가 이 실패 모드에 대해 심도 있게 다루며, 본 가이드는 실제 상황에서 이를 제한하는 구체적인 Mnemosyne 구성에 초점을 맞춥니다. Mnemosyne이 다른 Hermes 기억 백엔드 대비 어디에 위치하는지 확인하려면 에이전트 기억 제공자 비교를 참조하세요.

1분 만에 알아보는 Mnemosyne

전형적인 기억 제공자는 캡처(capture), 추출(extract), 저장(store), 검색(retrieve), 그리고 미래 프롬프트에 주입(inject)하는 과정의 어떤 버전을 수행합니다. Mnemosyne은 이러한 기본 루프 주위에 여러개의 명확한 계층을 추가합니다: 작업 기억, 의미론적 및 어휘적 검색, 구조화된 사실, 시계열 정보, 엔티티 링크, 에피소드 기억, 통합(consolidation), 정준 사실(canonical facts), 그리고 기억 검증(memory validation). 저장소는 FTS5와 선택적 벡터 검색이 포함된 로컬 SQLite로, 클라우드 전용 기억 제품보다 훨씬 더 점검(inspectable)이 가능하며, 단순한 MEMORY.md 파일보다 더 강력한 기능을 제공합니다.

간략히, Hermes 제공자 생태계의 나머지 부분과 비교하면 다음과 같습니다: Holographic은 더 단순하며 의도적으로 사실 저장소(fact-store) 지향적입니다; Hindsight는 하이브리드 검색, 지식 그래프, 반성(reflection)을 강조합니다; Honcho는 변증법적 추론을 통한 동료 및 사용자 모델링을 강조합니다; 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

로컬 임베딩(embedding) 지원을 위해, 임베딩 추가 옵션(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 홈에 별도의 가상 환경을 설치하여 플러그인이 이미지 재빌드 후에도 유지되도록 하십시오:

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 메이저/마이너 버전을 사용해야 합니다 — PATH에 있는 관련 없는 python3를 가리키지 마십시오. 그 후 실제 컨테이너나 서비스를 재시작하고 hermes memory status와 함께 "$VENV/bin/mnemosyne-hermes" 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 출력을 뒤적이는 것보다 빠른 참조 자료입니다.

기본 보존 정책 주의

이해할 가치가 있는 첫 번째 컨트롤은 sync_roles입니다. 현재 Mnemosyne 기본값은 초기 릴리스보다 이미 더 보수적입니다 — 자동 Hermes 동기화는 사용자 턴(user turns)을 기본으로 하거나 사용자 및 어시스턴트 턴을 둘 다 기본으로 하지 않습니다 — 하지만 엄격한 명시적-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) 비활성화를 요구하지 않습니다. 유용한 정책은 자동 보존은 꺼두고, 자동 검색, 명시적 remember, 명시적 forget은 모두 켜두는 것입니다 — 기억은 읽기는 쉬워야 하고 쓰기는 어려워야 하며, 이는 “모든 것을 캡처하고 나중에 정리를 하자"는 기본값과 반대되는 방향에 가깝습니다.

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

제공자 구성은 제공자 수준의 자동 캡처를 차단하지만, 모델은 여전히 자신의 이니셔티브에 따라 명시적 쓰기 도구를 호출할 수 있습니다. SOUL.md에 명시적인 정책을 추가하십시오:

## Long-term memory policy

Mnemosyne is the long-term memory provider.

Do not write anything to Mnemosyne unless the user explicitly asks you to
remember, save, retain, or store that information.

If information appears useful for future sessions but the user did not
explicitly request that it be remembered, ask for permission before calling
mnemosyne_remember or another Mnemosyne write tool.

Do not create durable memories from your own reasoning, assumptions,
summaries, interpretations, conclusions, or inferred preferences.

Do not create durable memories from tool output unless the user explicitly
asks for that result to be remembered.

When storing an approved memory, preserve what the user actually stated.
Do not embellish it with inferred context or conclusions.

Reading and recalling Mnemosyne memories is allowed without asking for
permission.

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

hermes gateway restart

/new

이것은 모델에 의해 강제되는 정책이지, 하드 퍼미션 경계는 아닙니다 — 이는 위의 제공자 수준 구성을 대체하는 것이 아니라 보완합니다.

memory.write_approval은 어떨까요?

Hermes는 내장 MEMORY.md / USER.md 쓰기를 위해 memory.write_approval: true를 지원하고, Mnemosyne은 최신 릴리스에서 명시적 쓰기를 위한 자체 제공자-specific 스테이징(staging)을 구현했습니다. 이는 유망하지만, 진지하게 고려할 가치가 있는 아키텍처적 함정이 있습니다: Hermes는 아직 모든 외부 기억 제공자에 대해 하나의 통일된, 제공자-중립적 승인 컨트랙트를 노출하지 않으며, Mnemosyne의 pending/apply 구현은 공유된 표준의 일부가 아니라 제공자-specific입니다. 구성 키가 존재한다고 해서 승인이 올바르게 작동한다고 가정하지 마십시오 — 정확한 Hermes 및 Mnemosyne 버전에 대해 테스트하십시오. 제공자-독립적 승인이 성숙할 때까지, sync_roles: [], MNEMOSYNE_LOG_TOOLS=0, 그리고 위의 명시적 쓰기 SOUL.md 정책을 조합하면 신뢰할 수 있는 베이스라인을 제공하며, 승인 경로를 의지할 의도가 있다면 별도로 테스트하십시오.

self-echo 억제 활성화

현재 Mnemosyne은 선택적 self-echo 억제를 제공합니다:

MNEMOSYNE_SELF_ECHO_ENABLED=1

이것을 ~/.hermes/.env에 넣고, 재시작하십시오:

hermes gateway restart

self-echo 억제는 특별히 컨텍스트 압축 경계를 대상으로 합니다 — 그 목적은 제공자가 방금 만든 기억이 독립적인 컨텍트인 것처럼 에이전트에 즉시 다시 공급되는 경우를 줄이는 것입니다. 이는 의도적으로 best-effort이며 쓰기 필터링을 대체하지 않습니다: 쓰기 컨트롤은 의심스러운 기억이 처음부터 들어오는 것을 막고, self-echo 컨트롤은 최근의 제공자 출력이 바로 다시 튕겨 나오는 것을 막습니다. 둘 다 중요하며, 어느 하나도 다른 하나를 대체하지 않습니다.

보수적인 Mnemosyne 구성

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

memory:
  provider: mnemosyne

  mnemosyne:
    sync_roles: []

~/.hermes/.env에:

MNEMOSYNE_LOG_TOOLS=0
MNEMOSYNE_SELF_ECHO_ENABLED=1

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

Only store long-term memory when the user explicitly requests it.
Do not promote model-generated conclusions or tool output into durable memory
without explicit permission.

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

먼저 베이스라인 카운트를 확인하십시오:

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 로컬 저장 온, 자동 검색 온, 대화 자동 저장 오프, 어시스턴트 메시지 자동 저장 오프, 도구 결과 로깅 오프, 명시적 remember 및 forget 온, self-echo 억제 온, 세션 검색 온, 그리고 승인 경로가 테스트된 후에는 민감한 쓰기에 대한 인간 검토가 바람직합니다. 이 구성은 Mnemosyne을 트랜스크립트 아카이브가 아닌, 큐레이션된(long-term) 기억 저장소로 기능하게 합니다 — 목표는 Hermes가 이전에 말한 모든 것을 기억하도록 하는 것이 아니라, 다음 세션이 시작될 때 여전히 사실이 될 것들을 기억하도록 하는 것입니다. 다른 제공자 또는 보존 정책으로 여러 프로필을 실행한다면, Hermes Agent 프로덕션 설정이 일관성을 유지하기 위한 프로필 수준 배선을 다룹니다. 기억을 지식 그래프 및 reflect 연산과 함께 별도의 Docker 서비스로 실행하기를 선호한다면, Hermes Agent용 Hindsight가 외부 Docker 기반 제공자 가이드입니다.