메모리 구성 참조 자료

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

별도로 명시하지 않는 한, 모든 메모리 검색 설정은 openclaw.json의 agents.defaults.memorySearch 아래에 있습니다(또는 에이전트별 agents.list[].memorySearch로 재정의할 수 있습니다).

제공자 선택

provider를 설정하지 않으면 OpenClaw는 OpenAI 임베딩을 사용합니다. Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, 로컬 GGUF 모델 또는 OpenAI 호환 /v1/embeddings 엔드포인트를 사용하려면 provider를 명시적으로 설정하세요. 여전히 provider: "auto"를 사용하는 레거시 구성은 openai로 해석됩니다.

provider가 설정되지 않았거나, 레거시 provider: "auto"가 있거나, provider: "none"으로 의도적으로 FTS 전용 모드를 선택한 경우에는 임베딩을 사용할 수 없더라도 메모리 회상에서 어휘 기반 FTS 순위를 계속 사용할 수 있습니다.

명시적으로 지정한 로컬 외부 제공자는 사용 불가 시 실패로 처리됩니다. memorySearch.provider를 Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage 또는 OpenAI 호환 사용자 지정 제공자처럼 원격 기반의 구체적인 제공자로 설정했는데 런타임에 해당 제공자를 사용할 수 없다면, memory_search는 아무런 알림 없이 FTS 전용 회상을 사용하는 대신 사용할 수 없음 결과를 반환합니다. 제공자/인증 구성을 수정하거나, 접근 가능한 제공자로 전환하거나, 의도적으로 FTS 전용 회상을 사용하려면 provider: "none"을 설정하세요.

사용자 지정 제공자 ID

memorySearch.provider는 ollama 같은 메모리 전용 제공자 어댑터나 openai-responses / openai-completions 같은 OpenAI 호환 모델 API를 위한 사용자 지정 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", name: "Qwen3 Embedding 0.6B" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

API 키 확인

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

원격 엔드포인트 구성

전역 OpenAI 채팅 자격 증명을 상속하지 않아야 하는 범용 OpenAI 호환 /v1/embeddings 서버에는 provider: "openai-compatible"을 사용하세요.

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

