Total Recall — 자율 에이전트 메모리

스스로 관찰하는 유일한 메모리 스킬.

데이터베이스, 벡터, 수동 저장이 필요 없습니다. LLM 관찰자가 대화를 우선순위별 메모로 압축하고, 필요 시 통합하며, 놓친 내용을 복구합니다. 5중 중복 구조, 유지보수 불필요. ~$0.00/월 (무료 모델 사용 시).

다른 메모리 스킬이 "기억하라는 것을 기억"하라고 요구하는 동안, 이 스킬은 그냥 주의를 기울입니다.

아키텍처

계층 1: 관찰자 (cron, 15-30분마다)
    ↓ 최근 메시지 압축 → observations.md
계층 2: 반영자 (observations가 8000단어 초과 시 자동 실행)
    ↓ 통합, 구식 정보 제거 → 40-60% 축소
계층 3: 세션 복구 (모든 /new 또는 /reset 시 실행)
    ↓ 관찰자가 놓친 세션 포착
계층 4: 반응형 감시자 (inotify 데몬, Linux 전용)
    ↓ 40개 이상의 새 JSONL 쓰기 후 관찰자 트리거, 5분 쿨다운
계층 5: 사전 압축 훅 (memoryFlush)
    ↓ OpenClaw가 컨텍스트를 압축하기 전에 긴급 캡처

기능 설명

관찰자(Observer): 최근 세션 기록(JSONL)을 읽고 LLM으로 전송하여 압축된 관찰 내용을 observations.md에 우선순위(높음, 중간, 낮음)와 함께 추가합니다.
반영자(Reflector): 관찰 내용이 너무 커지면 자동 실행되어 관련 항목을 통합하고 오래된 저우선순위 항목을 제거합니다.
세션 복구(Session Recovery): 세션 시작 시 실행되며, 이전 세션이 캡처되었는지 확인하고 그렇지 않은 경우 긴급 관찰을 수행합니다.
반응형 감시자(Reactive Watcher): inotify를 사용하여 세션 디렉터리를 감시하므로, 활동이 많은 기간에 cron 간격보다 빠르게 캡처할 수 있습니다.
사전 압축 훅(Pre-compaction hook): OpenClaw가 컨텍스트를 압축하려고 할 때 실행되어 데이터 손실을 방지합니다.

빠른 시작

1. 스킬 설치

clawdhub install total-recall

2. API 키 설정

.env 또는 OpenClaw 설정에 추가:

OPENROUTER_API_KEY=sk-or-v1-xxxxx

3. 설정 스크립트 실행

bash skills/total-recall/scripts/setup.sh

다음을 수행합니다:

메모리 디렉터리 구조 생성 (memory/, logs/, backups)
Linux에서 inotify + systemd 사용 시: 반응형 감시자 서비스 설치
수동으로 추가해야 하는 cron 작업 및 에이전트 설정 지침 출력

4. 에이전트가 관찰 내용을 로드하도록 설정

에이전트의 워크스페이스 컨텍스트(예: MEMORY.md 또는 시스템 프롬프트)에 추가:

세션 시작 시 `memory/observations.md`를 읽어 교차 세션 컨텍스트를 확보합니다.

또는 OpenClaw의 memoryFlush.systemPrompt를 사용하여 시작 명령어를 주입합니다.

플랫폼 지원

플랫폼	관찰자 + 반영자 + 복구	반응형 감시자
Linux (Debian/Ubuntu 등)	전체 지원	inotify-tools 필요
macOS	전체 지원	사용 불가 (cron 전용)

모든 코어 스크립트는 이식 가능한 bash를 사용합니다. stat, date, md5 명령은 _compat.sh를 통해 크로스 플랫폼으로 처리됩니다.

설정

모든 스크립트는 합리적인 기본값을 가진 환경 변수에서 설정을 읽습니다:

변수	기본값	설명
`OPENROUTER_API_KEY`	(필수)	LLM 호출용 OpenRouter API 키
`MEMORY_DIR`	`$OPENCLAW_WORKSPACE/memory`	observations.md 위치
`SESSIONS_DIR`	`~/.openclaw/agents/main/sessions`	OpenClaw 세션 기록
`OBSERVER_MODEL`	`stepfun/step-3.5-flash:free`	압축용 기본 모델 (무료)
`OBSERVER_FALLBACK_MODEL`	`nvidia/nemotron-3-nano-30b-a3b:free`	기본 모델 실패 시 대체 (무료)
`OBSERVER_LOOKBACK_MIN`	`15`	되돌아볼 시간(분) (주간)
`OBSERVER_MORNING_LOOKBACK_MIN`	`480`	되돌아볼 시간(분) (오전 8시 이전)
`OBSERVER_LINE_THRESHOLD`	`40`	반응형 트리거 라인 수 (Linux)
`OBSERVER_COOLDOWN_SECS`	`300`	반응형 트리거 간 쿨다운 시간 (Linux)
`REFLECTOR_WORD_THRESHOLD`	`8000`	반영자 실행 임계 단어 수
`REFLECTOR_MODEL`	`nvidia/nemotron-3-super-120b-a12b:free`	관찰 통합용 모델 (무료)
`REFLECTOR_FALLBACK_MODEL`	`openrouter/hunter-alpha`	반영자 모델 실패 시 대체 (무료)
`OPENCLAW_WORKSPACE`	`~/your-workspace`	워크스페이스 루트

LLM 제공자 설정

Total Recall은 OpenAI 호환 채팅 완성 API를 사용합니다. 환경 변수를 설정하여 제공자를 전환할 수 있습니다:

변수	기본값	설명
`LLM_BASE_URL`	`https://openrouter.ai/api/v1`	API 엔드포인트
`LLM_API_KEY`	`OPENROUTER_API_KEY`로 대체	API 키
`LLM_MODEL`	`deepseek/deepseek-v3.2`	사용할 모델

제공자 예시

# OpenRouter (기본)
export OPENROUTER_API_KEY="your-key"

# Ollama (로컬)
export LLM_BASE_URL="http://localhost:11434/v1"
export LLM_API_KEY="ollama"
export LLM_MODEL="llama3.1:8b"

# Groq
export LLM_BASE_URL="https://api.groq.com/openai/v1"
export LLM_API_KEY="your-groq-key"
export LLM_MODEL="llama-3.3-70b-versatile"

생성되는 파일

memory/
  observations.md          # 주요 관찰 로그 (시작 시 로드)
  observation-backups/     # 반영자 백업 (최근 10개 유지)
  .observer-last-run       # 마지막 관찰자 실행 타임스탬프
  .observer-last-hash      # 마지막으로 처리된 메시지의 중복 제거 해시
logs/
  observer.log
  reflector.log
  session-recovery.log
  observer-watcher.log

Cron 작업

설정 스크립트는 다음 OpenClaw cron 작업을 생성합니다:

작업	일정	설명
`memory-observer`	15분마다	최근 대화 압축
`memory-reflector`	매시간	관찰 내용이 많으면 통합

반응형 감시자 (Linux 전용)

반응형 감시자는 inotifywait를 사용하여 세션 활동을 감지하고 cron 단독보다 빠르게 관찰자를 트리거합니다. inotify-tools가 설치된 Linux가 필요합니다.

# inotify-tools 설치 (Debian/Ubuntu)
sudo apt install inotify-tools

# 감시자 상태 확인
systemctl --user status total-recall-watcher

# 로그 보기
journalctl --user -u total-recall-watcher -f

비용

OpenRouter의 기본 무료 모델 사용 시:

일반적인 사용(관찰자 + 반영자)의 경우 ~$0.00/월 (무료 티어 모델 사용)
하루 약 15-30회의 cron 실행, 각각 수백 토큰 처리
모든 기본 모델은 무료 티어 모델

모델 참고 사항

스크립트는 API 응답의 .content 및 .reasoning 필드를 모두 방어적으로 처리합니다. 대부분의 모델은 표준 .content 필드에 콘텐츠를 반환하지만, .reasoning으로의 대체는 다른 응답 형식을 사용할 수 있는 모델과의 호환성을 보장합니다.

