ข้อมูลอ้างอิงการกำหนดค่าหน่วยความจำ

หน้านี้แสดงตัวเลือกการกำหนดค่าทั้งหมดสำหรับการค้นหาหน่วยความจำของ OpenClaw สำหรับภาพรวมเชิงแนวคิด โปรดดู:

การตั้งค่าการค้นหาหน่วยความจำทั้งหมดอยู่ภายใต้ agents.defaults.memorySearch ใน openclaw.json (หรือการแทนที่ agents.list[].memorySearch รายเอเจนต์) เว้นแต่จะระบุไว้เป็นอย่างอื่น

จดจำข้ามบทสนทนา

กำหนดค่าเป็นรายเอเจนต์เมื่อมีเพียงเอเจนต์ส่วนบุคคลที่เชื่อถือได้เท่านั้นที่ควรใช้ การเรียกคืนทรานสคริปต์ข้ามบทสนทนา:

{  agents: {    list: [      {        id: "personal",        memorySearch: {          rememberAcrossConversations: true,        },      },    ],  },}

ค่านี้เป็นไปตามการสืบทอด agents.defaults.memorySearch ตามปกติพร้อม การแทนที่รายเอเจนต์ เมื่อไม่ได้ตั้งค่า ระบบจะเปิดเป็นค่าเริ่มต้นเฉพาะเมื่อ session.dmScope ส่วนกลางไม่ได้ตั้งค่า หรือเป็น "main" และไม่มีการผูกใดมีการแทนที่ session.dmScope การกำหนดค่าการแยก DM ใดๆ จะทำให้ค่าเริ่มต้นเป็นปิด true หรือ false ที่กำหนดไว้อย่างชัดเจนจะมีผลเหนือกว่าเสมอ การเปิดใช้งานจะหมายรวมถึงการทำดัชนีทรานสคริปต์เซสชันและ เพิ่ม sessions ไปยังแหล่งหน่วยความจำที่แก้ไขแล้วของเอเจนต์ เมื่อใช้ QMD ระบบจะ เปิดใช้งานการส่งออกเซสชันของเอเจนต์นั้นด้วย โดยไม่ต้องมีการตั้งค่า memory.qmd.sessions.enabled แยกต่างหากสำหรับโหมดนี้

ผู้ให้บริการหน่วยความจำในตัวของ OpenClaw รองรับเส้นทางที่ได้รับการปกป้องนี้ทั้งกับ แบ็กเอนด์ในตัวและ QMD ผู้ให้บริการหน่วยความจำทางเลือกยังคงใช้ ฮุกการเรียกคืนของตนเองและเครื่องมือ Active Memory ขั้นสูงได้ แต่ระบบจะข้ามการตั้งค่านี้ เว้นแต่ผู้ให้บริการปัจจุบันรองรับการเรียกคืนทรานสคริปต์ส่วนตัวที่ได้รับการปกป้อง openclaw doctor จะรายงานผู้ให้บริการที่ไม่รองรับ หรือรายการ toolsAllow ของ Active Memory ที่กำหนดไว้อย่างชัดเจนซึ่งไม่มี memory_search

ขอบเขตการเรียกค้นแคบกว่าการค้นหาเซสชันทั่วไป:

• มีเพียงบทสนทนาส่วนตัวที่ระบบรู้จักของเอเจนต์เดียวกันเท่านั้นที่มีสิทธิ์
• ไม่รวมบทสนทนาที่กำลังตอบ
• ไม่รวมกลุ่มและช่องทางทั้งในฐานะแหล่งที่มาและปลายทาง
• ชนิดบทสนทนาที่ไม่รู้จักจะปฏิเสธโดยค่าเริ่มต้น
• การเรียกคืนในแซนด์บ็อกซ์ไม่สามารถใช้การอนุญาตพิเศษสำหรับการข้ามบทสนทนา

การตั้งค่านี้ไม่เปลี่ยน tools.sessions.visibility, คีย์เซสชัน, การจัดเก็บทรานสคริปต์ การกำหนดเส้นทางการส่ง หรือสิทธิ์ของ sessions_list, sessions_history และ sessions_send Active Memory จะดำเนินการ เรียกค้นแบบอ่านอย่างเดียวภายในขอบเขตที่จำกัด หากการเรียกค้นใช้งานไม่ได้หรือหมดเวลา จะไม่ขัดขวาง การตอบกลับ

การเลือกผู้ให้บริการ

