만약 여러분이 Claude Code, Codex, 또는 Cursor와 같은 코딩 에이전트(coding agents)를 단일 세션 이상으로 사용해 보았다면, 아마 다음과 같은 좌절감을 느껴보았을 것입니다. 새로운 터미널을 열고 새로운 작업을 시작하면 어제의 작업 내용이 모두 사라져 버리는 상황 말입니다. 에이전트는 여러분이 씨름했던 의존성(dependencies), 결정했던 커밋 메시지(commit messages), 또는 한 시간 동안 추적했던 버그를 전혀 기억하지 못합니다. 이는 마치 소프트웨어 개발을 위한 '성촉 데이(Groundhog Day, 매일 똑같은 하루가 반복되는 상황)'와 같습니다.

저 또한 이 문제에 크게 부딪혔습니다. 저는 Claude Code를 사용하여 마이크로서비스 모노레포(microservice monorepo)를 관리하고 있었는데, 새로운 세션이 시작될 때마다 동일한 상위 수준의 컨텍스트(high-level context)를 붙여넣고, 결정 사항들을 다시 타이핑하며, 에이전트가 이미 수정했던 실수를 반복하지 않기를 바라야만 했습니다. 에이전트의 내부 메모리를 패치(patching)하는 것은 실용적이지 않았으며(종종 깊고 취약한 훅(hooks)을 요구했습니다), 전체 로그를 복사하여 붙여넣거나 MCP 도구(tools)를 사용하는 것은 임시방편(duct tape)처럼 느껴졌습니다. 저에게는 에이전트 내부가 아니라, 에이전트 '옆에서' 작동하는 무언가가 필요했습니다.

그것이 바로 제가 Memory Sidecar를 구축한 이유입니다. 이는 여러분의 AI 에이전트 옆에 위치하여 과거 세션으로부터 학습하고, 가장 중요한 순간에 그 지식을 다시 전달하는 외부의, 에이전트 불가지론적(agent-agnostic) 메모리 시스템입니다. 현재 오픈 소스 프로젝트(v3.5.1)로 공개되었으며, 여러분의 워크플로우에 적합한지 판단할 수 있도록 작동 방식을 공유하고자 합니다.

핵심 아이디어: 에이전트 해킹 없는 메모리

사이드카(sidecar)는 메모리를 에이전트의 정신 구조에 해킹해 넣어야 할 기능이 아니라, 외부 서비스로 취급합니다. 사이드카는 에이전트의 데이터 디렉토리(AGENT_HOME 변수에 의해 구동됨)를 읽고, 완료된 세션을 아카이브하며, 계층화된 지식 저장소(knowledge store)를 구축합니다. 새로운 세션이 시작되면, 사이드카는 파일, 도구 정의(tool definition), 또는 환경 변수(environment variables)로서 관련 회상(recall) 정보를 에이전트의 컨텍스트에 주입합니다.

몽키 패칭(monkey-patching)은 없습니다. 에이전트 바이너리(binary)를 수정하지도 않습니다. 그저 관찰하고 제공하는 사이드카 프로세스만 있을 뿐입니다.

계층적 회상 아키텍처 (Layered Recall Architecture)

메모리를 유용하면서도 성능을 유지할 수 있도록, 사이드카는 지식을 네 가지 계층으로 구성합니다:

• Hot (핫) – 최근 몇 개의 가공되지 않은 세션(raw sessions)으로, 단기적 문맥(near-term context)을 위해 즉시 사용 가능합니다.
• Warm (웜) – 최근 세션에서 추출된 요약된 패턴(공통 명령줄 플래그, 프로젝트 컨벤션 등)입니다.
• Cold (콜드) – 아카이브된 세션에서 추출된 압축된 장기 지식(과거 결정 로그, 에러 이력)입니다.
• Curated (큐레이티드) – 사용자가 명시적으로 고정(pin)한 사용자 정의 노트(API 설계 규칙, 인프라 URL, 선호하는 도구 등)입니다.

새로운 세션이 시작될 때, 사이드카는 각 계층에서 가장 관련성이 높은 항목을 선택하고, 최신성(recency)과 현재 작업과의 유사성(similarity)에 따라 가중치를 부여한 뒤, 에이전트가 마치 네이티브 문맥(native context)의 일부인 것처럼 소비할 수 있는 "지식 주입 (knowledge injection)" 형태로 컴파일합니다.

