OpenClaw 로컬 메모리 시스템 분석: Markdown 파일로 AI 기억 저장하기

지난주 AI에게 분석을 맡겼던 아키텍처 방안을 대화 기록에서 찾아보니 이미 다른 내용에 밀려 사라진 뒤였습니다. AI 어시스턴트는 문제를 해결해 줄 수 있지만 기억이 짧아 대화가 끝나면 앞서 나눈 내용도 거의 잊어버립니다. 더 중요한 문제도 있습니다. 이 대화 데이터는 어디로 갈까요? 클라우드 서버에 저장될까요? 누가 볼 수 있을까요?

OpenClaw는 AI의 모든 기억을 Markdown 파일로 저장하며, 데이터는 로컬 디스크에 그대로 남습니다. 이 방식은 두 가지 문제를 해결합니다. AI에 장기 기억을 부여하면서도 데이터를 클라우드에 업로드하지 않습니다.

이 글에서는 OpenClaw의 메모리 시스템을 살펴봅니다. 2계층 아키텍처(임시 로그 + 영구 지식), 하이브리드 검색(BM25 키워드 + 벡터 의미 검색), 로컬 개인정보 보호 메커니즘을 차례로 설명합니다. 데이터를 온전히 통제할 수 있고, 언제든 VSCode로 열어 편집할 수 있으며 Git 버전 관리도 지원합니다.

저비용 ‘새우 키우기’ 가이드: ArkClaw로 AI Agent를 누구나 쉽게 사용하기

요즘 인기 있는 OpenClaw(바닷가재)는 유용하지만 설정 장벽이 너무 높다고 느끼셨나요? ByteDance Volcano Engine이 내놓은 ArkClaw는 그 문턱을 크게 낮췄습니다. 서버나 Token 설정을 씨름하지 않아도 클릭 한 번으로 24시간 온라인 상태를 유지하며 브라우저를 제어하고, 스크립트를 실행하고, 일정을 관리하는 ‘AI 일꾼’을 사용할 수 있습니다.

핵심은 실제로 저렴하다는 점입니다. 월 요금은 9.9위안이며, 제 초대 코드 ZLKUK54M을 사용해 여기에서 가입하면 8.9위안입니다. 프로그래머라면 Coding Plan Pro를 선택해 무료로 이용할 수도 있습니다.

Markdown을 선택한 이유: 파일 우선 설계 철학

솔직히 처음 OpenClaw가 Markdown으로 AI 기억을 저장한다는 말을 들었을 때는 조금 의아했습니다. Markdown은 문서 작성용 아닌가요? 어떻게 데이터베이스 역할까지 할 수 있을까요?

하지만 곰곰이 생각해 보면 꽤 영리한 설계입니다.

AI의 모든 기억이 PostgreSQL에 들어 있다고 생각해 봅시다. AI가 무엇을 기억하는지 보려면 데이터베이스 클라이언트를 열고 SQL 쿼리를 작성해야 합니다. 생각만 해도 번거롭습니다. 반면 Markdown 파일이라면 어떨까요? VSCode에서 바로 열면 내용을 한눈에 볼 수 있습니다. 수정하고 싶다면 편집기에서 고쳐 저장하면 됩니다. 백업하려면 폴더를 복사하고, 지난주 상태로 되돌리고 싶다면 Git 명령 하나면 충분합니다.

OpenClaw의 개발자는 이 설계 철학을 ‘파일 우선’(File-first)이라고 부릅니다. 본질적으로 Markdown 파일을 ‘단일 진실 공급원’(Single Source of Truth)으로 삼아 모든 데이터를 파일에 저장하고, 데이터베이스는 인덱싱과 검색 가속에만 사용합니다.

이 철학은 Anthropic이 권장하는 NOTES.md 패턴과 맥이 닿아 있습니다. Claude 공식 안내에서는 프로젝트 안에 NOTES.md 파일을 두고 개발 과정의 주요 결정과 맥락을 기록하라고 권장합니다. 그러면 AI 어시스턴트가 매번 이 파일을 읽어 일관된 맥락을 유지할 수 있습니다. OpenClaw는 이 아이디어를 한 단계 더 밀어붙였습니다. 파일 하나에 그치지 않고 전체 메모리 시스템을 Markdown 기반으로 만든 것입니다.

기존 방식과 비교해 보겠습니다.

