AI 에이전트 외장 기억 시스템: Memory Sidecar v3.2 아키텍처 분석

AI 에이전트(Agent)의 매번 새로운 세션은 백지상태와 같습니다. 이는 결함이 아니라 아키텍처의 제약 사항입니다. 하지만 프로덕션 환경에서 이러한 제약은 용납될 수 없습니다. 고객의 배경, 프로젝트 컨텍스트(Context), 과거의 결정 사항들을 매번 다시 입력해야 하기 때문입니다.

Memory Sidecar의 해결책은 매우 직접적입니다. 에이전트의 핵심 코드를 건드리지 않고, 옆에서 독립적인 기억 프로세스를 실행하여 에이전트가 '기억해낼 수 있도록' 만드는 것입니다. 최근 v3.2가 출시되었으며, 저는 그 설계를 분석해 보았습니다. 기록할 가치가 있는 내용입니다.

4계층이 아닌 3계층 기억

v3.0은 중간에 agentmemory Docker 브릿지 계층이 끼어 있는 4계층 아키텍처였습니다. v3.1에서 이 계층을 제거했습니다. 해당 Docker 계층은 13개의 만료된 데이터만 저장하고 있어 지연 시간(Latency)만 늘릴 뿐 다른 역할이 없었기 때문입니다. 현재는 3계층 구조입니다:

• Hot Layer (핫 레이어) — memory tool을 통해 직접 주입되며, 5KB 상한을 가집니다. 현재 사용자의 프로필과 설정을 저장하며, 지연 시간은 0ms입니다.
• Warm Layer (웜 레이어) — Hindsight (PostgreSQL 16)를 사용하며, 추출된 사실과 반복되는 패턴을 저장합니다. 지연 시간은 약 ~50ms입니다.
• Cold Layer (콜드 레이어) — gbrain 지식 그래프(Knowledge Graph) + FTS5 전체 텍스트 검색(Full-Text Search)을 사용하며, 영구 아카이브 용도로 사용됩니다. 지연 시간은 약 ~500ms–2s입니다.

검색(Recall) 시 세 계층이 병렬로 검색되며, RRF(Reciprocal Rank Fusion) 융합 랭킹을 사용합니다. 어떤 계층에서 적중(Hit)하느냐에 따라 해당 계층을 사용하며, 반드시 콜드 레이어를 거쳐야 하는 것은 아닙니다.

Focused Dossier: 중점 파일

v3.1에서 도입된 실용적인 기능입니다. 별칭 목록, 주제 태그, 보존 우선순위 및 타임라인 추적을 포함하는 '중점 파일(Focused Dossier)'을 선언합니다. 키워드가 적중하면 파일 검색을 우선적으로 수행하며, 데이터가 삭제되지 않습니다.

첫 번째 실제 적용 사례는 관계 기억 파일(Relationship Memory Dossier)입니다. 수백 개의 세션과 수천 개의 추출된 사실이 있는 규모에서도 이 패턴이 안정적임을 검증했습니다. 새로운 파일을 추가하려면 memory_family_registry.py에 프로필을 하나 추가하기만 하면 됩니다.

v3.2에서 무엇이 업데이트되었나

두 개의 신규 스크립트와 두 개의 개선 사항이 추가되었습니다:

• memory_watermark.py — 기억 용량을 자동으로 감지하고 만료된 항목을 아카이브하여 데이터 팽창을 방지합니다.
• memory_snapshot_backup.py — 주기적인 스냅샷 백업을 수행하여 문제 발생 시 롤백할 수 있습니다.
• hindsight-service.py — 독립 데몬(Daemon) 프로세스를 간소화하여 기존 PG(5432)를 사용하며, 더 이상 별도의 포트를 열지 않습니다.
• hindsight_mcp_bridge.py — 행 끝 형식을 정리하고 MCP stdio 브릿지를 개선했습니다.
• session_to_gbrain.py — 환경 변수를 기반으로 토큰(Token)을 설정하여 더 이상 키(Key)를 하드코딩하지 않습니다.

Embedding 서비스: 50줄의 코드

시맨틱 검색(Semantic Search)은 콜드 레이어 검색의 핵심입니다. 프로젝트는 임베딩(Embedding) 서비스에 종속되지 않으며, 직접 배포할 수 있는 최소한의 구현체를 제공합니다:

from sentence_transformers import SentenceTransformer
from http.server import HTTPServer, BaseHTTPRequestHandler
import json
...

96MB 크기의 BGE-small-zh부터 2GB 크기의 BGE-m3까지 6가지 모델을 지원하므로 리소스에 따라 선택할 수 있습니다. 설치하지 않아도 사용할 수 있습니다. FTS5 전체 텍스트 검색만으로도 대부분의 시나리오를 처리하기에 충분합니다.

프로덕션 데이터

단순한 장난감이 아닙니다. 2026년 4월부터 현재까지 연속적으로 프로덕션 운영 중입니다:

• 10,885개의 gbrain 페이지 — 완전한 지식 그래프
• 42,481개의 Hindsight 노드 — 추출된 사실
• 105,601개의 인덱스 메시지 — FTS5 전체 텍스트 커버리지
• 100% 임베딩 커버리지
• 뇌 분할(Brain Split) 73

모든 에이전트에 적응 가능

$AGENT_HOME/state.db와 세션 파일만 읽기 전용으로 사용하므로, 에이전트 프로세스 외부에서 완전히 실행됩니다. AGENT_HOME=~/.claude로 설정하면 Claude Code에 적응하고, ~/.cursor로 설정하면 Cursor에 적응합니다. 설치 프로그램은 9개의 핵심 스크립트를 원클릭으로 배포하며, cron 스케줄러를 통해 일상적인 유지보수 주기를 관리합니다.

핵심 아이디어는 단 하나입니다: 기억은 기능이 아니라 인프라입니다. 기억을 에이전트 코드에서 분리하여 독립적으로 진화하고 독립적으로 유지 관리해야 프로덕션 환경에서 안정적으로 구동될 수 있습니다.

프로젝트 주소: github.com/mage0535/hermes-memory-installer