เอกสารอ้างอิงการกำหนดค่าหน่วยความจำ

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

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

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

เมื่อไม่ได้ตั้งค่า 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 เท่านั้นโดยเจตนา

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

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

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

ใช้ 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

ระยะหมดเวลาของการฝังข้อมูลแบบอินไลน์

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

ทั้งหมดอยู่ภายใต้ 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 ที่อยู่เบื้องหลัง

สำหรับการค้นหาบันทึกบทสนทนาข้ามเอเจนต์ที่จำกัดขอบเขตตามเอเจนต์ ให้ใช้ 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 ซ้ำสำหรับข้อความที่ไม่มีการเปลี่ยนแปลงระหว่างการจัดทำดัชนีใหม่หรือการอัปเดตบทถอดเสียง ปล่อย maxEntries ไว้โดยไม่ตั้งค่าสำหรับแคชแบบไม่จำกัด หรือกำหนดค่าเมื่อการเพิ่มขึ้นของพื้นที่ดิสก์สำคัญกว่าความเร็วสูงสุดในการจัดทำดัชนีใหม่ เมื่อกำหนดค่าแล้ว รายการที่เก่าที่สุด (ตามเวลาที่อัปเดตล่าสุด) จะถูกลบออกก่อนเมื่อแคชเกินขีดจำกัด

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

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

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

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

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

จัดทำดัชนีบทถอดเสียงของเซสชันและแสดงผลผ่าน memory_search:

ผลการค้นพบจากบทถอดเสียงของเซสชันยังอยู่ภายใต้ข้อกำหนดของ tools.sessions.visibility การมองเห็นเริ่มต้นแบบ tree จะแสดงเฉพาะเซสชันปัจจุบันและเซสชันที่เซสชันนี้สร้างขึ้นเท่านั้น หากต้องการ เรียกคืนเซสชันที่ไม่เกี่ยวข้องกันซึ่งดำเนินการโดยเอเจนต์เดียวกันและ Gateway เป็นผู้ส่งงานจากอีก เซสชันหนึ่ง เช่น DM ให้ขยายการมองเห็นเป็น 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 จะย้อนกลับไปใช้การวัดความคล้ายคลึงแบบโคไซน์ภายในโปรเซสโดยอัตโนมัติ

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

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

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

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

searchMode: "search" ใช้การค้นหาเชิงคำศัพท์/BM25 เท่านั้น OpenClaw จะไม่เรียกใช้การตรวจสอบความพร้อมของเวกเตอร์เชิงความหมายหรือการบำรุงรักษาเอ็มเบดดิงของ QMD สำหรับโหมดนี้ รวมถึงระหว่าง memory status --deep; ส่วน vsearch และ query ยังคงต้องใช้ความพร้อมของเวกเตอร์และเอ็มเบดดิงจาก 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 เป็นจริงและไม่ได้กำหนดการบำรุงรักษาตามช่วงเวลา/การฝังข้อมูลไว้ การเริ่มต้นระบบจะใช้ตัวจัดการแบบทำงานครั้งเดียวสำหรับการรีเฟรชตอนบูต แล้วปิดตัวจัดการนั้น หากกำหนดช่วงเวลาการอัปเดตหรือการฝังข้อมูลไว้ การเริ่มต้นระบบจะเปิดตัวจัดการ 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 ทำงานเป็นการกวาดตามกำหนดเวลาเพียงครั้งเดียว และใช้ระยะเบา/ลึก/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",          },        },      },    },  },}

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

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