자율형 AI 에이전트의 부상은 소프트웨어 시스템에 새로운 패러다임, 즉 지속형 기계 인지(persistent machine cognition)를 가져왔습니다. 상태를 저장하지 않는 전통적 챗봇과 달리, OpenClaw와 같은 현대적 에이전트 프레임워크는 연속적이고 문맥 인지적인 AI 워크플로를 가능하게 합니다. 이 능력의 핵심에는 OpenClaw의 메모리 시스템이 있으며, 이를 통해 에이전트는 세션을 넘어 지식을 저장, 검색, 진화시킬 수 있습니다.
지속형 메모리는 AI 어시스턴트를 단발성 대화 도구에서 의사결정을 기억하고, 선호를 학습하며, 시간에 걸쳐 프로젝트 수준의 지식을 유지할 수 있는 상태 보존 시스템으로 바꿉니다. 실무적으로 이는 개발자가 에이전트와 상호작용할 때마다 컨텍스트를 반복 설명하거나 워크플로를 매번 재초기화할 필요가 없음을 의미합니다(여전히 OpenClaw를 어떻게 시작하고 구성하는지 궁금하다면, 여기를 참고하세요: CometAPI로 OpenClaw 구성하는 5분 튜토리얼).
그러나 이러한 아키텍처 전환은 복잡한 엔지니어링 과제도 함께 가져옵니다:
- 메모리는 어떻게 저장되고 검색되는가?
- 개발자는 메모리 동작을 어떻게 제어하는가?
- 지속형 에이전트 메모리가 보안에 미치는 영향은 무엇인가?
- LLM 컨텍스트 윈도우를 압도하지 않으면서 메모리를 어떻게 확장할 수 있는가?
이 글은 OpenClaw 메모리 시스템의 아키텍처, 스토리지 모델, 검색 파이프라인, 제어 메커니즘, 보안 고려사항을 포함한 심층 기술 탐구를 제공합니다.
What is OpenClaw?
OpenClaw는 오픈소스의, 워크스페이스 우선(workspace-first) 개인용 AI 어시스턴트로, 여러분의 기기에서 직접 실행합니다. WhatsApp, Telegram, Slack, Discord 등 채팅 플랫폼에 연결하고, Gateway 제어 플레인을 노출하며, 무엇보다도 이 글의 주제와 관련해 워크스페이스 디렉터리 내에 “기억하는 것”을 일반 파일로 보관합니다. 이러한 설계는 메모리를 투명하게 하고 직접 제어 가능하게 합니다. 메모리는 모델 내부의 숨겨진 데이터베이스가 아니라 에이전트 워크스페이스의 파일이 단일 진실의 원천입니다.
Stateless vs Stateful AI Systems
전통적인 대화형 AI 시스템은 무상태(stateless) 모드로 동작합니다. 각 상호작용은 독립적으로 처리되며, 이전 세션에 대한 인식은 프롬프트에 명시적으로 제공되지 않는 한 존재하지 않습니다.
이는 다음과 같은 한계를 만듭니다:
- 세션 간 컨텍스트가 초기화됨
- 사용자가 정보를 반복해야 함
- 장기 학습이 불가능함
- 워크플로가 지속될 수 없음
OpenClaw는 에이전트 워크스페이스에 직접 저장되는 지속형 메모리를 도입하여 이러한 한계를 해결합니다.
언어 모델의 컨텍스트 윈도우에만 의존하는 대신, OpenClaw는 에이전트가 읽고 업데이트할 수 있는 구조화된 파일로 저장되는 로컬 메모리 계층을 유지합니다.
이를 통해 다음이 가능해집니다:
- 세션 간 컨텍스트 연속성
- 장기 지식 저장
- 개인화된 AI 어시스턴트
- 장기간에 걸친 워크플로 자동화
그 결과, OpenClaw는 AI 어시스턴트를 무상태 응답자에서 지식을 보유한 에이전트로 전환합니다.
Memory architecture — the four layers that matter
OpenClaw의 런타임은 정보를 여러 레이어로 구성합니다. 이 레이어를 이해하는 것이 에이전트가 무엇을 기억하고 무엇에 접근할 수 있는지를 제어하는 핵심입니다.
1) Workspace bootstrap files — the durable core
SOUL.md, AGENTS.md, IDENTITY.md, TOOLS.md, MEMORY.md 같은 파일은 워크스페이스 루트에 존재하며 부트스트랩 자료로 취급됩니다. 이들은 세션 시작 시 디스크에서 다시 로드되며 가장 내구적인 메모리입니다. 토큰 컴팩션을 넘어 생존하고, 일시적 세션 기록이 아니라 디스크에서 다시 프롬프트에 주입됩니다. 이 파일을 장기(사용자 선호, 법적 제약, 프로젝트 결정 등) 사실에 사용하세요.
2) Daily/session files — short- to medium-term context
OpenClaw는 대화 기록을 수집하고 세션 파일(예: memory/ 폴더 아래의 일일 노트)을 저장합니다. 이는 최근 컨텍스트와 세션 연속성에 유용하지만, 에이전트의 컨텍스트 윈도우가 너무 커질 때는 정리하거나 컴팩트하게 만들 수 있습니다. 많은 사용자가 memory/2026-03-10.md 같은 일일 노트 파일을 즉석 사실 캡처에 활용합니다.
3) LLM context window — ephemeral but decisive
각 턴의 프롬프트는 부트스트랩 파일, 최근 세션 기록, 검색된 메모리 결과를 조합해 구성됩니다. 이 프롬프트 내 컨텍스트가 LLM이 실제로 답변을 생성할 때 “보는” 것입니다. 이는 휘발성이며(토큰 예산으로 제한), 매 턴마다 재구성됩니다. 에이전트가 일관되게 동작하길 원한다면, 필수 지침은 일시적 메시지에만 두지 말고 부트스트랩 파일에 배치하세요.
4) Semantic index / memory plugin — fast retrieval
에이전트가 과거 노트에서 관련 항목을 찾을 수 있도록, OpenClaw는 Markdown 파일과 선택적 외부 벡터 스토어(sqlite-vec, LanceDB, QMD 등)에 대해 시맨틱 검색을 제공하는 메모리 플러그인(기본값: memory-core)을 사용합니다. 인덱스는 파일과 분리되어 있습니다. 파일이 진실의 원천이고, 인덱스는 검색 속도를 높입니다. 플러그인을 교체해 백엔드 동작(임베딩 제공자, 검색 알고리즘, 영속성)을 변경할 수 있습니다.
How OpenClaw memory Work?
Gateway-Based Agent Architecture
OpenClaw는 여러 시스템 구성요소 간 통신을 오케스트레이션하는 게이트웨이 중심 아키텍처를 사용합니다.
핵심 구성 요소:
| Component | Function |
|---|---|
| Gateway | 통신을 관리하는 중앙 프로세스 |
| Brain | LLM 추론 엔진 |
| Hands | 실행 레이어 (셸, 파일시스템, 브라우저) |
| Memory | 지속적 지식 저장소 |
| Channels | 메시징 인터페이스 |
| Skills | 확장 가능한 자동화 모듈 |
이 아키텍처에서 메모리는 에이전트 지식의 장기 저장 계층 역할을 합니다.
Memory as files (the canonical truth)
OpenClaw는 에이전트 워크스페이스에 있는 일반 Markdown 파일을 메모리 모델의 중심에 둡니다. 에이전트는 이 파일에 쓰고 이 파일에서 읽습니다. 이들은 지속적이며 사람이 편집 가능한 저장소입니다. LLM은 오직 디스크에 기록된 것만 “기억”합니다. 휘발성 세션 컨텍스트는 별개입니다. 일반적인 파일과 관례는 다음과 같습니다:
MEMORY.md— 큐레이션된 장기·내구 메모리 항목(결정, 사용자 프로필 사실, 지속적 선호).memory/YYYY-MM-DD.md— 추가 전용 일일 로그로, 일일/휘발성 메모리에 사용.USER.md,SOUL.md,AGENTS.md— 에이전트 성격이나 동작에 영향을 주는 기타 워크스페이스 파일.
이러한 파일은 에이전트 워크스페이스(기본~/.openclaw/workspace)에 있으며, 언제든지 읽거나 편집할 수 있습니다.
Two access paths: file-backed + index-backed
일반 파일만으로는 대규모 시맨틱 검색이 비효율적이기 때문에, OpenClaw는 Markdown 소스에 인덱스(벡터 스토어 + 선택적 BM25 텍스트 인덱스)를 결합합니다. 인덱스는 에이전트가 사용하는 memory_search 도구에서 활용되며, 특정 읽기는 파일/라인 범위를 직접 읽는 memory_get을 사용합니다. 임베딩(벡터) + BM25(키워드)의 하이브리드 인덱싱 접근법은 시맨틱 회상력과 정확 일치 신뢰성을 모두 제공합니다. 전형적인 인덱스 저장소는 벡터 검색으로 확장된 로컬 SQLite 파일입니다(예: ~/.openclaw/agents/<agentId>/index.sqlite).
memory_search(query, topK)— 메타데이터(경로, 라인, 점수)와 함께 순위화된 일치 스니펫 리스트를 반환합니다. 답변 전 “우선 검색”이 필요할 때 사용합니다.memory_get(path, startLine, endLine)— Markdown 파일의 원시 슬라이스를 반환합니다. 메모리 위치를 이미 알고 있을 때 사용합니다.
이는 내장 에이전트 도구이며, 스킬과 커스텀 코드에서도 필요에 따라 호출할 수 있습니다.
Lifecycle: write, index, recall, flush, compact
OpenClaw는 명시적 메모리 라이프사이클을 구현합니다:
- 쓰기(Write) — 메모리 가치가 있는 이벤트가 발생하면(명시적 요청, 결정 기록, 자동 메모리 플러시) 에이전트가 Markdown 파일에 메모리를 기록합니다.
- 인덱싱(Index) — 파일 워처와 배치 작업이 새/변경 파일을 벡터 + BM25 저장소에 점진적으로 인덱싱합니다.
- 회수(Recall) — 세션 중 에이전트가
memory_search(시맨틱) 또는memory_get(타깃) 호출을 통해 메모리를 불러옵니다. - 메모리 플러시(사전 컴팩션) — 세션 컨텍스트가 모델 윈도우 한계에 가까워지면, OpenClaw는 컴팩션 전에 반드시 보존해야 한다고 판단한 내용을 디스크에 기록하는 묵시적 에이전트 턴을 트리거합니다(구성 가능).
- 컴팩션(Compaction) — 활성 세션을 작게 유지하기 위해 컨텍스트를 압축/요약합니다. 메모리 파일은 내구성 있는 폴백입니다.
Chunking and embedding pipeline(technical detail)
파일을 인덱싱할 때는 청킹(~300–500 토큰/청크, 오버랩 포함 같은 일반적 휴리스틱 적용) 후, 각 청크를 선택한 제공자(OpenAI, Gemini, 로컬 GGUF 임베딩 등)를 사용해 임베딩으로 변환합니다. 결과 벡터는 소스 메타데이터(파일 경로, 시작/끝 라인, 타임스탬프)와 함께 저장되어 검색에 활용됩니다. 검색 시에는 쿼리 임베딩을 계산하고, 벡터 공간에서 근접 이웃 검색을 수행한 뒤, 필요 시 BM25 점수와 리랭커를 결합합니다. 이 하이브리드 접근법은 패러프레이즈된 콘텐츠에 대한 시맨틱 회상을 유지하면서 사실 질의의 정밀도를 개선합니다.
Concrete: how to control memory (commands, files, config)
아래는 표준 로컬 설치(기본 워크스페이스: ~/.openclaw/workspace, agents.defaults.workspace로 오버라이드 가능)를 가정한 상태에서 운영자와 개발자가 OpenClaw의 메모리를 점검, 수정, 제어하기 위해 사용할 수 있는 단계별 실무 액션입니다.
Inspect and back up the raw memory files
메모리는 Markdown입니다. 워크스페이스를 백업하거나 최소한 MEMORY.md와 memory/ 폴더를 복사하세요.
셸 예시:
# 워크스페이스 위치 표시(권장)openclaw config get agents.defaults.workspace# 메모리 파일을 타임스탬프가 포함된 백업으로 복사cp -r ~/.openclaw/workspace ~/.openclaw/workspace-backup-$(date +%F-%H%M)# 또는 메모리 파일만:cp ~/.openclaw/workspace/MEMORY.md ~/backups/opencaw-MEMORY-$(date +%F).mdcp -r ~/.openclaw/workspace/memory ~/backups/opencaw-memory-$(date +%F)/
문서와 커뮤니티 가이드는 내보내기/백업을 위해 MEMORY.md + memory/ 복사를 명시적으로 권장합니다.
Edit MEMORY.md — the recommended way to encode long-term facts
안정적인 선호와 사실을 MEMORY.md에 넣으세요. 이 파일은 세션 시작 시 컨텍스트에 직접 주입되도록 읽힙니다.
예시 MEMORY.md 스니펫:
# MEMORY.md## User preferences- timezone: Asia/Tokyo- prefers_brief_responses: true- default_calendar: personal@gmail.com## Projects- acme-internal: deploy target Cloudflare Workers, main repo: github.com/org/acme
편집 후 새 세션의 파일 읽기를 위해 재시작은 필요하지 않습니다. 다만 플러그인 인덱스에 의존하는 경우 재인덱싱이 필요할 수 있습니다(아래 참고).
Programmatically writing memory (Node.js example)
메모리가 파일이기 때문에, 간단한 스크립트로 메모리 항목을 추가하거나 생성할 수 있습니다. 이는 외부 시스템이 에이전트 워크스페이스에 사실을 기록하려는 경우 유용합니다.
// append-memory.js (Node.js)import {writeFileSync, appendFileSync} from 'fs';import {homedir} from 'os';import path from 'path';const ws = path.join(homedir(), '.openclaw', 'workspace');const mdPath = path.join(ws, 'memory', `${new Date().toISOString().slice(0,10)}.md`);// 폴더가 존재하는지 확인하고 사실을 추가appendFileSync(mdPath, `\n- ${new Date().toISOString()}: Completed deployment for project X\n`);console.log(`${mdPath}에 기록했습니다`);
팁: 작성 전에 워크스페이스 경로를 확인하려면 openclaw config get agents.defaults.workspace를 사용하세요.
Reindexing and plugin control
메모리 파일을 변경했고 시맨틱 검색에 의존한다면, 재인덱싱(또는 플러그인의 자동 인덱서 대기)이 필요합니다.
- 어떤 플러그인이 활성화되어 있는지 확인:
openclaw config get plugins.slots.memory - 재인덱싱(플러그인에 따라 다름 — 많은 플러그인이
openclaw memory reindex같은 CLI를 제공하거나 Gateway 재시작이 필요함)
메모리 플러그인을 비활성화(파일 전용 동작 강제)하는 구성 예시:
// ~/.openclaw/openclaw.json (partial){ "plugins": { "slots": { "memory": "none" } }}
플러그인 설정을 변경한 후, 구성을 반영하려면 Gateway를 재시작하세요:
openclaw gateway restart
문서와 구성 참조는 plugins.slots.memory와 plugins.installs가 메모리 플러그인 관리를 위한 제어 항목임을 구체적으로 보여줍니다.
Swap memory backends — example: add a LanceDB plugin
기본 메모리 백엔드를 더 대규모 벡터 스토어로 교체하는 커뮤니티 플러그인이 존재합니다. 예시 패턴(널리 사용되는 커뮤니티 플러그인에서):
# 워크스페이스 루트에서cd ~/.openclaw/workspacegit clone https://github.com/win4r/memory-lancedb-pro.git plugins/memory-lancedb-procd plugins/memory-lancedb-pronpm install# 그런 다음 openclaw.json을 업데이트해 'memory-lancedb-pro' 플러그인을 활성화# 그리고 게이트웨이 재시작:openclaw gateway restart
플러그인 README와 작성자는 plugins.load.paths에 절대 경로 사용과 임베딩 API 키용 명시적 환경 변수를 권장합니다.
CLI memory search and troubleshooting
OpenClaw는 시맨틱 인덱스를 검색하거나 관리하기 위한 openclaw memory 같은 CLI 도우미를 제공합니다. 플러그인별 이슈에 유의하세요(예: QMD 백엔드 사용자는 재구성이 필요한 인덱스/검색 불일치 문제를 보고했습니다). 결과가 누락된다면, 재인덱싱하고 플러그인 로그를 확인하세요.
Memory as files (the canonical truth)
OpenClaw는 에이전트 워크스페이스에 있는 일반 Markdown 파일을 메모리 모델의 중심에 둡니다. 에이전트는 이 파일에 쓰고 이 파일에서 읽습니다. 이들은 지속적이며 사람이 편집 가능한 저장소입니다. LLM은 오직 디스크에 기록된 것만 “기억”합니다. 휘발성 세션 컨텍스트는 별개입니다. 일반적인 파일과 관례는 다음과 같습니다:
MEMORY.md— 큐레이션된 장기·내구 메모리 항목(결정, 사용자 프로필 사실, 지속적 선호).memory/YYYY-MM-DD.md— 추가 전용 일일 로그로, 일일/휘발성 메모리에 사용.USER.md,SOUL.md,AGENTS.md— 에이전트 성격이나 동작에 영향을 주는 기타 워크스페이스 파일.
이러한 파일은 에이전트 워크스페이스(기본~/.openclaw/workspace)에 있으며, 언제든지 읽거나 편집할 수 있습니다.
Conclusion
OpenClaw의 메모리 시스템은 AI 아키텍처의 근본적 변화를 나타냅니다.
일시적인 대화 대신, 이 플랫폼은 시간이 지남에 따라 AI 에이전트가 지식을 축적할 수 있게 하는 지속적이며 개발자 제어형 메모리 계층을 도입합니다.
이 설계는 다음을 강조합니다:
- 파일 기반 스토리지를 통한 투명성
- 임베딩 기반 검색을 통한 확장성
- 구성(configuration)을 통한 개발자 제어
- 플러그인을 통한 확장성
그러나 지속형 메모리는 개발자가 신중히 관리해야 하는 새로운 엔지니어링 및 보안 과제도 함께 가져옵니다.
자율형 에이전트의 성능이 더 강력해지고 보급이 확대됨에 따라, OpenClaw와 같은 메모리 시스템은 차세대 지능형 소프트웨어 시스템의 핵심 구성 요소가 될 가능성이 큽니다.
CometAPI는 이제 openclaw와 통합됩니다. Claude, Gemini, GPT-5 Series를 지원하는 API를 찾고 있다면, CometAPI는 openclaw 사용에 최적의 선택이며, API 가격은 지속적으로 할인되고 있습니다.). OpenClaw는 최근 GPT-5.4와의 호환성을 업데이트하고 워크플로를 최적화했습니다. 이제 CometAPI의 GPT-5.4를 통해서도 OpenClaw를 구성할 수 있습니다.
Ready to Go?→ 오늘 OpenClaw에 가입하세요