실행 방법 (매우 빠릅니다)

설치 흐름은 에이전트 종류에 구애받지 않습니다(agent-agnostic). 에이전트의 홈 디렉토리를 지정하기만 하면 자동으로 설정됩니다:

git clone https://github.com/mage0535/hermes-memory-installer.git
cd hermes-memory-installer
python install.py --agent $(dirname $(which claude))   # Claude Code용
...

AGENT_HOME 기반 설계 덕분에 Claude Code, Codex, Cursor, Hermes, 그리고 파일 시스템에 세션을 저장하는 모든 에이전트와 함께 작동합니다. 사이드카는 파이프(pipe)의 반대편에 무엇이 있는지 상관하지 않으며, 오직 디렉토리 구조에만 집중합니다.

실제 적용 효과

제 일상적인 워크플로우에 사이드카를 추가한 이후 가장 큰 변화는 바로 _연속성(continuity)_입니다. 새로운 작업을 시작해도 에이전트는 제가 3일 전에 설정한 로드 밸런서 토큰, 로컬 테스트를 위해 생성한 docker-compose.override.yml, 그리고 왜 특정 엔드포인트에 비동기 워커(async workers)를 사용하기로 결정했는지까지 기억합니다. 과거 정보를 반복하느라 컨텍스트 윈도우(context window)를 낭비하지 않고, 새로운 정보에 집중하여 사용합니다.

물론 트레이드오프(trade-off)는 존재합니다. 작업 방향을 크게 변경했을 경우, 메모리 주입(memory injection) 과정에서 간혹 오래된 컨텍스트(stale context)가 포함될 수 있습니다. 하지만 웜(warm) 및 큐레이션(curated) 티어(tier)를 통해 수동 고정(manual pinning)으로 이를 덮어쓸 수 있으며, 콜드(cold) 티어는 세 번의 갱신 주기(renewal cycles)가 지난 매우 오래된 세션을 자동으로 우선순위에서 제외합니다. 일상적인 업무 측면에서 볼 때, 80%의 "양호한 회상(good recall)"은 회상 능력이 전혀 없는 상태보다 훨씬 큰 이점입니다.

언제 사용하지 말아야 할까요?

• 에이전트가 이미 강력한 네이티브 메모리 인터페이스를 갖추고 있는 경우 (예: 개인화된 메모리 기능이 있는 ChatGPT Pro와 같은 관리형 서비스를 완전히 사용 중인 경우), 이 사이드카(sidecar)는 기능이 중복될 수 있습니다.
• 프로젝트가 단일 세션용 일회성 작업(일회성 스크립트, 빠른 프로토타입)인 경우, 메모리를 설정하는 오버헤드(overhead)가 그만한 가치가 없습니다.
• 에이전트 세션 내용의 개인정보 보호를 매우 중요하게 생각하는 경우, 사이드카가 에이전트의 데이터를 읽고 저장한다는 점을 인지해야 합니다. 다만, 로컬 파일 시스템 외부에는 아무것도 저장하지 않으며, 코드는 감사를 위해 공개되어 있습니다.

v3.5.1: 운영 안정화 (Operational Hardening)

최신 릴리스의 핵심은 사이드카를 일상적인 사용에 있어 지루할 정도로 신뢰할 수 있게 만드는 것입니다. 더 깔끔해진 AGENT_HOME 감지, 하드코딩된 경로 제거, 그리고 더 단순해진 설치 환경을 제공합니다. 화려한 신기능은 없습니다. 그저 Claude Code 및 Codex를 통한 집중적인 반복 테스트를 통해 얻은 안정성뿐입니다.

직접 시도해 보세요

코딩 에이전트의 건망증 때문에 짜증이 났었다면, 사이드카를 한 번 돌려보세요. MIT 라이선스로 제공되며, 일반적인 Python 3.9+ 환경에서 실행되고, 시도하는 데 5분도 걸리지 않습니다. 미래의 당신(그리고 당신의 에이전트)이 고마워할 것입니다.

GitHub: github.com/mage0535/hermes-memory-installer

문제가 발생하면 스타(star)를 눌러주거나 이슈(issue)를 제기해 주세요. 실제 피드백을 바탕으로 활발히 개발하고 있습니다.