agentmemory 소개
agentmemory는 코딩 에이전트가 세션이 끝날 때마다 잃어버리는 맥락을 로컬 서버에 남겨 두는 오픈소스 메모리 계층입니다. 어제 왜 그 라이브러리를 골랐는지, 어떤 시도가 실패했는지, 프로젝트의 규칙이 무엇인지를 에이전트는 새 대화가 시작될 때마다 다시 배워야 합니다. 이를 피하려고 전체 맥락을 매번 붙여 넣으면 컨텍스트 윈도우가 감당하지 못하고, 요약해서 넣으면 토큰 비용이 계속 쌓입니다. agentmemory는 에이전트의 훅(hook)에 붙어 작업 기록을 자동으로 수집하고, 필요한 순간에 필요한 만큼만 대화에 되돌려 넣는 방식을 택했습니다.
수집은 사람이 따로 명령하지 않아도 진행됩니다. SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, SubagentStart/Stop, Stop, SessionEnd 훅마다 무엇을 붙잡을지 정해져 있어서, 도구 호출과 그 결과, 파일 접근 패턴, 실패했을 때의 맥락이 모두 기록됩니다. 저장 전에 API 키와 비밀값, <private> 태그로 감싼 내용은 걸러집니다. 서버는 기본적으로 3111번 포트에서 돌고, 3113번 포트에는 무엇이 저장되고 있는지 볼 수 있는 실시간 뷰어가 함께 뜹니다.
메모리 서버 하나를 여러 에이전트가 공유하는 구조라서, 훅이나 MCP, REST API를 지원하는 도구라면 종류를 가리지 않고 붙습니다. Claude Code, Codex CLI, GitHub Copilot CLI, Cursor, Gemini CLI 등의 연결 방법이 각각 준비되어 있습니다. 아래에서는 저장과 회수가 어떻게 도는지, 기억을 네 단계로 나눈 이유가 무엇인지, 그리고 공개된 벤치마크 수치를 차례로 살펴봅니다.
agentmemory의 저장과 회수 흐름
agentmemory에는 방향이 반대인 두 개의 파이프라인이 있습니다. 하나는 작업을 기록으로 남기는 저장 경로이고, 다른 하나는 새 세션이 시작될 때 기억을 꺼내 대화에 넣는 회수 경로입니다.
저장 쪽은 PostToolUse 훅이 발생하면서 시작합니다. 5분 창을 기준으로 SHA-256 해시로 중복을 걸러 내고, 비밀값을 제거한 뒤 원본 관측을 저장합니다. 그 다음 LLM이 이를 압축해 구조화된 사실과 개념, 서술로 바꾸고, 임베딩을 만들어 BM25와 벡터 색인에 함께 넣습니다. 세션이 끝날 때 도는 Stop 및 SessionEnd 훅에서는 세션 요약이 만들어지고, 설정을 켜 두었다면 지식 그래프 추출과 슬롯 반영도 이어집니다.
회수 쪽은 SessionStart 훅이 담당합니다. 프로젝트 프로필에 해당하는 주요 개념과 파일, 패턴을 불러온 뒤 하이브리드 검색을 돌리고, 기본값 2,000 토큰의 예산 안에서 잘라 대화에 주입합니다. 검색은 세 갈래를 합칩니다. BM25는 어간 처리와 동의어 확장을 거친 키워드 매칭으로 항상 동작하고, 벡터 검색은 임베딩 제공자가 설정되어 있을 때, 그래프 순회는 질의에서 엔티티가 감지될 때 붙습니다. 세 결과는 역순위 융합(Reciprocal Rank Fusion, k=60)으로 합쳐지며 한 세션에서 최대 3건까지만 남기는 방식으로 다양성을 확보합니다.
한국어 사용자라면 토큰화 부분을 짚고 넘어갈 필요가 있습니다. BM25가 그리스 문자와 키릴 문자, 히브리 문자, 아랍 문자, 악센트가 붙은 라틴 문자는 기본으로 처리하지만, 한국어와 중국어, 일본어 메모리에는 별도 분절기가 필요합니다. 설치하지 않으면 덩어리 단위 토큰화로 넘어가면서 표준 오류로 한 번 안내를 출력합니다.
npm install @node-rs/jieba tiny-segmenter
agentmemory의 4단계 기억 구조
저장된 기억은 한 덩어리로 쌓이지 않고 네 단계로 나뉩니다. 개발자는 이 구조가 사람의 뇌가 수면 중에 기억을 정리하는 방식에서 착안한 것이라고 설명합니다.
| 단계 | 담는 내용 | 대응하는 개념 |
|---|---|---|
| 작업 기억(Working) | 도구 사용에서 나온 원본 관측 | 단기 기억 |
| 일화 기억(Episodic) | 압축된 세션 요약 | 무슨 일이 있었는가 |
| 의미 기억(Semantic) | 추출된 사실과 패턴 | 무엇을 알고 있는가 |
| 절차 기억(Procedural) | 작업 흐름과 의사결정 패턴 | 어떻게 하는가 |
기억은 시간이 지나면서 에빙하우스 망각 곡선을 따라 약해지고, 자주 참조되는 기억은 반대로 강해집니다. 오래된 기억은 자동으로 밀려나며, 서로 모순되는 내용은 감지해 정리합니다. 이 밖에도 버전 관리와 대체 관계를 기록하는 기억 진화, 어떤 관측에서 나온 기억인지 추적하는 출처 표기, 팀원 간 공유 영역과 개인 영역을 분리하는 네임스페이스, git 스냅샷으로 기억 상태를 되돌리는 기능이 들어 있습니다.
agentmemory의 벤치마크 결과
개발자는 두 가지 검색 정확도 측정 결과를 공개했습니다. 하나는 자체 제작한 15개 세션 규모의 coding-agent-life-v1 코퍼스이고, 다른 하나는 ICLR 2025에서 발표된 공개 벤치마크 LongMemEval-S의 500문항입니다.
| 시스템 | R@5 | R@10 | MRR |
|---|---|---|---|
| agentmemory | 95.2% | 98.6% | 88.2% |
| BM25 단독 폴백 | 86.2% | 94.6% | 71.5% |
자체 코퍼스에서는 하이브리드 검색이 P@5 0.240, R@5 1.000으로 상위 5건 적중률 15/15를 기록했고 p50 지연은 14밀리초였습니다. 같은 조건의 grep 기준선은 P@5 0.227, R@5 0.967입니다. 개발자는 이 코퍼스가 작고 정답이 희소해서 P@5의 수학적 상한이 0.240이라는 점, 따라서 여기서 얻은 이득은 정밀도가 아니라 재현율과 시간 관련 질의에서 나온다는 점을 함께 적어 두었습니다. 규모가 큰 LongMemEval-S 쪽이 차이를 더 잘 보여준다는 설명도 덧붙어 있습니다. 위 수치들은 로컬에서 무료로 도는 all-MiniLM-L6-v2 임베딩 모델을 기준으로 측정한 값이며, 재현용 하네스는 저장소의 eval/ 디렉토리에 들어 있습니다.
토큰 사용량 비교도 함께 제시되어 있습니다. 전체 맥락을 그대로 붙여 넣는 방식은 연간 1,950만 토큰이 넘어 컨텍스트 윈도우를 초과하고, LLM으로 요약하는 방식은 약 65만 토큰에 연 500달러 수준입니다. agentmemory는 약 17만 토큰에 연 10달러 정도이며, 로컬 임베딩을 쓰면 비용이 들지 않습니다.
agentmemory 설치 및 연결 방법
전역 설치 후 서버를 띄우고 에이전트를 연결하는 순서입니다.
npm install -g @agentmemory/agentmemory # 한 번만, PATH에 agentmemory 등록
agentmemory # 3111 포트에서 메모리 서버 시작
agentmemory demo # 샘플 세션을 넣고 회수 동작 확인
agentmemory connect claude-code # MCP 연결 (copilot-cli, codex, cursor, gemini-cli 등도 가능)
터미널을 두 개 열기 번거로우면 agentmemory demo --serve 로 서버 기동과 데모 실행, 정리를 한 번에 처리할 수 있습니다. 설치 없이 써 보려면 npx @agentmemory/agentmemory 를 쓰되, npx가 버전별로 캐시하므로 오래된 릴리스가 뜨면 npx -y @agentmemory/agentmemory@latest 로 최신 버전을 강제하면 됩니다.
에이전트가 이 도구들을 언제 써야 하는지 알도록 하는 스킬도 별도로 제공됩니다.
npx skills add rohitg00/agentmemory -y
MCP 서버로는 53개의 도구와 6개의 리소스, 3개의 프롬프트, 15개의 스킬이 노출됩니다. 임베딩 제공자는 자동 감지되며, 로컬 실행을 권장하는 쪽은 @xenova/transformers 를 설치해 쓰는 all-MiniLM-L6-v2 구성입니다. 그 밖에 Gemini, OpenAI, Voyage AI, Cohere, OpenRouter를 선택할 수 있습니다.
Windows에서는 WSL2가 권장 경로입니다. 네이티브 Windows 환경 설정은 수동으로 10분에서 20분 정도 걸리고 agentmemory connect 는 현재 지원되지 않으므로, 해당 환경이라면 저장소의 Windows 안내를 먼저 확인하는 편이 좋습니다.
agentmemory의 라이선스
agentmemory는 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
agentmemory 공식 홈페이지
agentmemory 프로젝트 GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 