مرور کلی حافظه

OpenClaw با نوشتن فایل‌های ساده Markdown در فضای کاری عامل شما (پیش‌فرض ~/.openclaw/workspace) اطلاعات را به خاطر می‌سپارد. مدل فقط چیزهایی را به خاطر می‌سپارد که روی دیسک ذخیره شده‌اند؛ هیچ حالت پنهانی وجود ندارد.

نحوه کار

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

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

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

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

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

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

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

وارد کردن از دستیارهای کدنویسی

رابط کاربری کنترل می‌تواند حافظه محلی موجود را از Codex و Claude Code وارد کند. Settings ← Import Memory را باز کنید، عامل مقصد را انتخاب کنید، فایل‌های شناسایی‌شده را بازبینی کنید و وارد کردن را تأیید کنید. OpenClaw فقط حافظه Markdown را کپی می‌کند:

• Codex: فایل‌های تجمیع‌شده MEMORY.md و memory_summary.md در ~/.codex/memories (یا CODEX_HOME/memories). فایل‌های خام اجرای مدل و رونوشت وارد نمی‌شوند.
• Claude Code: فایل‌های Markdown از پوشه حافظه خودکار هر پروژه در ~/.claude/projects/*/memory، به‌علاوه یک autoMemoryDirectory پیکربندی‌شده توسط کاربر، در صورت وجود. دستورالعمل‌های پروژه، نشست‌ها، تنظیمات و اطلاعات احراز هویت بخشی از این عملیات صرفاً حافظه‌ای نیستند.

فایل‌های واردشده در memory/imports/codex/ و memory/imports/claude-code/ در فضای کاری عامل انتخاب‌شده جدا باقی می‌مانند. آن‌ها برای memory_search نمایه‌سازی می‌شوند و از طریق memory_get در دسترس‌اند؛ با MEMORY.md راه‌اندازی عامل ادغام نمی‌شوند. فایل‌های منبع بدون تغییر باقی می‌مانند.

پیش‌نمایش، تعارض‌های مقصد را مشخص می‌کند. برای جایگزینی آن فایل‌ها، Replace existing imports را فعال کنید؛ اعمال عملیات، یک پشتیبان تأییدشده پیش از وارد کردن ایجاد می‌کند و نسخه‌های جداگانه فایل‌های بازنویسی‌شده را در گزارش مهاجرت نگه می‌دارد.

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

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

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

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

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

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

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

مثال:

مهاجرت API در نشست دیگری در حال طراحی است. نوبت‌های آینده نبایدپیاده‌سازی API را از این رشته ویرایش کنند؛ تا زمان نهایی شدن برنامه مهاجرت، یافته‌های اینجا را فقط به‌عنوانورودی طراحی استفاده کنید.

مثالی دیگر:

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

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

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

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

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

آزمایش تعهدات استنباط‌شده بازنشسته شده است. OpenClaw دیگر آن پیگیری‌ها را استخراج یا تحویل نمی‌دهد. برای اقدامات آینده از وظایف زمان‌بندی‌شده استفاده کنید؛ فرمان قدیمی openclaw commitments همچنان برای بررسی یا رد کردن ردیف‌های ذخیره‌شده موجود در دسترس است.

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

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

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

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

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

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

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

بک‌اندهای حافظه

لایه ویکی دانش

اگر می‌خواهید حافظه ماندگار بیشتر شبیه یک پایگاه دانش نگه‌داری‌شده عمل کند تا یادداشت‌های خام، از Plugin همراه memory-wiki استفاده کنید. این Plugin دانش ماندگار را در یک مخزن ویکی با ساختار صفحه قطعی، ادعاها و شواهد ساختاریافته، ردیابی تناقض و تازگی، داشبوردهای تولیدشده، چکیده‌های کامپایل‌شده و ابزارهای بومی ویکی (wiki_status، wiki_search، wiki_get، wiki_apply، wiki_lint) کامپایل می‌کند.

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

تخلیه خودکار حافظه

پیش از آنکه Compaction گفت‌وگوی شما را خلاصه کند، OpenClaw یک نوبت بی‌صدا اجرا می‌کند که به عامل یادآوری می‌کند زمینه مهم را در فایل‌های حافظه ذخیره کند. این قابلیت به‌طور پیش‌فرض فعال است؛ برای غیرفعال کردن آن agents.defaults.compaction.memoryFlush.enabled: false را تنظیم کنید.

برای نگه‌داشتن آن نوبت نگه‌داری روی یک مدل محلی، یک بازنویسی دقیق تنظیم کنید که فقط بر نوبت تخلیه حافظه اعمال شود (این نوبت زنجیره جایگزین مدل نشست فعال را به ارث نمی‌برد):

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

Dreaming

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

• اختیاری: به‌طور پیش‌فرض غیرفعال است.
• زمان‌بندی‌شده: وقتی فعال باشد، memory-core یک کار Cron تکرارشونده را برای مرور کامل Dreaming به‌طور خودکار مدیریت می‌کند.
• آستانه‌دار: ارتقاها باید از دروازه‌های امتیاز، فراوانی یادآوری و تنوع پرس‌وجو عبور کنند.
• قابل‌بازبینی: خلاصه‌های مرحله و ورودی‌های دفترچه در DREAMS.md برای بازبینی انسانی نوشته می‌شوند.

برای جزئیات رفتار مرحله‌ها، سیگنال‌های امتیازدهی و دفترچه رؤیا به Dreaming مراجعه کنید.

بازپُرکنی مستند و ارتقای زنده

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

• Dreaming زنده با مخزن کوتاه‌مدت Dreaming در memory/.dreams/ کار می‌کند و مرحله عمیق عادی از آن برای تصمیم‌گیری درباره مواردی که به MEMORY.md راه می‌یابند استفاده می‌کند.
• بازپُرکنی مستند یادداشت‌های تاریخی memory/YYYY-MM-DD.md را به‌عنوان فایل‌های روز مستقل می‌خواند و خروجی ساختاریافته بازبینی را در DREAMS.md می‌نویسد.

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

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

پرچم --stage-short-term نامزدهای ماندگار مستند را در همان مخزن کوتاه‌مدت Dreaming قرار می‌دهد که مرحله عمیق عادی از قبل استفاده می‌کند؛ این پرچم آن‌ها را مستقیماً ارتقا نمی‌دهد. بنابراین:

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

برای بازگرداندن یک بازپخش بدون دست‌زدن به ورودی‌های معمول دفترچه یا وضعیت عادی یادآوری:

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

CLI

openclaw memory status          # بررسی وضعیت نمایه و ارائه‌دهندهopenclaw memory search "query"  # جست‌وجو از خط فرمانopenclaw memory index --force   # بازسازی نمایه

مطالعه بیشتر

• جست‌وجوی حافظه: پایپ‌لاین جست‌وجو، ارائه‌دهندگان و تنظیم دقیق.
• موتور حافظه داخلی: بک‌اند پیش‌فرض SQLite.
• موتور حافظه QMD: سایدکار پیشرفته با رویکرد محلی‌محور.
• حافظه Honcho: حافظه بومی هوش مصنوعی میان نشست‌ها.
• حافظه LanceDB: Plugin مبتنی بر LanceDB با امبدینگ‌های سازگار با OpenAI.
• ویکی حافظه: مخزن دانش کامپایل‌شده و ابزارهای بومی ویکی.
• Dreaming: ارتقای پس‌زمینه‌ای از یادآوری کوتاه‌مدت به حافظه بلندمدت.
• مرجع پیکربندی حافظه: همه گزینه‌های پیکربندی.
• Compaction: نحوه تعامل فشرده‌سازی با حافظه.
• حافظه فعال: حافظه زیرعامل برای نشست‌های گفت‌وگوی تعاملی.