작동 방식 (기술적)

관찰자

최근 수정된 세션 JSONL 파일 찾기
하위 에이전트/cron 세션 필터링
되돌아보기 창에서 사용자 + 어시스턴트 메시지 추출
MD5 해시 비교를 통한 중복 제거
LLM으로 전송 (우선순위 기반 압축)
결과를 observations.md에 추가
단어 수가 임계값 초과 시 반영자 트리거

반영자

현재 관찰 내용 백업
전체 로그를 LLM으로 전송 (통합 지침 포함)
출력이 입력보다 짧은지 확인 (안전 검사)
관찰 내용을 통합 버전으로 교체
오래된 백업 정리 (최근 10개 유지)

세션 복구

모든 /new 또는 /reset 시 실행
마지막 세션 파일의 최근 라인 해싱
마지막 관찰자 실행의 저장된 해시와 비교
불일치 시: 복구 모드로 관찰자 실행 (4시간 되돌아보기)
대체: 관찰자 실패 시 원시 메시지 추출

반응형 감시자

inotifywait로 세션 디렉터리 모니터링
기본 세션 파일에 대한 JSONL 쓰기만 카운트
40라인 초과 시: 관찰자 트리거 (5분 쿨다운)
cron/외부 관찰자 실행 감지 시 카운터 리셋

프롬프트 커스터마이징

관찰자와 반영자의 시스템 프롬프트는 prompts/에 있습니다:

prompts/observer-system.txt — 대화 압축 방식 제어
prompts/reflector-system.txt — 관찰 통합 방식 제어

에이전트의 성격과 우선순위에 맞게 편집하세요.

꿈 주기 (Dream Cycle)

꿈 주기는 선택적인 야간 에이전트로, 업무 시간 이후에 실행되어 observations.md를 통합합니다. 오래된 항목을 보관하고 의미론적 훅(semantic hook)을 추가하여 유용한 정보가 실제로 손실되지 않도록 합니다. 컨텍스트는 가볍게 유지되고, 모든 것을 찾을 수 있습니다.

기능

멀티 훅 검색 — 보관된 항목당 4-5개의 대체 검색 구문. 원본과 다른 단어로 검색해도 메모리를 찾을 수 있습니다.

신뢰도 점수 — 모든 관찰에 신뢰도 점수(0.0-1.0)와 소스 유형(explicit, implicit, inference, weak, uncertain)이 할당됩니다. 신뢰도가 높은 항목은 더 오래 보존되고, 낮은 항목은 더 빨리 보관됩니다.

메모리 유형 시스템 — 7가지 유형과 유형별 TTL: event (14일), fact (90일), preference (180일), goal (365일), habit (365일), rule (영구), context (30일). observations.md에 보이지 않는 HTML 메타데이터 주석으로 포함됩니다.

관찰 청킹 — 3개 이상의 관련 관찰 클러스터가 단일 요약 항목으로 압축됩니다. 원본 관찰은 보관되고, 청크 훅이 이를 대체합니다. 최대 75% 토큰 감소 효과.

중요도 감쇠 — 각 보관 결정 전에 유형별 일일 감쇠가 중요도 점수에 적용됩니다. 보관 임계값 이하로 감쇠된 항목은 제거 대기열에 추가됩니다. 비율: event (-0.5/일), fact (-0.1/일), preference (-0.02/일), rule/habit/goal (감쇠 없음).

패턴 승격 — 최근 꿈 로그에서 반복되는 테마(3일 이상 3회 이상 발생)를 스캔합니다. 승격 제안을 memory/dream-staging/에 작성하여 사람이 검토할 수 있도록 합니다. staging-review.sh를 사용하여 제안을 나열, 표시, 승인 또는 거부합니다. context 유형은 자동으로 승격되지 않습니다.

설정

bash skills/total-recall/scripts/setup.sh 실행 — Dream Cycle 디렉터리를 자동으로 생성합니다.

야간 cron 작업을 전체 에이전트 턴으로 추가:

# Dream Cycle — 야간 (오전 3시 권장; 시간대에 맞게 조정)
# Dream Cycle은 전체 에이전트 턴으로 실행됩니다 — 직접 bash 호출이 아닙니다.
# dream-cycle.sh는 에이전트가 호출하는 파일 작업 헬퍼이며, 진입점이 아닙니다.
#
# 0 3 * * * bash -c 'source ~/.openclaw/shared/secrets/openclaw-secrets.env \
#   && openclaw agent --agent main \
#   --message "Total Recall Dream Cycle을 실행하세요. \
# $WORKSPACE/skills/total-recall/prompts/dream-cycle-prompt.md의 지침을 정확히 따르세요. \
# READ_ONLY_MODE=false 및 DREAM_PHASE=1을 사용하세요." \
#   --json >> $WORKSPACE/logs/dream-cycle.log 2>&1'

prompts/dream-cycle-prompt.md를 시스템 프롬프트로 사용하여 cron 에이전트를 구성하세요. 권장 모델: Dreamer용 Claude Sonnet (분석 + 결정), Observer용 DeepSeek v3.2 (저렴하고 빠름).
처음 몇 밤은 READ_ONLY_MODE=true로 시작하세요. 각 실행 후 memory/dream-logs/를 확인하여 무엇을 보관했을지 검증하세요.
만족스러우면 READ_ONLY_MODE=false로 전환하세요.

설정

변수	기본값	설명
`DREAM_TOKEN_TARGET`	`8000`	통합 후 observations.md의 토큰 목표
`READ_ONLY_MODE`	`false`	쓰기 없는 분석 실행을 위해 `true`로 설정

파일

파일	설명
`scripts/dream-cycle.sh`	에이전트가 호출하는 셸 헬퍼 (독립 실행형이 아님): 사전 점검, 보관, 관찰 업데이트, 로그 쓰기, 메트릭 쓰기, 검증, 롤백
`prompts/dream-cycle-prompt.md`	야간 Dream Cycle 실행을 위한 에이전트 프롬프트
`dream-cycle/README.md`	Dream Cycle 빠른 참조
`schemas/observation-format.md`	확장된 관찰 메타데이터 형식

생성되는 디렉터리

memory/
  archive/
    observations/        # 보관된 항목 (야간당 하나의 .md 파일)
    chunks/              # 청킹된 관찰 그룹
  dream-logs/            # 야간 실행 보고서
  dream-staging/         # 사람 검토 대기 중인 패턴 승격 제안
  .dream-backups/        # 실행 전 안전 백업
research/
  dream-cycle-metrics/
    daily/               # 야간당 JSON 메트릭

문제 해결

관찰자가 실행되지 않나요?

logs/observer.log에서 오류 확인
OPENROUTER_API_KEY가 설정되어 있고 유효한지 확인
cron 활성 상태 확인: crontab -l

세션 시작 시 관찰 내용이 로드되지 않나요?

에이전트 시작 명령어에 memory/observations.md 읽기가 포함되어 있는지 확인
MEMORY_DIR이 올바른 위치를 가리키는지 확인

반응형 감시자가 트리거되지 않나요? (Linux)

systemctl --user status total-recall-watcher 실행
inotify-tools 설치 확인: which inotifywait
감시자 로그 보기: journalctl --user -u total-recall-watcher -f

Dream Cycle이 너무 적극적으로 보관하나요?

READ_ONLY_MODE=true를 활성화하고 실행 전에 꿈 로그를 검토하세요.
DREAM_TOKEN_TARGET을 높여 실행당 보관량을 줄이세요.

Dream Cycle이 충분히 보관하지 않나요?

DREAM_TOKEN_TARGET을 낮추어 더 적극적인 통합을 유도하세요.

영감

이 시스템은 수면 중 인간 기억이 작동하는 방식에서 영감을 받았습니다. 해마(관찰자)는 경험을 포착하고, 수면 중 통합(반영자)을 통해 중요한 기억은 강화되고 잡음은 폐기됩니다.

자세히 읽기: Your AI Has an Attention Problem

"화성에 니 엉덩이를 가져가라." — 에이전트의 기억을 제대로 작동시키세요.

즐겨 사용하는 AI에게 물어보기

문서