Claude Code 세션 메모리 유지하는 Recall 설정 방법

Claude Code 메모리를 위한 Recall의 기능

Recall은 각 프로젝트에 세션 간 유지되는 메모리를 제공하는 Claude Code 플러그인입니다. 이 플러그인은 프로젝트 내부의 .recall/ 폴더에 두 개의 마크다운 파일을 작성합니다. 하나는 작업 내용을 기록하는 추가 전용(append-only) 로그 파일이고, 다른 하나는 작업 중단 지점을 요약한 짧은 요약 파일입니다. 두 파일 모두 사용자의 로컬 머신에서 실행되는 Python 요약기에 의해 생성되므로, 메모리 사용 자체에는 API 토큰이 소모되지 않습니다.

이 플러그인이 해결하는 문제는 작지만 지속적입니다. 화요일에 VPS에서 세션을 종료했다고 가정해 보겠습니다. 수요일에 새로운 세션을 시작하면 Claude Code의 내장 자동 메모리가 세션 간 노트를 유지할 수는 있지만, 화요일의 대화 내용을 자동으로 불러오지는 않습니다. 만약 해당 노트에 작업 중단 지점이 기록되어 있지 않다면, 사용자는 프로젝트 상황을 직접 다시 설명하거나 모델이 저장소의 절반을 다시 읽게 하여 상황을 파악하도록 해야 합니다. 두 방법 모두 토큰을 소모하며, 특히 후자는 매우 많은 토큰을 소비합니다.

2026년 7월 18일에 출시된 Recall 버전 0.4.0은 2026년 10월 기준으로도 최신 릴리스이며, 해당 프로젝트는 MIT 라이선스를 따릅니다. 이 플러그인은 네트워크 호출을 전혀 수행하지 않습니다.

VPS에서 필요한 사항

Recall의 캡처 훅은 플러그인과 함께 제공되는 Python 스크립트입니다. 타사 의존성이 없으므로 유일한 실제 요구 사항은 인터프리터뿐입니다.

python3 -V

Ubuntu 24.04는 Python 3.12.3에 해당합니다. Recall은 Python 3.9 이상 버전을 지원합니다. 최소화된 컨테이너 이미지에는 인터프리터가 포함되지 않은 경우가 있으며, 이 경우 셸은 python3: command not found을 반환합니다. 진행하기 전에 인터프리터를 설치하십시오.

sudo apt update && sudo apt install -y python3

NumPy는 요약기(summarizer)의 한 단계를 가속하기 위한 선택 사항입니다. 반드시 필요한 것은 아닙니다.

python3 -c "import numpy"

ModuleNotFoundError: No module named 'numpy'는 이 경우 허용되는 답변입니다. 요약기에는 순수 Python 경로가 포함되어 있으며, 프로젝트의 테스트 스위트는 두 경로 모두 동일한 문장을 선택하는지 확인합니다.

서버 작업은 며칠에 걸쳐 짧은 방문 형태로 이루어지므로, 노트북보다 서버에서 세션 메모리가 더 중요합니다. 이미 VPS의 tmux에서 실행 중인 Claude Code가 있다면, Recall은 어제의 세션을 오늘로 이어주는 역할을 합니다.

플러그인 마켓플레이스에서 Recall 설치하기

Claude Code 세션 내에서 다음 두 명령어를 입력합니다.

/plugin marketplace add raiyanyahya/recall
/plugin install recall@recall

두 번째 명령어는 plugin@marketplace을 읽습니다. 여기서 두 이름 모두 recall로 표기되어 있는데, 이는 복사-붙여넣기 실수가 아니며 의도된 것입니다.

플러그인 자체 명령어를 실행하여 설치를 확인합니다.

/recall:show

/recall:show는 현재 요약 정보를 출력합니다. 새 프로젝트에서는 아직 출력할 내용이 없으므로, 이 확인 과정의 목적은 해당 명령어가 존재하는지 확인하는 것입니다. Claude Code가 /recall:show을 인식하지 못한다면 플러그인이 로드되지 않은 것이며, 어떤 훅(hook)도 실행되지 않습니다.

체크아웃한 소스 코드에서 직접 실행하려면, 저장소를 복제하고 먼저 유효성을 검사합니다.

git clone https://github.com/raiyanyahya/recall ~/recall
cd ~/recall && claude plugin validate .