• Redis/인메모리 데이터베이스: 성능은 좋지만 재시작하면 데이터가 사라지므로 별도 영속화가 필요합니다.
• PostgreSQL/MySQL: 기능은 강력하지만 무겁고 운영이 필요하며 데이터를 직관적으로 보기 어렵습니다.
• 벡터 데이터베이스(Pinecone 등): AI에 특화됐지만 대개 클라우드 서비스여서 데이터가 로컬을 벗어납니다.

Markdown 방식의 장점은 분명합니다.

1. 사람이 읽을 수 있음: 파일을 언제든 열어 AI가 무엇을 기억하는지 확인할 수 있습니다.
2. 완전한 통제: 데이터가 내 디스크에 있으므로 원하는 대로 백업하고, 삭제하고, 암호화할 수 있습니다.
3. Git 친화적: 버전 관리로 기억의 변화를 추적하고 여러 사람이 협업할 수도 있습니다.
4. 의존성 없음: 데이터베이스 서비스, Docker, 클라우드 서비스가 필요하지 않습니다.

물론 이 방식도 완벽하지는 않습니다. 가장 큰 문제는 검색 효율입니다. 대량의 텍스트 파일에서 관련 내용을 어떻게 빠르게 찾을 수 있을까요? 이 문제는 뒤에서 살펴보겠습니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

2계층 메모리 아키텍처: 임시 기억과 영구 기억의 균형

OpenClaw의 메모리 시스템은 인간의 뇌와 꽤 비슷하게 설계됐습니다. 사람에게 단기 기억과 장기 기억이 있듯 OpenClaw도 임시 로그(Daily Logs)와 영구 지식(Curated Knowledge)의 두 계층으로 나뉩니다.

임시 로그는 단기 기억과 같습니다. 오늘 무엇을 했고 방금 무슨 말을 했는지를 memory/YYYY-MM-DD.md 형식의 로그 파일에 저장합니다. 예를 들어 오늘이 2026년 2월 5일이면 OpenClaw는 memory/2026-02-05.md를 자동으로 만들고 모든 활동을 Append-only 방식으로 추가합니다.

이 설계가 영리한 이유는 OpenClaw가 오늘과 어제의 로그를 자동으로 불러온다는 데 있습니다. 왜 이틀일까요? 최근 맥락을 이어갈 수 있기 때문입니다. 어제 AI에게 한 말을 오늘도 기억합니다. 그보다 오래된 로그는 자동으로 불러오지 않습니다. 모두 불러오면 컨텍스트 창이 넘칠 수 있기 때문입니다.

영구 지식은 정리된 장기 기억으로, 전용 MEMORY 디렉터리에 저장됩니다. 이 파일들은 프로젝트 아키텍처 문서, 주요 결정 기록, 자주 쓰는 코드 조각처럼 수동 또는 자동으로 추출한 중요한 정보입니다.

다음과 같은 구조를 생각해 볼 수 있습니다.

memory/
├── 2026-02-01.md          # 오래된 로그, 자동으로 불러오지 않음
├── 2026-02-04.md          # 어제 로그, 자동으로 불러옴
├── 2026-02-05.md          # 오늘 로그, 자동으로 불러옴
└── MEMORY/
    ├── project-architecture.md   # 영구 지식, 필요할 때 검색
    ├── deployment-notes.md
    └── troubleshooting-guide.md

AI가 시작될 때마다 최근 이틀의 로그 파일을 직접 읽어 컨텍스트 창에 넣습니다. 덕분에 어제 이야기하다 멈춘 주제도 오늘 자연스럽게 이어갈 수 있습니다. 하지만 한 달 전에 기록한 정보를 찾으려면 검색 시스템으로 MEMORY 디렉터리를 뒤져야 합니다.

이 2계층 아키텍처에는 실용적인 기능이 하나 더 있습니다. 바로 자동 보관입니다. 로그 파일이 너무 많이 쌓이면 OpenClaw가 flush 메커니즘을 작동시켜 오래된 로그를 압축하거나 보관하고 디스크가 가득 차는 일을 막습니다. 중요한 정보는 수동 또는 자동으로 영구 저장소에 추출할 수 있습니다.

솔직히 이 설계를 보면 인간의 망각 곡선이 떠오릅니다. 모든 기억을 영원히 저장할 필요는 없으며, 대부분의 임시 정보는 자연스럽게 잊히는 편이 나을 때도 있습니다. 정말 중요한 내용만 장기 기억에 쌓입니다.

효율적인 검색: SQLite 벡터 검색을 결합한 하이브리드 방식

이제 문제가 생깁니다. Markdown 파일이 수백 개라면 관련 내용을 어떻게 빠르게 찾을 수 있을까요?

grep이나 전문 검색만으로는 부족합니다. ‘컨테이너 애플리케이션 배포 방법’을 찾고 싶은데 파일에는 ‘Docker 이미지 빌드와 K8s 배포 절차’라고 적혀 있다고 해 봅시다. 키워드가 일치하지 않으므로 결과를 찾지 못합니다. 순수 텍스트 검색은 글자 그대로만 일치시킬 뿐 의미를 이해하지 못한다는 한계가 있습니다.

OpenClaw의 해법은 하이브리드 검색입니다. 키워드 검색(BM25 알고리즘)과 의미 검색(벡터 유사도)을 결합합니다.

구체적인 방식은 다음과 같습니다.

1. 인덱스 계층: SQLite로 인덱스를 만듭니다. Markdown 파일에 쓸 때마다 OpenClaw가 내용을 작은 조각(chunks)으로 나눈 뒤 다음 작업을 수행합니다.

   • SQLite의 FTS5(Full-Text Search) 엔진으로 전문 인덱스를 만들어 키워드를 빠르게 일치시킵니다.
   • Embedding API를 호출해 텍스트를 벡터로 변환하고 SQLite에 저장합니다.

2. 검색 시점: ‘컨테이너 애플리케이션 배포 방법’을 물으면 시스템은 다음과 같이 처리합니다.

   • BM25 검색으로 ‘배포’, ‘컨테이너’ 키워드가 포함된 텍스트 조각을 찾습니다.
   • 벡터 검색으로 의미상 가장 관련성이 높은 텍스트 조각을 찾습니다.
   • 두 결과의 점수를 혼합해 Top-K를 반환합니다.

이 방식은 키워드 일치가 빠르고 의미 검색은 정확하다는 장점이 있습니다. 두 방식이 서로 보완하므로 정확한 쿼리와 모호한 개념 질문을 모두 처리할 수 있습니다.

벡터 검색을 이야기하려면 Embedding 모델 선택도 빼놓을 수 없습니다. OpenClaw는 세 가지 방식을 지원합니다.

• 로컬 모델: 완전히 오프라인으로 작동해 데이터가 로컬을 벗어나지 않지만 API보다 결과가 떨어질 수 있습니다.
• OpenAI Embedding API: 결과는 좋지만 클라우드 서비스를 호출하므로 API 키가 필요합니다.
• Gemini Embedding API: Google 방식이며 무료 할당량이 더 큽니다.

시스템은 설정에 따라 자동으로 선택합니다. 개인정보 보호를 특히 중요하게 생각한다면 로컬 모델을, 결과 품질을 중시한다면 OpenAI 또는 Gemini를 사용할 수 있습니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

저도 이 하이브리드 검색을 써 봤는데 grep만 사용하는 것보다 확실히 훨씬 나았습니다. 예전에 ‘Nginx 리버스 프록시 설정’이라는 메모를 기록한 뒤 나중에 ‘로드 밸런싱 설정 방법’을 물었더니, 당시 ‘로드 밸런싱’이라는 단어를 쓰지 않았는데도 그 메모를 찾아냈습니다. 이것이 의미 검색의 힘입니다.

개인정보 보호와 보안: 로컬 우선 보호 메커니즘

데이터 저장을 이야기할 때 개인정보 보호 문제를 피할 수는 없습니다.

많은 사람이 AI 어시스턴트를 사용할 때 회사 내부 아키텍처, 고객 데이터, 개인 정보 같은 민감한 내용을 무의식적으로 피합니다. 왜일까요? 이 대화가 클라우드에 업로드되는지, 모델 학습에 사용되는지, 제3자가 볼 수 있는지 알 수 없기 때문입니다.

OpenClaw의 ‘로컬 우선’ 아키텍처는 이 문제를 구조적으로 해결합니다. 모든 메모리 파일은 로컬 디스크에 저장되며 어떤 곳에도 자동으로 업로드되지 않습니다. 클라우드에 백업하려면 Dropbox나 Git으로 직접 동기화하고, 암호화하려면 VeraCrypt나 FileVault를 직접 사용하면 됩니다. 통제권은 온전히 사용자에게 있습니다.

