Claude Code 메모리 문제 해결 방법: QMD 검색 엔진과 /recall 스킬로 만드는 컨텍스트 중심 AI 워크플로우

AI 코딩 도구가 발전하면서 개발자의 생산성은 크게 향상되었습니다. 그러나 세션이 바뀔 때마다 이전 대화와 맥락이 사라지는 문제는 여전히 많은 사용자들이 겪는 불편함 중 하나입니다. 특히 장기간 프로젝트를 진행하거나 복잡한 의사결정을 반복해야 하는 환경에서는 이러한 컨텍스트 손실이 작업 효율을 크게 떨어뜨립니다.

이번 글에서는 Claude Code 사용 과정에서 발생하는 세션 간 컨텍스트 유실 문제를 해결하기 위해 구축된 메모리 시스템을 소개합니다. 로컬 검색 엔진 QMD와 /recall 스킬을 결합하여 과거 작업 기록을 빠르게 검색하고 전체 맥락을 복원하는 방식입니다. 또한 기존 grep 기반 검색의 한계를 비교하고 BM25, 시맨틱 검색, 하이브리드 검색을 활용하는 방법까지 함께 살펴봅니다.

이 글을 통해 AI 에이전트 환경에서 컨텍스트 중심 워크플로우를 어떻게 구축할 수 있는지 이해할 수 있습니다.

반응형

---

Claude Code의 세션 기반 구조와 컨텍스트 유실 문제

Claude Code는 기본적으로 모든 대화를 **제로 상태(Zero State)**에서 시작하는 구조입니다. 즉, 이전 세션의 내용을 자동으로 기억하지 않습니다.

실제 사용 사례에서는 약 3주 동안 700개 이상의 세션이 생성되면서 다음과 같은 문제가 발생했습니다.

• 매 세션마다 이전 결정 사항을 다시 확인해야 하는 반복 작업 발생
• 대화 중 컨텍스트 사용량이 약 60%에 도달하면 compact 또는 hand off 과정이 필요
• 이 과정에서 이전 대화의 절반 이상이 요약되거나 사라짐
• 다음 날 작업을 이어갈 때 이전 작업 맥락을 찾기 어려움

기존에는 파일 검색을 위해 grep 기반 검색을 사용했지만, 세션 기록이 많아질수록 검색 결과의 정확성과 속도 모두에서 한계가 드러났습니다.

---

QMD: Obsidian 볼트를 위한 로컬 검색 엔진

이 문제를 해결하기 위해 사용된 도구가 QMD 검색 엔진입니다.

QMD는 Shopify CEO인 Tobias Lutke가 만든 로컬 검색 엔진으로, Obsidian 볼트를 인덱싱하여 빠르게 검색할 수 있도록 설계되었습니다.

주요 특징

• Obsidian Vault 전체를 인덱싱
• 1초 이내 검색 결과 반환
• 다양한 검색 방식 지원
• 컬렉션 단위 검색 가능

볼트 내부 폴더를 컬렉션으로 매핑하면 특정 데이터만 집중적으로 검색할 수 있습니다.

예시 컬렉션 구조

• notes
• daily notes
• session 기록
• transcript 데이터

기본 사용 예시

qmd collection list
qmd search "video workflow" -c notes -n 3

위 명령은 notes 컬렉션에서 “video workflow”와 관련된 상위 3개의 결과를 반환합니다.

---

기존 Grep 검색 방식의 한계

Claude Code 기본 검색 방식은 Haiku 서브 에이전트가 모든 파일을 grep 방식으로 검색하는 구조입니다.

테스트 결과는 다음과 같습니다.

항목	Grep 검색
검색 시간	약 3분
반환 파일	약 300개
정확도	낮음
노이즈	매우 많음

예를 들어 “sleep”을 검색하면 다음과 같은 문제가 발생합니다.

• 수면 관련 기록
• 프로그래밍 함수 sleep() 호출
• 관련 없는 로그

이처럼 키워드만 일치하면 결과에 포함되기 때문에 노이즈가 많아집니다.

---

BM25 검색: 정확한 키워드 기반 검색

QMD의 기본 검색 방식은 BM25 알고리즘입니다.

BM25는 풀텍스트 검색 알고리즘으로 다음 요소를 기반으로 점수를 계산합니다.

• 단어 등장 빈도
• 문서 길이
• 전체 문서에서 단어의 희소성

예를 들어 다음 두 문서를 비교합니다.

• 100단어 노트에서 "sleep" 5번 등장
• 10,000단어 문서에서 "sleep" 1번 등장

BM25는 첫 번째 문서에 더 높은 점수를 부여합니다.

특징

• AI 모델이나 임베딩 없이 수학적 연산으로 작동
• 빠른 검색 속도
• 구조화된 문서에 적합

---

시맨틱 검색: 의미 기반 검색

시맨틱 검색은 임베딩 기반 검색 방식입니다.

이 방식은 정확한 단어가 없어도 의미적으로 유사한 문서를 찾아낼 수 있습니다.

예를 들어 다음과 같은 검색이 가능합니다.

검색어

couldn't sleep, bad night

검색 결과

• 과거 수면 습관 목표 기록
• 수면 패턴 관련 노트
• 건강 관련 기록

흥미로운 점은 결과 중 대부분이 검색어 단어를 포함하지 않았다는 것입니다. 대신 의미적으로 연결된 문서가 발견됩니다.

---

하이브리드 검색: BM25 + 시맨틱 검색 결합

QMD는 하이브리드 검색 방식도 제공합니다.

qmd query

이 방식은 다음 두 가지를 결합합니다.

• BM25 키워드 검색
• 시맨틱 임베딩 검색