claude plugin validate .는 .claude-plugin/의 매니페스트를 읽고 플러그인이 올바르게 구성되었는지 보고합니다. 그런 다음 프로젝트 디렉터리에서 claude --plugin-dir ~/recall을 사용하여 Claude Code를 시작합니다.

훅이 기록하는 내용과 시점

Recall은 세 가지 Claude Code 훅을 등록합니다. 각 훅은 플러그인 디렉터리에 있는 Python 스크립트를 실행합니다.

• SessionStart는 시작, 재개, 초기화 시점에 실행됩니다. 이 훅은 context.md을 호출하여 세션이 열릴 때 요약 내용을 화면에 표시합니다.
• Stop은 Claude가 응답을 마칠 때마다 실행됩니다. 이 훅은 해당 턴의 내용을 로그에 추가합니다.
• SessionEnd는 세션이 종료될 때 실행되며, 요약을 재생성할 수 있습니다.

이 과정에서 .recall/ 내부에 두 개의 파일이 생성됩니다.

• history.md는 추가 전용 기록으로, 프롬프트, 응답, 수정된 파일, 실행된 명령을 포함합니다.
• context.md는 생성된 요약본으로, 목표, 요약, 다음 단계, 수정된 파일, 실행된 명령, git 컨텍스트를 포함합니다.

실제 세션을 한 번 진행한 뒤 해당 디렉터리를 확인하십시오.

ls -la .recall/

캡처가 활성화되어 있고 일시 정지 마커가 없으며 트랜스크립트가 존재한다면, history.md에 내용이 채워진 것을 확인할 수 있습니다. context.md이 전혀 보이지 않을 수도 있는데, 이는 오류가 아니라 기본 동작 방식입니다. auto_save_context은 기본적으로 off 상태이므로, 요약은 사용자가 직접 요청할 때만 작성됩니다.

/recall:save

위 명령은 로컬 요약기를 실행하여 history.md을 분석하고 context.md을 다시 작성합니다. 사용된 알고리즘은 TF-IDF(단어 빈도-역문서 빈도) 점수를 TextRank 문장 순위 알고리즘에 적용하는 방식입니다. 이 과정은 결정론적이고 추출적이며, 로그에 이미 존재하는 문장을 선택합니다. 모델을 호출하지 않으므로 비용이 발생하지 않으며 오프라인 상태에서도 작동합니다.

프로젝트별 Recall 구성

구성은 프로젝트 루트의 recall.config.json 파일에 저장됩니다. 다음은 기본으로 제공되는 설정입니다.

{
  "output_dir": ".recall",
  "capture_history": true,
  "summary_sentences": 8,
  "redact": true,
  "include_git": true,
  "max_input_chars": 200000
}

• output_dir은 두 파일이 위치할 경로를 설정합니다. 프로젝트 내부에 유지하십시오.
• capture_history는 history.md 로그의 활성화 여부를 결정합니다.
• auto_save_context은 off 또는 on_end 값을 허용하며, 기본값은 off입니다.
• summary_sentences은 context.md에 남길 문장 수를 결정합니다. 이 값을 높이면 요약이 길어지지만 세션 시작 시 로드 시간이 약간 증가합니다.
• redact는 디스크에 기록하기 전에 일반적인 비밀 정보 패턴을 제거합니다.
• include_git은 현재 diff 통계와 최근 커밋 내용을 요약에 추가합니다.
• max_input_chars는 요약기가 한 번에 읽을 history.md의 최대 범위를 제한합니다.

VPS에서 운영하는 프로젝트의 경우, 터미널이 종료될 때 세션이 끊기는 경우가 많으므로 자동 저장 기능을 사용하는 것이 유용합니다.

{
  "auto_save_context": "on_end",
  "summary_sentences": 12
}

설정을 변경하지 않고 일시적으로 캡처를 중단하려면 일시 정지 마커를 생성하십시오. 캡처를 다시 시작하려면 해당 마커를 삭제하십시오.

touch .recall/.capture-paused

레다크션(redaction)은 필터일 뿐 완벽한 보장이 아니므로, 운영 환경의 자격 증명을 다루는 세션 전에는 반드시 이 작업을 수행하십시오. AI 에이전트가 비밀 정보를 보지 못하게 하기와 같은 맥락에서, 가장 안전한 비밀 정보는 에이전트가 절대 보지 못하게 하는 것입니다.

Recall은 토큰을 얼마나 절약합니까?

이는 대체 수단이 무엇이었는지에 따라 다릅니다. 세션 시작 시 요약본을 불러오는 것은 비용이 저렴합니다. 요약본이 대체하는 작업은 비용이 많이 들 수 있는데, 프로젝트에 대한 기억이 없는 모델은 파일을 읽어 프로젝트를 다시 파악해야 하기 때문입니다.

[
  {
    "label": "Recall context.md",
    "char_count": "4,800",
    "est_tokens": "1,200"
  },
  {
    "label": "Hand-written CLAUDE.md",
    "char_count": "3,200",
    "est_tokens": "800"
  },
  {
    "label": "Re-reading the repo",
    "char_count": "120,000",
    "est_tokens": "30,000"
  },
  {
    "label": "Full transcript replay",
    "char_count": "340,000",
    "est_tokens": "85,000"
  }
]

다음은 중간 규모 프로젝트의 일반적인 수치이며, 귀하의 프로젝트를 측정한 값은 아닙니다. Recall 요약본은 대략 1,200 토큰으로 로드되며, 이는 프로젝트에서 발표한 재개(resume)당 1,000~2,000 토큰이라는 수치와 일치합니다. 이전 대화 기록 전체를 다시 재생하면 85,000 토큰 범위의 전체 대화가 다시 로드됩니다. 모델이 파일을 읽어 프로젝트를 다시 파악하게 두는 방식은 그 사이인 30,000 토큰 근처이며, 이 수치는 저장소 규모에 따라 증가합니다. CLAUDE.md 행은 비교를 위한 기준점입니다. 이 행은 짧고 정적이기 때문에 비용이 저렴하며, 어젯밤에 무슨 일이 있었는지보다는 귀하의 기본 규칙을 모델에 전달합니다.

귀하의 수치를 직접 측정하십시오. 토큰 하나는 영어 산문 기준으로 대략 4글자이며, 코드의 경우 그보다 약간 적습니다. 동일한 VPS에서 로컬 모델에 요약본을 입력하는 경우, Ollama의 기본 컨텍스트 길이는 가용 VRAM에 따라 달라지므로 재개 기능을 신뢰하기 전에 요약본이 들어가는 윈도우 크기를 확인하십시오.

wc -c .recall/context.md .recall/history.md
echo $(( $(wc -c < .recall/context.md) / 4 ))

세션 내부에서 /context은 현재 컨텍스트 윈도우에 무엇이 로드되어 있는지 보여주며, /cost은 세션 총계를 보고합니다. 한 세션은 차갑게(cold) 시작하고, 다음 세션은 요약본을 적용하여 시작한 뒤 비교해 보십시오. 세션 토큰이 실제로 어디에 사용되는지에 대한 전체적인 내용은 Claude Code의 토큰 사용 내역에서 상세히 확인할 수 있습니다.

이 주장을 객관적으로 유지하기 위한 주의 사항이 하나 있습니다. 요약본은 모든 세션 시작 시 로드되므로, 전혀 사용하지 않는 요약본은 절약이 아니라 작은 비용 부담이 됩니다. 세션이 길게 유지되지 않는다면 summary_sentences를 기본값 근처로 유지하십시오. 더 조용한 세션은 장부의 반대편에서 도움이 됩니다. 작동하는 최소한의 변경 사항을 지향하는 에이전트는 요약기가 순위를 매겨야 할 로그를 더 짧게 남기기 때문입니다.

세션 없이 요약본 재생성하기

저장소를 복제했다면 요약 도구(summarizer)를 위한 별도의 명령줄 진입점이 존재합니다. 이는 터미널 세션이 종료된 VPS 환경에서 요약본을 생성해야 할 때 유용합니다.

python3 ~/recall/scripts/make_context.py --help

도움말 출력에는 사용 가능한 플래그가 나열되어 있습니다. 프로젝트 루트를 지정하는 --cwd, 명시적인 트랜스크립트 파일을 지정하는 --transcript, 출력을 억제하는 --quiet, 그리고 claude와 opencode 중 하나를 선택하는 --harness이 있습니다. 다음과 같이 프로젝트 경로를 지정하십시오.

python3 ~/recall/scripts/make_context.py --cwd /srv/projects/api

이 도구는 세션 트랜스크립트와 history.md를 읽은 뒤, 전달한 디렉터리 아래에 context.md를 작성합니다. 마켓플레이스를 통해 설치했다면 플러그인은 Claude Code가 관리하는 디렉터리에 위치하며, 동일한 작업을 수행하는 지원 방식은 /recall:save입니다.