이 설계 철학은 요즘 널리 쓰이는 ‘Local-first Software’ 개념과 같습니다. 데이터 주권은 사용자에게 있고 소프트웨어는 도구일 뿐입니다.

하지만 로컬 저장이 절대적인 안전을 뜻하지는 않습니다. OpenClaw에도 몇 가지 보안 과제가 있습니다.

1. API 키 노출: 메모리 파일에 API 키를 실수로 기록한 뒤 파일을 GitHub 공개 저장소에 동기화하면 큰 문제가 됩니다.
2. 파일 시스템 권한: OpenClaw는 실행 중 memory 디렉터리를 읽고 쓸 수 있어야 합니다. 권한 설정이 잘못되면 악성 프로그램에 악용될 수 있습니다.
3. 악성 skill/plugin: OpenClaw는 확장 skill을 지원합니다. 악성 plugin을 설치하면 로컬 데이터를 빼낼 수 있습니다.
4. 외부에 노출된 인스턴스: 보안 연구에 따르면 인증 없이 인터넷에 노출된 OpenClaw 인스턴스가 수백 개에 달해 누구나 접근할 수 있습니다.

특히 네 번째 항목은 위험합니다. Cisco와 Vectra AI 모두 많은 사용자가 기본 인증조차 적용하지 않은 채 OpenClaw를 인터넷에 직접 배포했다고 경고했습니다. 해커가 모든 메모리 파일을 읽고, 임의 명령을 실행하고, 백도어까지 심을 수 있다는 뜻입니다.

어떻게 대응해야 할까요? 다음과 같은 보안 모범 사례가 있습니다.

• Docker 샌드박스 실행: 컨테이너로 OpenClaw를 격리하고 접근 가능한 파일 범위를 제한합니다.
• 최소 권한 원칙: OpenClaw에 필요한 파일 읽기 및 쓰기 권한만 부여하고 root로 실행하지 않습니다.
• 민감 데이터 암호화: 메모리 파일에 민감한 정보가 있다면 파일 시스템 수준 암호화를 고려합니다.
• 접근 제어: 인터넷에 공개해야 한다면 반드시 인증을 설정하고 Nginx 리버스 프록시로 basic auth 또는 OAuth를 적용합니다.
• 정기 감사: memory 디렉터리에 있으면 안 되는 파일이 없는지, skill 목록에 의심스러운 plugin이 없는지 확인합니다.

DigitalOcean에는 보안을 강화한 배포 방법을 자세히 설명한 자료가 있으니 꼼꼼히 살펴보는 것이 좋습니다.

결국 로컬 저장은 개인정보를 보호할 가능성을 제공할 뿐입니다. 실제 보안 수준은 설정하고 사용하는 방식에 달려 있습니다. 자물쇠를 받았더라도 문을 잠그는 것은 사용자의 몫입니다.

실전 가이드: 메모리 데이터 관리 및 최적화 방법

원리를 이해했으니 이제 메모리 파일을 실제로 관리하는 방법을 살펴보겠습니다.

파일 구성

OpenClaw의 기본 구조는 다음과 같습니다.

memory/
├── 2026-02-05.md          # 일일 로그
├── MEMORY/                # 영구 지식 저장소
│   ├── projects/          # 주제별 분류
│   │   ├── project-a.md
│   │   └── project-b.md
│   ├── reference/         # 참고 자료
│   └── troubleshooting/   # 문제 해결 기록
└── .memory_index.db       # SQLite 인덱스 파일

필요에 따라 디렉터리 구조를 조정할 수 있습니다. 저는 보통 프로젝트와 주제별로 다음처럼 분류합니다.

MEMORY/
├── work/
│   ├── backend-api-design.md
│   └── database-migration-notes.md
├── learning/
│   ├── rust-ownership-model.md
│   └── kubernetes-networking.md
└── personal/
    └── recipe-collection.md

데이터 유지 관리 전략

