agentmemory - AI 코딩 에이전트용 영구 메모리 시스템 완벽 가이드

agentmemory — AI 코딩 에이전트용 영구 메모리 시스템

agentmemory - AI 코딩 에이전트용 영구 메모리 시스템 완벽 가이드

AI 코딩 에이전트를 매일 쓰면서 같은 설명을 반복한 경험이 있나요? JWT 인증을 세션 1에서 설정했는데, 세션 2에서 다시 설명해야 하는 상황. 바로 이 문제를 해결하는 도구가 agentmemory입니다.

문제의 핵심

Claude Code에는 MEMORY.md가 있고, Cursor에는 notepad가 있으며, Cline에는 memory bank가 있습니다. 하지만제시 임시 메모리에 불과합니다. 200줄 이상의 파일은 만들 수 없고, 오래되면 내용이 흐릿해집니다. 또한 에이전트를 바꿀 때마다 메모리를 이전할 방법이 없습니다.

agentmemory는 이 문제를 완전히 다른 방식으로 해결합니다. 검색 가능한 데이터베이스 형태로 세션 간 모든 것을 기억하는 것입니다.

설치부터 기본 사용까지

agentmemory 설치는 한 줄로 끝납니다.

npm install -g @agentmemory/agentmemory

서버를 시작하려면 터미널에서 다음 명령어를 실행합니다.

agentmemory

별도의 데이터베이스 설치가 필요하지 않습니다. SQLite와 iii-engine 위에서 동작하므로, 설치와 동시에 메모리 서버가 로컬의 3111 포트에서 실행됩니다. 실시간 뷰어는 3113 포트에서 확인할 수 있습니다.

데모를 실행하면 실제 검색 기능을 눈으로 볼 수 있습니다.

agentmemory demo

세 개의 샘플 세션(JWT 인증 설정, N+1 쿼리 수정, Rate Limiting)이 시딩되고, "데이터베이스 성능 최적"이라고 검색하면 "N+1 쿼리 수정"을 찾아줍니다. 키워드 매칭으로는 절대 불가능한 검색 결과입니다.

검색 정확도 수치

agentmemory의 성능은 벤치마크에서 입증되고 있습니다.

coding-agent-life-v1 데이터셋에서 agentmemory는 P@5가 0.578로, grep 베이스라인의 0.267보다 2.2배 뛰어넘었습니다. Top-5 적중률은 100%입니다.

ICLR 2025의 LongMemEval-S(500개 질문)에서는 R@5가 95.2%에 달합니다. 같은 조건에서 BM25만 사용하면 86.2%에 그칩니다. 토큰 비용 측면에서도 강점이 있습니다.하문에 전체를 붙이면 연간 1950만 토큰 이상이 필요하지만, agentmemory는 약 17만 토큰으로 같은 효과를 냅니다. 비용은 약 10달러 수준입니다.

다중 에이전트 지원

agentmemory의 가장 큰 강점 중 하나는 다양한 AI 코딩 에이전트와 통합된다는 점입니다.

Claude Code는 12개의 네이티브 후크와 MCP를 지원하며, Codex CLI는 6개의 후크와 MCP를 제공합니다. Hermes는 파이썬 플러그인으로 연결됩니다. 그 외에도 Cursor, Gemini CLI, OpenCode, Cline, Goose, Kilo Code, Aider, Windsurf, Roo Code 등 거의 모든 주요 에이전트를 지원합니다.

모든 에이전트가 하나의 메모리 서버를 공유합니다. 한 에이전트에서 쌓은 지식을 다른 에이전트가 그대로 활용할 수 있습니다.

검색 방식의 혁신

agentmemory는 세 가지 검색 방식을 결합합니다. BM25(LEXICAL), Vector(SEEMANTIC), Knowledge Graph(RELATIONAL)를 동시에 활용합니다. 세 결과는 장치 내 리랭커를 거치며 최종 순위가 결정됩니다.

P50 지연시간이 노트북에서 20밀리초 미만입니다. 사용자 입장에서 체감 속도는 체감 불가 수준입니다.

내장 임베딩 모델로 all-MiniLM-L6-v2를 사용합니다. 로컬에서 동작하므로 API 키가 필요하지 않습니다.

자동 메모리 캡처

12개의 자동 후크가 동작합니다. PreToolUse, PostToolUse, SessionStart, SessionEnd 등 주요 이벤트가 자동으로 메모리 파이프라인에 연결됩니다. 별도의 glue 코드를 작성할 필요가 없습니다. 플러그인을 설치하면 끝입니다.

수동으로 메모리를 추가하는 것도 가능합니다.

await memory_save({type: "insight",content: "이 프로젝트에서는 jose 미들웨어를 사용한다",confidence: 0.9});

검색도 간단합니다.

const results = await memory_recall({query: "jwt 인증 설정",limit: 5});

세션 리플레이 기능

