내 PC/서버에 직접 설치해 텔레그램·디스코드로 제어하는 셀프호스팅 AI 에이전트 플랫폼입니다.
외부 서버 없이 로컬 환경에서 Claude, GPT 등 LLM을 연결해 나만의 AI 직원을 구성할 수 있습니다.
"내 AI 에이전트는 왜 며칠 전 대화를 기억하지 못할까?", "API 요금이 갑자기 왜 이렇게 많이 나왔지?", "내가 부르지 않아도 스스로 주기적인 알림을 주게 할 수는 없을까?" 셀프호스팅 AI를 운영하다 보면 누구나 한 번쯤 마주하는 고민들입니다.
이번 14편에서는 openclaw agent 메모리의 4가지 핵심 메커니즘—Context Pruning, Compaction, Memory Search, Heartbeat—을 처음부터 끝까지 해설합니다. 이 원리를 이해하면 API 비용을 최소화하면서도 진정으로 '기억하는' AI 에이전트를 구축할 수 있습니다.
지난 편(이전: OpenClaw 아키텍처 완전 해설 — Gateway·Node·Client 관계 이해)에서는 Gateway·Node·Client 세 계층이 어떻게 맞물려 작동하는지 큰 그림을 살펴보았습니다. 이번 편에서는 그 구조 안에서 실제 '뇌(Brain)' 역할을 하는 에이전트의 메모리 메커니즘을 해부합니다.
Context Pruning — 불필요한 단기 기억 잘라내기
에이전트의 기억 관리에서 가장 먼저 이해해야 할 개념이 contextPruning(문맥 가지치기)입니다. AI 에이전트는 대화를 나눌 때마다 이전 대화 기록(Context)과 툴 사용 결과를 계속해서 누적합니다. 이를 방치하면 세션 파일이 수 MB 단위로 거대해지고, 모델의 최대 토큰 한계를 초과해 AI가 갑자기 응답을 멈추거나 API 비용이 폭발적으로 증가하는 사태가 벌어집니다.
이를 방지하기 위해 LLM 호출 직전에 오래되거나 거대한 툴 실행 결과를 자동으로 잘라내는 설정이 필요합니다. agents.defaults 블록 안에 아래와 같이 설정합니다.
// ~/.openclaw/openclaw.json 설정 예시
{
"agents": {
"defaults": {
"contextPruning": {
"mode": "cache-ttl",
"ttl": "6h",
"keepLastAssistants": 3
}
}
}
}각 설정 항목의 의미
mode: "cache-ttl": 프롬프트 캐시 만료 시간에 맞춰 오래된 문맥을 자동 정리합니다.ttl: "6h": 6시간 동안 캐시를 유지합니다. 빈번한 대화를 나눈다면 더 길게, 간헐적이라면 더 짧게 조정하세요.keepLastAssistants: 3: 맥락 연속성을 위해 가장 최근의 AI 응답 3개는 삭제하지 않고 보존합니다.
contextPruning은 반드시 agents.defaults 블록 안에 설정해야 전역으로 적용됩니다. 개별 에이전트 설정에 넣어도 동작하지 않을 수 있으니 주의하세요. 📎 OpenClaw 공식 문서 원문 보기 →
contextPruning으로 오래된 단기 기억을 주기적으로 정리해 토큰 낭비를 막습니다. keepLastAssistants로 최근 대화의 연속성은 유지하면서 불필요한 기록만 선별 삭제합니다.Compaction & Memory Flush — 핵심을 장기 기억으로 압축하기
단기 기억을 가지치기했다면, 그중 중요한 정보는 '장기 기억'으로 넘겨야 합니다. 컨텍스트 윈도우가 설정한 한계(softThresholdTokens)에 다다르면 OpenClaw의 compaction 기능이 발동합니다. 과거의 방대한 대화를 짧은 요약본으로 압축하여 교체하는 것이 이 기능의 핵심입니다.
특히 memoryFlush를 활성화하면 에이전트가 "이 대화에서 무엇을 기억해야 하는지" 핵심 결정 사항이나 상태 변화를 추출하여 memory/YYYY-MM-DD.md 형태의 마크다운 파일로 영구 저장합니다. 이것이 진정한 '장기 기억'의 구현 방식입니다.
// ~/.openclaw/openclaw.json 설정 예시
{
"agents": {
"defaults": {
"compaction": {
"mode": "safeguard",
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 40000,
"prompt": "Extract key decisions, state changes to memory/YYYY-MM-DD.md. Skip routine work. NO_FLUSH if nothing important."
}
}
}
}
}설정 항목 해설
mode: "safeguard": 매우 긴 대화 기록을 안전하게 분할·요약합니다.softThresholdTokens: 40000: 컨텍스트가 4만 토큰을 넘어서면 Compaction을 트리거합니다.- prompt의
NO_FLUSH: 중요한 내용이 없으면 파일 저장 자체를 건너뛰어 불필요한 파일 생성을 막습니다.
Memory Search — 과거의 기억 되살리기
장기 기억 파일을 저장해 두었다면, 이제 필요할 때 자동으로 꺼내보는 기능이 필요합니다. 바로 임베딩(Embedding) 모델을 활용한 Memory Search입니다. 사용자의 질문과 의미적으로 유사한 과거 기억 파일을 벡터 검색으로 자동 탐색해 AI가 참고하도록 주입합니다.
수천 번의 검색을 수행해도 비용이 매우 저렴한 임베딩 전용 모델(text-embedding-3-small 등)을 사용하므로 비용 부담이 거의 없습니다.
{
"agents": {
"defaults": {
"memorySearch": {
"enabled": true,
"sources": ["memory", "sessions"],
"provider": "openai",
"model": "text-embedding-3-small"
}
}
}
}sources 항목 설명
"memory":memoryFlush로 저장된memory/*.md파일들을 대상으로 검색합니다."sessions": 이전 세션의 대화 기록도 검색 대상에 포함합니다. 오래된 대화에서도 관련 맥락을 찾아 활용할 수 있습니다.
memorySearch는 memoryFlush와 함께 사용할 때 진가를 발휘합니다. 저장된 기억이 없으면 검색도 무의미합니다. 두 설정을 반드시 함께 활성화하세요.Heartbeat — 스스로 깨어나 작동하는 심장
내가 직접 말을 걸지 않아도 AI가 백그라운드에서 파일 상태를 읽거나 특정 조건을 검사하여 알림을 주게 만드는 기능이 바로 Heartbeat(하트비트)입니다. 진정한 자동화 에이전트의 핵심 기능으로, 예를 들어 "매 30분마다 특정 폴더를 확인해서 새 파일이 생기면 텔레그램으로 알려줘" 같은 시나리오를 구현할 수 있습니다.
{
"agents": {
"defaults": {
"heartbeat": {
"model": "openrouter/openai/gpt-4o-mini"
}
}
}
}Heartbeat 모델 선택이 중요한 이유
Heartbeat는 하루에도 수십~수백 번 자동으로 실행될 수 있습니다. 따라서 모델 선택이 비용에 직결됩니다. gpt-4o-mini나 gpt-5-nano처럼 가장 저렴하고 가벼운 모델을 지정하는 것이 필수입니다. Claude Sonnet이나 GPT-4 같은 고성능 모델을 배정하면 한 달 API 비용이 예상치 못하게 폭증할 수 있습니다.
실전 팁과 주의사항
- 모든 에이전트 설정은
agents.defaults에 전역으로 설정:contextPruning,compaction같은 코어 설정은 개별 에이전트 블록에 넣어도 무시될 수 있습니다. 반드시agents.defaults블록 안에 위치시키고, 수정 후openclaw doctor --fix로 설정 위치를 검증하세요. - Memory Flush와 Memory Search는 반드시 함께 활성화: 기억을 저장(
memoryFlush)하더라도 검색(memorySearch)을 켜지 않으면 AI가 과거 기억을 참조하지 못합니다. 두 설정은 항상 쌍으로 운영하세요. - Heartbeat 모델은 가장 저렴한 모델로 고정: Heartbeat는 백그라운드에서 자동 반복 실행됩니다.
gpt-4o-mini수준의 저비용 모델을 배정하지 않으면 월 API 비용이 예상치 못하게 치솟을 수 있습니다. - Memory Flush의 NO_FLUSH 지시어 활용: 프롬프트에 "중요한 내용이 없으면 NO_FLUSH로 기록 스킵" 지시를 반드시 포함하세요. 이 지시가 없으면 일상적인 대화까지 모두 파일로 저장되어 검색 품질이 저하되고 디스크 공간을 낭비합니다.
자주 묻는 질문 (FAQ)
- 에이전트가 자꾸 예전 대화를 까먹는데 어떻게 해야 하나요?
memoryFlush가 비활성화되어 있거나,memorySearch가 꺼져 있을 가능성이 높습니다. 본문의 예시처럼 두 기능을 모두 활성화하고, AI가 중요한 맥락을 마크다운 파일로 저장하도록 프롬프트를 설정해 보세요. 저장된 기억이 있어도 검색이 꺼져 있으면 AI가 과거 기억을 참조하지 못합니다.- Memory Flush 파일이 쌓이면 서버 용량을 많이 차지하지 않나요?
- 거의 차지하지 않습니다. 텍스트 기반의 마크다운 포맷으로 핵심 내용만 요약 저장하기 때문에 파일 하나의 크기가 매우 작습니다. 오히려 수십만 토큰의 대화 내역을 매번 AI에 전송하는 것보다 API 비용과 서버 메모리를 획기적으로 절약하는 최적의 셀프호스팅 AI 운영 방식입니다.
- Heartbeat 모델로 Claude Sonnet이나 GPT-4를 쓰면 안 되나요?
- 기술적으로는 가능하지만 권장하지 않습니다. Heartbeat는 내가 잠든 시간에도 주기적으로 자동 실행되어 "새로운 변화가 있는지" 확인합니다. 비싼 모델을 배정하면 한 달 API 비용이 수십 달러 이상 낭비될 수 있습니다. 반드시
gpt-4o-mini처럼 가장 저렴한 모델로 지정하세요. - 설정 파일을 수정했는데 에이전트 기억력에 변화가 없어요.
contextPruning이나compaction설정이agents.defaults블록이 아닌 다른 위치에 들어갔을 가능성이 높습니다. 수정 후 반드시 터미널에서openclaw doctor --fix를 실행해 잘못된 위치에 있는 설정 키를 자동으로 교정받으세요.
이 글이 도움이 됐다면 댓글로 여러분의 경험을 알려주세요! 🙌
openclaw agent 메모리 설정에서 막히는 부분은 댓글에 남겨주세요 — 직접 답변드립니다.
📬 새 편 알림 받기 → AI 활용 가이드 구독
댓글