حافظهٔ پایدار برای ایجنت‌ها؛ ایجنتی که درس دیروز را فراموش نمی‌کند

یک شرکت نرم‌افزاری در تهران ایجنت بازبینی کد راه انداخته بود. ایجنت کارش را خوب انجام می‌داد: هر Pull Request را می‌خواند، ایراد می‌گرفت، پیشنهاد می‌داد. اما یک چیز آزاردهنده بود. هفتهٔ اول، ایجنت در یک اسکریپت خزندهٔ چندنخی یک باگ کلاسیک پیدا کرد — لیستی که چند نخ همزمان به آن append می‌کردند و نتیجه هر بار فرق داشت. توضیح مفصلی هم نوشت. هفتهٔ سوم، در یک کلاینت غیرهمگام دقیقاً همان الگو تکرار شد: چند تسک همزمان در یک لیست مشترک می‌نوشتند. ایجنت باز از صفر شروع کرد؛ باز همان تحلیل را از اول ساخت؛ باز همان توکن‌ها را خرج کرد. هیچ‌چیز از هفتهٔ اول باقی نمانده بود.

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

آنچه در این درس یاد می‌گیرید

• تفاوت بنیادی ابزار حافظه با ابزارهای معمول: چرا اجرایش تماماً روی دوش شماست
• شش فرمانی که هندلر حافظه باید پیاده کند و ساختار پوشهٔ /memories
• نوشتن حلقهٔ گفتگویی که فرمان‌های حافظه را اجرا می‌کند
• ویرایش زمینه: پاک کردن خودکار نتایج قدیمی ابزار بدون از دست دادن دانش ذخیره‌شده
• تصمیم‌گیری دربارهٔ اینکه چه چیزی ارزش ماندن در حافظه را دارد و چه چیزی ندارد
• دو ریسک امنیتی جدی — پیمایش مسیر و مسموم‌سازی حافظه — و راه مهارشان

حافظه چیست و چه چیزی نیست

اول یک بدفهمی رایج را کنار بگذاریم: ابزار حافظه یک سرویس ذخیره‌سازی در سمت آنتروپیک نیست. مدل هیچ فایلی جایی نگه نمی‌دارد. کاری که می‌کند این است که فرمان می‌دهد؛ مثلاً «فایل /memories/review.md را بخوان» یا «این متن را در آن بنویس». اجرای این فرمان‌ها کامل با شماست. یعنی شما تصمیم می‌گیرید فایل‌ها کجا بنشینند، چقدر عمر کنند، چه کسی به آن‌ها دسترسی داشته باشد و چه چیزی اصلاً اجازهٔ نوشته‌شدن داشته باشد. این «سمت‌کلاینت بودن» هم مزیت بزرگ ابزار است و هم مسئولیت بزرگش.

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

response = client.beta.messages.create(
    betas=["context-management-2025-06-27"],
    model="claude-sonnet-4-6",
    messages=messages,
    tools=[{"type": "memory_20250818", "name": "memory"}],
    max_tokens=2048,
)

مدل‌هایی که این ابزار را می‌شناسند خانوادهٔ چهارم و بالاتر هستند: اوپوس ۴ و ۴.۱، سونت ۴ و ۴.۶، و هایکو ۴.۵. اگر مدل قدیمی‌تری انتخاب کنید، ابزار بی‌اثر می‌ماند.

شش فرمانی که باید پیاده کنید

ابزار حافظه در عمل یک فایل‌سیستم کوچک است که ریشه‌اش پوشهٔ /memories است. مدل با شش فرمان با آن حرف می‌زند:

• فرمان view — محتوای یک فایل یا فهرست یک پوشه را برمی‌گرداند. معمولاً اولین کاری است که ایجنت در شروع گفتگو انجام می‌دهد.
• فرمان create — فایل می‌سازد یا فایل موجود را کامل بازنویسی می‌کند.
• فرمان str_replace — یک تکهٔ متن را با تکهٔ دیگر عوض می‌کند؛ برای به‌روزرسانی‌های کوچک ارزان‌ترین راه است.
• فرمان insert — متنی را در شمارهٔ خط مشخص وارد می‌کند.
• فرمان delete — فایل یا پوشه را حذف می‌کند.
• فرمان rename — فایل را تغییر نام می‌دهد یا جابه‌جا می‌کند؛ برای مرتب‌کردن حافظهٔ شلوغ لازم می‌شود.

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

/memories/
├── review.md                     # الگوهای بازبینی کد
├── concurrency_patterns/
│   └── thread_safety.md
├── domain_knowledge/
│   └── patterns.md
└── user_preferences.md

هندلر: قلب پیاده‌سازی

هندلر همان کلاسی است که فرمان‌های مدل را به عملیات واقعی فایل ترجمه می‌کند. نکتهٔ حیاتی، اعتبارسنجی مسیر است — که یک سطر بعد به آن می‌رسیم: