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

Claude Code 메모리를 위한 Recall의 역할

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

이 플러그인이 해결하는 문제는 작지만 지속적입니다. 화요일에 VPS에서 세션을 종료하면, 수요일의 Claude Code는 화요일의 작업 내용을 전혀 알지 못합니다. 사용자가 직접 프로젝트를 다시 설명하거나, 모델이 저장소의 절반을 다시 읽어 상황을 파악하게 해야 합니다. 두 방식 모두 토큰 비용이 발생하며, 특히 후자는 매우 많은 토큰을 소모합니다.

Recall 버전 0.4.0은 2026년 7월 기준 최신 버전이며, 프로젝트는 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은 3개의 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(term frequency, inverse document frequency) 점수를 기반으로 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 행은 비교를 위한 기준점입니다. 이 행은 짧고 정적이라 비용이 저렴하며, 어젯밤에 무슨 일이 있었는지보다 사용자의 상시 규칙을 모델에 전달합니다.

직접 수치를 측정해 보십시오. 1토큰은 영어 산문 기준 약 4글자이며, 코드의 경우 그보다 조금 적습니다. 만약 동일한 VPS에서 로컬 모델에 요약본을 입력한다면, 재개 기능을 신뢰하기 전에 모델의 컨텍스트 윈도우를 확인하십시오. Ollama는 긴 프롬프트를 작은 기본 컨텍스트 길이에서 잘라내며 끝부분이 삭제되었다고 알려주지 않기 때문입니다.

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

세션 내부에서 /context는 현재 컨텍스트 윈도우에 무엇이 로드되어 있는지 보여주며, /cost은 세션 총계를 보고합니다. 한 세션은 처음부터 시작하고, 다음 세션은 요약본을 적용하여 시작한 뒤 비교해 보십시오. 세션 토큰이 실제로 어디에 사용되는지에 대한 전체적인 내용은 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을 시도하므로, 두 경로가 모두 없는 환경에서는 아무것도 기록되지 않으며 별도의 경고도 발생하지 않습니다.

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을 사용해야 합니다. 또한 세션 간 데이터 공유도 지원하지 않습니다. 동일한 VPS에서 두 세션을 동시에 열어도 서로의 로그를 볼 수 없습니다. 따라서 한 세션이 다른 세션의 작업 내용을 알아야 할 경우, 실행 중에 세션 간 직접 텍스트를 전달해야 합니다.

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

요약본은 설계상 신뢰할 수 없는 입력으로 간주됩니다. context.md은 펜싱 처리 및 라벨링되어 주입되며, Claude는 이를 신뢰하기 전에 사용자에게 확인을 요청합니다. 이러한 설계는 커밋된 .recall/ 디렉터리에 커밋 권한이 있는 누구나 에이전트가 읽을 텍스트를 작성할 수 있기 때문에 도입되었습니다. 에이전트가 읽은 내용에 대해 얼마나 자주 확인을 요청할지는 세션 시작 시 설정하는 권한 모드에 따라 결정되며, 2026년 8월 14일부터는 auto 모드가 Claude Code의 기본값이 됩니다. .recall/를 개인용으로 사용할지 공유용으로 사용할지 결정하십시오. 개인 메모리로 사용하려면 .gitignore에 추가하고, 공유하려면 커밋하여 다른 기여물처럼 검토하십시오. 에이전트를 무인으로 실행하는 경우 VPS에서 Claude Code를 안전하게 실행하는 방법을 참조하여 더 넓은 범위의 보안을 고려하십시오.

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

버전 번호는 소프트웨어의 성숙도를 정직하게 반영합니다. 2026년 7월 기준 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까지 누락되었다면 훅이 전혀 실행되지 않는 상태입니다. /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를 시작하십시오.