30초 요약

• 하드 스탑(429 오류로 트래픽 중단)은 OpenAI API 계정에서 Settings → Organization limits → Enforce a hard limit 켜기로 즉시 적용된다. 알림(alert)만으로는 지출이 멈추지 않는다.
• Claude API(Console)는 워크스페이스별 월 지출 한도가 있고, Claude Code 구독(Pro/Max)은 claude.ai 설정에서 월 지출 한도를 설정한다. 사용량 크레딧을 켜지 않으면 한도가 무제한(Unlimited)으로 표시된다.
• Gemini CLI는 무료로 시작할 수 있지만 Google 계정 로그인 기준 1,000회/일, API 키 무료 티어는 250회/일·Flash 모델 전용이다. 무료 한도를 넘는 순간 과금 또는 차단이 발생한다.
• 예산 상한은 “실행 후 확인”이 아니라 “실행 전 설정”이 원칙이다. 실제 사건들(Codex 826개 하위 태스크 병렬 실행 등)은 상한 부재 상태에서 발생했다.
• 비용 절감은 상한 설정 이후에 적용한다: /clear, /compact(컨텍스트 관리), MAX_THINKING_TOKENS 환경변수(추론 예산 하한), CLI 도구 우선(MCP 서버 최소화) 순서가 공식 문서 권장 순서다.

코딩 에이전트 요금은 왜 순식간에 커지나

챗봇은 질문 1번에 응답 1번이다. 코딩 에이전트는 다르다. 목표를 달성하기 위해 계획을 세우고, 도구를 호출하고, 결과를 검토한 뒤 다시 판단하는 루프를 돈다. 이 과정이 몇 번 반복될지는 미리 알기 어렵고, 하위 에이전트가 파생되면 호출 수는 곱셈으로 늘어난다.

2026년 9월 26일 공개된 한 사례는 이 구조의 극단을 보여준다. VS Code에서 시작한 단순한 UI/UX 검토 요청이 Codex 계정에서 826개의 하위 태스크로 병렐 실행됐고, 요청자는 승인한 적 없는 약 7만 8천 달러 규모 사용량과 기록 삭제를 발견했다. OpenAI에 2주 넘게 티켓을 열어도 인간 응답을 받지 못했다는 게 이 사례의 두 번째 문제다. 이 사용자 계정에 하드 스탑 지출 한도가 설정돼 있었다면, 첫 429 오류 시점에 실행이 멈췄을 것이다.

같은 시기 국내에서도 유사한 이슈가 보도됐다. 국내 대학생 Claude 이용자의 카드에 약 25억 원, 이후 약 250억 원 결제 시도가 반복됐고, Anthropic은 “자동 충전 금액이 비정상적으로 높게 설정된 오류”라고 설명했지만 당사자는 자동 충전을 설정한 적이 없다고 밝혔다. 다행히 카드 한도로 실제 출금은 없었지만, 비정상 금액이 카드 승인 단계까지 전달됐다는 점이 사건의 무게를 달리 한다.

조직 차원에서는 Uber가 2026년 연간 AI 예산을 Claude Code 사용으로 4개월 만에 소진했다는 보도(Fortune, 2026년 5월), 이후 도구 사용량 상한을 두겠다는 후속 보도(Bloomberg, 2026년 6월)가 이어졌다. Anthropic 자체도 Claude Code의 엔터프라이즈 평균 비용으로 개발자당 활성 사용일 $13, 월 $150~250을 공식 제시하며 비용 관리 가이드를 운영 중이다. 즉 “에이전트가 비싸다”가 아니라 “경계 없는 자동 실행은 통제 불능이 된다”가 실제 문제다.

도구별 예산 상한 설정법 — 공식 문서 기준

OpenAI API / Codex: 하드 스탑이 핵심

OpenAI API 플랫폼은 두 가지 지출 통제를 제공한다.

설정 순서는 다음과 같다.

