스킬 챕터 · agentmemory — 클로드 코드 교육

한눈에

무엇인가

AI 코딩 에이전트용 영구 기억 미들웨어(훅+스킬+MCP)

핵심 원리

활동 자동 기록 → 압축 → 임베딩 → 하이브리드 검색으로 재주입

설치 난이도

어려움 (Node 20↑·로컬 서버, Windows는 WSL2 권장)

사용자 추천도 (참고)

★★★★☆ — 같은 프로젝트를 오래 이어갈 때

만든이 · 라이선스

rohitg00 · Apache-2.0 · TypeScript

저장

로컬 SQLite + 로컬 임베딩(외부 DB 불필요)

작동 원리 (자세히)

클로드 코드의 수명주기 훅이 작업을 감지하면, 아래 파이프라인을 배경에서 돌립니다.

활동 감지(훅)→ 비밀정보 필터→ LLM 압축→ 임베딩(로컬 기본)→ 색인(키워드+벡터+그래프)

4단계 기억 정리

작업(Working)

원시 관찰

에피소드

세션 요약

의미(Semantic)

추출된 사실·패턴

절차(Procedural)

워크플로우·결정

자주 쓰는 기억은 강화되고, 오래된 건 자동으로 밀려납니다. 검색은 키워드(BM25)+벡터+그래프를 합쳐(RRF) 관련 기억을 뽑아 새 세션에 주입합니다.

▸ 프로젝트 상태나 결정을 문서 파일로 직접 정리하던 일을 자동화한 버전이라고 볼 수 있습니다.

설치

플러그인 마켓 + 훅 연결

Claude Code / 터미널

/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory
# 훅 연결(터미널):
agentmemory connect claude-code

⚠️ 전제조건 · Windows 주의: Node.js 20 이상이 필요하고, 로컬 서버(포트 3111~3113)를 띄웁니다. Windows 네이티브는 설정이 까다로워 WSL2를 권장합니다(agentmemory connect가 네이티브에서 미지원). 설치 부담이 큰 편이라, 개념만 익히고 필요할 때 도전하세요.

사용법

Claude Code

> /remember 이 프로젝트는 더미데이터 원칙을 지킨다
> /recall 지난번에 정한 색상 규칙이 뭐였지?
> /session-history        (최근 세션 목록)
> /forget                 (특정 기억 삭제)

검색은 키워드가 달라도 의미로 찾아줍니다. 예: "데이터베이스 성능 최적화"로 검색 → 저장된 "N+1 쿼리 수정" 기억을 회수.

수치로 보는 강점 (제작자 자체 벤치마크)

검색 정확도

상위 5개 회수율 95.2% (기준 대비 향상).

토큰 절약

전체 붙여넣기 대비 약 92% 절감(로컬 임베딩 시 비용 0에 근접).

속도

상위 5개 회수 지연 중앙값 약 14ms.

※ 위 수치는 저장소가 밝힌 자체 측정값으로, 독립 검증된 값은 아닙니다.

장점 · 단점

👍 장점

자동 기록(수동 입력 불필요). 의미 기반 하이브리드 검색. 외부 DB 불필요(로컬 저장). 여러 에이전트 공유 가능. 로컬 임베딩은 무료·오프라인.

👎 단점

설치가 무거움(엔진·로컬 서버). Windows 네이티브 취약(WSL2 권장). 배경에서 활동을 항상 기록 → 프라이버시 유의(비밀정보 필터는 있음). 신생·빠른 변화로 API 변동 가능. 웹 뷰어는 인증 없음 → 외부 노출 금지.

when

언제 쓰고, 언제 피하나

쓰기 좋을 때: 같은 코드베이스를 여러 세션에 걸쳐 오래 작업하고, 매번 재설명이 싫을 때. 로컬 서버 운영에 거부감이 없을 때.
피할 때: WSL2 없는 Windows, 데몬 없는 단순 방식을 원할 때, 배경 상시 기록이 부담스러울 때(작은 프로젝트는 CLAUDE.md로 충분).