1. 정기 정리: 매달 오래된 로그를 살펴보고 불필요한 내용은 삭제하며 중요한 내용은 MEMORY 디렉터리로 옮깁니다.
2. 직접 편집: Markdown 파일은 언제든 열어 편집할 수 있습니다. AI가 잘못 기억한 내용을 발견하면 바로 수정합니다.
3. 버전 관리: memory 디렉터리를 Git으로 관리하면 commit 기록이 곧 기억의 변화 이력이 됩니다.
4. 백업: 하드 디스크 고장에 대비해 클라우드나 외장 디스크에 정기적으로 백업합니다.

성능 최적화

메모리 파일이 너무 많으면 성능 문제가 생길 수 있습니다. 다음 방법을 권장합니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

• 개별 파일 크기 제한: Markdown 파일 하나는 1MB를 넘기지 않는 것이 좋습니다. 너무 크면 여러 파일로 나눕니다.
• 컨텍스트 창 합리적으로 설정: 기본값은 최근 이틀 로그를 불러옵니다. 컨텍스트가 너무 길어 응답이 느려진다면 당일 로그만 불러오도록 바꿉니다.
• 정기적인 인덱스 재구축: 데이터가 늘수록 SQLite 인덱스 파일도 커집니다. .memory_index.db를 정기적으로 삭제해 시스템이 다시 만들도록 합니다.
• 사전 압축 작동 임계값: 로그 파일이 일정 수량(예: 30일분)을 넘으면 오래된 파일을 자동으로 압축하거나 보관합니다.

작은 팁이 하나 있습니다. MEMORY 디렉터리에 INDEX.md 파일을 두고 모든 중요 파일의 요약과 링크를 직접 정리해 보세요. 검색 시스템에 문제가 생겨도 필요한 정보를 빠르게 찾을 수 있습니다.

솔직히 메모리 파일을 관리하는 일은 노트를 정리하는 것과 비슷해서 약간의 규칙과 습관이 필요합니다. 하지만 자신만의 흐름을 만들고 나면 클라우드 서비스에 무작정 의존하는 것보다 훨씬 편안하다는 점을 알게 됩니다. 데이터를 직접 쥐고 있다는 통제감도 든든합니다.

마무리

지금까지 살펴본 내용을 바탕으로 처음 질문으로 돌아가 보겠습니다. AI 어시스턴트의 기억은 어디에 저장해야 할까요?

OpenClaw의 답은 로컬 Markdown 파일입니다. 다소 ‘복고적’으로 보이지만 클라우드 저장의 두 가지 핵심 문제인 데이터 개인정보 보호와 사용자 통제권을 해결합니다.

2계층 메모리 아키텍처(임시 로그 + 영구 지식)는 인간의 기억 방식을 본떠 최근 맥락을 이어가면서도 컨텍스트 창이 넘치는 문제를 피합니다. 하이브리드 검색 시스템(BM25 + 벡터 검색)은 평문 저장 방식에서도 지능형 검색을 가능하게 합니다. 또한 ‘파일 우선’ 설계 철학 덕분에 개발자는 가장 익숙한 도구인 편집기, Git, 파일 관리자로 AI의 기억을 관리할 수 있습니다.

물론 이 방식이 만능은 아닙니다. 개인정보 보호를 중시하고 로컬 워크플로를 선호하며 어느 정도 기술 역량이 있는 개발자에게 적합합니다. 여러 기기 동기화, 팀 협업, 완전한 무운영 환경이 필요하다면 클라우드 서비스가 더 나을 수 있습니다.

제게 OpenClaw의 메모리 시스템은 중요한 통찰을 하나 줬습니다. AI의 기억은 꼭 블랙박스 안에 있을 필요가 없습니다. 투명하고, 통제할 수 있으며, 사용자 자신의 것이 될 수 있습니다.

AI Agent 애플리케이션을 개발하고 있다면 Markdown 메모리 방식을 시도해 보세요. 간단한 NOTES.md 파일 하나로 시작해 자신만의 메모리 시스템을 단계적으로 만들 수 있습니다. 중요한 것은 기술이 얼마나 고급인지가 아니라 데이터를 누가 통제하느냐입니다.

OpenClaw 구현을 더 자세히 알고 싶다면 공식 문서와 소스 코드를 확인해 보세요. 커뮤니티도 활발해 문제가 생겨도 대부분 답을 찾을 수 있습니다.

그리고 보안 설정을 잊지 마세요. 내 기억이 다른 사람의 데이터가 되게 두어서는 안 됩니다.