1. platform.openai.com/settings/organization/limits 접근 (또는 프로젝트별 Settings → Limits)
2. Spend → Edit spend limit 클릭
3. Monthly spend limit 금액 입력
4. Enforce a hard limit 토글 켜기 — 이 토글이 핵심이다. 꺼져 있으면 한도는 알림 역할만 한다.
5. 저장

주의할 점 두 가지. 첫째, 하드 한도 적용은 즉각적이지 않아서 기록된 지출이 설정 금액을 소액 초과할 수 있다(공식 문서 명시). 둘째, 한도 도달 시 오류 코드가 organization_spend_limit_exceeded(조직 전체) 또는 project_spend_limit_exceeded(프로젝트별)로 구분되므로, 에이전트의 재시도 로직이 이 오류를 “일시 오류”로 분류해 재시도 폭주를 일으키지 않도록 처리해야 한다.

Codex가 ChatGPT 구독 크레딧으로 과금되는 조직이라면 관리 콘솔의 사용량 한도(Usage limits)를 별도로 설정한다. 워크스페이스 기본값 → 그룹 기본값 → 사용자 예외 순서로 적용되며, 사용자 한도는 공유 크레딧 풀이 남아 있어도 개인 사용을 먼저 멈춘다. 토큰 기반 과금 조직은 워크스페이스 월 예산(USD)이 별도 상한이다.

Claude Code: 어디서 과금되는지 먼저 확인

Claude Code 비용은 인증 방식에 따라 상한 설정 위치가 완전히 달라진다.

개인 Pro/Max 사용자가 가장 흔히 빠뜨리는 단계가 사용량 크레딧(usage credits) 활성화다. 이 기능을 켜야 월 지출 한도 설정이 노출되고, /usage 화면의 사용량 크레딧 행에서 현재 월 지출을 한도 대비로 볼 수 있다. 켜져 있지 않으면 행이 Unlimited로 표시된다. Claude Code 내부에서 /usage를 실행하면 세션 토큰 사용량, 모델별 귀속, MCP 서버별 점유율, 동작 플래그(긴 컨텍스트·캐시 미스 등)를 로컬에서 바로 확인할 수 있다.

Console(API) 사용자는 워크스페이스 단위로 월 지출 한도와 요청/분, 입력·출력 토큰/분 제한을 함께 걸 수 있다. 주의점: 기본 워크스페이스에는 한도를 설정할 수 없고, 워크스페이스 한도는 조직 한도보다 낮게만 설정 가능하다.

Gemini CLI: 무료 한도의 정확한 경계

Gemini CLI는 인증 방식별로 일일 요청 한도가 갈린다.

핵심은 API 키 무료 티어는 Flash 모델만 호출 가능하고 250회/일이라는 점이다. 코딩 에이전트를 무료 API 키로 돌리면 하루 몇 시간 만에 한도에 닿고, 이후 429 오류 또는 과금 전환이 발생한다. 개인 Google 계정 로그인(1,000회/일)이 무료로 쓸 수 있는 상한이 가장 높다. 무료 한도를 넘어 장시간 작업이 필요하면 종량제 전환 또는 Google AI Pro 구독이 공식 권장 경로다.

예산이 이미 폭주했을 때: 확인 → 차단 → 원인 순서

요금 폭주를 발견한 직후의 대응은 다음 순서로 한다.

1. 현재 지출 확인: OpenAI는 platform.openai.com/settings/organization/usage, Claude는 /usage(Claude Code) 또는 Console 사용량 페이지에서 확인한다.
2. 즉시 차단: 하드 한도가 꺼져 있으면 즉시 설정(또는 프로젝트별 한도를 소액으로 조정)해 다음 요청부터 429로 멈춘다. 구독 크레딧 사용 중이면 사용량 크레딧을 끄거나 한도를 낮춘다.
3. 원인 파악: 재시도 루프(429를 일시 오류로 오분류한 에이전트), 하위 에이전트 폭주, MCP 서버 오버헤드, 컨텍스트 누적 중 무엇인지 /usage의 귀속 표와 동작 플래그로 식별한다.
4. 재발 방지: 429 *_spend_limit_exceeded 오류를 재시도 대상에서 제외하고, 장기 작업은 세션 예산 단위로 분할한다.

