원문 캡처 · github.com
원문 캡처 · github.com

Sleep는 Pi, OmO, Claude Code에서 세션 중 관찰한 내용을 임시로 모으고 세션이 끝난 뒤 잠정 기억으로 정리하는 도구다. 사용자가 승인해야만 잠정 기억을 영구 기억으로 옮기므로, 에이전트의 기억을 자동으로 영구화하지 않으려는 사용자에게 적합하다.

  • 작업 중 관찰을 수집하고, 조건을 충족한 뒤 모델이 이를 잠정 기억으로 정리한다.
  • 반복된 선호를 모델 호출 없이 찾아내며, 선택한 작업을 기억 사용 여부에 따라 재생해 비교할 수 있다.
  • Pi와 OmO는 자동 연동에 사용자 설치 확장이 필요하다. Claude Code는 자체 훅을 이용한다.

기억 수집과 승인 절차

Sleep는 기억을 세 단계로 나눈다. T0는 훅, 확장 또는 capture 명령이 기록하는 임시 세션 관찰이다. T1은 정리 과정이나 mine이 만든 잠정 기억으로, 검증되지 않은 배경 정보로 표시된다. T2는 영구 기억이며, 사용자가 명시적으로 promote 명령을 실행해야만 기록된다.

일반 세션에서는 연동 기능이 관찰을 T0 버퍼에 수집한다. 기본 수면 조건은 기록이 3개 이상이고 이전 실행 이후 6시간이 지난 경우다. 조건을 통과하면 모델이 버퍼를 T1 후보로 압축한다. 잠정 후보는 해당 프로젝트에서 배경 정보로 표시될 수 있다. 사용자는 후보를 확인한 뒤 영구 기억으로 승격할지 선택한다.

text
session activity -> T0 buffer -> gated sleep -> T1 provisional memory                                                    |                                              review or replay                                                    |                                              explicit promote                                                    |                                              T2 permanent memory

후보를 확인하고 승인하는 기본 절차는 다음과 같다.

sh
./sleep.py status -v
./sleep.py show <candidate-id>
./sleep.py promote <candidate-id> --dry-run
./sleep.py promote <candidate-id>

잘못된 후보는 감사 기록을 삭제하지 않고 거부 사유와 함께 남길 수 있다.

sh
./sleep.py refuse <candidate-id> --note "Incorrect for the current deployment."

설치와 에이전트 연동

요구 사항은 Python 3.10 이상이다. 모델을 사용하는 정리와 재생 기능에는 Claude Code CLI가 필요하다. Pi, OmO, Claude Code 중 하나 또는 여러 개를 함께 사용할 수 있다.

sh
./install.sh --dry-run # show every change without writing
./install.sh # install the shared skill and Claude Code hooks
./install.sh --extension # also install the Pi/OmO extension
./install.sh --launchd # also schedule the nightly pass on macOS

설치 프로그램은 먼저 테스트를 실행하고, 설정을 바꾸기 전에 백업을 만든다. 다시 실행해도 안전하다고 안내한다. 설치 변경 없이 점검하려면 --dry-run을 사용한다. 삭제하고 백업된 설정을 복구하려면 다음 명령을 실행한다.

sh
./uninstall.sh

Pi와 OmO에서 세션을 자동으로 연동하려면 사용자 설치 확장이 필요하다.

sh
./install.sh --extension

설치 프로그램은 저장소의 extension/ 디렉터리를 다음 위치에 연결한다.

text
~/.omo/agent/extensions/sleep

확장은 다음 Pi 또는 OmO 세션부터 로드되며, 사용자 메시지와 관련 도구 활동을 T0에 기록하고, 일치하는 프로젝트의 T1 잠정 기억을 에이전트 문맥에 주입한다. 에이전트가 안정된 뒤에는 수면 정책을 깨워 실행 여부를 확인한다. 로드 여부는 다음 명령으로 확인할 수 있다.

sh
omo -p 'hi' >/dev/null 2>&1
tail -4 ~/.sleep/logs/extension.log

로그에는 session_start, publish, agent_settled 항목이 있어야 한다. 확장을 설치하지 않아도 Sleep CLI 명령을 수동 실행할 수 있고 Claude Code는 자체 훅을 사용할 수 있다. 하지만 Pi와 OmO는 세션을 자동으로 기록하거나 잠정 기억을 주입하지 않으며, 수면 절차도 자동으로 시작하지 않는다.

Pi와 OmO에서는 저장소를 복제하지 않고 npm 패키지 pi-sleep-agent를 설치해 확장을 사용할 수도 있다.

sh
pi install npm:pi-sleep-agent
# or, for a specific published version
pi install npm:pi-sleep-agent@0.1.0

