VPS에서 Claude Code에 Recall 메모리 설정하기

Claude Code 메모리에서 Recall이 수행하는 작업

Recall은 각 프로젝트가 세션 간에 메모리를 유지하도록 하는 Claude Code 플러그인입니다. Recall은 프로젝트 내부의 .recall/ 폴더에 두 개의 markdown 파일을 기록합니다. 하나는 발생한 일을 추가만 하는 로그이고, 다른 하나는 마지막으로 작업한 위치를 간단히 요약한 파일입니다. 두 파일 모두 작업 중인 컴퓨터에서 로컬 Python 요약기가 생성합니다. 따라서 메모리 자체에는 API 토큰이 전혀 들지 않습니다.

Recall은 작지만 지속적인 문제를 해결합니다. 화요일에 VPS에서 세션을 종료하면, 수요일의 Claude Code는 화요일에 수행한 작업을 전혀 알지 못합니다. 프로젝트를 직접 다시 설명하거나, 모델이 저장소의 절반을 다시 읽고 상황을 파악하도록 해야 합니다. 두 방법 모두 토큰이 필요하며, 후자는 많은 토큰이 필요합니다.

2026년 7월 기준으로 Recall의 현재 버전은 0.4.0이며, 프로젝트는 MIT 라이선스를 따릅니다. Recall은 플러그인입니다. Recall은 네트워크 호출을 수행하지 않습니다.

VPS에 필요한 항목

Recall의 캡처 hook은 plugin과 함께 릴리스되는 Python script입니다. 서드파티 의존성은 없으므로 실제로 필요한 것은 interpreter뿐입니다.

python3 -V

Ubuntu 24.04에서는 Python 3.12.3이 출력됩니다. Recall은 Python 3.9 이상을 지원합니다. 최소 container image에는 interpreter가 전혀 없을 수 있으며, 이 경우 shell은 python3: command not found을 출력합니다. 계속하기 전에 interpreter를 설치합니다.

sudo apt update && sudo apt install -y python3

NumPy는 summarizer의 한 단계에서 사용하는 선택적 가속기입니다. 설치하지 않아도 됩니다.

python3 -c "import numpy"

ModuleNotFoundError: No module named 'numpy'도 여기서는 허용되는 응답입니다. summarizer에는 pure-Python 경로가 있으며, 프로젝트의 test suite는 두 경로가 동일한 문장을 선택하는지 확인합니다.

서버에서는 노트북보다 session memory가 더 중요합니다. 서버 작업은 며칠에 걸쳐 짧은 방문으로 진행되기 때문입니다. 이미 VPS의 tmux에서 Claude Code 실행을 사용하고 있다면, Recall은 어제의 session을 오늘로 전달하는 구성 요소입니다.

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

Claude Code 세션 안에서 다음 2개 명령을 입력합니다.

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

두 번째 명령은 plugin@marketplace을 읽습니다. 두 이름은 여기에서 모두 recall이며, 복사하여 붙여넣는 과정에서 생긴 오류가 아닙니다.

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

/recall:show

/recall:show은 현재 요약을 출력합니다. 새로 만든 프로젝트에는 아직 출력할 내용이 없으므로, 실제로 확인하는 것은 해당 명령이 존재하는지 여부입니다. Claude Code가 /recall:show을 인식하지 못하면 플러그인이 로드되지 않은 것이며, 어떤 hook도 실행되지 않습니다.

checkout에서 실행하려면 먼저 repository를 clone하고 유효성을 확인합니다.

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

claude plugin validate .은 .claude-plugin/의 manifest를 읽고 플러그인이 올바른 형식인지 보고합니다. 그런 다음 claude --plugin-dir ~/recall을 사용하여 프로젝트 디렉터리에서 Claude Code를 시작합니다.

hook이 기록하는 내용과 실행 시점

Recall은 3개의 Claude Code hook을 등록합니다. 각 hook은 plugin 디렉터리의 Python 스크립트를 실행합니다.

• SessionStart은 시작, 재개 및 clear 시 실행됩니다. context.md을 표시하므로 세션이 요약을 확인할 수 있는 상태로 열립니다.
• Stop은 Claude가 응답을 완료할 때마다 실행됩니다. 해당 대화 차례를 로그에 추가합니다.
• SessionEnd은 세션이 종료될 때 실행되며 요약을 다시 생성할 수 있습니다.

이 과정에서 2개의 파일이 생성되며, 두 파일 모두 .recall/ 안에 저장됩니다.

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

실제 세션을 1번 실행한 후 디렉터리를 확인합니다.

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