비용 절감은 상한 설정 이후에 — 공식 권장 순서

상한은 사고를 막는 장치고, 절감은 평소 운영 기술이다. Anthropic 공식 문서가 권장하는 절감 순서를 요약하면 다음과 같다.

• 컨텍스트 관리 먼저: 작업 전환 시 /clear, 장기 세션은 /compact(보존할 내용 지정 가능)로 컨텍스트를 줄인다. 오래된 컨텍스트는 이후 모든 요청에 토큰 낭비를 반복한다.
• 모델 선택: 단순 작업은 경량 모델로. 고정 추론 예산 모델은 MAX_THINKING_TOKENS=8000 같은 환경변수로 사고 예산을 낮출 수 있다(적응형 추론 모델은 예산 대신 노력 수준 사용).
• MCP 서버 최소화: gh, aws 등 CLI 도구가 MCP 서버보다 컨텍스트 효율적이다. /mcp로 사용하지 않는 서버를 비활성화한다.
• 세션 단위 위임: 문서 처리·테스트 실행 같은 무거운 작업은 하위 에이전트(subagent)로 위임해 메인 컨텍스트를 보호한다.

실전 체크리스트 — 오늘 10분에 끝내는 예산 설정

• ☐ OpenAI API: Organization limits에서 Enforce a hard limit 켰는가
• ☐ OpenAI API: 지출 알림을 하드 한도보다 낮은 임계(예: 80%)로 설정했는가
• ☐ Codex(구독 크레딧): 관리 콘솔 사용량 한도에서 워크스페이스 기본값·그룹·사용자 예외를 점검했는가
• ☐ Claude Code 구독: 사용량 크레딧을 켜고 월 지출 한도를 설정했는가 (Unlimited가 아니어야 한다)
• ☐ Claude API(Console): 워크스페이스 지출 한도 + 분당 요청/토큰 한도를 같이 걸었는가
• ☐ Gemini CLI: 무료 API 키(250회/일·Flash 전용)로 코딩 에이전트를 돌리지 않는가 — 개인 계정 로그인(1,000회/일)으로 시작하는가
• ☐ 에이전트 재시도 로직이 429 spend_limit_exceeded를 재시도 대상에서 제외하는가
• ☐ 장기 작업에 세션/태스크 단위 예산(Anthropic Managed Agents 세션 예산 등)을 적용했는가

자주 묻는 질문

하드 지출 한도를 걸면 진행 중인 작업은 어떻게 되나?

OpenAI는 “적용이 즉각적이지 않아 기록 지출이 설정 금액을 소액 초과할 수 있다”고 명시한다. 진행 중 요청은 마무리될 수 있고, 그만큼 한도를 살짝 넘을 수 있다. Anthropic Managed Agents의 세션 예산도 같은 구조다 — 상한 도달 시 새 모델 요청을 시작하지 않고 budget_reached로 일시 정지하며, 진행 중이던 요청은 끝까지 실행된다.

지출 알림만 설정해도 되나?

안 된다. OpenAI 공식 문서 기준 알림은 “트래픽을 중단하지 않는다”고 명시돼 있다. 알림은 하드 한도 이전의 경고용으로만 조합하라. 국내 250억 원 결제 시도 사례도 알림이 아니라 카드 한도가 유일한 방어선이었다.

무료 티어만 쓰면 폭주 위험이 없지 않나?

