메모리 구성 참조

이 페이지는 OpenClaw 메모리 검색의 모든 구성 조정 항목을 나열합니다. 개념 개요는 다음을 참조하세요.

별도로 명시하지 않는 한 모든 메모리 검색 설정은 openclaw.json의 agents.defaults.memorySearch 아래에 있습니다.

# 제공자 선택

# 자동 감지 순서

provider가 설정되지 않은 경우 OpenClaw는 사용 가능한 첫 번째 항목을 선택합니다.

ollama는 지원되지만 자동 감지되지는 않습니다(명시적으로 설정하세요).

# 사용자 지정 제공자 ID

memorySearch.provider는 사용자 지정 models.providers.<id> 항목을 가리킬 수 있습니다. OpenClaw는 엔드포인트, 인증, 모델 접두사 처리를 위해 사용자 지정 제공자 ID를 유지하면서 임베딩 어댑터에 대한 해당 제공자의 api 소유자를 확인합니다. 이를 통해 멀티 GPU 또는 멀티 호스트 설정에서 메모리 임베딩을 특정 로컬 엔드포인트에 전용으로 할당할 수 있습니다.

{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

# API 키 확인

원격 임베딩에는 API 키가 필요합니다. 대신 Bedrock은 AWS SDK 기본 자격 증명 체인을 사용합니다(인스턴스 역할, SSO, 액세스 키).

# 원격 엔드포인트 구성

사용자 지정 OpenAI 호환 엔드포인트를 사용하거나 제공자 기본값을 재정의하는 경우:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

# 제공자별 구성

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}

{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

openclaw memory status --deep --agent main
openclaw memory index --force --agent main

# 인라인 임베딩 시간 제한

# 하이브리드 검색 설정

모두 memorySearch.query.hybrid 아래에 있습니다.

# 전체 예시

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

# 추가 메모리 경로

{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}

경로는 절대 경로이거나 워크스페이스 기준 상대 경로일 수 있습니다. 디렉터리는 .md 파일을 찾기 위해 재귀적으로 스캔됩니다. 심볼릭 링크 처리는 활성 백엔드에 따라 달라집니다. 내장 엔진은 심볼릭 링크를 무시하고, QMD는 기본 QMD 스캐너 동작을 따릅니다.

에이전트 범위의 교차 에이전트 트랜스크립트 검색에는 memory.qmd.paths 대신 agents.list[].memorySearch.qmd.extraCollections를 사용하세요. 이러한 추가 컬렉션은 동일한 { path, name, pattern? } 형태를 따르지만 에이전트별로 병합되며, 경로가 현재 워크스페이스 외부를 가리킬 때 명시적인 공유 이름을 보존할 수 있습니다. 동일하게 해석된 경로가 memory.qmd.paths와 memorySearch.qmd.extraCollections에 모두 나타나면 QMD는 첫 번째 항목을 유지하고 중복 항목을 건너뜁니다.

# 멀티모달 메모리(Gemini)

Gemini Embedding 2를 사용해 Markdown과 함께 이미지 및 오디오를 인덱싱합니다.

지원 형식: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif(이미지); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac(오디오).

# 임베딩 캐시

재인덱싱 또는 대화 기록 업데이트 중 변경되지 않은 텍스트를 다시 임베딩하지 않도록 합니다.

# 배치 인덱싱

openai, gemini, voyage에서 사용할 수 있습니다. OpenAI 배치는 일반적으로 대규모 백필에 가장 빠르고 비용이 저렴합니다.

remote.nonBatchConcurrency는 로컬/자체 호스팅 제공자와, 제공자 배치 API가 활성화되지 않은 경우 호스팅 제공자가 사용하는 인라인 임베딩 호출을 제어합니다. Ollama는 더 작은 로컬 호스트에 과부하를 주지 않도록 비배치 인덱싱의 기본값을 1로 설정합니다. 더 큰 머신에서는 더 높은 값을 설정하세요.

이는 인라인 임베딩 호출의 시간 제한을 제어하는 sync.embeddingBatchTimeoutSeconds와는 별개입니다.

# 세션 메모리 검색(실험적)

세션 대화 기록을 인덱싱하고 memory_search를 통해 노출합니다.

# SQLite 벡터 가속(sqlite-vec)

sqlite-vec을 사용할 수 없는 경우 OpenClaw는 자동으로 프로세스 내부 코사인 유사도로 대체합니다.

# 인덱스 저장소

# QMD 백엔드 구성

활성화하려면 memory.backend = "qmd"를 설정하세요. 모든 QMD 설정은 memory.qmd 아래에 있습니다.

searchMode: "search"는 lexical/BM25 전용입니다. OpenClaw는 memory status --deep 중을 포함하여 해당 모드에 대해 시맨틱 벡터 준비 상태 프로브나 QMD 임베딩 유지 관리를 실행하지 않습니다. vsearch와 query는 계속 QMD 벡터 준비 상태와 임베딩을 요구합니다.

OpenClaw는 현재 QMD 컬렉션과 MCP 쿼리 형태를 선호하지만, 필요할 때 호환 가능한 컬렉션 패턴 플래그와 이전 MCP 도구 이름을 시도하여 오래된 QMD 릴리스도 계속 동작하도록 유지합니다. QMD가 여러 컬렉션 필터 지원을 알리면, 동일 소스 컬렉션은 하나의 QMD 프로세스로 검색됩니다. 오래된 QMD 빌드는 컬렉션별 호환성 경로를 유지합니다. 동일 소스란 영속 메모리 컬렉션이 함께 그룹화되고, 세션 기록 컬렉션은 별도 그룹으로 남아 소스 다양화가 여전히 두 입력을 모두 갖는다는 뜻입니다.

{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}

QMD 부팅 새로 고침은 Gateway 시작 중 일회성 하위 프로세스 경로를 사용합니다. 장기 실행 QMD 관리자는 메모리 검색이 대화형 사용을 위해 열렸을 때 여전히 일반 파일 감시자와 간격 타이머를 소유합니다.

# 전체 QMD 예시

{
  memory: {
    backend: "qmd",
    citations: "auto",
    qmd: {
      includeDefaultMemory: true,
      update: { interval: "5m", debounceMs: 15000 },
      limits: { maxResults: 6, timeoutMs: 4000 },
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

# Dreaming

Dreaming은 agents.defaults.memorySearch 아래가 아니라 plugins.entries.memory-core.config.dreaming 아래에서 구성됩니다.

Dreaming은 하나의 예약된 스윕으로 실행되며 내부 light/deep/REM 단계를 구현 세부 사항으로 사용합니다.

개념적 동작과 슬래시 명령은 Dreaming을 참조하세요.

# 사용자 설정

# 예시

{
  plugins: {
    entries: {
      "memory-core": {
        subagent: {
          allowModelOverride: true,
          allowedModels: ["anthropic/claude-sonnet-4-6"],
        },
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
            model: "anthropic/claude-sonnet-4-6",
          },
        },
      },
    },
  },
}

# 관련 항목

• 구성 참조
• 메모리 개요
• 메모리 검색