메모리 개요

OpenClaw은 에이전트의 작업 공간(기본값: ~/.openclaw/workspace)에 일반 Markdown 파일을 작성하여 정보를 기억합니다. 모델은 디스크에 저장된 내용만 기억하며, 숨겨진 상태는 없습니다.

작동 방식

에이전트에는 메모리와 관련된 세 가지 파일이 있습니다.

• MEMORY.md — 장기 메모리입니다. 지속적으로 보존할 사실, 선호 사항, 결정을 기록합니다. 세션을 시작할 때 불러옵니다.
• memory/YYYY-MM-DD.md(또는 memory/YYYY-MM-DD-<slug>.md) — 일일 메모입니다. 진행 중인 맥락과 관찰 내용을 기록합니다. 인자 없이 /new 또는 /reset을 실행하면 오늘과 어제 날짜의 메모를 자동으로 불러옵니다. 번들 세션 메모리 훅이 작성하는 파일과 같은 슬러그 변형도 날짜만 있는 파일과 함께 불러옵니다.
• DREAMS.md(선택 사항) — 근거가 있는 과거 보충 항목을 포함하여, 사람이 검토할 수 있도록 Dream Diary와 Dreaming 스윕 요약을 기록합니다.

각 파일에 저장되는 내용

MEMORY.md는 간결하게 선별된 계층입니다. 세션 시작 시 사용할 수 있어야 하는 지속적인 사실, 선호 사항, 상시 적용되는 결정, 짧은 요약을 담습니다. 원본 대화 기록, 일일 로그 또는 전체 아카이브를 저장하는 곳이 아닙니다.

memory/YYYY-MM-DD.md 파일은 작업 계층입니다. 나중에도 유용할 수 있는 상세한 일일 메모, 관찰 내용, 세션 요약, 원본 맥락을 담습니다. 이러한 파일은 memory_search와 memory_get을 위해 인덱싱되지만, 매 턴의 부트스트랩 프롬프트에는 삽입되지 않습니다.

시간이 지나면 에이전트는 일일 메모에서 유용한 자료를 추려 MEMORY.md에 기록하고 오래된 장기 항목을 제거합니다. 생성된 작업 공간 지침과 Heartbeat 흐름이 이 작업을 주기적으로 수행하므로, 모든 세부 사항에 대해 MEMORY.md를 직접 편집할 필요는 없습니다.