있다. Gemini API 무료 티어는 250회/일·Flash 전용이다. 코딩 에이전트의 루프 구조상 하루 한도는 몇 시간 만에 소진되고, 이후 429 차단으로 작업이 중단된다. “폭주 요금”은 아니지만 “작업 중단”이라는 다른 형태의 실패가 발생한다. 종량제 키를 무료 티어 키로 착각해 설정하면 과금 폭주로 이어진다.

Claude Code 구독(Pro/Max)은 정액제 아닌가?

정액제 안에서도 사용량 기반 제한이 있다. 사용량 크레딧을 켜면 정가 기준 토큰 비용이 측정되고 월 지출 한도를 초과하면 사용이 멈춘다. 구독 요금 외 추가 과금을 막으려면 이 한도를 명시적으로 설정해야 한다. Anthropic이 제시하는 엔터프라이즈 평균(활성일 $13, 월 $150~250)은 팀 규모 산정의 기준선이 된다.

세션 예산과 지출 한도는 어떻게 다르게 쓰나?

지출 한도는 계정/워크스페이스 단위의 월 상한이고, 세션 예산은 개별 장기 작업 단위의 상한이다. 장시간 실행되는 에이전트 작업이 많다면 세션 예산으로 작업별 손실 한계를 정하고, 계정 전체는 지출 한도로 최종 방어선을 만드는 이중 구조가 안전하다. Anthropic Managed Agents는 세션 생성 시 budget 필드로 공개 정가 기준 상한(max_list_cost)을 지정하며, 상한 도달 시 일시 정지 후 사람이 상한을 올리거나 제거하면 재개된다.

결론: 설정은 실행 전에, 점검은 주 단위로

에이전트 요금 폭주는 모델이 아니라 설정 부재에서 온다. OpenAI의 하드 한도 토글 하나, Claude의 월 지출 한도 하나, Gemini의 올바른 인증 방식 선택이면 개인 개발자도 오늘 10분 안에 방어선을 만들 수 있다. 이미 여러 사건이 보여줬듯, 사후 대응(지원 티켓, 카드사 문의)은 느리고 불확실하다. 지출이 멈추는 지점을 먼저 정하는 것 — 그것이 코딩 에이전트를 “맡겨도 되는 도구”로 만드는 유일한 방법이다.

참고자료

• Anthropic, “비용을 효과적으로 관리하기” (Claude Code 공식 문서, 2026-09-29 확인) — https://code.claude.com/docs/ko/costs
• OpenAI, “Spend limits” (API 공식 문서) — https://developers.openai.com/api/docs/guides/spend-limits
• OpenAI Help Center, “Manage usage limits and overages in ChatGPT Enterprise and Edu” — https://help.openai.com/en/articles/20001001
• Google, “Gemini CLI: Quotas and pricing” (공식 문서) — https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/resources/quota-and-pricing.md
• Anthropic, “Session budgets” (Managed Agents 공식 문서) — https://platform.claude.com/docs/en/managed-agents/budgets
• Anthropic, “Workspace limits” — https://platform.claude.com/docs/en/build-with-claude/workspaces
• Hacker News, “OpenAI Codex agents go rogue and consumes USD 78,000 without authorization” (2026-09-26) — https://news.ycombinator.com/item?id=49861047
• Fortune, “Uber blows through its AI budget in 1 quarter” (2026-05-26) — https://fortune.com/2026/05/26/uber-coo-ai-spending-tokens-claude-code/
• Bloomberg, “Uber Caps Usage of AI Tools Like Claude Code to Cut Costs” (2026-06-02) — https://www.bloomberg.com/news/articles/2026-06-02/uber-caps-usage-of-ai-tools-like-claude-code-to-cut-costs
• 디지털투데이, “클로드 코드 비용 ‘2배 폭등’…개인 개발자, 감당할 수 있나” — https://www.digitaltoday.co.kr/news/articleView.html?idxno=661191
• 내부 링크: 코딩 AI 구독, API로 바꾸면 진짜 쌀까? — 조합별 월 비용 손익분기 계산법 — https://blog.kwt.co.kr/coding-ai-subscription-vs-api-cost-breakeven-2026/
• 내부 링크: AI 코딩 에이전트 비교 — https://blog.kwt.co.kr/ai-%EC%BD%94%EB%94%A9-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-%EB%B9%84%EA%B5%90-claude-code-vs-codex-vs-gemini-cli-%EB%AD%90%EA%B0%80-%EB%8B%A4%EB%A5%B8%EA%B9%8C/