เมื่อไม่ได้ตั้งค่า provider OpenClaw จะใช้การฝังของ OpenAI ตั้งค่า provider อย่างชัดเจนเพื่อใช้ Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, โมเดล GGUF ภายในเครื่อง หรือปลายทาง /v1/embeddings ที่เข้ากันได้กับ OpenAI การกำหนดค่ารุ่นเก่าที่ยังระบุ 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 เท่านั้นโดยไม่แจ้งให้ทราบ แก้ไข การกำหนดค่าผู้ให้บริการ/การตรวจสอบสิทธิ์ เปลี่ยนไปใช้ผู้ให้บริการที่เข้าถึงได้ หรือตั้งค่า provider: "none" หากต้องการใช้การเรียกคืนแบบ FTS เท่านั้นโดยเจตนา

ID ผู้ให้บริการแบบกำหนดเอง

memorySearch.provider สามารถชี้ไปยังรายการ models.providers.<id> แบบกำหนดเองสำหรับอะแดปเตอร์ผู้ให้บริการเฉพาะหน่วยความจำ เช่น ollama หรือสำหรับ API โมเดลที่เข้ากันได้กับ OpenAI เช่น openai-responses / openai-completions OpenClaw จะแก้ไขเจ้าของ api ของผู้ให้บริการนั้นสำหรับอะแดปเตอร์การฝัง ขณะเดียวกันยังคงรักษา ID ผู้ให้บริการแบบกำหนดเองไว้สำหรับการจัดการปลายทาง การตรวจสอบสิทธิ์ และคำนำหน้าโมเดล ซึ่งช่วยให้การตั้งค่าแบบหลาย 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 key

การฝังระยะไกลต้องใช้ API key ส่วน Bedrock ใช้สายโซ่ข้อมูลประจำตัวเริ่มต้นของ AWS SDK แทน (บทบาทอินสแตนซ์, SSO, คีย์การเข้าถึง หรือ Bedrock API key)

การกำหนดค่าปลายทางระยะไกล

ใช้ provider: "openai-compatible" สำหรับเซิร์ฟเวอร์ /v1/embeddings ทั่วไปที่เข้ากันได้กับ OpenAI ซึ่งไม่ควรสืบทอดข้อมูลประจำตัวการแชต OpenAI ส่วนกลาง

