agent-memory: 코딩 에이전트가 세션을 넘어 기억하게 만들기

에이전트는 세션을 닫으면 그 안에서 배운 것을 잊어요. 어떤 파일을 고쳤고 왜 그렇게 했는지, 어떤 시도가 실패했는지가 다음 세션에는 없어요. agent-memory는 이 손실을 메우는 실행 도구예요.

기억을 다루는 방식은 두 갈래로 갈려 있어요. 하나는 임베딩과 지식 그래프로 찾아 주는 검색 엔진이고, 다른 하나는 에이전트가 직접 읽는 파일 시스템이에요. 앞은 잘 찾지만 내용을 검사하기 어렵고, 뒤는 읽기 쉽지만 찾기가 느려져요.

이 도구는 둘을 한 저장소에 넣어요. 파일은 그대로 두고 그 위에 색인을 얹어서, 검색은 색인이 하고 읽기는 파일이 해요.

기억은 대화 전문을 붙여 넣은 덩어리가 아니에요. 무엇을 했고 왜 그렇게 했는지를 한 파일에 적고, 관련된 파일끼리 링크로 이어 둬요.

기억은 마크다운 파일 하나하나가 단위예요. 파일 안의 링크가 관계를 만들고, 같은 폴더에 있는 파일끼리는 이웃이 돼요. 그래프 데이터베이스를 따로 두지 않아도 관계가 유지돼요.

색인은 언제든 지워도 돼요. 색인 폴더를 지우고 다시 만들면 잃는 지식이 없고, 이건 문서의 약속이 아니라 테스트로 확인해요.

rm -rf .index/ && mem rebuild

아직 PyPI에 없어서 저장소를 받아 설치해요. 파이썬 3.12 이상이 필요하고, 설치하면 mem과 MCP¹ 서버, 훅 실행 파일이 함께 만들어져요.

uv sync --all-packages

저장소를 만든 뒤에는 쓰고 있는 에이전트에 맞춰 설정을 붙여요. 호스트마다 설정 파일 위치가 달라서 명령에 호스트 이름을 넣어 실행해요.

검색을 하면 본문이 아니라 한 줄 요약과 파일 경로, 점수가 돌아와요. 에이전트는 그 목록을 보고 필요한 파일만, 필요한 깊이로 열어요.

본문을 붙여 넣으면 컨텍스트가 금방 차고, 무엇을 읽었는지 확인하기도 어려워요. 경로로 답하면 에이전트가 연 파일과 열지 않은 파일이 대화 기록에 남아요.

에이전트가 기억을 남기기로 판단하기를 기다리지 않아요. 대화가 끊기는 지점에서 정리가 시작되고, 그 작업이 진행 중인 일을 붙잡지 않아요.

남길 만한 것은 대개 작업이 끝나는 순간에 드러나요. 어떤 선택을 했고 무엇이 실패했는지가 그때 정리돼요.

정리 전에 원본 대화 기록을 먼저 복사해요. 그래서 정리 단계에서 놓친 내용이 시스템에서 사라지는 일은 없어요.

라이브러리 안에 모델 클라이언트가 없어요. 판단은 호스트 에이전트의 CLI²가 하고, 그 판단은 대화 기록에 남아서 나중에 확인할 수 있어요.

대화가 없을 때 통합 작업이 돌아요. 새로 들어온 기억을 합치고, 가치가 낮은 것을 잊어요. 이 작업은 자기 주기로 돌아서 요청을 기다리지 않아요.

사람이 없는 사이에 할 수 있는 일과 없는 일이 나뉘어 있어요. 추가와 갱신은 스스로 하지만, 삭제는 제안으로만 남기고 확인을 받아요.

잊는 것도 기능이에요. 같은 내용이 여러 파일에 흩어지면 검색 결과가 중복으로 차고, 오래된 판단이 최신 판단을 가려요.

갱신해도 이전 기록이 사라지지 않아요. 특정 날짜를 지정하면 그 시점의 기억으로 답할 수 있어서, 무엇이 언제 바뀌었는지 추적할 수 있어요.

개발팀이 LongMemEval-S를 120개 에피소드로 줄여 측정했어요. 회수 범위를 12개 세션으로 제한했고, 호스트는 Claude Haiku 4.5, 채점은 Sonnet 5가 맡았어요.

이 숫자는 글쓰기 품질이나 추론 능력을 잰 것이 아니에요. 이전 세션의 사실을 얼마나 정확히 다시 꺼내는지만 봤어요.

Claude Code가 남긴 기억을 Codex CLI가 찾고, Hermes가 다시 이어 쓰는 조합을 확인했어요. 세 호스트를 쓰는 9가지 순서 조합이 모두 통과했고, 특정 내용이 그대로 남아 있었어요.

호스트를 바꿔도 기억이 이어지는 것은 저장소가 파일이기 때문이에요. 특정 앱의 데이터베이스 안에 갇혀 있으면 다른 앱에서 꺼낼 수 없어요.

기억 없이 시작한 경우와 비교하면 36번 중 2번에서 13번으로 늘었어요. 호스트를 바꿔도 기억이 이어진다는 뜻이에요.

버전은 0.1.0이고 아직 PyPI에 없어요. 명령 이름과 설정 항목이 바뀔 수 있어서, 설치한 시점의 문서를 기준으로 따라가는 편이 안전해요.

측정값은 회수 범위를 12개 세션으로 제한한 실험이에요. 그래서 이 숫자는 기억을 쓰는 방식에 대한 비교이고, 큰 말뭉치에서의 성능 비교가 아니에요.

에이전트를 바꾸면 훅과 설정을 다시 설치해야 해요. 기억 자체는 마크다운이라 그대로 남지만, 어느 호스트가 언제 쓰는지는 설정에 따라 달라져요.