메모리 시스템

기준일: 2026-07-26
난이도: 중급
공식 기준: Memory overview, Memory CLI, Active memory, Dreaming, Agent workspace

OpenClaw의 메모리는 모델 내부의 숨은 기억이 아니라 워크스페이스에 저장되는 Markdown 파일과 그 파일을 찾기 위한 검색 인덱스로 동작합니다. 중요한 내용은 파일에 남아야 다음 세션에서 다시 사용할 수 있습니다.

핵심 개념

메모리 파일 3종

파일	역할	주입 방식
MEMORY.md	오래 유지할 사실, 선호, 결정, 짧은 요약	세션 시작 시 Project Context에 주입될 수 있음
memory/YYYY-MM-DD.md	그날의 작업 맥락, 관찰, 세션 요약	검색 도구가 색인하고 필요할 때 찾아 읽음
DREAMS.md	dreaming sweep과 grounded backfill 결과 검토	사람이 검토하는 기록 표면

MEMORY.md는 원문 로그가 아니라 압축된 장기 기억입니다. 자세한 기록은 memory/YYYY-MM-DD.md에 두고, 장기적으로 필요한 요약만 MEMORY.md로 승격하는 흐름이 안전합니다.

기억은 파일에 저장될 때만 유지됩니다

사용자가 "이 내용을 기억해줘"라고 말하면 에이전트는 적절한 메모리 파일에 기록합니다. 기록되지 않은 대화 내용은 compaction이나 세션 전환 뒤 사라질 수 있습니다.

메모리 도구

OpenClaw의 에이전트 도구에는 두 가지 메모리 도구가 있습니다.

도구	용도
memory_search	표현이 달라도 의미적으로 관련된 메모리 검색
memory_get	특정 메모리 파일 또는 줄 범위 읽기

검색은 설정된 embedding provider가 있을 때 의미 검색과 키워드 검색을 결합할 수 있습니다. provider, 모델, 비용은 설치 환경과 설정에 따라 달라지므로 문서 안에 고정하지 않습니다.

메모리 CLI

공식 CLI 네임스페이스는 openclaw memory입니다.

명령	용도
openclaw memory status	에이전트별 메모리 상태, 인덱스, provider 준비 상태 확인
openclaw memory index	메모리 인덱스 갱신
openclaw memory search	CLI에서 메모리 검색
openclaw memory promote	daily note 기반 후보를 평가하고 필요하면 MEMORY.md에 반영
openclaw memory promote-explain	promotion 후보의 점수 근거 확인
openclaw memory rem-harness	REM 반영과 promotion 결과를 쓰기 없이 미리 보기
openclaw memory rem-backfill	과거 daily note를 읽어 DREAMS.md 검토 항목으로 되살림

공식 Memory CLI에 없는 관리 명령은 이 문서에서 절차로 제시하지 않습니다.

Dreaming

Dreaming은 선택적 백그라운드 메모리 정리 흐름입니다. light, REM, deep 단계로 후보를 정리하고, deep 단계만 MEMORY.md에 장기 기억을 씁니다.

• 기능 활성화와 세부 설정은 공식 Dreaming과 Memory CLI를 확인합니다.
• 채팅에서는 /dreaming on, /dreaming off, /dreaming status로 토글하거나 상태를 봅니다.
• CLI에서 REM 검토를 하려면 openclaw memory rem-harness와 openclaw memory rem-backfill을 사용합니다.
• Dreaming 검토도 openclaw memory 하위 명령으로만 다룹니다.
• openclaw memory status는 light/REM 단계가 켜져 있을 때 Dreaming: off로 오인하지 않도록 활성 단계를 표시합니다 (v2026.6.11 계열 수정).

Active Memory

Active memory는 플러그인이 소유하는 블로킹 메모리 서브에이전트로, 대화형 세션에 관련 기억을 주입합니다. 기본 Markdown 파일 메모리와 별개로 켜는 표면이므로, 활성화·타임아웃·dreaming과의 상호작용은 공식 문서와 플러그인 설정을 따릅니다. nightly dreaming 작업이 불필요한 recall을 돌리지 않도록 조정된 이력이 있습니다 (v2026.6.11 노트).

선택 기준

필요	사용할 표면
기억이 저장되어 있는지 빠르게 확인	openclaw memory status
검색 결과가 오래됐거나 누락되는 느낌	openclaw memory index --force
이전 결정이나 선호를 찾기	openclaw memory search "검색어"
장기 기억 후보를 미리 검토	openclaw memory promote
왜 promotion 후보가 선택됐는지 확인	openclaw memory promote-explain <selector>
과거 daily note를 검토 표면으로 재생	openclaw memory rem-backfill --path <file-or-dir>
쓰기 없이 REM 결과만 보기	openclaw memory rem-harness --path <file-or-dir> --grounded

실습

1. 상태 확인

openclaw memory status

더 깊은 provider와 semantic search 준비 상태가 필요할 때만 deep 확인을 실행합니다.

openclaw memory status --deep

2. 인덱스 갱신

openclaw memory index --force

3. 검색

openclaw memory search "TypeScript 선호도"

결과 수나 점수 기준이 필요하면 공식 옵션을 함께 씁니다.

openclaw memory search --query "프로젝트 결정" --max-results 5 --min-score 0.5

4. 장기 기억 후보 검토

openclaw memory promote --limit 5

검토 후 실제로 MEMORY.md에 쓰려면 명시적으로 --apply를 붙입니다.

openclaw memory promote --limit 5 --apply

5. Dreaming 검토

쓰기 없이 과거 daily note를 확인합니다.

openclaw memory rem-harness --path ./memory --grounded

검토 결과를 DREAMS.md에 남기려면 다음 명령을 사용합니다.

openclaw memory rem-backfill --path ./memory --stage-short-term

되돌릴 때는 공식 rollback 옵션을 사용합니다.

openclaw memory rem-backfill --rollback
openclaw memory rem-backfill --rollback-short-term

도구에 입력할 프롬프트

OpenClaw 메모리를 점검해줘.
1. MEMORY.md에 남길 장기 기억과 memory/YYYY-MM-DD.md에 둘 작업 로그를 구분해줘.
2. 공식 CLI인 openclaw memory status/index/search/promote/rem-harness/rem-backfill만 사용해 확인 절차를 제안해줘.
3. 공식 Memory CLI에 없는 관리 명령이나 별도 Dreaming CLI 네임스페이스를 가정하지 말아줘.

체크리스트

• MEMORY.md와 memory/YYYY-MM-DD.md의 역할을 구분했다.
• 장기 기억은 raw transcript가 아니라 durable summary로만 유지한다.
• 검색 이상 시 openclaw memory status와 openclaw memory index로 먼저 확인한다.
• 실제 검색은 openclaw memory search 또는 memory_search 도구를 사용한다.
• openclaw memory promote는 기본적으로 검토 흐름이며, 쓰기는 --apply를 명시할 때만 한다.
• Dreaming 관련 CLI는 openclaw memory rem-harness와 openclaw memory rem-backfill만 문서화했다.
• provider, 모델명, 비용, 기본 모델 값은 고정하지 않았다.
• 민감 정보는 워크스페이스 메모리 파일에 저장하지 않는다.

다음 단계

• 워크스페이스 모범 사례에서 메모리 파일을 안전하게 백업하는 기준을 봅니다.
• 문제 해결에서 memory status, doctor, logs를 이용한 점검을 익힙니다.
• 부록에서 공식 문서와 내부 가이드의 기준일을 확인합니다.