메모리 검색

memory_search는 표현이 원문과 다르더라도 메모리 파일에서 관련 메모를 찾습니다. 메모리를 작은 조각으로 나눈 다음 임베딩, 키워드 또는 두 가지 모두를 사용해 검색합니다.

빠른 시작

OpenClaw는 기본적으로 OpenAI 임베딩을 사용합니다. 다른 제공자를 사용하려면 명시적으로 설정하십시오.

{  agents: {    defaults: {      memorySearch: {        provider: "openai", // 또는 "gemini", "voyage", "mistral", "bedrock", "local", "ollama", "lmstudio", "github-copilot", "openai-compatible"      },    },  },}

provider는 사용자 지정 models.providers.<id> 항목(예: ollama-5080)을 참조할 수도 있습니다. 단, 해당 항목에서 api를 "ollama" 또는 메모리 임베딩 어댑터가 있는 다른 제공자 ID로 설정해야 합니다.

API 키 없이 로컬 임베딩을 사용하려면 공식 llama.cpp 제공자 Plugin을 설치하고 provider: "local"을 설정하십시오.

openclaw plugins install @openclaw/llama-cpp-provider

소스 체크아웃에서는 여전히 네이티브 빌드 승인이 필요합니다. pnpm approve-builds를 실행한 다음 pnpm rebuild node-llama-cpp를 실행하십시오.

일부 OpenAI 호환 임베딩 엔드포인트에는 검색용 "query"와 인덱싱된 청크용 "document"/"passage"처럼 비대칭 input_type 레이블이 필요합니다. queryInputType과 documentInputType으로 이를 설정하십시오. 자세한 내용은 메모리 구성 참고 자료를 참조하십시오.

지원되는 제공자

검색 작동 방식

OpenClaw는 두 검색 경로를 병렬로 실행하고 결과를 병합합니다.

flowchart LR
    Q["쿼리"] --> E["임베딩"]
    Q --> T["토큰화"]
    E --> VS["벡터 검색"]
    T --> BM["BM25 검색"]
    VS --> M["가중 병합"]
    BM --> M
    M --> R["상위 결과"]

• 벡터 검색은 유사한 의미를 일치시킵니다("gateway host"는 "OpenClaw를 실행하는 시스템"과 일치합니다).
• BM25 키워드 검색은 정확한 용어(ID, 오류 문자열, 구성 키)를 일치시킵니다.
• 파일 이름 검색은 경로를 메모 본문과 별도로 인덱싱합니다. 정확한 전체 경로, 기본 이름, 파일 이름 어간은 부분 경로 일치보다 높은 순위를 차지하며, 스니펫과 본문 키워드 점수는 계속 메모 내용에서 산출됩니다.

한 경로만 사용할 수 있으면 해당 경로만 실행됩니다.

FTS 전용 모드. 임베딩을 의도적으로 비활성화하고 키워드로만 검색하려면 provider: "none"을 설정하십시오. provider를 설정하지 않거나 "auto"로 설정한 경우에도 임베딩 인증이 구성되지 않았다면 오류 없이 키워드 전용 순위 지정으로 대체됩니다. provider: "local"(GGUF/llama.cpp 제공자)이 실패한 경우에도 마찬가지입니다.

명시적으로 지정한 제공자를 사용할 수 없는 경우. 다른 제공자(예: openai, ollama, gemini)를 명시적으로 지정했는데 요청 시점에 사용할 수 없게 되면(잘못된 인증, 네트워크 장애) memory_search는 FTS 전용 결과로 조용히 성능을 낮추는 대신 메모리를 사용할 수 없다고 보고합니다. 이를 통해 구성된 제공자의 문제를 명확히 드러냅니다. 의도적으로 FTS 전용 회상을 사용하려면 provider: "none"을 설정하고, 의미 기반 순위 지정을 복원하려면 제공자/인증 구성을 수정하십시오.

검색 품질 개선

대규모 메모 기록에는 두 가지 선택적 기능이 유용합니다.

시간적 감쇠

오래된 메모는 순위 가중치가 점차 감소하여 최근 정보가 먼저 표시됩니다. 기본 반감기인 30일을 적용하면 지난달의 메모 점수는 원래 가중치의 50%가 됩니다. MEMORY.md 및 memory/ 아래의 날짜가 없는 다른 파일은 상시 유지되며 감쇠되지 않습니다. 날짜가 있는 memory/YYYY-MM-DD.md 파일만 감쇠됩니다.

MMR(다양성)

중복 결과를 줄입니다. 5개의 메모가 모두 동일한 라우터 구성을 언급하더라도 MMR을 사용하면 상위 결과가 반복되는 대신 서로 다른 주제를 다룹니다.

두 기능 모두 활성화

{  agents: {    defaults: {      memorySearch: {        query: {          hybrid: {            mmr: { enabled: true },            temporalDecay: { enabled: true },          },        },      },    },  },}

멀티모달 메모리

gemini-embedding-2-preview를 사용하면 Markdown과 함께 이미지 및 오디오를 인덱싱할 수 있습니다. 이 기능은 memorySearch.extraPaths 아래의 파일에만 적용됩니다. 기본 메모리 루트(MEMORY.md, memory/*.md)는 Markdown 전용으로 유지됩니다. 검색 쿼리는 계속 텍스트이지만 시각 및 오디오 콘텐츠와 일치할 수 있습니다. 설정 방법은 메모리 구성 참고 자료를 참조하십시오.

세션 메모리 검색

세션 기록에서 정확한 전체 텍스트를 회상하려면 sessions_search를 사용한 다음 sessions_history로 결과를 여십시오. 세션 메모리 검색은 의미 기반의 실험적 보완 기능으로 유지됩니다.

선택적으로 세션 기록을 인덱싱하여 memory_search가 이전 대화를 회상할 수 있게 할 수 있습니다. 이 기능은 옵트인입니다. experimental.sessionMemory: true를 설정하고 sources에 "sessions"를 추가하십시오(기본 sources는 ["memory"]입니다).

세션 검색 결과에는 tools.sessions.visibility가 적용됩니다. 기본값 "tree"는 현재 세션과 이 세션이 생성한 세션만 노출합니다. 다른 세션에서 관련 없는 동일 에이전트의 세션(예: DM에서 Gateway가 디스패치한 세션)을 회상하려면 가시성을 "agent"로 확장하십시오.

QMD 백엔드를 사용할 때는 기록이 QMD 컬렉션으로 내보내지도록 memory.qmd.sessions.enabled: true도 설정하십시오. experimental.sessionMemory와 sources만으로는 기록이 QMD로 내보내지지 않습니다. 자세한 내용은 구성 참고 자료를 참조하십시오.

문제 해결

결과가 없습니까? 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
• 내장 메모리 엔진
• 메모리 구성 참고 자료