모든 AI 에이전트를 위한 지속성 메모리: 즉시 작동하는 사이드카 (v3.1.0)

만약 당신이 Claude Code, Cursor, 또는 커스텀 AI 에이전트를 사용하여 사소하지 않은 무언가를 구축해 본 적이 있다면, 그 고통을 느껴보았을 것입니다. 모든 새로운 세션이 백지 상태에서 시작된다는 점 말입니다. 에이전트는 우리가 두 번 전의 대화에서 논의했던 내용, 그동안 구축해 온 프로젝트 컨텍스트(Context), 또는 어제 반복하며 수정했던 버그 수정 사항을 기억하지 못합니다.

물론, 일부 도구들은 내장된 메모리 기능을 갖추고 있습니다. 대개 대화 로그(Conversation log)나 사용자가 명시적으로 관리해야 하는 벡터 스토어(Vector store) 형태입니다. 하지만 이러한 기능들은 특정 에이전트에 종속되어 있거나, 에이전트의 내부 코드를 패치해야 하거나, 혹은 당신이 직접 지속성 계층(Persistence layer)을 재발명하기를 요구합니다. 이는 프로덕션 워크플로우(Production workflows) 관점에서 실용적이지 않습니다.

저는 에이전트의 코드를 건드리지 않고도 — 다음 달에 제가 바꿀지도 모르는 에이전트를 포함하여 — 어떠한 에이전트와도 작동하는 무언가를 원했습니다. 그래서 Memory Sidecar를 만들었습니다.

작동 방식

Memory Sidecar는 에이전트 옆에 위치하는 별도의 프로세스입니다. 이 프로세스는 에이전트의 세션 출력(파일, 데이터베이스)을 모니터링하고 지속적인 지식 베이스(Knowledge base)를 구축합니다. 에이전트가 새로운 세션을 시작하면, 사이드카는 관련 컨텍스트를 에이전트의 시스템 프롬프트(System prompt)에 다시 주입합니다. 에이전트는 자신이 메모리를 가지고 있다는 사실을 전혀 알지 못하며, 그저 더 똑똑해진 프롬프트를 받게 될 뿐입니다.

아키텍처는 직관적이며 의도적으로 설계되었습니다:

Hot Layer: 가장 최근의 약 5KB 대화 내용을 롤링 컨텍스트(Rolling context)로 유지합니다. 빠르고 저렴하며, 즉각적인 회상을 위해 항상 사용 가능합니다.
Warm Layer: 나중에 검토하거나 의미론적 검색(Semantic search)을 할 수 있도록 전체 세션을 아카이브하는 PostgreSQL 기반 스토어(Hindsight)입니다.
Cold Layer: 주제, 결정 사항, 프로젝트 패턴에 대한 장기적이고 세션 간의 검색을 위해 벡터 검색(Embeddings), 전체 텍스트 검색(FTS5), 그리고 경량 지식 그래프(gbrain)를 결합한 형태입니다.

에이전트가 컨텍스트를 필요로 할 때, 사이드카는 계층적 검색(Tiered retrieval)을 수행합니다. 먼저 Hot Layer를 확인하고, 그다음 Cold Layer에서 의미론적 검색 + 키워드 검색을 수행하며, 필요에 따라 더 깊은 탐색을 위해 Warm Layer의 아카이브를 가져옵니다. 모든 정보는 토큰 예산(Token budgets)을 준수하면서 간결한 프롬프트 주입(Prompt injection) 형태로 병합됩니다.

v3.1.0 변경 사항

Version 3.1.0에서는 설계를 정리했습니다. 오래된 기록을 보유하고 있던 레거시 Docker 브리지 레이어(legacy Docker bridge layer)를 제거하고, zero value를 위한 의존성(dependency)을 추가했습니다. 콜드 레이어(cold layer)는 이제 벡터(vector), 키워드(keyword), 그래프 조회(graph lookups)를 수행하는 단일 통합 엔진(gbrain)을 사용합니다. 그 결과 배포는 더 간단해졌으며(PostgreSQL을 사용하는 순수 Python 3.9+), 쿼리 속도는 더 빨라졌습니다.

시작하기

에이전트의 코드를 수정할 필요가 없습니다. Memory Sidecar를 에이전트의 데이터 디렉토리(세션 로그나 체크포인트가 기록되는 곳)로 지정하기만 하면 됩니다. 예시는 다음과 같습니다:

# 설치
pip install memory-sidecar

...

사이드카(sidecar)가 기존 세션을 처리하고 인덱싱(indexing)하며, 다음 재시작 시 에이전트에 컨텍스트(context)를 주입하기 시작합니다. 에이전트는 다음과 같은 시스템 프롬프트 접두사(system prompt prefix)를 받게 됩니다:

[Recalled context: previous session discussed API redesign for project X.
 Key decision: use FastAPI over Flask for async support.
 Open issue: rate limiting not yet implemented.]

이것으로 끝입니다. SDK, 에이전트 플러그인, 패치된 포크(patched forks)는 필요하지 않습니다.

효과적인 경우 (및 그렇지 않은 경우)

다음과 같은 상황에서 매우 유용합니다:

컨텍스트가 몇 주에 걸쳐 쌓이는 장기 프로젝트
에이전트를 공유하는 팀 — 모두가 축적된 지식의 혜택을 누림
구조화된 세션 로그를 생성하는 에이전트 (Hermes, Claude Code, Codex, 커스텀 스크립트)

다음과 같은 경우에는 유용성이 떨어집니다:

에이전트가 설계상 상태를 유지하지 않는(stateless) 방식이며 결정론적 출력(deterministic outputs)을 선호하는 경우
사이드카 프로세스를 실행할 수 없는 엄격한 샌드박스(sandboxed) 환경을 사용하는 경우
에이전트가 파싱 가능한(parseable) 방식으로 세션 데이터를 내보내지 않는 경우 (단, 많은 형식이 지원됩니다)

이 프로젝트를 공유하는 이유

에이전트를 위한 메모리 라이브러리는 많지만, 거의 모든 라이브러리가 특정 에이전트에 맞춘 커스텀 통합(custom integration) 구축을 요구합니다. Memory Sidecar는 정반대의 접근 방식을 취합니다. 메모리 시스템은 독립적이며, 에이전트는 이를 전혀 인지하지 못한 채로 유지됩니다. 이러한 분리 덕분에 지속성(persistence)을 다시 작성할 필요 없이 에이전트를 더 쉽게 유지 관리, 업그레이드 및 교체할 수 있습니다.

이 프로젝트는 오픈 소스 (MIT)이며 코드는 GitHub에 있습니다: memory-sidecar-installer. 만약 여러분도 동일한 컨텍스트 손실 (context-loss) 문제로 어려움을 겪고 있다면, 한 번 사용해 보세요. 에이전트에게 프로젝트 컨텍스트를 다시 설명하는 데 드는 수많은 시간을 절약해 주었습니다.

아키텍처 (architecture) 및 설정에 대한 자세한 내용은 ARCHITECTURE doc을 확인하시기 바랍니다. 기여 (contributions)와 피드백은 언제나 환영합니다.