모든 세션은 다시 재생할 수 있습니다. 뷰어의 Replay 탭을 열면 타임라인을 따라 프롬프트, 도구 호출, 도구 결과, 응답을Discrete Events로 확인할 수 있습니다. 재생, 일시정지, 속도 조절(0.5배~4배), 키보드 단축키(스페이스 토글, 화살표 스텝)가 제공됩니다.

이전 Claude Code JSONLTranscript를 가져올 수도 있습니다.

agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl

가져온 세션은 네이티브 세션과 함께 Replay 목록에 나타납니다.

경쟁 도구와의 비교

mem0(5만3천 스타), Letta/MemGPT(2만2천 스타)와 비교할 때 agentmemory의 차별점은 명확합니다.

메모리 유형에서 agentmemory는 검색 정확도 R@5가 95.2%로, mem0의 68.5%와 Letta의 83.2%를 크게 앞서습니다. 자동 캡처 기능은 12개의 후크로 구현되어 있어, mem0의 수동 add() 호출이나 Letta의 에이전트 자체 수정보다 훨씬 편리합니다. 외부 의존성에서도 차이가 납니다. agentmemory는 SQLite만 사용하지만, mem0는 Qdrant, Letta는 Postgres를 필요로 합니다. 토큰 효율성은 연간 약 1900 토큰(10달러) 수준으로, mem0나 Letta보다 훨씬 경제적입니다.

실제 적용 사례

실제 개발자들이 실제로 사용하는 방법입니다.

한 개발자는 지난 한 달간의 Cursor 에이전트 Transcript를 전부 가져와서 agentmemory에 입력했습니다. 결과는 놀라웠습니다. 자신이 놓쳤던 것들을 에이전트가 기억하고 있었고, 이전에 시도했다가 중단했던 접근 방식을 정확히 찾아냈습니다.

다른 개발자는 2주 연속 사용 후 확실한 개선을 경험했습니다. 같은 라이브러리 설정 방법을 반복 설명할 필요가 없어졌고, 에이전트가 이전 세션의 컨텍스트를 즉시 파악했습니다.

지식 그래프 추출

메모리를 압축하는 과정에서 지식 그래프가 자동으로 추출됩니다. 엔티티와 관계가 노드로 구성되고, 시간 간격도 Temporal Edge로 연결됩니다.

그래프는 뷰어에서 Force-Directed Visualisation으로 확인할 수 있습니다. 프로젝트별, 유형별, 신뢰도별로 필터링할 수 있습니다.

외부 데이터베이스 없는 아키텍처

agentmemory의 핵심 설계는 단순함입니다. 단일 노드 프로세스로 동작하며, Redis, Kafka, Postgres, Qdrant, Neo4j가 필요하지 않습니다. 모든 상태는 디스크의 JSON으로 저장됩니다. 이것이 전체 스택입니다.

오픈소스(Apache-2.0)로 제공되며, Linux Foundation에서 후원합니다.

시작하는 방법

먼저 설치합니다.

npm install -g @agentmemory/agentmemory

메모리 서버를 시작합니다.

agentmemory

원하는 에이전트에 연결합니다.

agentmemory connect claude-code

Claude Code의 경우 /plugin marketplace add rohitg00/agentmemory로 직접 설치할 수도 있습니다.

앞으로 기대되는 발전

에이전트 메모리 시스템은 AI 코딩의 핵심 인프라로 자리잡가고 있습니다. 모델 성능이 올라갈수록 더 많은 컨텍스트를 활용하게 되는데, 이때마다 전체 문맥을 넣는 것은 비효율적입니다. 필요한 정보만 빠르게 검색해서주입하는 방식이 표준이 될 것입니다.

agentmemory는 이미 1만6천 스타 이상을 받았으며, 벤치마크에서도 검증된 결과를 보여주고 있습니다. 특히 외부 데이터베이스가 필요 없다는점하 자체 호스팅 환경에서 매력적입니다. 무료 로컬 임베딩과 결합하면 비용도 거의 들지 않습니다.

AI 코딩 에이전트를 매일 사용하는 분이라면, agentmemory는 반드시 시도해볼 도구입니다. 세션을 넘나드는 정보를 매번 설명하는 수고를 줄이고, 더 빠르게 가치 있는 결과에 도달할 수 있습니다.

---

핵심 정리

• 설치: npm install -g @agentmemory/agentmemory

• 실행: agentmemory (3111 포트 서버, 3113 포트 뷰어)

• 검색 정확도: LongMemEval-S에서 R@5 95.2%

• 지원 에이전트: Claude Code, Codex CLI, Cursor, Gemini CLI, Hermes, OpenCode, Cline, Goose 등 12개 이상

• 외부 의존성: 없음 (SQLite + iii-engine만 사용)

• 토큰 비용: 약 170K 토큰/년, 약 10달러

• 라이선스: Apache-2.0

---

📚 출처

• https://news.hada.io/topic?id=29754