운영 환경 자격 증명을 처리하는 세션을 시작하기 전에 이 작업을 수행합니다. 삭제 처리는 필터일 뿐이며 완전한 보장이 아니기 때문입니다. 일반적으로 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 토큰으로 로드됩니다. 이는 프로젝트에 게시된 재개 비용인 1천~2천 토큰과 비슷합니다. 이전 transcript 전체를 재생하면 전체 대화가 다시 로드되며, 비용은 85,000 토큰 수준입니다. 모델이 파일을 읽으면서 프로젝트 내용을 다시 파악하도록 하면 두 수치의 중간인 약 30,000 토큰이 필요합니다. 이 수치는 repository의 크기가 커질수록 증가합니다. CLAUDE.md 행은 규모를 비교하기 위한 것입니다. 이 행은 짧고 정적이므로 비용이 더 낮으며, 전날 발생한 일이 아니라 모델이 따라야 할 지속적인 규칙을 알려 줍니다.

직접 수치를 측정하십시오. 토큰 1개는 일반적으로 영어 문장 약 4자에 해당하며, 코드에서는 이보다 조금 적습니다.

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

세션 내에서 /context는 현재 context window에 로드된 내용을 보여 주고, /cost는 세션 누적량을 보고합니다. 첫 번째 세션은 아무것도 로드하지 않은 상태로 시작하고, 다음 세션은 요약이 있는 상태로 시작한 뒤 결과를 비교하십시오. 세션의 토큰이 실제로 어디에 사용되는지 전체적으로 확인하려면 Claude Code가 토큰을 사용하는 방식에서 세부 내역을 확인할 수 있습니다.

이 주장을 정확하게 이해하려면 한 가지 주의할 점이 있습니다. 요약은 세션이 시작될 때마다 로드되므로, 사용하지 않는 요약은 절약이 아니라 소규모 비용이 됩니다. 세션이 오래 실행되는 경우가 아니라면 summary_sentences는 기본값에 가깝게 유지하십시오.

세션 없이 요약 다시 생성

저장소를 clone한 경우 summarizer에는 자체 command line 진입점이 있습니다. 터미널과 함께 세션이 종료되었지만 요약을 생성해야 하는 VPS에서 유용합니다.

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

도움말 출력에는 지원되는 flag가 나열됩니다. --cwd은 project root를 지정하고, --transcript는 transcript 파일을 직접 지정하며, --quiet은 출력을 억제하고, --harness은 claude와 opencode 중 하나를 선택합니다. 이를 project에 지정합니다.

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

summarizer는 세션 transcript와 history.md을 읽은 다음, 전달한 디렉터리 아래에 context.md을 기록합니다. marketplace를 통해 설치한 경우 plugin은 Claude Code가 관리하는 디렉터리에 있으며, /recall:save이 같은 작업을 수행하는 지원되는 방법입니다.

아무것도 기록되지 않는 이유

전체 세션이 끝난 후에도 .recall/ 디렉터리가 없습니다. hook이 실행되지 않은 것입니다. /recall:show을 입력하여 plugin이 로드되었는지 확인한 다음 python3 -V을 실행합니다. hook command는 먼저 python3을 시도하고, 다음으로 python을 시도합니다. 두 항목이 모두 없는 환경에서는 아무것도 기록되지 않으며 오류도 표시되지 않습니다.

history.md는 증가하지만 context.md은 전혀 변경되지 않습니다. 기본적으로 auto_save_context는 off입니다. /recall:save을 실행하거나, key를 on_end로 설정하여 SessionEnd hook이 처리하도록 합니다.

파일이 잘못된 project 아래에 생성됩니다. Recall은 Claude Code를 시작한 디렉터리를 기준으로 상대 경로에 기록합니다. 따라서 home directory에서 세션을 시작하면 memory가 해당 위치에 저장됩니다. project root에서 시작하고, ls -la .recall/을 사용하여 파일이 실제로 저장된 위치를 확인합니다.

기록이 중단되었지만 경고가 표시되지 않습니다. ls -a .recall/로 pause marker를 확인합니다. 지난주에 생성한 .capture-paused 파일이 계속 작동하고 있을 수 있습니다.

긴 세션이 끝난 후에도 summary가 빈약합니다. max_input_chars은 summarizer 입력을 200000자로 제한하므로 매우 긴 log는 잘립니다. log를 rotate합니다.

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

그 후 짧은 세션을 1회 실행하고 ls -la .recall/를 다시 확인하여 새로운 history.md이 생성되었는지 확인합니다.

Recall이 중단되는 지점

Recall은 로그와 요약 도구입니다. 따라서 어떤 내용이 제외되는지 명확히 이해해야 합니다.

