نمای کلی حافظه

OpenClaw چیزها را با نوشتن فایل‌های Markdown ساده در فضای کاری عامل شما به خاطر می‌سپارد. مدل فقط آنچه را که روی دیسک ذخیره می‌شود «به خاطر می‌سپارد»؛ هیچ وضعیت پنهانی وجود ندارد.

سازوکار

عامل شما سه فایل مرتبط با حافظه دارد:

• MEMORY.md — حافظهٔ بلندمدت. واقعیت‌ها، ترجیحات و تصمیم‌های ماندگار. در آغاز هر نشست پیام مستقیم بارگذاری می‌شود.
• memory/YYYY-MM-DD.md (یا memory/YYYY-MM-DD-<slug>.md) — یادداشت‌های روزانه. زمینهٔ در حال اجرا و مشاهدات. یادداشت‌های امروز و دیروز به‌طور خودکار بارگذاری می‌شوند، و گونه‌های دارای slug، مانند مواردی که hook حافظهٔ نشستِ همراه در /new یا /reset می‌نویسد، اکنون همراه با فایل فقط‌تاریخ نیز دریافت می‌شوند.
• DREAMS.md (اختیاری) — دفترچهٔ Dreaming و خلاصه‌های sweep مربوط به Dreaming برای بازبینی انسانی، شامل ورودی‌های backfill تاریخیِ مستند.

این فایل‌ها در فضای کاری عامل قرار دارند (پیش‌فرض ~/.openclaw/workspace).

چه چیزی کجا قرار می‌گیرد

MEMORY.md لایهٔ فشرده و گزینش‌شده است. از آن برای واقعیت‌های ماندگار، ترجیحات، تصمیم‌های پایدار و خلاصه‌های کوتاهی استفاده کنید که باید در آغاز یک نشست خصوصی اصلی در دسترس باشند. قرار نیست این فایل transcript خام، گزارش روزانه، یا آرشیو کامل باشد.

فایل‌های memory/YYYY-MM-DD.md لایهٔ کاری هستند. از آن‌ها برای یادداشت‌های روزانهٔ جزئی، مشاهدات، خلاصه‌های نشست، و زمینهٔ خامی استفاده کنید که شاید بعداً همچنان مفید باشد. این فایل‌ها برای memory_search و memory_get نمایه‌سازی می‌شوند، اما در prompt راه‌اندازی معمول در هر نوبت تزریق نمی‌شوند.

با گذشت زمان، انتظار می‌رود عامل مطالب مفید را از یادداشت‌های روزانه استخراج کرده و در MEMORY.md خلاصه کند و ورودی‌های بلندمدت منسوخ را حذف کند. دستورالعمل‌های تولیدشدهٔ فضای کاری و جریان Heartbeat می‌توانند این کار را دوره‌ای انجام دهند؛ لازم نیست برای هر جزئیات به‌خاطر‌سپرده‌شده، MEMORY.md را دستی ویرایش کنید.