The post 코딩 에이전트 요금 폭주, 실행 전에 막는 법 — Claude Code·Codex·Gemini CLI 예산 설정 총정리 appeared first on .

핵심 요약

• 정체: 코딩 에이전트 세션 로그 색인·검색 로컬 메모리 (MCP 서버 + CLI, Go 단일 바이너리, MIT 라이선스)
• 해결 문제: “이 문제 예전에 해결했었는데” — Claude Code/Codex/Cursor 등 22종 에이전트의 과거 세션을 통합 검색하고 MCP recall 도구로 자동 회수
• 차별점: mem0·CLAUDE.md 같은 기존 메모리 도구는 ‘앞으로 쌓는’ 방식, deja-vu는 ‘이미 디스크에 있는’ 과거 기록부터 색인. 임베딩·LLM 없이 어휘 검색이라 비용 0원
• 검증: 2026-09-06 격리 HOME에서 v0.19.3 설치·색인·검색·비밀값 가림·제거 직접 확인 (sha256 체크섬 일치)
• 주의: 세션 로그 통독 도구이므로 출처·체크섬 확인 필수. macOS·Linux가 공식 지원, Windows는 Scoop·zip으로 설치

deja-vu가 필요한 순간

에이전트는 세션을 끝내면 대부분 잊는다. Claude Code는 ~/.claude/projects에 JSONL로 대화를 쌓고, Codex는 ~/.codex에, Cursor는 자체 스토어에 기록을 남긴다. 파일은 있는데 아무도 검색하지 않는다. 결과는 반복 노동이다.

deja-vu README의 표현이 정확하다. “모든 메모리 도구는 비어 있는 상태로 시작해 앞으로 기록한다. deja는 가득 찬 상태로 시작한다.” 설치 즉시 이미 디스크에 있는 수개월치 세션을 전부 색인하기 때문에, 별도 학습 없이 첫 순간부터 과거 기록을 검색할 수 있다.

실제로 이런 질문이 가능해진다:

"jwt refresh rotation 이전에 처리한 적 있지? 기억 확인해줘"

에이전트가 MCP recall 도구를 스스로 호출해 8개월 전 세션의 해결 기록을 가져온다. deja install --auto를 켜면 세션 시작·프롬프트마다·파일 편집 전·명령 실패 후 등 훅 시점에 관련 기억을 자동으로 주입하도록 설정할 수도 있다.

기본 정보와 검증 시점

stars 증가 속도는 이 스냅숏 체계로 관측 중이다. 이 도구는 2026-09-06 이번 실행에서 처음 관측해 779 stars를 기록했다. 1일·7일 증분은 아직 이력이 없어 unavailable로 표기하며, 총 stars에서 역산한 평균 속도(7월 14일 생성 이후 약 54일간 약 14.4 stars/일의 단순 평균, provisional)로만 참고한다. 확정 가능한 사실은 7월 중순 HN 131점 논의 이후 약 7주 만에 779 stars에 도달했고, 9월 4~5일에도 매일 기능 커밋·이슈 마감이 이뤄지고 있다는 유지보수 활동이다.

Claude Code·Codex·Hermes 설치 방법

공통 준비 (macOS · Linux)

curl -fsSL https://raw.githubusercontent.com/vshulcz/deja-vu/main/install.sh | sh
deja install --auto

