Memory configuration reference
기준일: 2026-07-26
공식 기준: Memory configuration reference
Memory configuration reference 문서는 OpenClaw 공식 문서(reference/memory-config)를 한국어로 정리한 가이드입니다. Memory search providers, retrieval modes, QMD, and multimodal indexing 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.
핵심 요약
Memory search providers, retrieval modes, QMD, and multimodal indexing
한국어 가이드 범위: reference/memory-config 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.
문서 구성
공식 문서의 주요 섹션은 다음과 같습니다.
- Remember across conversations
- Provider selection
- Custom provider ids
- API key resolution
- Remote endpoint config
- Provider-specific config
- Indexing behavior
- Hybrid search config
- Full example
- Additional memory paths
- Multimodal memory (Gemini)
- Embedding cache
- Batch indexing
- Session memory search
- SQLite vector acceleration (sqlite-vec)
- Index storage
- QMD backend config
- Full QMD example
- Dreaming
- User settings
- 예제
- 관련 문서
상세 내용
본문
This page lists every configuration knob for OpenClaw memory search. For conceptual overviews, see:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Remember across conversations
Configure it per agent when only a trusted personal agent should use cross-conversation transcript recall:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- only the same agent's recognized private conversations are eligible
- the conversation being answered is excluded
- groups and channels are excluded as sources and destinations
- unknown conversation kinds fail closed
- sandboxed recall cannot use the special cross-conversation authorization
| Key | Type | Default | Description |
|---|---|---|---|
rememberAcrossConversations |
boolean |
On for personal installs; off with configured DM isolation | Use relevant context from this agent's other recognized private conversations. |
{
agents: {
entries: {
personal: {
memory: {
search: {
rememberAcrossConversations: true,
},
},
},
},
},
}
Provider selection
When provider is not set, OpenClaw uses OpenAI embeddings. Set provider explicitly to use Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, a local GGUF model, or an OpenAI-compatible /v1/embeddings endpoint. Legacy configs that still say provider: "auto" resolve to openai.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
boolean |
true |
Enable or disable memory search |
provider |
string |
"openai" |
Embedding adapter ID such as bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai, openai-compatible, or voyage; may also be a configured models.providers.<id> whose api points at a memory embedding adapter or OpenAI-compatible model API |
model |
string |
provider default | Embedding model name |
fallback |
string |
"none" |
Fallback adapter ID when the primary fails |
Custom provider ids
memory.search.provider can point at a custom models.providers. entry for memory-specific provider adapters such as ollama, or for OpenAI-compatible model APIs such as openai-responses / openai-completions. OpenClaw resolves that provider's api owner for the embedding adapter while preserving the custom provider id for endpoint, auth, and model-prefix handling. This lets multi-GPU or multi-host setups dedicate memory embeddings to a specific local endpoint:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
{
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" }],
},
},
},
memory: {
search: {
provider: "ollama-5080",
model: "qwen3-embedding:0.6b",
},
},
}
API key resolution
Remote embeddings require an API key. Bedrock uses the AWS SDK default credential chain instead (instance roles, SSO, access keys, or a Bedrock API key).
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Provider | Env var | Config key |
|---|---|---|
| Bedrock | AWS credential chain, or AWS_BEARER_TOKEN_BEDROCK |
No API key needed |
| DeepInfra | DEEPINFRA_API_KEY |
models.providers.deepinfra.apiKey |
| Gemini | GEMINI_API_KEY |
models.providers.google.apiKey |
| GitHub Copilot | COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN |
Auth profile via device login |
| Mistral | MISTRAL_API_KEY |
models.providers.mistral.apiKey |
| Ollama | OLLAMA_API_KEY (placeholder) |
-- |
| OpenAI | OPENAI_API_KEY |
models.providers.openai.apiKey |
| Voyage | VOYAGE_API_KEY |
models.providers.voyage.apiKey |
Remote endpoint config
Use provider: "openai-compatible" for a generic OpenAI-compatible /v1/embeddings server that should not inherit global OpenAI chat credentials.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
{
memory: {
search: {
provider: "openai-compatible",
model: "text-embedding-3-small",
remote: {
baseUrl: "https://api.example.com/v1/",
apiKey: "YOUR_KEY",
},
},
},
}
Provider-specific config
Changing model or outputDimensionality changes the index identity. OpenClaw pauses vector search until you explicitly rebuild the memory index.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
{
memory: {
search: {
provider: "openai-compatible",
remote: {
baseUrl: "https://embeddings.example/v1",
apiKey: "${EMBEDDINGS_API_KEY}",
},
model: "asymmetric-embedder",
queryInputType: "query",
documentInputType: "passage",
},
},
}
{
memory: {
search: {
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
Indexing behavior
Memory engines own synchronization, batching, watch, and post-compaction indexing heuristics. OpenClaw keeps these behaviors enabled with maintained defaults rather than exposing per-install timing switches.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Hybrid search config
Hybrid retrieval remains enabled; MMR and temporal decay remain disabled by the built-in engine policy.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Default | Description |
|---|---|---|---|
maxResults |
number |
6 |
Max memory hits returned before injection |
minScore |
number |
0.35 |
Minimum relevance score to include a hit |
Full example
{
memory: {
search: {
query: {
maxResults: 6,
minScore: 0.35,
},
},
},
}
Additional memory paths
Paths can be absolute or workspace-relative. Directories are scanned recursively for .md files. Symlink handling depends on the active backend: the builtin engine skips symlinks, while QMD follows the underlying QMD scanner behavior.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Description |
|---|---|---|
extraPaths |
string[] |
Additional directories or files to index |
{
memory: {
search: {
extraPaths: ["../team-docs", "/srv/shared-notes"],
},
},
}
Multimodal memory (Gemini)
Index images and audio alongside Markdown using Gemini Embedding 2:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Default | Description |
|---|---|---|---|
multimodal.enabled |
boolean |
false |
Enable multimodal indexing |
multimodal.modalities |
string[] |
-- | ["image"], ["audio"], or ["all"] |
multimodal.maxFileBytes |
number |
10485760 |
Max file size for indexing (10 MiB) |
Embedding cache
Prevents re-embedding unchanged text during reindex or transcript updates.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Default | Description |
|---|---|---|---|
cache.enabled |
boolean |
true |
Cache chunk embeddings in SQLite |
Batch indexing
Available for gemini, openai, and voyage. OpenAI batch is typically fastest and cheapest for large backfills.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Default | Description |
|---|---|---|---|
remote.nonBatchConcurrency |
number |
4 |
Parallel inline embeddings |
remote.batch.enabled |
boolean |
false |
Enable batch embedding API |
Session memory search
Index session transcripts and surface them via memory_search:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Default | Description |
|---|---|---|---|
rememberAcrossConversations |
boolean |
false |
Permit private cross-conversation recall |
sources |
string[] |
["memory"] |
Add "sessions" to include transcripts |
{
memory: {
search: {
experimental: { sessionMemory: true },
sources: ["memory", "sessions"],
},
},
tools: {
sessions: { visibility: "agent" },
},
}
{
memory: {
backend: "qmd",
search: {
experimental: { sessionMemory: true },
sources: ["memory", "sessions"],
},
qmd: {
sessions: { enabled: true },
},
},
tools: {
sessions: { visibility: "agent" },
},
}
SQLite vector acceleration (sqlite-vec)
When sqlite-vec is unavailable, OpenClaw falls back to in-process cosine similarity automatically.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Default | Description |
|---|---|---|---|
store.vector.enabled |
boolean |
true |
Use sqlite-vec for vector queries |
store.vector.extensionPath |
string |
bundled | Override sqlite-vec path |
Index storage
Built-in memory indexes live in each agent's OpenClaw SQLite database at agents//agent/openclaw-agent.sqlite.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Default | Description |
|---|---|---|---|
store.fts.tokenizer |
string |
unicode61 |
FTS5 tokenizer (unicode61 or trigram) |
QMD backend config
Set memory.backend = "qmd" to enable. All QMD settings live under memory.qmd:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Key | Type | Default | Description |
|---|---|---|---|
command |
string |
qmd |
QMD executable path; set an absolute path when service PATH differs from your shell |
searchMode |
string |
search |
Search command: search, vsearch, query |
rerank |
boolean |
-- | Set to false with searchMode: "query" and QMD 2.1+ to skip QMD reranking |
includeDefaultMemory |
boolean |
true |
Auto-index MEMORY.md + memory/**/*.md |
paths[] |
array |
-- | Extra paths: { name, path, pattern? } |
sessions.enabled |
boolean |
false |
Export session transcripts into QMD |
sessions.retentionDays |
number |
-- | Transcript retention |
sessions.exportDir |
string |
-- | Export directory |
{
memory: {
qmd: {
scope: {
default: "deny",
rules: [{ action: "allow", match: { chatType: "direct" } }],
},
},
},
}
Full QMD example
{
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 is configured under plugins.entries.memory-core.config.dreaming, not under memory.search.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
User settings
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
boolean |
false |
Enable or disable dreaming entirely |
frequency |
string |
0 3 * * * |
Optional cron cadence for the full dreaming sweep |
model |
string |
default model | Optional Dream Diary subagent model override |
phases.deep.maxPromotedSnippetTokens |
number |
160 |
Maximum estimated tokens kept from each short-term recall snippet promoted into MEMORY.md; provenance metadata remains visible |
예제
주요 항목:
- Dreaming writes machine state to
memory/.dreams/. - Dreaming writes human-readable narrative output to
DREAMS.md(or existingdreams.md). dreaming.modeluses the existing plugin subagent trust gate; setplugins.entries.memory-core.subagent.allowModelOverride: truebefore enabling it.- Dream Diary retries once with the session default model when the configured model is unavailable. Trust or allowlist failures are logged and are not silently retried.
- The light/deep/REM phase policy and thresholds are internal behavior, not user-facing config.
{
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",
},
},
},
},
},
}
관련 문서
주요 항목:
- Configuration reference
- Memory overview
- Memory search
실습 체크리스트
- 공식 문서와 로컬 버전을 대조합니다:
https://docs.openclaw.ai/reference/memory-config - 관련 CLI는
openclaw --help및 하위 명령--help로 옵션을 확인합니다. - 설정 변경 시
openclaw config/openclaw doctor로 유효성을 검사합니다. - Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.
자주 쓰는 명령·설정 예시
{
agents: {
entries: {
personal: {
memory: {
search: {
rememberAcrossConversations: true,
},
},
},
},
},
}
{
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" }],
},
},
},
memory: {
search: {
provider: "ollama-5080",
model: "qwen3-embedding:0.6b",
},
},
}
{
memory: {
search: {
provider: "openai-compatible",
model: "text-embedding-3-small",
remote: {
baseUrl: "https://api.example.com/v1/",
apiKey: "YOUR_KEY",
},
},
},
}
{
memory: {
search: {
provider: "openai-compatible",
remote: {
baseUrl: "https://embeddings.example/v1",
apiKey: "${EMBEDDINGS_API_KEY}",
},
model: "asymmetric-embedder",
queryInputType: "query",
documentInputType: "passage",
},
},
}
{
memory: {
search: {
provider: "bedrock",
model: "amazon.titan-embed-text-v2:0",
},
},
}
{
"Effect": "Allow",
"Action": "bedrock:InvokeModel",
"Resource": "*"
}
관련 링크
이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.