SQLite 파일 하나에 담기는 Claude Code 메모리 관리 도구 'nan-forget' 공개

실용적 조언

Claude Code나 Cursor 사용 시 세션 간 컨텍스트 유지를 위해 npx nan-forget setup 명령어로 즉시 설치하여 사용 가능하다.
벡터 DB 대신 SQLite를 활용해 로컬 리소스 점유율을 최소화하는 메모리 시스템 설계 방식을 참고할 수 있다.

섹션별 상세

기존 메모리 도구들이 과도한 RAM을 사용하거나 경량화를 위해 벡터 검색을 포기하는 문제를 해결하기 위해 nan-forget을 개발했다. SQLite 단일 파일(~3MB)에 모든 메모리를 저장하며 별도의 백그라운드 서비스 없이 로컬에서 실행된다. 이 아키텍처는 리소스가 제한된 환경에서도 LLM의 장기 기억을 유지할 수 있게 한다.

검색 성능 최적화를 위해 인지(recognition), 회상(recall), 확산 활성화(spreading activation)로 구성된 3단계 검색 파이프라인을 구축했다. Claude가 직접 SQLite 마이그레이션과 벡터 검색 스코어링의 예외 케이스 처리를 설계에 참여했다. 이를 통해 단순 키워드 매칭을 넘어선 고도화된 의미 기반 검색이 가능하다.

사용자가 명시적으로 저장 명령을 내리지 않아도 4개의 훅(hook)이 작업 컨텍스트를 자동으로 저장한다. 저장된 메모리는 문제, 해결책, 개념 필드로 구조화되어 관리된다. 과거의 버그 수정 사례가 수개월 뒤 동일한 에러 발생 시 자동으로 표면화되어 재사용성을 높인다.

메모리의 효율적 관리를 위해 30일 반감기를 적용한 메모리 감쇠(decay) 시스템을 도입했다. 오래된 메모리는 요약본으로 통합되고 활성 메모리는 더욱 정교해지는 메커니즘을 갖췄다. MCP, REST API, CLI 등 다양한 인터페이스를 지원하여 Claude Code뿐만 아니라 Cursor나 Codex에서도 동일한 데이터베이스를 공유할 수 있다.

용어 해설

모델 컨텍스트 프로토콜(MCP): — Anthropic이 발표한 개방형 표준으로, AI 모델이 로컬 데이터나 외부 도구와 안전하게 상호작용할 수 있도록 연결하는 규격이다. 이를 통해 Claude Code와 같은 에이전트가 로컬 파일이나 데이터베이스에 직접 접근하여 작업을 수행할 수 있다.
확산 활성화(Spreading Activation): — 인지 심리학에서 유래한 정보 검색 모델로, 하나의 개념 노드가 활성화되면 그와 연결된 다른 노드들로 활성화가 퍼져나가는 방식이다. LLM 메모리 시스템에서 관련 있는 과거 컨텍스트를 연쇄적으로 찾아내는 데 활용된다.
벡터 검색(Vector Search): — 데이터를 수치화된 벡터로 변환하여 키워드가 아닌 의미적 유사성을 기준으로 정보를 찾는 기술이다. nan-forget은 SQLite를 기반으로 이 기능을 구현하여 별도의 서버 없이도 의미 기반 검색을 지원한다.
컨텍스트 손실(Context Loss): — LLM과의 대화 세션이 종료되거나 길어질 때 이전의 작업 내용이나 설정 정보를 잊어버리는 현상이다. 이를 해결하기 위해 외부 메모리 시스템을 구축하여 과거의 중요한 정보를 다시 주입하는 방식이 사용된다.

언급된 도구

nan-forget추천링크

LLM용 초경량 로컬 메모리 관리 도구

Claude Code추천

Anthropic의 CLI 기반 코딩 에이전트

SQLite추천

단일 파일 기반 데이터 저장 및 검색 엔진

언급된 리소스

GitHubnan-forget GitHub Repository