설치 스크립트를 직접 열어 확인한 동작은 다음과 같다. (1) GitHub 최신 릴리스 태그 조회 (2) 플랫폼별 tar.gz와 checksums.txt 다운로드 (3) sha256 비교 (4) ~/.local/bin/deja 설치 (5) PATH 등록 안내. 셸 프로필 수정은 대화형으로 y/N을 물어보고, 파이프 설치 시에는 안내 문구만 출력한다. --yes 플래그가 없으면 아무것도 강제로 바꾸지 않는다.

deja install --auto가 실제 배선 단계다. 발견한 에이전트별 MCP 설정에 recall 도구를 등록하고, 세션 시작 회수가 가능한 에이전트에서는 훅도 켠다. 이 단계가 에이전트 설정 파일을 수정하는 유일한 지점이다.

Claude Code (플러그인 마켓플레이스 방식)

claude plugin marketplace add vshulcz/deja-vu
claude plugin install deja-vu@deja-vu

Codex / 기타 MCP 클라이언트

MCP 서버로 연결한다. deja install이 ~/.codex/config.toml에 자동 등록해 주며, 수동으로는 각 클라이언트의 MCP 설정에 deja 바이너리를 stdio 서버로 지정한다. 데스크톱 앱은 릴리스에 포함된 .mcpb 번들을 열면 된다.

Hermes

deja install이 Hermes 프로파일(~/.hermes/config.yaml)도 감지해 배선한다. 격리 검증에서 deja sources 출력에 hermes ~/.hermes/profiles 스토어가 확인됐다.

Windows

install.sh는 셸 스크립트라 지원하지 않는다. Scoop 메인 버킷(scoop install deja-vu) 또는 릴리스의 deja-vu_<버전>_windows_amd64.zip을 받아 %USERPROFILE%\.local\bin에 두고 PATH에 추가한다.

설치 시 바뀌는 경로·파일

제거·원상복구

deja uninstall --all     # 각 에이전트에서 MCP 배선 제거 시도
rm -rf ~/.cache/deja     # 색인 데이터 완전 삭제
rm ~/.local/bin/deja     # 바이너리 삭제

deja uninstall --all은 자신이 수정한 배선을 되돌리려 시도하고, 색인 캐시는 별도 삭제가 필요하다. 원본 세션 로그(~/.claude/projects 등)는 건드리지 않는다 — 삭제해도 에이전트 기록은 그대로다.

무엇을 검증했고 무엇을 못 했나

직접 검증한 것 (2026-09-06, 격리 HOME)

• v0.19.3 linux_arm64 바이너리 다운로드 후 sha256 체크섬 일치 확인 (checksums.txt의 855661d4…와 로컬 계산값 동일)
• 임시 HOME에서 deja --version → deja 0.19.3 출력
• 가상 Claude Code 세션 JSONL 3메시지 색인 → deja index 성공 (claude: 1 session, 3 messages)
• deja "jwt refresh" 검색 → 세션 매치·발췌 출력 정상
• 비밀값 가림(redaction) 확인: 세션에 포함된 AWS 예제 키(AKIA…7EXAMPLE, AWS 공식 문서 예시용)를 검색했더니 색인에 없음. 색인 시점에 가려진다는 README 설명과 일치
• deja doctor --offline, deja sources로 지원 harness 목록·MCP 배선 상태 진단 정상 동작
• deja uninstall --all + 캐시 삭제로 임시 환경 정리. 실제 사용자 HOME은 변경 없음 확인

검증하지 못한 것

• 실사용 환경에서의 자동 recall 품질 (수개월치 실세션 대상 성능)
• deja sync ssh 기계 간 동기화, deja handoff 에이전트 전환
• LongMemEval-S 85.3%·LoCoMo 69.6% 벤치마크 수치 재현 (README·공식 문서 발췌이며 제3자 검증 아님)
• Windows 설치 경로

