Claude Code를 쓰다 보면 세션이 끝나도 기억이 남는 게 고맙습니다. 기본으로 들어 있는 auto-memory가 대화 중 기억할 만한 걸 알아서 파일로 저장해두고, 다음 세션에서 다시 불러오니까요. 저도 한동안은 이걸로 충분했습니다.
문제는 메모리가 쌓이고 나서였어요. 제 경우 파일로만 380개가 넘게 모였는데, auto-memory는 인덱스 역할을 하는 MEMORY.md를 매 세션 통째로 읽어 들입니다. 기억이 늘수록 세션 시작이 무거워지고, 정작 필요한 기억 하나를 키워드로 찾아 꺼내 쓰기는 마땅치 않았습니다. 그래서 검색 계층을 하나 얹어보기로 했습니다. auto-memory를 들어내는 게 아니라, 그 위에 agentmemory라는 영속 메모리 서버를 병행으로 올리는 방식입니다.
agentmemory가 뭔가
GitHub rohitg00/agentmemory, npm으로는 @agentmemory/agentmemory(v0.9.24)입니다. 세션을 넘어 기억을 유지한다는 점은 auto-memory와 같지만, 별도 서버를 띄워서 그 기억을 검색으로 꺼내 쓴다는 게 다릅니다.
설치하면 번들된 Rust 바이너리 iii(v0.11.2)가 자동으로 뜹니다. Postgres나 Redis 같은 외부 DB는 필요 없어요. 데이터는 로컬 파일 DB(file_based, state_store.db)에 들어가고, REST와 WebSocket, 뷰어까지 전부 localhost에서 돕니다. 포트는 REST가 :3111, WebSocket이 :3112, 실시간 뷰어가 :3113입니다.
설치
Claude Code에서는 두 줄이면 끝납니다.
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory이 한 번으로 훅 12개, 스킬 8개(/recall /remember /recap /handoff /forget /commit-context /commit-history /session-history), MCP 툴 53개가 등록됩니다. REST 엔드포인트는 125개고요. 양이 좀 많지만 대부분은 알아서 동작하고, 직접 손댈 건 몇 개 안 됩니다.
설치하면서 알아두면 좋은 게 하나 있습니다. macOS에서는 launchd 데몬으로 상시 기동됩니다(KeepAlive=true, RunAtLoad=true). 그래서 agentmemory stop으로 멈춰도 launchd가 바로 다시 띄워버립니다. 완전히 내리려면 launchd 단에서 빼야 해요.
launchctl bootout gui/501/com.agentmemory.server켜기 전에 짚을 안전 설정
이 부분은 글로 남겨두는 게 도움이 될 것 같습니다. AGENTMEMORY_INJECT_CONTEXT와 AGENTMEMORY_AUTO_COMPRESS, 두 토글은 코드 기본값이 OFF입니다. provider도 기본이 noop이라 LLM 키 없이 돕니다.
두 토글을 켜면 백그라운드에서 Agent SDK 자식 세션이 뜨는데, 이게 Claude Max 구독과는 분리된 별도 크레딧 풀(종량제)을 까먹습니다. 무심코 켜뒀다가 비용이 새는 걸 모를 수 있어요. 저는 기본값 그대로 OFF로 두고 시작했습니다.
noop 모드의 부작용이 하나 있는데, LLM 요약 함수인 mem::summarize가 호출되면 전부 실패로 잡힙니다. 처음엔 버그인 줄 알았는데, LLM 호출만 의도적으로 막아둔 상태일 뿐이라 캡처와 검색 자체는 멀쩡합니다.
검색은 키 없이도 한국어가 된다
제가 가장 걱정한 게 검색이었습니다. 임베딩(의미검색) 없이 키 없는 상태로 한국어 메모리를 제대로 찾을까 싶었거든요. 결론부터 말하면, 임베딩 없이도 BM25 키워드 검색이 한국어로 잘 됩니다. 실제로 "리모델링" 키워드로 한국어 메모리가 그대로 회상되는 걸 확인했습니다.
의미검색까지 원하면 로컬 임베딩 모델 all-MiniLM-L6-v2를 붙이면 됩니다. API 키 없이 무료로 켤 수 있어요. 유료 클라우드 임베딩도 고를 수 있지만, 로컬이면 비용이 들지 않습니다.
기존 메모리 이관
파일로 쌓아둔 메모리 380개는 REST /remember로 한 번에 밀어 넣었습니다. 원본 파일은 지우지 않고 그대로 뒀어요. 직접 열어 편집할 가능성을 남겨두고 싶었거든요. 그래서 지금은 파일과 서버가 병존하는 상 태입니다. 대시보드 기준 저장된 메모리는 381개입니다.
auto-memory와 뭐가 다른가
오해하기 쉬운 부분부터 정리하면, auto-memory도 자동 저장과 세션 영속을 합니다. "기억하느냐"로 보면 둘 다 기억해요. 차이는 규모가 커졌을 때 그 기억을 꺼내 쓰는 방식입니다.
요약하면, auto-memory는 매 세션 인덱스를 통째로 읽기 때문에 메모리가 늘수록 무거워집니다. agentmemory는 그때그때 검색해서 필요한 것만 가져오고요. 그리고 MCP/REST 인터페이스라 Claude Code 말고 다른 에이전트도 같은 기억을 공유할 수 있습니다. auto-memory는 Claude Code 안에서만 쓰이죠.
자동 캡처는 생각보다 부지런하다
써보니 자동 캡처가 꽤 활발합니다. 작업 세션마다 관찰(observation)이 수십에서 수백 건씩 쌓여요. 한 세션에서 497건이 잡힌 적도 있습니다.
대신 노이즈도 같이 들어옵니다. OpenClaw keepalive 핑처럼 의미 없는 1건짜리 세션도 그대로 잡히거든요. 기계적으로 다 잡는 방식의 트레이드오프라 생각하고 받아들이는 중입니다.
대시보드
localhost:3113에 실시간 뷰어가 있습니다. 상단 탭이 12개입니다. Dashboard / Graph / Memories / Timeline / Sessions / Lessons / Actions / Crystals / Audit / Activity / Profile / Replay.
촬영 시점 라이브 수치는 이랬습니다. Memories 381, Sessions 65, Token Savings 11%(약 16,320토큰, $4.90 절약), 가동 58시간, Health는 healthy, Circuit Breaker는 closed. Graph Nodes와 Lessons, Crystals는 0입니다. 이 고급 기능들은 LLM 키가 있어야 켜지는데, 저는 noop로 쓰고 있으니 비어 있는 게 정상입니다.
고급 기능, 다만 솔직하게
기능 목록만 보면 욕심날 만큼 많습니다. 검증된 것들을 추려보면 이렇습니다.
- 4-Tier 기억 통합: Working에서 Episodic, Semantic, Procedural로 이어지는 단계. 자주 쓰는 기억은 강화하고, 오래된 기억은 망각 곡선대로 정리하고, 모순을 감지합니다.
- 지식 그래프: 엔티티와 관계를 추출.
- 액션과 멀티 에이전트 협업: lease 배타 점유, signal 메시지, mesh P2P 동기화.
- 교훈(Lessons), 결정화(Crystals).
- 프라이버시: 저장 전 API 키와 시크릿을 제거.
- 자가 치유: 서킷 브레이커, provider fallback.
- 팀 메모리.
- Git 스냅샷: 버전, 롤백, diff.
- Session Replay: 세션 재생 0.5x~4x, 기존 Claude Code JSONL import도 됩니다.
한 가지 분명히 해둘 건, 그래프 추출과 기억 통합, LLM 압축은 LLM 키가 있어야 동작한다는 점입니다(기본 off). 다만 클라우드 키만 답은 아니에요. Ollama나 LM Studio 같은 OpenAI 호환 로컬 LLM을 붙이면 키 없이 무료로 고급 기능도 돌릴 수 있습니다. 저는 아직 거기까지 안 갔습니다.
README 벤치마크
공개 README에 있는 수치도 참고로 옮겨둡니다. 자체 코퍼스에서 grep 대비 검색 정밀도가 약 2.2배(P@5 0.578 vs 0.267), top-5 적중 100%, p50 14ms라고 합니다. LongMemEval-S(ICLR 2025, 500문항)에서는 R@5 95.2%였고요.
토큰 비용 쪽이 인상적인데, 풀컨텍스트를 그냥 붙여넣으면 연 19.5M 토큰이 넘어 윈도우를 초과하니 사실상 불가능합니다. agentmemory로 검색해 쓰면 연 약 17만 토큰, 비용으로는 약 $10 수준이라고 합니다(로컬 임베딩이면 $0). 코드 규모는 소스 파일 약 118개, 21,800 LOC, 테스트 950개 이상입니다.
며칠 써보고
정리하면 이렇습니다. auto-memory는 출발점으로 좋지만, 메모리가 커지면 매 세션 인덱스를 통째로 로드하는 구조가 부담이 됩니다. agentmemory는 그 위에 검색 계층을 얹는 선택지고, auto-memory를 대체한다기보다 병존시키는 쪽에 가깝습니다.
고급 기능이 많지만 상당수는 LLM 키가 있어야 켜집니다. 저처럼 키 없이 noop로 쓰면 Graph, Lessons, Crystals는 0인 상태로 남습니다. 그래도 자동 캡처에 BM25 검색, 대시보드만으로 일상적인 회상에는 충분했어요. 위험한 토글 두 개는 끈 채로 noop와 BM25부터 시작해보는 걸 권합니다. 더 욕심이 나면 그때 로컬 임베딩이나 로컬 LLM을 붙이면 되니까요.