اگر MEMORY.md از بودجهٔ فایل راه‌اندازی فراتر برود، OpenClaw فایل را روی دیسک دست‌نخورده نگه می‌دارد اما نسخه‌ای را که به زمینهٔ مدل تزریق می‌شود کوتاه می‌کند. این را نشانه‌ای بدانید برای انتقال دوبارهٔ مطالب جزئی به memory/*.md، نگه داشتن فقط خلاصهٔ ماندگار در MEMORY.md، یا افزایش محدودیت‌های راه‌اندازی اگر صراحتاً می‌خواهید بودجهٔ prompt بیشتری مصرف کنید. برای دیدن اندازه‌های خام در برابر تزریق‌شده و وضعیت کوتاه‌سازی، از /context list، /context detail، یا openclaw doctor استفاده کنید.

حافظه‌های حساس به اقدام

بیشتر حافظه‌ها را می‌توان به‌صورت یادداشت‌های معمولی Markdown نوشت. اما بعضی حافظه‌ها بر کاری که عامل باید بعداً انجام دهد اثر می‌گذارند. برای این موارد، زمان امن بودن اقدام بر اساس یادداشت را ثبت کنید، نه فقط خود واقعیت را.

این مرز اقدام را زمانی ثبت کنید که یادداشت شامل موارد زیر است:

• الزامات تأیید یا اجازه،
• محدودیت‌های موقت،
• واگذاری به نشست، thread، یا فرد دیگر،
• شرایط انقضا،
• زمان‌بندی امن برای اقدام،
• اعتبار منبع یا مالک،
• دستورالعمل‌هایی برای پرهیز از اقدامی وسوسه‌انگیز.

یک حافظهٔ حساس به اقدامِ مفید روشن می‌کند:

• چه چیزی رفتار آینده را تغییر می‌دهد،
• چه زمانی یا تحت چه شرطی اعمال می‌شود،
• چه زمانی منقضی می‌شود، یا چه چیزی اقدام را آزاد می‌کند،
• عامل باید از انجام چه کاری پرهیز کند،
• اگر بر اعتماد یا اختیار اثر دارد، منبع یا مالک چه کسی است.

حافظه می‌تواند زمینهٔ تأیید را حفظ کند، اما سیاست را اعمال نمی‌کند. برای کنترل‌های عملیاتی سخت، از تنظیمات تأیید OpenClaw، sandboxing، و وظایف زمان‌بندی‌شده استفاده کنید.

مثال:

The API migration is being designed in another session. Future turns should not edit the API implementation from this thread; use findings here only as design input until the migration plan lands.

مثالی دیگر:

A report from an untrusted source needs review before promotion. Future turns should treat it as evidence only; do not store it as durable memory until a trusted reviewer confirms the contents.

برای پیگیری‌های استنباط‌شده و کوتاه‌مدت از تعهدها استفاده کنید. برای یادآورها، بررسی‌های زمان‌دار، و کارهای تکرارشوندهٔ دقیق از وظایف زمان‌بندی‌شده استفاده کنید. حافظه همچنان می‌تواند زمینهٔ ماندگار پیرامون هر مسیر را خلاصه کند.

این یک schema الزامی برای هر حافظه نیست. واقعیت‌های ساده می‌توانند کوتاه بمانند. زمانی از مرزهای حساس به اقدام استفاده کنید که از دست رفتن زمان‌بندی، اختیار، انقضا، یا زمینهٔ امن برای اقدام می‌تواند باعث شود عامل بعداً کار اشتباهی انجام دهد.

تعهدهای استنباط‌شده

برخی پیگیری‌های آینده، واقعیت‌های ماندگار نیستند. اگر به مصاحبه‌ای در فردا اشاره کنید، حافظهٔ مفید ممکن است «بعد از مصاحبه پیگیری کن» باشد، نه «این را برای همیشه در MEMORY.md ذخیره کن.»

تعهدها حافظه‌های پیگیریِ اختیاری و کوتاه‌مدت برای همین مورد هستند. OpenClaw آن‌ها را در یک گذر پس‌زمینهٔ پنهان استنباط می‌کند، به همان عامل و channel محدودشان می‌کند، و رسیدگی‌های سررسیدشده را از طریق Heartbeat تحویل می‌دهد. یادآورهای صریح همچنان از وظایف زمان‌بندی‌شده استفاده می‌کنند.

ابزارهای حافظه

عامل دو ابزار برای کار با حافظه دارد:

• memory_search — یادداشت‌های مرتبط را با جست‌وجوی معنایی پیدا می‌کند، حتی وقتی عبارت‌بندی با متن اصلی متفاوت باشد.
• memory_get — یک فایل حافظه یا بازهٔ خطوط مشخص را می‌خواند.

هر دو ابزار توسط Plugin حافظهٔ فعال ارائه می‌شوند (پیش‌فرض: memory-core).

Plugin همراه Memory Wiki

اگر می‌خواهید حافظهٔ ماندگار بیشتر شبیه یک پایگاه دانش نگه‌داری‌شده عمل کند تا صرفاً یادداشت‌های خام، از Plugin همراه memory-wiki استفاده کنید.

memory-wiki دانش ماندگار را در یک خزانهٔ wiki با این ویژگی‌ها کامپایل می‌کند:

• ساختار صفحهٔ قطعی
• ادعاها و شواهد ساختاریافته
• رهگیری تناقض و تازگی
• dashboardهای تولیدشده
• digestهای کامپایل‌شده برای مصرف‌کنندگان عامل/runtime
• ابزارهای بومی wiki مانند wiki_search، wiki_get، wiki_apply، و wiki_lint

این جایگزین Plugin حافظهٔ فعال نمی‌شود. Plugin حافظهٔ فعال همچنان مالک recall، promotion، و Dreaming است. memory-wiki یک لایهٔ دانش غنی از provenance در کنار آن اضافه می‌کند.

Memory Wiki را ببینید.

جست‌وجوی حافظه

وقتی یک ارائه‌دهندهٔ embedding پیکربندی شده باشد، memory_search از جست‌وجوی ترکیبی استفاده می‌کند؛ یعنی ترکیب شباهت برداری (معنای معنایی) با تطبیق کلیدواژه (عبارت‌های دقیق مانند شناسه‌ها و نمادهای کد). وقتی برای هر ارائه‌دهندهٔ پشتیبانی‌شده کلید API داشته باشید، این قابلیت بدون تنظیم اضافه کار می‌کند.

برای جزئیات دربارهٔ سازوکار جست‌وجو، گزینه‌های تنظیم، و راه‌اندازی ارائه‌دهنده، جست‌وجوی حافظه را ببینید.

backendهای حافظه

لایهٔ wiki دانش

flush خودکار حافظه

پیش از آنکه Compaction گفت‌وگوی شما را خلاصه کند، OpenClaw یک نوبت بی‌صدا اجرا می‌کند که به عامل یادآوری می‌کند زمینهٔ مهم را در فایل‌های حافظه ذخیره کند. این به‌طور پیش‌فرض فعال است؛ لازم نیست چیزی را پیکربندی کنید.

برای نگه داشتن آن نوبت خانه‌داری روی یک مدل local، یک override دقیق برای مدل memory-flush تنظیم کنید:

{  "agents": {    "defaults": {      "compaction": {        "memoryFlush": {          "model": "ollama/qwen3:8b"        }      }    }  }}

این override فقط برای نوبت memory-flush اعمال می‌شود و زنجیرهٔ fallback نشست فعال را به ارث نمی‌برد.

Dreaming

Dreaming یک گذر تلفیق پس‌زمینهٔ اختیاری برای حافظه است. سیگنال‌های کوتاه‌مدت را جمع‌آوری می‌کند، candidateها را امتیازدهی می‌کند، و فقط موارد واجد شرایط را به حافظهٔ بلندمدت (MEMORY.md) promote می‌کند.

برای حفظ signal بالا در حافظهٔ بلندمدت طراحی شده است:

• اختیاری: به‌طور پیش‌فرض غیرفعال است.
• زمان‌بندی‌شده: وقتی فعال باشد، memory-core یک job تکرارشوندهٔ Cron را برای sweep کامل Dreaming به‌طور خودکار مدیریت می‌کند.
• آستانه‌دار: promotionها باید از gateهای امتیاز، فراوانی recall، و تنوع query عبور کنند.
• قابل بازبینی: خلاصه‌های phase و ورودی‌های diary در DREAMS.md برای بازبینی انسانی نوشته می‌شوند.

برای رفتار phase، سیگنال‌های امتیازدهی، و جزئیات دفترچهٔ Dreaming، Dreaming را ببینید.

backfill مستند و promotion زنده

سیستم Dreaming اکنون دو مسیر بازبینی نزدیک به هم دارد:

• Dreaming زنده از store کوتاه‌مدت Dreaming در memory/.dreams/ کار می‌کند و همان چیزی است که phase عمیق معمول هنگام تصمیم‌گیری دربارهٔ اینکه چه چیزی می‌تواند به MEMORY.md منتقل شود، استفاده می‌کند.
• backfill مستند یادداشت‌های تاریخی memory/YYYY-MM-DD.md را به‌عنوان فایل‌های روز مستقل می‌خواند و خروجی بازبینی ساختاریافته را در DREAMS.md می‌نویسد.

backfill مستند زمانی مفید است که بخواهید یادداشت‌های قدیمی‌تر را دوباره پخش کنید و بررسی کنید سیستم چه چیزی را ماندگار می‌داند، بدون اینکه MEMORY.md را دستی ویرایش کنید.

وقتی از این استفاده می‌کنید:

openclaw memory rem-backfill --path ./memory --stage-short-term

candidateهای ماندگار مستند مستقیماً promote نمی‌شوند. آن‌ها در همان store کوتاه‌مدت Dreaming قرار داده می‌شوند که phase عمیق معمول از قبل استفاده می‌کند. یعنی:

• DREAMS.md سطح بازبینی انسانی باقی می‌ماند.
• store کوتاه‌مدت سطح ranking رو‌به‌ماشین باقی می‌ماند.
• MEMORY.md همچنان فقط توسط promotion عمیق نوشته می‌شود.

اگر تصمیم گرفتید بازپخش مفید نبوده است، می‌توانید artifactهای stage‌شده را بدون دست زدن به ورودی‌های diary معمولی یا وضعیت recall عادی حذف کنید:

openclaw memory rem-backfill --rollbackopenclaw memory rem-backfill --rollback-short-term

CLI

openclaw memory status          # Check index status and provideropenclaw memory search "query"  # Search from the command lineopenclaw memory index --force   # Rebuild the index

مطالعهٔ بیشتر

• موتور حافظهٔ داخلی: backend پیش‌فرض SQLite.
• موتور حافظهٔ QMD: sidecar پیشرفته با اولویت محلی.
• حافظهٔ Honcho: حافظهٔ میان‌نشستیِ بومی AI.
• Memory LanceDB: Plugin مبتنی بر LanceDB با embeddingهای سازگار با OpenAI.
• Memory Wiki: خزانهٔ دانش کامپایل‌شده و ابزارهای بومی wiki.
• جست‌وجوی حافظه: pipeline جست‌وجو، ارائه‌دهندگان، و تنظیم.
• Dreaming: promotion پس‌زمینه از recall کوتاه‌مدت به حافظهٔ بلندمدت.
• مرجع پیکربندی حافظه: همهٔ knobهای پیکربندی.
• Compaction: نحوهٔ تعامل Compaction با حافظه.

مرتبط

• Active Memory
• جست‌وجوی حافظه
• موتور حافظهٔ داخلی
• حافظهٔ Honcho
• Memory LanceDB
• تعهدها