Claude Code를 위한 영구적이고 확장 가능한 로컬 메모리 백엔드 bkmr

실용적 조언

에이전트용 도구 개발 시 --json 및 --np(no-prompt) 플래그를 구현하여 사람이 개입하지 않는 구조화된 출력을 제공하라.
중복 데이터 저장을 방지하기 위해 저장 전 유사도 체크 로직을 추가하여 메모리 효율성을 높여라.

섹션별 상세

Claude Code의 기본 메모리 시스템은 세션 간 지식 공유와 대규모 데이터 확장에 한계가 있다. 이를 해결하기 위해 bkmr은 로컬 데이터베이스를 기반으로 한 읽기/쓰기 메모리 백엔드를 제공한다. 사용자는 명령어를 통해 사실 정보나 설정값을 태그와 함께 저장할 수 있으며, 이는 컨텍스트 윈도우를 낭비하지 않고도 수천 개의 기억을 관리할 수 있게 한다. 에이전트는 필요할 때만 관련 정보를 호출하여 효율적으로 지식을 활용한다.

bash

bkmr add "Prod DB is PostgreSQL 15 on port 5433" fact,database \
--title "Production database config" -t mem --no-web

bkmr 도구를 사용하여 새로운 지식(메모리)을 태그와 함께 로컬에 저장하는 예시

bash

bkmr hsearch "database configuration" -t _mem_ --json --np

에이전트가 소비할 수 있도록 구조화된 JSON 형식으로 하이브리드 검색을 수행하는 예시

검색 성능을 높이기 위해 전체 텍스트 검색과 시맨틱 검색을 결합한 하이브리드 검색 방식을 채택했다. Reciprocal Rank Fusion(RRF) 알고리즘을 사용하여 두 검색 결과의 순위를 통합함으로써 정확도를 극대화한다. 예를 들어 'database config'라는 쿼리를 입력하면 'postgresql' 태그가 달린 메모리를 의미론적으로 찾아낼 수 있다. 이러한 방식은 키워드가 일치하지 않더라도 맥락에 맞는 정보를 정확히 추출하는 데 기여한다.

보안과 개인정보 보호를 위해 모든 임베딩 연산은 ONNX Runtime을 통해 로컬에서 오프라인으로 실행된다. 데이터가 외부 서버로 전송되지 않으므로 민감한 설정 정보나 프로젝트 기밀을 안전하게 보관할 수 있다. 또한 메모리 저장 시 유사도 검사를 수행하여 중복된 기억이 생성되는 것을 방지하는 데두플리케이션(Deduplication) 기능을 포함한다. 에이전트가 사용하기 적합하도록 프롬프트 없는 JSON 출력을 지원하여 자동화 워크플로우에 최적화되었다.

용어 해설

하이브리드 검색(Hybrid Search): — 키워드 기반의 전체 텍스트 검색(BM25 등)과 의미 기반의 벡터 검색을 결합한 방식이다. 두 방식의 결과를 상호 재순위화(RRF)하여 정확도를 높이며, 특정 용어의 일치와 문맥적 유사성을 동시에 고려할 수 있어 검색 품질을 극대화한다.
상호 순위 결합(Reciprocal Rank Fusion): — 서로 다른 검색 알고리즘에서 나온 결과 순위들을 하나의 통합된 순위로 결합하는 기법이다. 각 결과의 순위 역수를 합산하여 점수를 계산하며, 하이브리드 검색에서 텍스트 검색과 시맨틱 검색 결과를 공정하게 통합하는 데 필수적이다.
ONNX 런타임(ONNX Runtime): — 다양한 프레임워크에서 학습된 머신러닝 모델을 최적화하여 실행할 수 있게 돕는 고성능 추론 엔진이다. 이 도구에서는 로컬 환경에서 임베딩 모델을 실행하여 외부 API 호출 없이 데이터를 처리하는 데 사용된다.
컨텍스트 윈도우(Context Window): — LLM이 한 번에 처리할 수 있는 토큰의 최대 범위를 의미한다. 모든 기억을 여기에 넣으면 비용이 상승하고 성능이 저하되므로, 필요한 정보만 검색하여 주입하는 전략이 대규모 지식 관리에 중요하다.

언급된 도구

bkmr추천

하이브리드 검색 기반의 로컬 영구 메모리 백엔드

ONNX Runtime추천

로컬 환경에서의 고성능 임베딩 모델 추론