Sessions and memory
메모리 검색
memory_search는 문구가 원문과 달라도 메모리 파일에서 관련 노트를 찾습니다. 메모리를 작은 청크로 색인하고 임베딩, 키워드 또는 둘 다를 사용해 검색하는 방식으로 동작합니다.
빠른 시작
GitHub Copilot 구독, OpenAI, Gemini, Voyage 또는 Mistral API 키가 구성되어 있으면 메모리 검색이 자동으로 동작합니다. 제공자를 명시적으로 설정하려면 다음과 같이 하세요.
{
agents: {
defaults: {
memorySearch: {
provider: "openai", // or "gemini", "local", "ollama", etc.
},
},
},
}
다중 엔드포인트 설정에서는 해당 제공자가 api: "ollama" 또는 다른 임베딩 어댑터 소유자를 설정하는 경우 provider가 ollama-5080 같은 사용자 지정 models.providers.<id> 항목일 수도 있습니다.
API 키 없이 로컬 임베딩을 사용하려면 provider: "local"을 설정하세요. 소스 체크아웃에는 여전히 네이티브 빌드 승인이 필요할 수 있습니다. pnpm approve-builds를 실행한 다음 pnpm rebuild node-llama-cpp를 실행하세요.
일부 OpenAI 호환 임베딩 엔드포인트는 검색에는 input_type: "query", 색인된 청크에는 input_type: "document" 또는 "passage" 같은 비대칭 레이블이 필요합니다. memorySearch.queryInputType 및 memorySearch.documentInputType으로 이를 구성하세요. 자세한 내용은 메모리 구성 참조를 참고하세요.
지원되는 제공자
| 제공자 | ID | API 키 필요 | 참고 |
|---|---|---|---|
| Bedrock | bedrock |
아니요 | AWS 자격 증명 체인이 확인되면 자동 감지 |
| Gemini | gemini |
예 | 이미지/오디오 색인 지원 |
| GitHub Copilot | github-copilot |
아니요 | 자동 감지되며 Copilot 구독 사용 |
| Local | local |
아니요 | GGUF 모델, 약 0.6GB 다운로드 |
| Mistral | mistral |
예 | 자동 감지 |
| Ollama | ollama |
아니요 | 로컬, 명시적으로 설정해야 함 |
| OpenAI | openai |
예 | 자동 감지, 빠름 |
| Voyage | voyage |
예 | 자동 감지 |
검색 작동 방식
OpenClaw는 두 가지 검색 경로를 병렬로 실행하고 결과를 병합합니다.
flowchart LR
Q["Query"] --> E["Embedding"]
Q --> T["Tokenize"]
E --> VS["Vector Search"]
T --> BM["BM25 Search"]
VS --> M["Weighted Merge"]
BM --> M
M --> R["Top Results"]
- 벡터 검색은 의미가 비슷한 노트를 찾습니다("gateway host"가 "the machine running OpenClaw"와 일치).
- BM25 키워드 검색은 정확한 일치 항목을 찾습니다(ID, 오류 문자열, 구성 키).
하나의 경로만 사용할 수 있는 경우(임베딩이 없거나 FTS가 없는 경우) 다른 경로가 단독으로 실행됩니다.
임베딩을 사용할 수 없을 때도 OpenClaw는 원시 정확 일치 순서에만 의존하지 않고 FTS 결과에 어휘 순위 지정을 사용합니다. 이 성능 저하 모드는 더 강한 쿼리 용어 포함 범위와 관련 파일 경로가 있는 청크의 가중치를 높여 sqlite-vec 또는 임베딩 제공자가 없어도 재현율을 유용하게 유지합니다.
검색 품질 개선
큰 노트 기록이 있을 때 도움이 되는 선택적 기능 두 가지가 있습니다.
시간 감쇠
오래된 노트는 순위 가중치가 점진적으로 낮아져 최신 정보가 먼저 드러납니다. 기본 반감기 30일을 사용하면 지난달의 노트는 원래 가중치의 50%로 점수가 매겨집니다. MEMORY.md 같은 상시 유지 파일은 감쇠되지 않습니다.
MMR(다양성)
중복 결과를 줄입니다. 다섯 개의 노트가 모두 같은 라우터 구성을 언급하더라도 MMR은 상위 결과가 반복되는 대신 서로 다른 주제를 포함하도록 합니다.
둘 다 활성화
{
agents: {
defaults: {
memorySearch: {
query: {
hybrid: {
mmr: { enabled: true },
temporalDecay: { enabled: true },
},
},
},
},
},
}
멀티모달 메모리
Gemini Embedding 2를 사용하면 Markdown과 함께 이미지 및 오디오 파일을 색인할 수 있습니다. 검색 쿼리는 텍스트로 유지되지만 시각 및 오디오 콘텐츠와 일치합니다. 설정은 메모리 구성 참조를 확인하세요.
세션 메모리 검색
선택적으로 세션 기록을 색인하여 memory_search가 이전 대화를 떠올릴 수 있습니다. 이는 memorySearch.experimental.sessionMemory를 통한 옵트인 기능입니다. 자세한 내용은 구성 참조를 확인하세요.
문제 해결
결과가 없나요? openclaw memory status를 실행해 색인을 확인하세요. 비어 있으면 openclaw memory index --force를 실행하세요.
키워드 일치만 나오나요? 임베딩 제공자가 구성되지 않았을 수 있습니다. openclaw memory status --deep을 확인하세요.
로컬 임베딩 시간이 초과되나요? ollama, lmstudio, local은 기본적으로 더 긴 인라인 배치 시간 제한을 사용합니다. 호스트가 단순히 느린 경우 agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds를 설정하고 openclaw memory index --force를 다시 실행하세요.
CJK 텍스트를 찾을 수 없나요? openclaw memory index --force로 FTS 색인을 다시 빌드하세요.
더 읽어보기
- Active Memory -- 대화형 채팅 세션을 위한 하위 에이전트 메모리
- 메모리 -- 파일 레이아웃, 백엔드, 도구
- 메모리 구성 참조 -- 모든 구성 옵션