기록이 남지 않는 이유

전체 세션 이후에도 .recall/ 디렉터리가 생성되지 않음. 캡처가 비활성화되었는지, 출력 디렉터리가 다른 곳으로 설정되었는지, 혹은 훅이 실행되기 전에 트랜스크립트가 발견되지 않았는지 확인하십시오. /recall:show을 입력하여 플러그인이 로드되었는지 확인한 다음, python3 -V를 실행하십시오. 훅 명령은 먼저 python3을 시도하고 그다음 python를 시도하므로, 두 도구가 모두 없는 환경에서는 stderr와 함께 종료 상태 코드 127을 반환하며 실패합니다. Claude Code는 stderr의 첫 번째 줄을 포함한 비차단 훅 오류 알림을 표시합니다.

history.md는 커지지만 context.md은 전혀 변하지 않음. auto_save_context은 기본적으로 off로 설정되어 있습니다. /recall:save를 실행하거나, 해당 키를 on_end으로 설정하여 SessionEnd 훅이 이를 처리하도록 하십시오.

파일이 잘못된 프로젝트 아래에 생성됨. Recall은 Claude Code를 시작한 디렉터리를 기준으로 파일을 작성하므로, 홈 디렉터리에서 세션을 시작하면 메모리 파일도 그곳에 저장됩니다. 프로젝트 루트에서 시작하고, ls -la .recall/을 사용하여 파일이 실제로 어디에 저장되었는지 확인하십시오.

캡처가 중단되었으나 경고가 표시되지 않음. ls -a .recall/를 사용하여 일시 중지 마커가 있는지 확인하십시오. 지난주에 생성한 .capture-paused 파일이 여전히 작동 중일 수 있습니다.

긴 세션 이후 요약 내용이 부족함. max_input_chars는 요약기 입력 크기를 200000자로 제한하므로, 매우 긴 로그는 잘릴 수 있습니다. 로그를 순환(rotate)시키십시오.

mv .recall/history.md .recall/history-2026-07-30.md

이후 짧은 세션을 한 번 실행하고 ls -la .recall/를 다시 확인하여 새로운 history.md이 생성되었는지 확인하십시오.

Recall의 한계

Recall은 로그와 요약기로 구성되어 있으며, 이 도구가 다루지 않는 범위를 명확히 이해하는 것이 중요합니다.

요약기는 추출 방식입니다. TextRank는 이미 history.md에 존재하는 문장을 선택하므로, 결정의 옳고 그름을 판단하지 않습니다. 화요일에 기록된 잘못된 방향 설정은 수요일의 올바른 결정과 똑같이 읽힙니다. 중요한 사안이라면 context.md을 직접 읽고 수정하십시오. 이는 마크다운 파일이므로 언제든지 편집할 수 있습니다.

검색 기능은 없습니다. 프로젝트당 하나의 현재 요약과 하나의 누적 로그만 제공하며, 여러 프로젝트를 아우르는 쿼리 가능한 메모리는 지원하지 않습니다. 3주 전에 데이터베이스에 대해 어떤 결정을 내렸는지 확인하려면 history.md에서 grep을 사용해야 합니다. 실시간 협업 기능도 제공하지 않습니다. 동일한 프로젝트의 두 세션은 로그 파일을 공유하지만, Recall은 새로운 로그 항목을 다른 세션의 컨텍스트로 푸시하지 않습니다. 따라서 한 세션이 다른 세션의 작업 내용을 알아야 할 경우, 실행 중에 세션 간에 직접 텍스트를 전달해야 합니다.

세션 내부의 문제는 해결하지 않습니다. 세션 도중 컨텍스트 윈도우가 가득 차는 것은 다른 해결책이 필요한 별개의 문제이며, 단일 세션 내에서 컨텍스트 윈도우를 관리하는 방법은 이 가이드의 보완 자료입니다.