패키지에는 확장(pi.extensions), Sleep 스킬(pi.skills), Python 런타임이 들어 있어 설치한 패키지에서 CLI도 작동한다. Pi가 패키지를 자체 디렉터리에 관리하므로 설치 경로를 추측하지 말라고 안내한다. 확장은 패키지 안에서 런타임을 직접 찾고 그 경로를 로그에 기록한다. 아래 확인 절차는 저장소 복제본이 아니라 설치된 패키지의 확장과 런타임이 로드됐는지 확인한다.

sh
omo -p 'hi' >/dev/null 2>&1
tail -4 ~/.sleep/logs/extension.log # session_start, publish, agent_settled

세 로그 항목은 패키지에 포함된 확장이 로드되고 Python 런타임이 실행됐다는 확인 기준이다. 항목이 나타나지 않으면 pi install로 다시 설치하거나 세션을 재시작해 확장을 다시 로드한다. 패키지 디렉터리 안에서 경로를 추측하지 말라고 안내한다.

게시하지 않고 tarball 구성을 확인하는 명령은 다음과 같다.

sh
npm run pack:check # what npm pack would ship, as JSON
npm run smoke:package # install the tarball into an isolated Pi home and prove it loads

Claude Code는 UserPromptSubmit, PostToolUse, Stop, PreCompact 훅을 사용한다. Pi와 OmO는 ./install.sh --extension으로 사용자 확장을 설치해야 한다. 두 연동은 $SLEEP_HOME을 공유하므로 프로젝트 범위가 일치하면 한 클라이언트에서 검토한 후보를 다른 클라이언트에서도 볼 수 있다.

시작과 일상 사용

설치를 확인할 때는 상태, 진단, 수면 조건의 실행 여부를 차례로 살펴본다.

sh
./sleep.py status -v
./sleep.py doctor
./sleep.py sleep --dry-run

필요하면 관찰을 직접 기록할 수 있다.

sh
./sleep.py capture --text "The staging gateway requires X-Route: blue." --kind fact --source user

정리 절차가 조건을 충족하는지 미리 확인한 뒤, 필요하면 강제로 실행한다.

sh
./sleep.py sleep --dry-run
./sleep.py sleep --force

후보를 영구 기억으로 만들기 전에 status와 show로 내용을 확인하고, promote --dry-run으로 승격을 미리 점검할 수 있다. 잘못된 후보는 refuse와 메모를 사용해 거부한다.

야간 꿈 주기와 재생

Dream은 사용자가 자리를 비운 동안 실행할 수 있는 비대화형 성찰 단계다. 모델 가중치를 업데이트하지 않으며, 자체적으로 영구 기억을 기록하지 않는다. 세 단계로 구성된다.

  • mine은 같은 프로젝트의 별도 세션에서 반복한 지시를 찾는다. 결정론적으로 작동하며 모델을 호출하지 않는다.
  • consolidate는 수면 조건을 통과했을 때 설정된 모델에 최근 T0 관찰을 T1 후보로 정리하도록 요청한다.
  • replay는 실행 시기가 된 작업을 잠정 기억을 끈 경우와 켠 경우로 실행하고 비교 보고서를 작성한다.

모든 결과는 검토할 수 있으며, 후보는 promote를 명시적으로 실행하기 전까지 T1에 남는다. 전체 야간 절차를 모델 호출이나 기록 없이 미리 보려면 다음을 실행한다.

sh
./sleep.py nightly --dry-run

지금 실행하려면 다음 명령을 사용한다.

sh
./sleep.py nightly --force

원하는 경우 구성 요소를 따로 실행할 수 있다.

sh
./sleep.py mine --dry-run
./sleep.py mine

./sleep.py replay --limit 3 # show the replay plan
./sleep.py replay --run --limit 3 --budget 0.10

--budget은 재생의 양쪽 실행을 합쳐 작업 하나에 허용하는 최대 비용이다. Dream 보고서는 $SLEEP_HOME/reports/에 저장되며 자동으로 기억을 승격하지 않는다.

명령어와 모델 설정

자주 쓰는 명령은 다음과 같다.

  • ./sleep.py status -v: 버퍼, 후보, 격리 항목, 영구 기억의 상태를 보여준다.
  • ./sleep.py sleep --dry-run: 수면 조건이 실행될지 확인한다.
  • ./sleep.py sleep --force: 정리 작업을 즉시 실행한다.
  • ./sleep.py show <id>: 후보와 렌더링된 문맥을 확인한다.
  • ./sleep.py promote <id>: 승인한 후보를 영구 기억으로 옮긴다.
  • ./sleep.py refuse <id> --note "...": 후보가 잘못됐다는 기록을 남긴다.
  • ./sleep.py replay --run --limit 3: 선택한 작업을 기억을 끈 경우와 켠 경우로 비교한다.
  • ./sleep.py mine --dry-run: 세션에서 반복된 선호를 찾는다.
  • ./sleep.py nightly --dry-run: 비대화형 야간 작업을 미리 확인한다.
  • ./sleep.py doctor: 중복되거나 겹치는 기억 기록을 찾는다.
  • ./sleep.py inject --project "$PWD": 현재 프로젝트의 잠정 문맥을 출력한다.