요약기는 추출 방식으로 작동합니다. TextRank는 이미 history.md에 있는 문장을 선택하므로, 결정이 옳았는지는 판단하지 않습니다. 화요일에 기록된 잘못된 선택도 수요일에 기록된 올바른 결정과 동일한 방식으로 표시됩니다. 중요한 사안이라면 context.md를 읽고 직접 수정합니다. 이 파일은 markdown 파일이므로 자유롭게 편집할 수 있습니다.

검색 기능은 없습니다. 프로젝트마다 현재 요약 1개와 계속 추가되는 로그 1개가 제공될 뿐이며, 프로젝트 전체에서 조회할 수 있는 메모리는 제공되지 않습니다. 3주 전에 데이터베이스에 대해 무엇을 결정했는지 확인하려면 history.md에서 grep을 실행해야 합니다.

세션 내부에서는 도움이 되지 않습니다. 세션 중간에 컨텍스트 창이 가득 차는 문제는 다른 문제이며 해결 방법도 다릅니다. 한 세션에서 컨텍스트 창 관리하기는 이 가이드의 관련 문서입니다.

요약은 의도적으로 신뢰할 수 없는 입력으로 처리됩니다. context.md는 fence로 감싸고 레이블을 지정하여 주입되며, Claude는 이를 사용하기 전에 확인을 요청합니다. 이 설계가 필요한 이유는 commit된 .recall/ 디렉터리에 commit 권한이 있는 누구나 에이전트가 읽을 텍스트를 작성할 수 있기 때문입니다. .recall/를 개인용으로 사용할지 공유할지 한 번 결정합니다. 개인 메모리로 사용할 경우 .gitignore에 추가하고, 공유할 경우 commit한 뒤 다른 기여와 동일한 방식으로 검토합니다. 에이전트가 무인 상태로 실행된다면 VPS에서 Claude Code를 안전하게 실행하기에서 더 넓은 보안 경계를 다룹니다.

Redaction은 최선의 노력으로 수행됩니다. API 키, 토큰, PEM 블록, .env 할당과 같은 일반적인 패턴을 대상으로 합니다. commit하기 전에 .recall/를 읽습니다.

버전 번호는 현재 성숙도를 정확히 반영합니다. 2026년 7월의 0.4.0에서는 config 키와 파일 레이아웃이 release 간에도 변경될 수 있으므로, 의존하는 설정을 upgrade하기 전에 changelog를 읽습니다.

FAQ

Recall은 내 코드나 transcript를 어디로든 전송합니까?

아닙니다. 캡처 hook과 요약기는 자체 시스템에서 실행되는 Python 스크립트입니다. plugin에는 API key가 없으며 network call도 수행하지 않습니다. 요약에는 model 대신 TF-IDF와 TextRank를 사용하므로 이 단계에는 비용이 들지 않으며 시스템을 offline 상태로 사용할 수 있습니다. 단점은 요약이 extractive 방식이라는 점입니다. 새 문장을 작성하는 대신 log에서 문장을 선택합니다.

.recall/context.md이(가) 없거나 최신 상태가 아닌 이유는 무엇입니까?

auto_save_context의 기본값은 off이므로 /recall:save을 실행할 때만 요약이 다시 생성됩니다. 각 session이 종료될 때 다시 작성하려면 recall.config.json에서 "auto_save_context": "on_end"을 설정합니다. history.md도 없으면 hook이 전혀 실행되지 않는 것입니다. /recall:show으로 plugin이 load되었는지 확인한 다음, hook이 Python 스크립트이므로 해당 box에서 python3 -V이 응답하는지 확인합니다.

Recall은 session마다 얼마나 절약합니까?

요약을 load하는 데는 일반적으로 1,200 token 정도가 필요합니다. 반면 repository를 다시 읽고 현재 위치를 파악해야 하는 model에는 일반적으로 30,000 token 정도가 필요합니다. 이는 일반적인 수치입니다. session 내부에서 wc -c .recall/context.md와 /context command를 사용하여, cold start와 요약에서 resume하는 경우를 비교해 직접 측정하십시오.

그래도 CLAUDE.md file이 필요합니까?

예. 두 file은 서로 다른 작업을 수행합니다. CLAUDE.md에는 사용자가 의도적으로 작성한 상시 규칙과 build command가 들어갑니다. context.md는 이전 session에서 실제로 발생한 일을 바탕으로 생성되므로, 직접 기록할 생각을 하지 못했을 미완료 migration도 포함합니다. 두 file을 모두 유지하십시오.

하나의 VPS에서 여러 project의 memory를 보관할 수 있습니까?

예. Recall은 각 project directory의 .recall/에 memory를 저장하므로 같은 server에 있는 두 project도 서로 분리된 log와 summary를 유지합니다. file은 user account가 아니라 working directory를 기준으로 적용되므로, 매번 project root에서 Claude Code를 시작하십시오.