요약은 설계상 신뢰할 수 없는 입력으로 간주됩니다. context.md은 펜스(fenced) 처리 및 라벨링되어 주입되며, Claude는 이를 신뢰하기 전에 사용자에게 확인을 요청합니다. 이러한 설계는 커밋된 .recall/ 디렉터리가 커밋 권한이 있는 사람이라면 누구나 에이전트가 읽을 텍스트를 작성할 수 있는 공간이기 때문에 존재합니다. 에이전트가 읽은 내용에 대해 얼마나 자주 확인을 요청할지는 세션 시작 시 설정된 권한 모드에 따라 결정됩니다. Claude Code v2.1.283 이상 버전에서는 모든 플랜과 제공자의 대화형 터미널 및 VS Code 세션에서 자동 모드가 기본 시작 모드로 설정되어 있으므로, 사용자가 아닌 분류기가 대부분의 작업을 검토합니다. HIPAA 구성이 적용된 조직은 여전히 수동 모드로 시작합니다. .recall/를 개인용으로 사용할지 공유용으로 사용할지 결정하십시오. 개인 메모리로 사용하려면 .gitignore에 추가하고, 공유하려면 커밋하여 다른 기여물처럼 검토하십시오. 에이전트를 무인으로 실행하는 경우 Claude Code를 VPS에서 안전하게 실행하는 방법을 참조하여 더 넓은 범위의 보안을 확인하십시오.

민감 정보 삭제(Redaction)는 최선의 노력에 기반합니다. API 키, 토큰, PEM 블록 및 .env 할당과 같은 일반적인 패턴을 대상으로 합니다. 커밋하기 전에 .recall/를 확인하십시오.

버전 번호는 제품의 성숙도를 정직하게 나타냅니다. 2026년 10월 기준 최신 릴리스인 0.4.0 버전에서는 설정 키와 파일 구조가 릴리스마다 변경될 수 있으므로, 의존성이 있는 설정을 업그레이드하기 전에 변경 로그를 확인하십시오.

FAQ

Recall이 내 코드나 대화 기록을 외부로 전송합니까?

아니요. 캡처 훅과 요약기는 사용자의 로컬 머신에서 실행되는 Python 스크립트입니다. 플러그인에는 API 키가 포함되어 있지 않으며, 네트워크 호출도 수행하지 않습니다. 요약 과정에서는 모델 대신 TF-IDF와 TextRank를 사용하므로 비용이 발생하지 않으며 오프라인 상태에서도 작동합니다. 대신 요약 방식은 추출형입니다. 즉, 새로운 문장을 생성하는 것이 아니라 로그에서 기존 문장을 선택합니다.

왜 .recall/context.md이 누락되었거나 최신 상태가 아닙니까?

auto_save_context의 기본값은 off이므로, 요약은 /recall:save를 실행할 때만 다시 생성됩니다. 각 세션이 종료될 때마다 요약이 다시 작성되도록 하려면 recall.config.json에서 "auto_save_context": "on_end"을 설정하십시오. 만약 history.md까지 누락되었다면 capture_history, .capture-paused 마커, 그리고 세션 기록이 존재하는지 확인하십시오. 훅이 실행되는 동안에는 해당 경우에 기록 작성을 건너뜁니다. /recall:show로 플러그인이 로드되었는지 확인한 다음, 훅이 Python 스크립트이므로 해당 장비에서 python3 -V이 응답하는지 확인하십시오.

Recall은 세션당 얼마나 절약합니까?

요약을 로드하는 데는 약 1,200 토큰이 소요됩니다. 반면, 저장소를 다시 읽어 현재 상태를 파악해야 하는 모델은 일반적으로 30,000 토큰이 소요됩니다. 이는 일반적인 수치입니다. 세션 내에서 wc -c .recall/context.md과 /context 명령을 사용하여 콜드 스타트와 요약본을 통한 재개 시의 토큰 사용량을 직접 측정해 보십시오.

여전히 CLAUDE.md 파일이 필요합니까?

네, 두 파일은 서로 다른 역할을 합니다. CLAUDE.md는 사용자가 의도적으로 작성하는 상시 규칙과 빌드 명령입니다. 반면 context.md은 지난 세션에서 실제로 발생한 일을 기반으로 생성되므로, 미처 기록해두지 못한 미완성 마이그레이션 작업 등을 담고 있습니다. 두 파일 모두 유지하십시오.

하나의 VPS에서 여러 프로젝트의 메모리를 관리할 수 있습니까?

네. Recall은 각 프로젝트 디렉터리 내부의 .recall/에 메모리를 보관합니다. 따라서 같은 서버에 있는 두 프로젝트는 각각 별도의 로그와 요약을 유지합니다. 파일은 사용자 계정이 아닌 작업 디렉터리를 따라가므로, 항상 프로젝트 루트에서 Claude Code를 시작하십시오.