벤치마크 수치는 제작자 자체 측정이고 재현 스크립트가 저장소에 포함되어 있지만 이번 실행에서 돌려보지는 못했다. ‘밀리초 조회’ 성능 주장도 공식 문서 기준으로만 인용한다.

권한·보안: 숨기지 않고 정리

세션 로그에는 평소 에이전트에게 보낸 코드·설명이 통째로 담긴다. “읽는 도구”가 생긴다는 점 자체가 보안 의사결정이다. 회사 정책상 민감한 프로젝트는 exclude 패턴으로 처음부터 배제하는 것이 안전하다.

기존 도구와 비교: mem0·CLAUDE.md 대신 쓸 것인가

비슷한 문제(에이전트 기억)를 푸는 대표 도구와의 관계를 정리한다.

분류: 보완재에 가깝다. mem0처럼 ‘앞으로 쌓는’ 시맨틱 메모리와 deja-vu의 ‘이미 있는 것을 뒤지는’ 어휘 검색은 해결 계층이 다르다. CLAUDE.md는 프로젝트 관례를 적는 자리지 과거 세션 검색 도구가 아니다. Claude Code를 쓰면서 “예전에 이거 고친 기록 어디 있지?”를 자주 겪는다면 deja-vu를 먼저 붙이고, 필요하면 시맨틱 메모리를 함께 쓰는 구성이 합리적이다.

추천하는 경우

• Claude Code·Codex·Cursor 등 둘 이상의 에이전트를 같이 쓰며 기록이 쌓여 있는 개발자
• 반복해서 비슷한 버그·설정 문제를 풀고, 과거 해결 이력을 못 찾아 답답한 팀·개인
• 클라우드·임베딩 비용 없이 로컬에서만 해결하려는 경우
• 세션 로그가 민감하지 않거나 exclude로 통제 가능한 환경

추천하지 않는 경우

• 세션 로그에 규정상 외부 도구가 색인하면 안 되는 코드·데이터가 섞여 있고 제외 통제가 어려운 환경
• Windows 전용 개발 환경에서 공식 install.sh 경로를 원하는 경우 (Scoop·zip 우회 필요)
• ‘요약된 지식’을 원하는 경우 — deja-vu는 원문 회수 도구지 요약 엔진이 아니다
• 벤치마크 수치를 근거로 도입을 결정해야 하는 조직 (제3자 검증 아직 부족)

설치 전 체크리스트

1. 기존 세션 로그 백업: cp -r ~/.claude ~/claude-backup (필요 시)
2. 공식 저장소·릴리스 확인: GitHub vshulcz/deja-vu Releases에서 최신 태그와 checksums.txt 확인
3. 격리 검증 먼저: 임시 HOME에서 색인·검색 동작 확인 후 실제 환경 적용
4. 민감 프로젝트 제외: ~/.config/deja/exclude에 경로 패턴 사전 등록
5. 배선 범위 확인: deja doctor로 어떤 에이전트 설정이 바뀌는지 먼저 조회
6. 제거 절차 숙지: deja uninstall --all + rm -rf ~/.cache/deja
7. 운영 환경(실제 프로젝트 설정)에는 바로 적용하지 않고 개인 환경에서 먼저 운영

안전한 복사·붙여넣기 프롬프트

이 글을 읽은 뒤 Claude Code나 Codex에 그대로 붙여넣어 설치를 요청할 수 있다. 아래 프롬프트는 버전 고정·체크섬 확인·백업·격리 검증·제거 절차를 포함한다.

deja-vu(v0.19.3, github.com/vshulcz/deja-vu, MIT) 설치를 도와줘.
다음 절차를 정확히 지켜줘:

1. 먼저 백업: ~/.claude 디렉터리와 각 에이전트 MCP 설정 파일을
   ~/deja-install-backup-$(date +%Y%m%d)/ 로 복사해 줘.
