OpenClaw 메모리 마스터하기: 에이전트에게 영구적인 기억력을 선물하세요

에이전트랑 한참 대화하다가 “아 맞다, 아까 그거 뭐였지?” 하고 물어봤는데 기억 못 하면 정말 답답하죠? 저도 처음에 OpenClaw를 쓸 때 에이전트가 중요한 설정을 자꾸 까먹어서 고생 좀 했거든요. RAM에만 의존하는 건 한계가 분명해요. 결국 에이전트가 똑똑해지려면 사람처럼 ‘기록하는 습관’이 필요하더라고요.

OpenClaw는 이 문제를 아주 심플하게 해결했어요. 복잡한 데이터베이스 대신 우리가 흔히 쓰는 Markdown 파일을 메모리로 사용합니다. 에이전트가 직접 파일에 글을 쓰고, 나중에 필요할 때 다시 읽어오는 방식이죠. 이제 에이전트에게 “이거 꼭 기억해 줘”라고 말하고 실제로 파일에 저장되는 마법을 설정해 볼게요.

필요한 것

시작하기 전에 아래 항목들이 준비되었는지 확인해 주세요.

• OpenClaw Gateway가 설치된 환경
• 쓰기 권한이 설정된 에이전트 workspace
• (선택 사항) OpenAI 또는 Gemini API 키 (Vector 검색용)
• Node.js 및 pnpm (로컬 모드 사용 시)

Quick Start: 5분 만에 메모리 설정하기

가장 빠른 방법은 기본 제공되는 memory-core 플러그인을 사용하는 거예요. 별도 설정이 없어도 OpenClaw는 workspace의 Markdown 파일을 소스로 사용합니다.

1. 파일 구조 만들기: workspace 폴더(기본값 ~/.openclaw/workspace)에 memory 폴더를 만드세요.
2. 기본 메모리 파일 생성: 루트에 MEMORY.md 파일을 만들고 중요한 규칙을 적어두세요.
3. 에이전트에게 시키기: 채팅창에 “앞으로 내 프로젝트 이름은 ‘쿠키몬스터’야. MEMORY.md에 기록해 줘.”라고 말해보세요.
4. 확인하기: 실제 파일에 내용이 적혔는지 확인하면 끝입니다.

메모리가 작동하는 방식

OpenClaw 메모리는 크게 두 가지 레이어로 나뉩니다.

• memory/YYYY-MM-DD.md: 그날그날의 로그입니다. 세션이 시작될 때 오늘과 어제의 기록을 읽어와서 문맥을 파악해요.
• MEMORY.md: 장기 기억 저장소예요. 결정된 사항이나 개인적인 취향처럼 오래 기억해야 할 내용을 담습니다.

자동으로 메모리 저장하기 (Compaction)

대화가 길어지면 토큰 제한 때문에 예전 기록을 지워야 할 때가 와요. OpenClaw는 이때 똑똑하게 행동합니다. 컨텍스트가 꽉 차기 직전에 에이전트에게 “중요한 내용은 미리 메모리에 적어둬!”라고 몰래 신호를 보내거든요.

설정 파일에서 이 동작을 조절할 수 있어요:

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          systemPrompt: "세션 압축이 임박했습니다. 중요한 기억을 지금 저장하세요.",
          prompt: "지속적인 노트는 memory/YYYY-MM-DD.md에 작성하세요. 저장할 게 없다면 NO_REPLY라고 답하세요.",
        },
      },
    },
  },
}

더 똑똑한 검색: Vector Search

단순히 텍스트를 읽는 걸 넘어, OpenClaw는 의미 기반의 검색도 지원해요. 질문의 단어가 조금 달라도 찰떡같이 알아듣고 관련 노트를 찾아냅니다.

• Hybrid Search: 의미를 찾는 Vector 방식과 정확한 키워드를 찾는 BM25 방식을 섞어서 사용해요.
• 자동 인덱싱: 파일을 수정하면 1.5초 뒤에 자동으로 검색 엔진에 반영됩니다.
• 로컬 모드: 외부 API 없이 node-llama-cpp를 통해 내 컴퓨터에서 직접 처리할 수 있어요.
• 임베딩 캐시: 한 번 분석한 내용은 SQLite에 저장해서 API 비용을 아껴줍니다.

Gemini를 사용해서 검색 성능을 높이고 싶다면 이렇게 설정해 보세요:

agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-001",
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

Troubleshooting: 문제가 생겼나요?

1. 메모리 검색 결과가 비어 있어요.

• API 키가 제대로 설정되었는지 확인해 보세요. 특히 임베딩용 API 키는 채팅용 키와 별도로 필요할 수 있습니다.
• workspaceAccess가 "ro"(읽기 전용)로 되어 있다면 에이전트가 메모리를 쓸 수 없으니 확인이 필요해요.

2. 로컬 모드에서 오류가 나요.

• node-llama-cpp를 사용하려면 네이티브 빌드 승인이 필요합니다. 터미널에서 pnpm approve-builds를 실행하고 node-llama-cpp를 선택한 뒤 다시 빌드해 보세요.

3. 검색 속도가 너무 느려요.

• 처음 실행할 때는 모델을 다운로드하느라 시간이 걸릴 수 있습니다. 잠시만 기다리면 다음부터는 캐시 덕분에 빨라질 거예요.

---

에이전트의 기억력을 설정하다가 막히는 부분이 있나요? AI Setup Assistant에게 물어보시면 바로 해결책을 알려줄 거예요.

다음 단계

• Agent workspace 설정 가이드
• 세션 관리 및 압축 기술 문서