AI 에이전트 세션을 재시작했을 때, 이전에 나누었던 모든 대화를 에이전트가 잊어버린 것을 깨달은 적이 있나요? 복잡한 프로젝트를 진행할 때 이러한 백지 상태는 생산성을 저해하는 요소입니다. 저는 긴 시스템 프롬프트(System Prompts), RAG 파이프라인, 파인튜닝(Fine-tuning) 등 다양한 접근 방식을 시도해 보았지만, 이들은 토큰 제한(Token Limits)에 걸리거나, 무거운 인프라를 요구하거나, 에이전트의 내부 코드를 수정해야만 하는 문제점이 있었습니다.

그렇기에 저는 Memory Sidecar v3.1.1을 구축하여 오픈 소스로 공개했습니다. 이것은 Hermes, Claude Code, Cursor, Codex 등 당신이 사용하는 에이전트와 나란히 실행되는 별도의 프로세스로, 에이전트 코드를 단 한 줄도 수정하지 않고도 실제적인 메모리를 부여합니다.

작동 원리

에이전트를 패치하는 대신, Memory Sidecar는 사이드카 패턴(Sidecar Pattern)을 사용합니다. 에이전트는 세션 데이터를 공유 데이터 디렉토리에 기록하고, 사이드카는 이를 소비 및 처리하여 이후 실행 시 관련 컨텍스트(Context)를 에이전트의 시스템 프롬프트에 다시 주입합니다. 이는 에이전트 아키텍처를 재설계하지 않고도 연속성을 유지해야 하는 프로덕션(Production) 환경을 위해 설계되었습니다.

검색 시스템은 계층화되어 있습니다:

• Hot Layer: 5KB 제한을 가진 단순한 메모리 도구로, 최근 컨텍스트를 즉각적으로 회상할 수 있게 합니다.
• Warm Layer: 재시작 후에도 유지되는 중기 메모리를 위한 Hindsight PostgreSQL입니다.
• Cold Layer: 장기적인 지식과 주제 추적을 위해 FTS5 전문 검색(Full-Text Search)과 결합된 지식 그래프(Knowledge Graph, gbrain)입니다.

이러한 계층적 접근 방식은 에이전트가 항상 적절한 양의 컨텍스트를 얻을 수 있음을 의미합니다. 최근 대화는 빠르고, 중요한 주제는 무기한으로 기억되며, 터미널을 닫더라도 아무것도 잃어버리지 않습니다.

v3.1.1의 새로운 기능

최신 릴리스에는 지속적인 운영을 위해 더욱 견고하게 만들어주는 두 가지 기능이 추가되었습니다:

1. Memory Watermark Detection (memory_watermark.py) – 메모리 사용량을 자동으로 모니터링하고 제한에 도달하기 전에 오래된 세션을 아카이브합니다.
2. Periodic Snapshot Backups (memory_snapshot_backup.py) – 에이전트의 메모리 상태를 절대 잃어버리지 않도록 정기적인 스냅샷을 생성합니다.

또한, 온보딩 가이드(HERMES_ONBOARDING.md)에는 이제 사용자 정의 에이전트를 통합하기 위한 전체 도구 목록이 포함되어 있으며, 모든 토큰은 환경 변수(environment variables)로 이동되었습니다. 더 이상 하드코딩된 비밀 정보(hardcoded secrets)는 없습니다.

시작하기

저장소(repo)를 클론(Clone)하고, 설치 프로그램을 실행한 뒤, 에이전트의 세션 디렉터리를 지정하기만 하면 됩니다. 그게 전부입니다. 나머지는 사이드카(sidecar)가 처리합니다. 이 프로젝트는 Python 3.9+로 작성되었으며 MIT 라이선스 하에 제공되므로, 어떤 프로젝트에도 마찰 없이 바로 적용할 수 있습니다.

git clone https://github.com/mage0535/hermes-memory-installer.git
cd hermes-memory-installer
pip install -r requirements.txt
...

저는 수개월 동안 여러 에이전트와 함께 이 설정을 사용해 왔으며, 장기 실행되는 코드 리뷰부터 며칠간 지속되는 연구 세션에 이르기까지 모든 것을 처리해 왔습니다. 더 깊이 파고들고 싶다면 저장소에 있는 아키텍처 문서(architecture doc)에서 전체 설계를 확인할 수 있습니다.

왜 단순히 벡터 DB(Vector DB)를 사용하지 않나요?

벡터 데이터베이스(Vector databases)는 유사도 검색(similarity search)에는 훌륭하지만, 구조—즉 엔티티(entities) 간의 관계, 이벤트 순서, 또는 어떤 사실이 오래되었는지 등을 포착하지 못합니다. Memory Sidecar의 지식 그래프(knowledge graph)는 이러한 연결 관계를 보존하며, 계층적 검색(layered retrieval) 방식을 통해 사소한 조회마다 벡터 인덱스(vector index)를 계속 두드리지 않아도 됩니다.

또한 에이전트 측면에서는 의도적으로 상태를 유지하지 않는(stateless) 방식으로 설계되었습니다. 컨텍스트(context)를 잃지 않고도 에이전트를 교체하거나, 실험을 수행하거나, 재시작할 수 있습니다. 이러한 유연성 덕분에 "그 대화가 어디로 갔지?"와 같은 디버깅에 소요되는 시간을 몇 시간씩 아낄 수 있었습니다.

GitHub에서 확인해 보세요: Memory Sidecar v3.1.1