2. 버전 고정: v0.19.3 릴리스의 linux 바이너리와 checksums.txt를 내려받고
   sha256sum으로 체크섬이 일치하는지 확인한 뒤 진행해 줘.
   최신 버전이 v0.19.3보다 높으면 먼저 알려주고 기다려 줘.
3. 격리 검증 먼저: 임시 홈(예: /tmp/deja-test)에서 deja --version,
   deja sources, 가상 세션 1건 색인·검색이 동작하는지 확인해 줘.
   실제 홈의 에이전트 설정은 아직 건드리지 마.
4. 격리 검증 결과를 보여준 뒤, 내가 승인하면 실제 환경에
   ~/.local/bin에 설치하고 deja install --auto로 배선해 줘.
   어떤 설정 파일이 바뀌었는지 하나씩 나열해 줘.
5. 보안 확인: 색인 대상에서 제외할 민감 프로젝트가 있으면
   ~/.config/deja/exclude에 추가하고, redaction 동작을
   테스트 문장으로 확인해 줘.
6. 마지막에 제거 방법을 안내해 줘:
   deja uninstall --all && rm -rf ~/.cache/deja

절대 하지 말 것: API 키·비밀 입력 요청, 운영 프로젝트 설정 변경,
체크섬 불일치 파일 실행, 백업 없이 에이전트 설정 수정.

FAQ

deja-vu는 에이전트 성능 벤치마크를 올려주는 도구인가?

아니다. 모델 성능을 바꾸는 도구가 아니라, 과거 세션에서 관련 기록을 찾아 현재 세션에 주입하는 회수 계층이다. “같은 실수를 반복하지 않게” 돕는 도구로 이해해야 한다.

임베딩 없이 어떻게 검색이 되나?

어휘(lexical) 검색과 시간 가중을 조합한 로컬 색인을 쓴다. 다중 단어는 AND, 정확 매치가 없으면 어형 변형·유사 철자로 확장한다. README 기준 조회 중앙값 약 0.4ms이며 이는 공식 문서 발췌다.

세션 로그가 크면 느려지지 않나?

수 GB 히스토리에서 밀리초 단위 조회를 목표로 설계됐다고 공식 문서에 명시돼 있다. 다만 이 수치는 제작자 측정이므로 자기 환경 규모로 검증 후 도입을 권한다.

mem0를 이미 쓰고 있는데 갈아탈 필요가 있나?

갈아탈 이유가 아니다. 둘은 보완 관계다. 이미 쌓인 과거 세션을 활용하는 건 deja-vu, 앞으로의 대화에서 시맨틱하게 기억하는 건 mem0의 영역이다.

회사 노트북에 설치해도 되나?

세션 로그 통독이 본질인 도구이므로 보안 정책부터 확인한다. 민감 프로젝트는 ~/.config/deja/exclude로 제외하고, 확실하지 않으면 보안 담당자에게 먼저 확인한다.

설치했더니 에이전트가 느려진 것 같다

deja install --auto가 켠 세션 시작 훅은 수십 밀리초 수준이라고 문서에 명시돼 있다. 그래도 부담되면 자동 배선 없이 바이너리만 두고 필요할 때 deja "<query>"로 수동 검색하는 구성도 가능하다.

공식 참고자료

• 공식 저장소: https://github.com/vshulcz/deja-vu
• 공식 문서: https://vshulcz.github.io/deja-vu/
• 보안 모델 문서: https://github.com/vshulcz/deja-vu/blob/main/docs/SECURITY-MODEL.md
• 벤치마크 페이지: https://vshulcz.github.io/deja-vu/guide/benchmarks.html
• 릴리스 (checksums·SBOM 포함): https://github.com/vshulcz/deja-vu/releases
• Hacker News 논의 (2026-07-15): https://news.ycombinator.com/item?id=48923111

The post Claude Code가 지난달의 나를 기억하게 만들기: deja-vu 설치·보안 검증 appeared first on .