명령별 선택지를 확인하려면 ./sleep.py <command> --help를 실행한다.

대화형 실행은 현재 환경 변수를 물려받는다. macOS에서 예약 실행하는 작업은 $SLEEP_HOME/env의 추가 값을 읽으며, 기본 위치는 ~/.sleep/env다. 파일을 준비할 때는 다음 명령을 사용할 수 있다.

sh
mkdir -p ~/.sleep
touch ~/.sleep/env
chmod 600 ~/.sleep/env

파일에는 KEY=VALUE 형식의 줄을 넣는다. 자주 쓰는 설정은 다음과 같다.

text
ANTHROPIC_API_KEY=... ANTHROPIC_BASE_URL=... ANTHROPIC_MODEL=... SLEEP_MODEL=...

모델 선택 우선순위는 명시한 --model, SLEEP_MODEL, ANTHROPIC_MODEL 순이다. 다만 이미 실행 중인 프로세스의 환경 변수 값은 파일에 적힌 값보다 우선한다.

예약 작업을 켜기 전에 같은 경로를 수동으로 시험하도록 안내한다.

sh
./sleep.py nightly --dry-run
./sleep.py sleep --force --budget 0.10

안전장치와 데이터 위치

Sleep는 모델이 생성한 출력을 항상 에이전트 생성으로 표시하며, 그 출력이 스스로 사용자 확인을 받은 내용이라고 주장할 수 없게 한다. 잠정 기억은 지시가 아니라 배경 정보로 표시된다. 비밀 정보처럼 보이는 값은 가림 표시로 대체하고, 프롬프트 인젝션이나 데이터 유출 형태를 띤 입력은 격리한다. 여러 프로젝트가 섞인 버퍼는 사실을 잘못된 프로젝트에 배정하지 않도록 처리를 중단한다. 재생은 결과를 보고할 뿐 기억을 자동 승격하지 않으며, 모든 모델 호출에는 명시적 예산 한도가 있다.

실행 데이터는 모두 $SLEEP_HOME 아래에 저장되며 기본값은 ~/.sleep이다. 위치별 데이터는 다음과 같다.

  • buffer/: 임시 T0 기록
  • candidates/: 잠정 T1 기록
  • reports/: 재생 보고서
  • logs/: 훅과 야간 작업 로그
  • .quarantine/: 안전하지 않은 것으로 분류된 입력
  • state.json: 수면 및 재생 시각
  • env: 예약 실행에 사용할 선택적 환경 설정

유용한 로그 파일은 다음과 같다.

text
~/.sleep/logs/hook-fires.log
~/.sleep/logs/hook.log
~/.sleep/logs/nightly.log

시험용이나 별도의 기억 저장소를 쓰려면 SLEEP_HOME을 바꿀 수 있다.

sh
SLEEP_HOME=/tmp/my-sleep ./sleep.py status -v

문제 해결

관찰이 수집되지 않으면 상태와 진단 결과를 확인한다.

sh
./sleep.py status -v
./sleep.py doctor

~/.sleep/logs/hook-fires.log도 살펴본다. 로그가 비어 있으면 연동이 실행되지 않은 것이다. 이벤트가 있지만 버퍼가 비어 있다면 해당 이벤트가 무시됐거나 격리됐을 수 있다.

수면 작업이 계속 건너뛰어지는 경우 기본 조건인 기록 3개 이상과 6시간 간격을 확인한다. 조건 판단은 다음 명령으로 살펴볼 수 있다.

sh
./sleep.py sleep --dry-run

모델을 호출하려는 경우에만 --force를 사용한다.

예약 작업이 모델에 연결되지 않으면 ~/.sleep/env 파일이 있는지, 권한이 0600인지, 대화형 셸에서 쓰는 것과 같은 제공자 설정이 들어 있는지 확인한다. launchd에 의존하기 전에 다음 명령으로 실행해 본다.

sh
./sleep.py sleep --force

후보가 잘못된 문맥에 나타나는 경우 show로 cwd 값을 확인한다. 프로젝트가 섞인 배치는 T0에 남고, 후보를 만들지 않은 채 오류를 반환한다.

sh
./sleep.py show <id>

추가 자료는 Measured evidence and validation history, Sleep Framework analysis, 공유 /sleep 스킬에서 확인할 수 있다.