npm에 Caveat 출시: 동일한 함정을 피하기 위한 장기 기억 레이어

Claude Code를 위한 장기 기억 레이어인 Caveat을 npm에 출시했습니다.

기능 설명

Claude Code를 사용할 때, 실제 구현을 하는 것보다 "타인의 사양(specifications)"을 해독하는 데 더 많은 시간을 소비할 때가 많습니다. GPU 드라이버 버전 제약, 네이티브 모듈 빌드 실패, IDE의 특이 사항, 또는 특정 OS에서만 발생하는 경로 문제 등으로 인해 막히게 됩니다. 한 번 고생해서 해결하더라도, 6개월 뒤 다른 프로젝트에서 똑같은 함정에 빠지게 됩니다. AI에게 물어보면 AI는 "모른다"고 말하는 대신 추측에 기반하여 행동하며, 이로 인해 당신은 다시 한번 시간을 낭비하게 됩니다.

Caveat은 "한 번 적어두면, 다음에 동일한 상황에 직면하는 순간 관련 메모가 자동으로 나타나는" 레이어입니다. 당신이 기억하지 못하더라도, 그리고 AI가 알지 못하더라도, 구조적으로 관련성을 감지합니다.

세 가지 트리거 포인트 (Trigger Points)

Caveat은 훅(hooks)을 사용하여 세 가지 지점에서 구현됩니다.

트리거 포인트	실행 시점	수행 작업
프롬프트 제출 (Prompt Submission)	프롬프트가 전송되는 순간	프롬프트를 분해하여 과거 메모와 두 개 이상의 단어가 공통으로 나타나는 항목만 노출함
...

"고군분투 신호(Struggle signals)"는 AI는 인지하지 못할 수 있지만, 객관적으로는 어려움을 겪고 있었음을 나타내는 흔적입니다. 예를 들어 도구(tool) 실패, 동일한 파일을 반복해서 편집, 반복적인 웹 검색, 또는 Bash 명령어를 재실행하는 것 등이 해당됩니다. Caveat은 세션 종료 시 이를 스캔하여 "오늘 세션에서 이 부분에서 막히셨죠? 이것을 함정으로 기록하시겠습니까?"라고 사용자에게 제안합니다.

키워드 목록 없는 설계

검색 로직은 오로지 **동시 출현 FTS (Co-occurrence FTS)**에만 의존합니다. "'rtx'라는 단어가 나오면 GPU 관련 메모를 표시하라"와 같은 키워드 대응 테이블은 존재하지 않습니다.

대신, 입력 프롬프트를 분해하여 두 개 이상의 단어가 동일한 항목에 동시에 나타나는 경우에만 해당 항목을 노출합니다. make나 new와 같은 일반적인 단어는 단독으로는 트리거되지 않지만, 두 개 이상의 기술적 단어가 겹치면 매칭됩니다.

새로운 함정(trap) 카테고리가 추가되더라도, 단순히 entries/<slug>.md 파일 하나만 추가하면 됩니다. 코드나 키워드 테이블을 수정할 필요가 없습니다. 트리거가 스스로 확장됩니다.

지식은 git 기반의 markdown입니다

데이터는 표준 마크다운 (markdown) 파일로 구성됩니다. 검색을 위한 파생 인덱스로 SQLite가 사용되며, 삭제되더라도 다시 구축할 수 있습니다.

~/.caveat/own/
├── entries/
│   ├── rtx-5090-cuda-12-init-fail.md
...

이를 Obsidian 보관함(vault)으로 직접 열 수 있습니다. 팀과 공유하고 싶다면 단순히 git push를 하면 됩니다. 중앙 서버는 존재하지 않습니다.

공개 / 비공개 레이어 (Public / Private Layers)

항목(entries)에는 visibility 속성이 있습니다.

• 공개 (Public): 동일한 외부 도구 또는 사양(GPU, 빌드 환경, IDE, 버전 제약 조건)을 사용하는 사람이라면 누구나 마주칠 수 있는 함정
• 비공개 (Private): 코드만 읽어서는 재구성할 수 없는 프로젝트 특정적 컨텍스트(의도적인 비표준 동작, 업스트림 수정 대기 중인 워크아라운드, 커스텀 습관)

Claude가 가시성(visibility)을 자동으로 결정합니다. 불확실한 경우, 유출을 방지하기 위해 기본적으로 비공개(private)로 설정됩니다. 만약

caveat search "rtx"        # 기존 노트 검색
caveat serve               # 읽기 전용 포털 시작
caveat uninstall           # Claude 연동만 제거 (데이터는 유지됨)

중앙 데이터베이스(Central DB) 없음

이전 버전에는 공유 데이터베이스가 있었으며, caveat push를 사용하여 지식을 공동으로 배양한다는 개념이 있었습니다. 이 방식은 폐기되었습니다.

caveat community add https://github.com/acme-corp/caveats
caveat pull

자세한 배경에 대해서는 다른 기사에서 다루겠습니다.

요구 사항

• Node.js 22.5+
• Claude Code (훅(hooks) 지원 포함)
• pnpm (개발용)

상태

v0.11.1, 203개의 테스트 통과. 개인 및 소규모 팀의 사용 사례를 가정합니다.

Caveat — GitHub

MIT License. 버그 보고 및 PR(Pull Request)을 환영합니다.