MEMORY.md가 부트스트랩 파일 예산을 초과해도 OpenClaw은 디스크의 파일을 그대로 유지하지만, 컨텍스트에 삽입되는 사본은 잘라냅니다. 이를 신호로 삼아 상세한 자료를 memory/*.md로 옮기고 MEMORY.md에는 지속적으로 보존할 요약만 남기거나, 프롬프트 예산을 더 사용하려면 부트스트랩 제한을 늘리세요. 원본 크기와 삽입된 크기 및 잘림 상태를 확인하려면 /context list, /context detail 또는 openclaw doctor를 사용하세요.

작업에 영향을 주는 메모리

대부분의 메모리는 일반적인 Markdown 메모입니다. 일부 메모리는 에이전트가 나중에 수행해야 할 작업에 영향을 줍니다. 이러한 경우에는 사실만 기록하지 말고, 해당 메모에 따라 작업해도 안전한 시점도 함께 기록하세요.

메모가 다음 내용을 포함한다면 작업 경계를 기록하세요.

• 승인 또는 권한 요구 사항
• 일시적인 제약
• 다른 세션, 스레드 또는 사람에게 인계하는 사항
• 만료 조건
• 작업해도 안전한 시점
• 출처 또는 소유자의 권한
• 하기 쉬운 특정 작업을 피하라는 지침

유용한 작업 민감형 메모리는 다음 내용을 명확하게 나타냅니다.

• 향후 동작을 변경하는 요소
• 해당 내용이 적용되는 시점 또는 조건
• 만료 시점 또는 작업을 허용하는 조건
• 에이전트가 피해야 할 작업
• 신뢰 또는 권한에 영향을 준다면 출처 또는 소유자가 누구인지

메모리는 승인 맥락을 보존할 수 있지만 정책을 강제하지는 않습니다. 강제적인 운영 제어에는 OpenClaw 승인 설정, 샌드박스, 예약된 작업을 사용하세요.

예:

The API migration is being designed in another session. Future turns shouldnot edit the API implementation from this thread; use findings here only asdesign input until the migration plan lands.

또 다른 예:

A report from an untrusted source needs review before promotion. Future turnsshould treat it as evidence only; do not store it as durable memory until atrusted reviewer confirms the contents.

모든 메모리가 이 스키마를 따라야 하는 것은 아닙니다. 단순한 사실은 간결하게 유지해도 됩니다. 시점, 권한, 만료 또는 작업해도 안전한 맥락을 잃어 에이전트가 나중에 잘못된 작업을 수행할 수 있다면 작업 민감형 경계를 사용하세요.

추론된 단기 후속 작업에는 약속을 사용하세요. 정확한 알림, 시간 지정 확인, 반복 작업에는 예약된 작업을 사용하세요. 메모리는 두 경로와 관련된 지속적인 맥락을 요약하는 데 계속 사용할 수 있습니다.

추론된 약속

일부 향후 후속 작업은 지속적으로 보존할 사실이 아닙니다. 내일 면접이 있다고 언급했다면 유용한 메모리는 "이 내용을 MEMORY.md에 영구적으로 저장"하는 것이 아니라 "면접이 끝난 뒤 확인"하는 것일 수 있습니다.

약속은 이러한 경우에 사용하는 선택형 단기 후속 메모리입니다. OpenClaw은 숨겨진 백그라운드 단계에서 이를 추론하고 동일한 에이전트와 채널로 범위를 제한하며, 실행 시점이 된 확인 메시지를 Heartbeat를 통해 전달합니다. 명시적인 알림에는 계속 예약된 작업을 사용합니다.

메모리 도구

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

• memory_search — 원문과 표현이 다르더라도 의미 검색을 사용하여 관련 메모를 찾습니다.
• memory_get — 특정 메모리 파일 또는 줄 범위를 읽습니다.

두 도구 모두 활성 메모리 Plugin(기본값: memory-core)에서 제공합니다.

메모리 검색

임베딩 공급자가 구성되어 있으면 memory_search는 하이브리드 검색을 사용합니다. 벡터 유사도(의미적 뜻)와 키워드 일치(ID 및 코드 기호와 같은 정확한 용어)를 결합합니다. 지원되는 공급자의 API 키가 있으면 별도 설정 없이 사용할 수 있습니다.

검색 작동 방식, 조정 옵션, 공급자 설정은 메모리 검색을 참조하세요.

메모리 백엔드

지식 위키 계층

지속적인 메모리를 원본 메모보다 관리되는 지식 베이스에 가깝게 사용하려면 번들 memory-wiki Plugin을 사용하세요. 지속적인 지식을 결정론적 페이지 구조, 구조화된 주장과 증거, 모순 및 최신성 추적, 생성된 대시보드, 컴파일된 요약, 위키 네이티브 도구(wiki_status, wiki_search, wiki_get, wiki_apply, wiki_lint)를 갖춘 위키 저장소로 컴파일합니다.

memory-wiki는 활성 메모리 Plugin을 대체하지 않습니다. 활성 메모리 Plugin은 계속 회상, 승격, Dreaming을 담당합니다. memory-wiki는 그 옆에 출처 정보가 풍부한 지식 계층을 추가합니다.

자동 메모리 플러시

Compaction이 대화를 요약하기 전에 OpenClaw은 에이전트에게 중요한 맥락을 메모리 파일에 저장하도록 알리는 무음 턴을 실행합니다. 이 기능은 기본적으로 활성화되어 있습니다. 비활성화하려면 agents.defaults.compaction.memoryFlush.enabled: false를 설정하세요.

해당 정리 턴을 로컬 모델에서 실행하려면 메모리 플러시 턴에만 적용되는 정확한 재정의를 설정하세요. 이 설정은 활성 세션의 모델 폴백 체인을 상속하지 않습니다.

{  "agents": {    "defaults": {      "compaction": {        "memoryFlush": {          "model": "ollama/qwen3:8b"        }      }    }  }}

Dreaming

Dreaming은 메모리를 위한 선택적 백그라운드 통합 단계입니다. 단기 회상 신호를 수집하고 후보를 평가한 뒤, 조건을 충족한 항목만 장기 메모리(MEMORY.md)로 승격합니다.

• 선택형: 기본적으로 비활성화되어 있습니다.
• 예약 실행: 활성화하면 memory-core가 전체 Dreaming 스윕을 수행하는 반복 Cron 작업 하나를 자동으로 관리합니다.
• 임계값 적용: 승격하려면 점수, 회상 빈도, 쿼리 다양성 조건을 통과해야 합니다.
• 검토 가능: 사람이 검토할 수 있도록 단계 요약과 일기 항목을 DREAMS.md에 기록합니다.

단계별 동작, 점수 산정 신호, Dream Diary 세부 정보는 Dreaming을 참조하세요.

근거 기반 과거 보충과 실시간 승격

Dreaming 시스템에는 서로 관련된 두 가지 검토 경로가 있습니다.

• 실시간 Dreaming은 memory/.dreams/ 아래의 단기 Dreaming 저장소를 사용하며, 일반 심층 단계에서 어떤 항목을 MEMORY.md로 승격할지 결정할 때 활용됩니다.
• 근거 기반 과거 보충은 과거 memory/YYYY-MM-DD.md 메모를 독립된 일별 파일로 읽고 구조화된 검토 결과를 DREAMS.md에 기록합니다.

근거 기반 과거 보충을 사용하면 MEMORY.md를 직접 편집하지 않고도 이전 메모를 다시 처리하고 시스템이 어떤 내용을 지속적으로 보존할 가치가 있다고 판단하는지 살펴볼 수 있습니다.

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

--stage-short-term 플래그는 근거를 갖춘 지속적 보존 후보를 일반 심층 단계에서 이미 사용하는 동일한 단기 Dreaming 저장소에 준비하며, 후보를 직접 승격하지는 않습니다. 따라서 다음과 같이 구분됩니다.

• DREAMS.md는 사람이 검토하는 영역으로 유지됩니다.
• 단기 저장소는 기계가 순위를 산정하는 영역으로 유지됩니다.
• MEMORY.md는 여전히 심층 승격을 통해서만 작성됩니다.

일반적인 일기 항목이나 일반 회상 상태에 영향을 주지 않고 재처리를 되돌리려면 다음을 실행하세요.

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

CLI

openclaw memory status          # Check index status and provideropenclaw memory search "query"  # Search from the command lineopenclaw memory index --force   # Rebuild the index

추가 자료

• 메모리 검색: 검색 파이프라인, 공급자, 조정 방법
• 내장 메모리 엔진: 기본 SQLite 백엔드
• QMD 메모리 엔진: 고급 로컬 우선 사이드카
• Honcho 메모리: AI 네이티브 세션 간 메모리
• Memory LanceDB: OpenAI 호환 임베딩을 사용하는 LanceDB 기반 Plugin
• Memory Wiki: 컴파일된 지식 저장소와 위키 네이티브 도구
• Dreaming: 단기 회상에서 장기 메모리로의 백그라운드 승격
• 메모리 구성 참고 자료: 모든 구성 옵션
• Compaction: Compaction과 메모리의 상호 작용 방식
• Active Memory: 대화형 채팅 세션을 위한 하위 에이전트 메모리