Sessions and memory
موتور حافظهٔ داخلی
موتور داخلی، بکاند پیشفرض حافظه است. این موتور نمایهٔ حافظهٔ شما را در یک پایگاهدادهٔ SQLite برای هر عامل ذخیره میکند و برای شروع به وابستگی اضافهای نیاز ندارد.
آنچه فراهم میکند
- جستوجوی کلیدواژهای از طریق نمایهسازی متن کامل FTS5 (امتیازدهی BM25).
- جستوجوی برداری از طریق بردارهای تعبیه از هر ارائهدهندهٔ پشتیبانیشده.
- جستوجوی ترکیبی که هر دو را برای بهترین نتیجهها ترکیب میکند.
- پشتیبانی از CJK از طریق توکنسازی سهحرفی برای چینی، ژاپنی و کرهای.
- شتابدهی sqlite-vec برای پرسوجوهای برداری درون پایگاهداده (اختیاری).
شروع به کار
اگر برای OpenAI، Gemini، Voyage، Mistral یا DeepInfra کلید API دارید، موتور داخلی آن را خودکار شناسایی میکند و جستوجوی برداری را فعال میکند. نیازی به پیکربندی نیست.
برای تنظیم صریح یک ارائهدهنده:
{
agents: {
defaults: {
memorySearch: {
provider: "openai",
},
},
},
}
بدون ارائهدهندهٔ بردار تعبیه، فقط جستوجوی کلیدواژهای در دسترس است.
برای اجبار به استفاده از ارائهدهندهٔ محلی داخلی بردار تعبیه، بستهٔ runtime اختیاری
node-llama-cpp را کنار OpenClaw نصب کنید، سپس local.modelPath
را به یک فایل GGUF اشاره دهید:
{
agents: {
defaults: {
memorySearch: {
provider: "local",
fallback: "none",
local: {
modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
},
},
},
},
}
ارائهدهندگان پشتیبانیشدهٔ بردار تعبیه
| ارائهدهنده | شناسه | شناسایی خودکار | نکتهها |
|---|---|---|---|
| OpenAI | openai |
بله | پیشفرض: text-embedding-3-small |
| Gemini | gemini |
بله | از چندرسانهای (تصویر + صوت) پشتیبانی میکند |
| Voyage | voyage |
بله | |
| Mistral | mistral |
بله | |
| DeepInfra | deepinfra |
بله | پیشفرض: BAAI/bge-m3 |
| Ollama | ollama |
خیر | محلی، بهصورت صریح تنظیم شود |
| محلی | local |
بله (اول) | runtime اختیاری node-llama-cpp |
شناسایی خودکار نخستین ارائهدهندهای را که کلید API آن قابل حل باشد، به ترتیبی که
نمایش داده شده انتخاب میکند. برای بازنویسی، memorySearch.provider را تنظیم کنید.
نمایهسازی چگونه کار میکند
OpenClaw فایلهای MEMORY.md و memory/*.md را به قطعهها (حدود ۴۰۰ توکن با
همپوشانی ۸۰ توکنی) نمایهسازی میکند و آنها را در یک پایگاهدادهٔ SQLite برای هر عامل ذخیره میکند.
- محل نمایه:
~/.openclaw/memory/<agentId>.sqlite - نگهداری ذخیرهسازی: فایلهای جانبی SQLite WAL با checkpointهای دورهای و هنگام خاموشی محدود نگه داشته میشوند.
- پایش فایل: تغییرات فایلهای حافظه یک نمایهسازی دوبارهٔ debounceشده را فعال میکنند (۱.۵ ثانیه).
- نمایهسازی دوبارهٔ خودکار: وقتی ارائهدهندهٔ بردار تعبیه، مدل، یا پیکربندی قطعهبندی تغییر کند، کل نمایه بهصورت خودکار از نو ساخته میشود.
- نمایهسازی دوباره بر اساس درخواست:
openclaw memory index --force
زمان استفاده
موتور داخلی انتخاب مناسب بیشتر کاربران است:
- بدون وابستگی اضافه، آمادهٔ استفاده است.
- جستوجوی کلیدواژهای و برداری را بهخوبی مدیریت میکند.
- از همهٔ ارائهدهندگان بردار تعبیه پشتیبانی میکند.
- جستوجوی ترکیبی بهترین بخشهای هر دو رویکرد بازیابی را با هم ترکیب میکند.
اگر به رتبهبندی دوباره، گسترش پرسوجو، یا نمایهسازی پوشههای خارج از workspace نیاز دارید، به QMD مهاجرت کنید.
اگر حافظهٔ بین نشستها با مدلسازی خودکار کاربر میخواهید، Honcho را در نظر بگیرید.
عیبیابی
جستوجوی حافظه غیرفعال است؟ openclaw memory status را بررسی کنید. اگر هیچ ارائهدهندهای
شناسایی نشد، یکی را صریح تنظیم کنید یا یک کلید API اضافه کنید.
ارائهدهندهٔ محلی شناسایی نمیشود؟ تأیید کنید مسیر محلی وجود دارد و اجرا کنید:
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
هم فرمانهای مستقل CLI و هم Gateway از همان شناسهٔ ارائهدهندهٔ local استفاده میکنند.
اگر ارائهدهنده روی auto تنظیم شده باشد، بردارهای تعبیهٔ محلی فقط وقتی ابتدا در نظر گرفته میشوند
که memorySearch.local.modelPath به یک فایل محلی موجود اشاره کند.
نتایج قدیمی هستند؟ برای بازسازی، openclaw memory index --force را اجرا کنید. پایشگر
ممکن است در موارد مرزی نادر برخی تغییرات را از دست بدهد.
sqlite-vec بارگذاری نمیشود؟ OpenClaw بهصورت خودکار به شباهت کسینوسی درونفرایندی
برمیگردد. openclaw memory status --deep ذخیرهساز برداری محلی را جدا از ارائهدهندهٔ بردار تعبیه
گزارش میکند؛ بنابراین Vector store: unavailable به بارگذاری sqlite-vec اشاره دارد، درحالیکه
Embeddings: unavailable به ارائهدهنده/احراز هویت یا آمادهبودن مدل اشاره میکند. برای خطای بارگذاری مشخص، logها را بررسی کنید.
پیکربندی
برای راهاندازی ارائهدهندهٔ بردار تعبیه، تنظیم جستوجوی ترکیبی (وزنها، MMR، کاهش زمانی)، نمایهسازی دستهای، حافظهٔ چندرسانهای، sqlite-vec، مسیرهای اضافه، و همهٔ گزینههای پیکربندی دیگر، مرجع پیکربندی حافظه را ببینید.