제공자별 구성

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        remote: {          baseUrl: "https://embeddings.example/v1",          apiKey: "${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 mainopenclaw memory index --force --agent main

인라인 임베딩 시간 초과

인덱싱 동작

별도로 명시되지 않은 항목은 모두 memorySearch.sync 아래에 있습니다.

하이브리드 검색 구성

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

그리고 memorySearch.query.hybrid 아래에는 다음 항목이 있습니다.

전체 예시

{  agents: {    defaults: {      memorySearch: {        query: {          maxResults: 6,          minScore: 0.35,          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(오디오).

임베딩 캐시

재인덱싱이나 트랜스크립트 업데이트 중 변경되지 않은 텍스트를 다시 임베딩하지 않도록 합니다. 무제한 캐시를 사용하려면 maxEntries를 설정하지 않은 상태로 두고, 최대 재인덱싱 속도보다 디스크 사용량 증가가 더 중요할 때 값을 설정하세요. 설정한 경우 캐시가 제한을 초과하면 마지막 업데이트 시간을 기준으로 가장 오래된 항목부터 제거됩니다.

일괄 인덱싱

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

remote.nonBatchConcurrency는 공급자 일괄 API가 활성화되지 않았을 때 로컬/자체 호스팅 공급자와 호스팅 공급자가 사용하는 인라인 임베딩 호출을 제어합니다. Ollama는 소규모 로컬 호스트의 과부하를 방지하기 위해 비일괄 인덱싱의 기본값으로 1을 사용합니다. 더 큰 머신에서는 더 높은 값을 설정하세요.

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

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

세션 트랜스크립트를 인덱싱하고 memory_search를 통해 표시합니다.

세션 트랜스크립트 검색 결과에도 tools.sessions.visibility가 적용됩니다. 기본 tree 가시성은 현재 세션과 이 세션이 생성한 세션만 노출합니다. DM과 같이 다른 세션에서 동일한 에이전트가 Gateway를 통해 디스패치한 관련 없는 세션을 회상하려면 가시성을 의도적으로 agent로 확장하세요. 에이전트 간 회상도 필요하고 에이전트 간 정책에서 허용하는 경우에만 all을 사용하세요.

아래 예시에서는 이러한 설정을 agents.defaults 아래에 배치합니다. 한 에이전트만 세션 트랜스크립트를 인덱싱하고 검색해야 하는 경우 에이전트별 재정의에 동등한 memorySearch 설정을 적용할 수도 있습니다.

동일 에이전트의 Gateway에서 DM으로 회상하려면:

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  tools: {    sessions: { visibility: "agent" },  },}

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },  tools: {    sessions: { visibility: "agent" },  },}

QMD를 사용할 때 agents.defaults.memorySearch.experimental.sessionMemory와 sources: ["sessions"]만으로는 트랜스크립트가 QMD로 내보내지지 않습니다. memory.qmd.sessions.enabled: true도 설정하세요.

SQLite 벡터 가속(sqlite-vec)

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

인덱스 저장소

기본 제공 메모리 인덱스는 각 에이전트의 OpenClaw SQLite 데이터베이스인 agents/<agentId>/agent/openclaw-agent.sqlite에 저장됩니다.

QMD 백엔드 구성

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

searchMode: "search"는 어휘/BM25 전용입니다. 해당 모드에서는 memory status --deep 실행 중을 포함하여 OpenClaw가 의미론적 벡터 준비 상태 검사나 QMD 임베딩 유지 관리를 실행하지 않습니다. vsearch와 query에는 계속 QMD 벡터 준비 상태와 임베딩이 필요합니다.

rerank: false는 QMD query 모드만 변경하며 QMD 2.1 이상이 필요합니다. 직접 CLI 모드에서 OpenClaw는 --no-rerank를 전달하고, mcporter 기반 MCP 모드에서는 QMD의 통합 쿼리 도구에 rerank: false를 전달합니다. QMD의 기본 쿼리 재순위 지정 동작을 사용하려면 설정하지 않은 상태로 두세요.

OpenClaw는 최신 QMD 컬렉션 및 MCP 쿼리 형식을 우선 사용하지만, 필요한 경우 호환되는 컬렉션 패턴 플래그와 이전 MCP 도구 이름을 시도하여 이전 QMD 릴리스도 계속 작동하도록 합니다. QMD가 여러 컬렉션 필터 지원을 알리면 동일 소스 컬렉션을 하나의 QMD 프로세스로 검색합니다. 이전 QMD 빌드에서는 컬렉션별 호환 경로를 유지합니다. 동일 소스란 영구 메모리 컬렉션(기본 메모리 파일과 사용자 지정 경로)이 함께 그룹화된다는 뜻이며, 세션 기록 컬렉션은 별도 그룹으로 유지되어 소스 다변화에 계속 두 입력이 모두 포함됩니다.

mcporter 통합

모든 설정은 memory.qmd.mcporter 아래에 있습니다. 쿼리마다 qmd를 생성하는 대신 장기 실행 mcporter MCP 데몬을 통해 QMD 검색을 라우팅하여 대형 모델의 콜드 스타트 오버헤드를 줄입니다.

mcporter가 설치되어 PATH에 있어야 하며, qmd mcp를 실행하도록 구성된 mcporter 서버도 필요합니다. 쿼리별 프로세스 생성 비용을 감수할 수 있는 단순한 로컬 설정에서는 비활성화 상태를 유지하세요.

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

Gateway 시작 시 QMD 초기화가 활성화되어 있으면 OpenClaw는 적격 에이전트에 대해서만 QMD를 시작합니다. update.onBoot가 true이고 간격/임베딩 유지 관리가 구성되어 있지 않으면, 시작 시 부팅 새로 고침에 일회성 관리자를 사용한 후 종료합니다. 업데이트 또는 임베딩 간격이 구성되어 있으면, 시작 시 장기 실행 QMD 관리자를 열어 감시자와 간격 타이머를 관리하도록 합니다. update.onBoot: false는 부팅 직후 새로 고침만 건너뜁니다.

전체 QMD 예시

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 4, 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은 예약된 단일 스윕으로 실행되며 내부의 얕은 수면/깊은 수면/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",          },        },      },    },  },}

관련 항목

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