{  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

การหมดเวลาของ embedding แบบอินไลน์

ลักษณะการทำดัชนี

ทั้งหมดอยู่ภายใต้ memorySearch.sync เว้นแต่จะระบุไว้:

การกำหนดค่าการค้นหาแบบไฮบริด

ทั้งหมดอยู่ภายใต้ memorySearch.query:

และภายใต้ memorySearch.query.hybrid:

ตัวอย่างฉบับเต็ม

{  agents: {    defaults: {      memorySearch: {        query: {          maxResults: 6,          minScore: 0.35,          hybrid: {            mmr: { enabled: true },            temporalDecay: { enabled: true },          },        },      },    },  },}

พาธหน่วยความจำเพิ่มเติม

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

พาธอาจเป็นพาธสัมบูรณ์หรือสัมพันธ์กับเวิร์กสเปซ ระบบจะสแกนไดเรกทอรีแบบเรียกซ้ำเพื่อค้นหาไฟล์ .md การจัดการลิงก์สัญลักษณ์ขึ้นอยู่กับแบ็กเอนด์ที่ใช้งานอยู่: เอนจินในตัวจะข้ามลิงก์สัญลักษณ์ ขณะที่ QMD จะทำตามพฤติกรรมของตัวสแกน QMD ที่อยู่เบื้องหลัง

สำหรับการค้นหาทรานสคริปต์ข้ามเอเจนต์ที่กำหนดขอบเขตตามเอเจนต์ ให้ใช้ agents.list[].memorySearch.qmd.extraCollections แทน memory.qmd.paths คอลเลกชันเพิ่มเติมเหล่านั้นใช้รูปแบบ { path, name, pattern? } เดียวกัน แต่จะถูกรวมแยกตามเอเจนต์ และสามารถคงชื่อที่ใช้ร่วมกันซึ่งระบุไว้อย่างชัดเจนได้เมื่อพาธชี้ออกนอกเวิร์กสเปซปัจจุบัน หากพาธที่แก้ไขแล้วเดียวกันปรากฏทั้งใน memory.qmd.paths และ memorySearch.qmd.extraCollections QMD จะเก็บรายการแรกและข้ามรายการที่ซ้ำ

หน่วยความจำหลายรูปแบบ (Gemini)

จัดทำดัชนีรูปภาพและเสียงควบคู่กับ Markdown โดยใช้ Gemini Embedding 2:

รูปแบบที่รองรับ: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (รูปภาพ); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (เสียง)

แคช Embedding

ป้องกันไม่ให้สร้าง Embedding ซ้ำสำหรับข้อความที่ไม่มีการเปลี่ยนแปลงระหว่างการจัดทำดัชนีใหม่หรือการอัปเดตทรานสคริปต์

การจัดทำดัชนีแบบแบตช์

ใช้ได้กับ gemini, openai และ voyage โดยทั่วไปแบตช์ของ OpenAI จะเร็วที่สุดและมีค่าใช้จ่ายต่ำที่สุดสำหรับการเติมข้อมูลย้อนหลังขนาดใหญ่

remote.nonBatchConcurrency ควบคุมการเรียกสร้าง Embedding แบบอินไลน์ที่ผู้ให้บริการในเครื่อง/โฮสต์เองและผู้ให้บริการแบบโฮสต์ใช้ เมื่อ API แบบแบตช์ของผู้ให้บริการไม่ได้ทำงานอยู่ Ollama มีค่าเริ่มต้นเป็น 1 สำหรับการจัดทำดัชนีแบบไม่ใช้แบตช์ เพื่อหลีกเลี่ยงการสร้างภาระมากเกินไปให้แก่โฮสต์ในเครื่องขนาดเล็ก ให้ตั้งค่าที่สูงขึ้นบนเครื่องที่มีขนาดใหญ่กว่า

ค่านี้แยกจาก sync.embeddingBatchTimeoutSeconds ซึ่งควบคุมระยะหมดเวลาสำหรับการเรียกสร้าง Embedding แบบอินไลน์

การค้นหาหน่วยความจำเซสชัน (ทดลอง)

จัดทำดัชนีทรานสคริปต์ของเซสชันและแสดงผ่าน memory_search:

การค้นหาทรานสคริปต์เซสชันทั่วไปที่โมเดลเรียกใช้จะเป็นไปตาม tools.sessions.visibility การมองเห็นเริ่มต้นแบบ tree จะเปิดให้เห็นเซสชันปัจจุบัน เซสชันที่เซสชันนี้สร้างขึ้น และ เซสชันกลุ่มของเอเจนต์เดียวกันที่เฝ้าดูผ่านการรับรู้กลุ่มโดยรอบ ส่วนเซสชันอื่นที่ ไม่เกี่ยวข้องต้องใช้การมองเห็นแบบ agent (หรือ all เฉพาะเมื่อจำเป็นต้อง เรียกคืนข้ามเอเจนต์ด้วย และนโยบายระหว่างเอเจนต์อนุญาต)

rememberAcrossConversations ไม่ได้ขยายการตั้งค่านั้น แต่ให้ การอนุญาตเฉพาะรันไทม์ที่แยกต่างหาก ซึ่งจำกัดไว้เฉพาะทรานสคริปต์ส่วนตัว ของเอเจนต์เดียวกันระหว่างรอบ Active Memory ที่มีขอบเขตจำกัด

ตัวอย่างด้านล่างวางการตั้งค่าเหล่านี้ไว้ภายใต้ agents.defaults นอกจากนี้ยังสามารถ ใช้การตั้งค่า memorySearch ที่เทียบเท่าในการแทนค่าระดับเอเจนต์ เมื่อควรมีเพียงเอเจนต์เดียว ที่จัดทำดัชนีและค้นหาทรานสคริปต์เซสชัน

สำหรับการเรียกคืนจาก Gateway ไปยังข้อความส่วนตัวภายในเอเจนต์เดียวกัน:

{  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 ด้วย ข้อยกเว้นคือการตั้งค่าระดับสูงกว่าอย่าง rememberAcrossConversations: true ซึ่งจะเปิดใช้การส่งออกเซสชัน QMD ที่จำเป็นสำหรับเอเจนต์นั้นโดยนัย การส่งออกโดยนัยยังคงเป็นส่วนตัว: จะใช้ตำแหน่งส่งออกภายในเริ่มต้นเสมอ (sessions.exportDir ที่กำหนดค่าไว้ ใช้กับการส่งออกโดยชัดแจ้งเท่านั้น) จะถูกค้นหาเฉพาะระหว่างการเรียกคืนข้ามบทสนทนา ของเอเจนต์นั้น และ memory_get ทั่วไปไม่สามารถอ่านได้ การตั้งค่า memory.qmd.sessions.enabled: true โดยชัดแจ้งจะคงลักษณะการทำงานเดิม และทำให้ ทรานสคริปต์ที่ส่งออกเป็นส่วนหนึ่งของคลังหน่วยความจำทั่วไป

การเร่งความเร็วเวกเตอร์ SQLite (sqlite-vec)

เมื่อ sqlite-vec ใช้งานไม่ได้ OpenClaw จะถอยกลับไปใช้การคำนวณความคล้ายคลึงแบบโคไซน์ภายในกระบวนการโดยอัตโนมัติ

ที่จัดเก็บดัชนี

ดัชนีหน่วยความจำในตัวจะอยู่ในฐานข้อมูล SQLite ของ OpenClaw สำหรับแต่ละเอเจนต์ที่ agents/<agentId>/agent/openclaw-agent.sqlite

การกำหนดค่าแบ็กเอนด์ QMD

ตั้งค่า memory.backend = "qmd" เพื่อเปิดใช้ การตั้งค่า QMD ทั้งหมดอยู่ภายใต้ memory.qmd:

searchMode: "search" ใช้เฉพาะการค้นหาเชิงคำศัพท์/BM25 เท่านั้น OpenClaw จะไม่ดำเนินการตรวจสอบความพร้อมของเวกเตอร์เชิงความหมายหรือบำรุงรักษา Embedding ของ QMD สำหรับโหมดดังกล่าว รวมถึงระหว่าง memory status --deep; ส่วน vsearch และ query ยังคงต้องใช้ความพร้อมของเวกเตอร์และ Embedding ของ QMD

rerank: false เปลี่ยนเฉพาะโหมด query ของ QMD และต้องใช้ QMD 2.1 หรือใหม่กว่า ในโหมด CLI โดยตรง OpenClaw จะส่ง --no-rerank; ในโหมด MCP ที่รองรับโดย mcporter จะส่ง rerank: false ไปยังเครื่องมือคิวรีแบบรวมของ QMD เว้นว่างไว้เพื่อใช้ลักษณะการจัดอันดับคิวรีใหม่ตามค่าเริ่มต้นของ QMD

OpenClaw เลือกใช้รูปแบบคอลเลกชันและคิวรี MCP ปัจจุบันของ QMD แต่ยังคงรองรับ QMD รุ่นเก่าโดยลองใช้แฟล็กรูปแบบคอลเลกชันที่เข้ากันได้และชื่อเครื่องมือ MCP รุ่นเก่าเมื่อจำเป็น เมื่อ QMD ประกาศว่ารองรับตัวกรองหลายคอลเลกชัน ระบบจะค้นหาคอลเลกชันจากแหล่งเดียวกันด้วยกระบวนการ QMD เดียว ส่วนบิลด์ QMD รุ่นเก่าจะยังคงใช้เส้นทางความเข้ากันได้แยกตามคอลเลกชัน แหล่งเดียวกันหมายถึงคอลเลกชันหน่วยความจำแบบคงทน (ไฟล์หน่วยความจำเริ่มต้นรวมกับพาธแบบกำหนดเอง) จะถูกจัดกลุ่มเข้าด้วยกัน ขณะที่คอลเลกชันทรานสคริปต์เซสชันยังคงเป็นอีกกลุ่มแยกต่างหาก เพื่อให้การกระจายแหล่งข้อมูลยังคงมีข้อมูลนำเข้าจากทั้งสองแหล่ง

การผสานรวม mcporter

ทั้งหมดอยู่ภายใต้ memory.qmd.mcporter โดยกำหนดเส้นทางการค้นหา QMD ผ่านดีมอน MCP mcporter ที่ทำงานต่อเนื่อง แทนการสร้าง qmd ต่อคิวรี ซึ่งช่วยลดโอเวอร์เฮดจากการเริ่มต้นแบบเย็นสำหรับโมเดลขนาดใหญ่

ต้องติดตั้ง mcporter และให้อยู่ใน PATH พร้อมทั้งกำหนดค่าเซิร์ฟเวอร์ mcporter ที่เรียกใช้ qmd mcp ให้ปิดใช้งานไว้สำหรับการตั้งค่าในเครื่องแบบเรียบง่าย ซึ่งยอมรับต้นทุนการสร้างกระบวนการต่อคิวรีได้

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

เมื่อเปิดใช้การเริ่มต้น QMD ขณะ Gateway เริ่มทำงาน 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 ภายใต้ plugins.entries.memory-core.config.dreaming ไม่ใช่ภายใต้ agents.defaults.memorySearch

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",          },        },      },    },  },}

ที่เกี่ยวข้อง

• ข้อมูลอ้างอิงการกำหนดค่า
• ภาพรวมหน่วยความจำ
• การค้นหาหน่วยความจำ