AI 에이전트가 모든 것을 잊어버리는 것을 방지하세요: 제대로 작동하는 사이드카 메모리 시스템 (Sidecar Memory System)

Claude Code, Cursor, 또는 커스텀 Hermes 에이전트와 같은 AI 에이전트를 사용해 보셨다면, 아마도 똑같은 좌절감을 경험했을 것입니다. 모든 새로운 세션이 백지 상태에서 시작된다는 점 말이죠. 에이전트는 당신이 어제 무엇을 논의했는지, 지난주에 어떤 아키텍처 결정을 내렸는지, 혹은 결제 모듈에서 반복적으로 발생하는 버그가 무엇인지 전혀 알지 못합니다. 마치 금붕어 기억력을 가진 사람과 대화하는 것과 같습니다.

물론 컨텍스트 (Context)를 수동으로 붙여넣거나, 모든 내용을 시스템 프롬프트 (System Prompts)에 집어넣을 수도 있지만, 이는 금방 한계에 부딪힙니다. 토큰 제한 (Token limits), 오래된 정보, 그리고 중요한 내용을 선별하는 데 드는 엄청난 노력은 실제 사용 환경에서 비실용적입니다.

저는 다른 것을 원했습니다. 에이전트와 나란히 실행되면서, 세션을 자동으로 아카이브 (Archive)하고, 필요할 때 관련 컨텍스트를 다시 제공하는 메모리 시스템 말입니다. 에이전트의 내부 구조를 패치할 필요도 없고, 커스텀 플러그인 (Custom plugins)도 필요 없습니다. 그저 사이드카 프로세스 (Sidecar process)와 공유 데이터 디렉토리 (Shared data directory)만 있으면 됩니다.

그렇게 해서 Memory Sidecar가 탄생했습니다.

실제로 하는 일

Memory Sidecar는 에이전트의 세션 출력을 감시하고, 이를 통해 구조화된 장기 지식을 구축하는 별도의 프로세스입니다. 에이전트를 전혀 수정하지 않습니다. 에이전트가 대화 내용을 기록하는 디렉토리를 지정하기만 하면 나머지는 알아서 처리합니다.

세 가지 핵심 기능:

1. 세션을 영구적인 지식으로 아카이브 – 대화 내용이 인덱싱 (Indexed)되어 저장되므로, 에이전트를 재시작해도 내용을 잃어버리지 않습니다.
2. 관련된 내용 회상 – 계층적 검색 전략 (Layered retrieval strategy)을 사용합니다: 먼저 최근 컨텍스트를 확인하고, 그다음 임베딩 (Embeddings)을 통한 시맨틱 검색 (Semantic search)을 수행하며, 더 깊은 연결을 위해 지식 그래프 (Knowledge graph) 조회를 실시합니다.
3. 중요 주제 추적 – 인물, 프로젝트, 반복되는 문제들은 자동으로 업데이트되는 고유의 "도시에 (Dossier)"를 갖게 됩니다.

하나의 거대한 단일 메모리 저장소 대신, 세 가지 계층이 존재합니다:

• Hot layer (핫 레이어) – 즉각적인 세션 컨텍스트를 위한 라이브 메모리 도구 (5KB 제한).
• Warm layer (웜 레이어) – 중기 회상을 위한 PostgreSQL 백엔드 저장소 (Hindsight라고 불림).
• Cold layer (콜드 레이어) – 장기 지식을 위한 FTS5 검색 기능이 포함된 그래프 데이터베이스 (gbrain).

에이전트가 컨텍스트 (context)가 필요할 때, 사이드카 (sidecar)는 계층화된 결과물을 시스템 프롬프트 (system prompt)에 주입합니다. 모든 데이터를 쏟아붓는 것이 아니라, 중요한 정보만을 전달받게 됩니다.

빠른 설정 (Quick Setup)

설치 방법은 간단합니다:

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

그 다음, 사이드카가 에이전트의 데이터 디렉토리를 감시하도록 설정하세요. 메모리 서비스는 데몬 (daemon)으로 실행되므로, 한 번 시작하면 신경 쓸 필요가 없습니다.

v3.1.1 릴리스에는 두 가지 새로운 유틸리티가 포함되어 있습니다:

• memory_watermark.py – 메모리 사용량이 임계값에 도달했을 때 자동 감지 및 아카이빙 (archiving).
• memory_snapshot_backup.py – 복구를 위한 주기적인 스냅샷 (snapshot).

만약 커스텀 에이전트 (Hermes가 아닌 경우)를 사용 중이라면, HERMES_ONBOARDING.md를 확인하세요. 모든 에이전트를 통합하기 위한 가이드가 담겨 있습니다.

사용 시점 (및 사용하지 말아야 할 때)

적합한 경우:

• 컨텍스트가 이어지는 장기적인 개발 세션.
• 각 프로젝트가 자체 지식 베이스 (knowledge base)를 갖는 멀티 프로젝트 설정.
• 에이전트 간에 공유 메모리를 원하는 팀.

적합하지 않은 경우:

• 세션 기록이 중요하지 않은 단순 일회성 작업.
• 대화 내용을 외부로 저장할 수 없는 규제가 엄격한 환경 (단, 모든 것을 셀프 호스팅 (self-host)할 수는 있습니다).
• 에이전트 간의 실시간 메모리 동기화가 필요한 경우 – 사이드카는 1초 미만의 실시간 방식이 아니라 정해진 일정에 따라 폴링 (polling)합니다.

실제 적용 시의 이점

이 시스템을 몇 주 동안 실행해 본 결과, 에이전트의 응답이 더욱 근거에 기반하여(grounded) 이루어지는 것을 확인했습니다. 제가 요청하지 않아도 과거의 결정 사항을 참조하곤 했습니다. 2주 전에 시작한 프로젝트의 기술 스택 (tech stack)을 기억하고 있었습니다. 심지어 이전에 수정되었던 버그와 유사한 회귀 (regression) 현상도 잡아냈습니다.

완벽했냐고요? 아니요. 지식 베이스가 매우 클 경우 콜드 레이어 (cold layer)가 느려질 수 있고, 설정 과정에서 여전히 약간의 조정이 필요합니다. 하지만 핵심적인 가치는 분명합니다. 바로 **에이전트를 새로 작성할 필요가 없는 지속 가능한 메모리 (persistent memory)**입니다.

컨텍스트를 복사하여 붙여넣는 작업에 지쳤다면, 한 번 시도해 보세요. 이 프로젝트는 오픈 소스(open source)이며, MIT 라이선스를 따르고, 아키텍처(architecture)가 잘 문서화되어 있습니다.

자세한 내용은 GitHub 저장소를 확인하세요: Memory Sidecar v3.1.1