예시 검색 결과

문서	관련도
sleep quality improvement	89%
sleep interrupted at 3am	51%
health sleep optimisation	42%

하이브리드 검색은 가장 균형 잡힌 결과를 제공합니다.

권장 검색 전략

• 전체 검색의 약 80% → BM25
• 비정형 데이터 (대화 기록, 트랜스크립트) → 시맨틱 검색

---

/recall 스킬: 과거 컨텍스트 복원 시스템

QMD 검색 엔진 위에서 동작하는 Claude Code 스킬이 /recall입니다.

이 스킬은 작업을 시작하기 전에 과거 세션의 컨텍스트를 자동으로 불러오는 기능을 제공합니다.

지원 모드

1. Temporal 모드
2. Topic 모드
3. Graph 모드

---

1. Temporal 모드 (시간 기반 검색)

날짜 기반으로 세션 기록을 불러옵니다.

예시

/recall yesterday
/recall last week

실제 테스트에서는 하루 동안 생성된 39개의 세션이 다음 정보와 함께 재구성되었습니다.

• 세션 시간
• 메시지 수
• 작업 내용 요약

---

2. Topic 모드 (주제 기반 검색)

특정 주제와 관련된 모든 컨텍스트를 검색합니다.

예시

/recall topic "QMD video"

검색 결과

• 관련 세션
• 프로젝트 노트
• 대시보드
• 프로덕션 계획
• TODO 리스트

기존 grep 방식보다 빠르고 정확한 결과를 제공합니다.

---

3. Graph 모드 (컨텍스트 시각화)

Graph 모드는 세션과 파일 관계를 시각적으로 표시합니다.

특징

• 최근 세션 → 보라색 강조
• 오래된 세션 → 흐리게 표시
• 파일 유형별 클러스터링

예시 파일 유형

• goals
• research
• voice
• docs
• content
• skills

이 그래프를 통해 오래된 작업도 쉽게 다시 찾을 수 있습니다.

---

700개 세션 자동 인덱싱 시스템

Claude Code는 모든 대화를 JSONL 형식으로 로컬 저장합니다.

3주 동안 약 700개의 세션 기록이 생성되었습니다.

원본 JSONL 파일에는 다음 데이터가 포함됩니다.

• tool 사용 기록
• 시스템 프롬프트
• role 정보

이 데이터를 자동 파싱하여 다음 과정이 진행됩니다.

1. 사용자 메시지 중심으로 데이터 정리
2. Markdown 형태로 변환
3. QMD 인덱스에 임베딩
4. 검색 가능 상태로 저장

자동화 방식

터미널 종료 시 자동 hook이 실행되어

• 세션 export
• 임베딩 생성
• QMD 인덱스 업데이트

가 자동으로 수행됩니다.

사용자는 별도의 수동 작업 없이 항상 최신 검색 인덱스를 유지할 수 있습니다.

---

잊혀진 아이디어를 다시 발견하는 검색

시맨틱 검색을 활용하면 과거에 기록했지만 실행하지 않았던 아이디어도 발견할 수 있습니다.

예시 검색

find the ideas that I have never acted on

검색 결과

• PhD 작성 대시보드 아이디어
• 일러스트 기반 앱 아이디어
• Obsidian 워크플로우 화면 녹화 아이디어

수개월 전에 기록했지만 완전히 잊혀졌던 아이디어들이 다시 발견되었습니다.

모든 임베딩 데이터는 로컬 환경에 저장됩니다.

---

컨텍스트 중심 AI 워크플로우

이 시스템의 핵심 개념은 컨텍스트 중심 워크플로우입니다.

기존 방식

도구 중심
AI → 작업

새로운 방식

컨텍스트 중심
데이터 → 검색 → AI

즉, AI 도구가 바뀌어도 컨텍스트만 유지하면 동일한 작업 흐름을 사용할 수 있습니다.

---

전체 시스템 구조

전체 스택 구조는 다음과 같습니다.

하단 레이어

• Obsidian Vault

중간 레이어

• QMD Search Engine

상단 레이어

• Claude Code
• OpenClaw

컨텍스트는 하단에서 상단으로 흐르는 구조입니다.

또한 다음 환경이 함께 사용됩니다.

• Obsidian Sync로 Mac과 Mac Mini 간 볼트 동기화
• Mac Mini에서 OpenClaw 24시간 실행
• 모바일에서 OpenClaw 접속 가능

이 구조를 통해 어디서든 동일한 컨텍스트와 검색 환경을 사용할 수 있습니다.

---

728x90

AI 코딩 도구는 강력하지만 세션 기반 구조로 인해 컨텍스트 손실 문제가 발생합니다. 이를 해결하기 위해 로컬 검색 엔진 QMD와 /recall 스킬을 결합한 메모리 시스템이 제안되었습니다.

핵심 특징은 다음과 같습니다.

• Obsidian Vault 기반 로컬 검색
• BM25, 시맨틱, 하이브리드 검색 지원
• 세션 기록 자동 인덱싱
• /recall 스킬로 컨텍스트 복원
• AI 도구와 독립적인 컨텍스트 레이어

이 접근 방식은 단순한 노트 관리 시스템을 넘어 AI 에이전트 환경에서 지속 가능한 메모리 시스템을 구축하는 방법을 보여줍니다.

앞으로 AI 모델과 도구는 계속 바뀔 수 있지만, 컨텍스트와 지식 구조를 유지하는 시스템을 구축한다면 어떤 AI 환경에서도 동일한 생산성을 유지할 수 있을 것입니다.

300x250

https://x.com/artemxtech/status/2028330693659332615

X의 Artem Zhutov님(@ArtemXTech)