SQLite 지식 저장소와 MCP 도구로 AI 컨텍스트 관리하기

AI 코딩 에이전트의 일반적인 문제점: CLAUDE.md 파일이 수천 줄로 늘어나 컨텍스트 예산을 소모하고 AI가 규칙의 절반을 무시하게 됩니다. 한 개발자가 r/ClaudeAI에서 이 문제를 해결하기 위해 RunawayContext(MIT 라이선스, 현재 Vista, Procore, Monday.com 등 건설 관리 통합에 사용됨)를 구축했습니다.

아키텍처

핵심 아이디어: 평면 마크다운 파일의 깊은 지식을 SQLite 데이터베이스로 옮기고, 전문 검색(FTS5)과 선택적 벡터 검색(sqlite-vec 사용)을 지원합니다. 매 세션마다 모든 것을 로드하는 대신, 소규모 프로젝트 개요(~150줄), 전역 헌장(~200줄), 포인터 전용 '살아있는 기억'(~50줄)만 사전 로드됩니다. AI는 search_lessons 및 get_chunk 같은 MCP 도구를 사용해 필요 시 데이터베이스를 쿼리합니다.

주요 구현 세부사항

• 토큰 계산: 약 280K 토큰이 여전히 존재하지만, 데이터베이스에 있을 뿐 컨텍스트에 로드되지 않습니다. AI는 작업 중간에 필요한 것을 가져옵니다.
• 코드 내 하드 제한: 재생성기는 150줄 제한을 초과하는 개요를 작성하지 않습니다. 15개의 명명된 아키텍처 규칙 각각에는 규칙이 변경되면 빌드를 실패시키는 CI 테스트가 있습니다.
• 하이브리드 검색: 벡터 전용 검색은 하이브리드보다 성능이 나빴습니다. 시스템은 FTS5 키워드 점수와 sqlite-vec 벡터 점수를 혼합하여 최상의 결과를 얻습니다.
• 인간 개입: AI는 새 레슨을 초안 받은편지함에 씁니다. 인간이 승인해야 지식 저장소로 승격되어 노이즈를 방지합니다.
• 보존된 내용: 자동 생성된 개요에는 <!-- PRESERVE_START --> 마커로 구분된 수동 큐레이션 블록이 포함됩니다. 재생성기는 그 부분을 그대로 유지하고 주변 부분만 재생성합니다.

교훈

• 정책이 아닌 코드로 규칙을 강제하세요 — '늘리지 않도록 주의' 지침은 수개월 내에 모두 위반되었습니다.
• 하이브리드 FTS5 + 벡터 검색이 벡터 전용 검색보다 낫습니다.
• AI가 직접 지식 저장소에 쓰면 노이즈가 발생합니다. 수동 승인이 있는 초안 받은편지함을 사용하세요.

이 시스템은 에이전트에 독립적이며 저장소는 누구나 적용할 수 있도록 공개되어 있습니다.