آموزش اضافه کردن حافظه به Claude Code با ابزار Recall

عملکرد Recall برای حافظه Claude Code

Recall یک افزونه برای Claude Code است که به هر پروژه حافظه‌ای در طول نشست‌های مختلف می‌دهد. این افزونه دو فایل markdown را در پوشه .recall/ در داخل پروژه شما می‌نویسد: یک لاگ فقط‌افزودنی (append-only) از وقایع، و یک خلاصه کوتاه از جایی که کار را متوقف کرده‌اید. هر دو فایل توسط یک خلاصه‌ساز محلی پایتون روی دستگاهی که با آن کار می‌کنید تولید می‌شوند، بنابراین خودِ حافظه هیچ هزینه توکن API ندارد.

شکافی که این ابزار پر می‌کند کوچک و همیشگی است. شما یک نشست را در روز سه‌شنبه روی VPS خود می‌بندید. در روز چهارشنبه، Claude Code هیچ اطلاعی از وقایع سه‌شنبه ندارد. شما پروژه را به‌صورت دستی دوباره توضیح می‌دهید، یا اجازه می‌دهید مدل نیمی از مخزن (repository) را دوباره بخواند تا وضعیت را درک کند. هر دو روش هزینه توکن دارند و روش دوم هزینه بسیار بالایی دارد.

نسخه 0.4.0 از Recall تا ژوئیه 2026 نسخه جاری است و این پروژه تحت مجوز MIT منتشر شده است. این یک افزونه است. هیچ بخشی از آن تماس شبکه‌ای برقرار نمی‌کند.

پیش‌نیازهای لازم روی VPS

هوک‌های ضبط (capture hooks) در Recall اسکریپت‌های پایتونی هستند که همراه با این افزونه ارائه می‌شوند. هیچ وابستگی شخص‌ثالثی وجود ندارد، بنابراین تنها نیاز واقعی، یک مفسر (interpreter) است.

python3 -V

سیستم‌عامل Ubuntu 24.04 به Python 3.12.3 پاسخ می‌دهد. Recall از پایتون 3.9 و نسخه‌های جدیدتر پشتیبانی می‌کند. ایمیج‌های کانتینر مینیمال گاهی اوقات هیچ مفسری ندارند و در آن صورت، شل به python3: command not found پاسخ می‌دهد. پیش از ادامه، یکی از آن‌ها را نصب کنید.

sudo apt update && sudo apt install -y python3

کتابخانه NumPy یک شتاب‌دهنده اختیاری برای یکی از مراحل خلاصه‌ساز (summarizer) است. شما به آن نیازی ندارید.

python3 -c "import numpy"

ModuleNotFoundError: No module named 'numpy' در اینجا پاسخ قابل‌قبولی است. خلاصه‌ساز یک مسیر کاملاً پایتونی دارد و مجموعه تست‌های پروژه بررسی می‌کنند که هر دو مسیر، جملات یکسانی را انتخاب کنند.

حافظه نشست (session memory) روی سرور اهمیت بیشتری نسبت به لپ‌تاپ دارد، زیرا کارهای سروری در قالب بازدیدهای کوتاه و پراکنده در طول چند روز انجام می‌شوند. اگر از قبل Claude Code را در tmux روی یک VPS اجرا کرده‌اید، Recall همان قطعه‌ای است که نشست دیروز را به امروز منتقل می‌کند.

نصب Recall از بازارچه افزونه‌ها

دو دستور که در یک نشست Claude Code تایپ می‌شوند:

/plugin marketplace add raiyanyahya/recall
/plugin install recall@recall

دستور دوم plugin@marketplace را می‌خواند. هر دو نام در اینجا recall هستند که ممکن است شبیه به یک اشتباه در کپی-پیست به نظر برسد، اما این‌طور نیست.

نصب را با اجرای یکی از دستورات خودِ افزونه بررسی کنید:

/recall:show

/recall:show خلاصه فعلی را چاپ می‌کند. در یک پروژه کاملاً جدید هنوز چیزی برای چاپ وجود ندارد، بنابراین آنچه در واقع بررسی می‌کنید این است که آیا دستور اصلاً وجود دارد یا خیر. اگر Claude Code دستور /recall:show را تشخیص ندهد، افزونه بارگذاری نشده است و هیچ هوکی (hook) اجرا نخواهد شد.

برای اجرا از روی یک checkout، ابتدا مخزن را clone کرده و آن را اعتبارسنجی کنید:

git clone https://github.com/raiyanyahya/recall ~/recall
cd ~/recall && claude plugin validate .

claude plugin validate . فایل manifest موجود در .claude-plugin/ را می‌خواند و گزارش می‌دهد که آیا افزونه به‌درستی ساختاریافته است یا خیر. سپس Claude Code را از دایرکتوری پروژه خود با claude --plugin-dir ~/recall اجرا کنید.

هوک‌ها چه چیزی را و چه زمانی می‌نویسند

Recall سه هوک Claude Code را ثبت می‌کند. هر کدام یک اسکریپت Python را از دایرکتوری پلاگین اجرا می‌کنند.

• SessionStart در زمان راه‌اندازی، ازسرگیری و پاک‌سازی اجرا می‌شود. این هوک context.md را نمایش می‌دهد تا نشست با خلاصهٔ شما در دیدرس باز شود.
• Stop هر بار که Claude پاسخ‌دهی را تمام می‌کند، اجرا می‌شود. این هوک آن نوبت را به لاگ اضافه می‌کند.
• SessionEnd هنگام بستن نشست اجرا می‌شود و می‌تواند خلاصه را بازتولید کند.

دو فایل از این فرآیند حاصل می‌شود که هر دو در .recall/ قرار دارند.

• history.md سابقهٔ فقط‌افزودنی (append-only) است: پرامپت‌ها، پاسخ‌ها، فایل‌های دست‌کاری‌شده و دستورات اجراشده.
• context.md چکیدهٔ تولیدشده است: هدف، خلاصه، گام‌های بعدی، فایل‌های دست‌کاری‌شده، دستورات اجراشده و کانتکست git.

پس از یک نشست واقعی، دایرکتوری را بررسی کنید.

ls -la .recall/

شما باید history.md را با محتوا در آن ببینید. ممکن است اصلاً context.md را نبینید، و این رفتار پیش‌فرض است نه یک خطا. auto_save_context به صورت off است مگر اینکه آن را تنظیم کنید، بنابراین خلاصه فقط زمانی نوشته می‌شود که شما آن را بخواهید:

/recall:save

آن دستور، خلاصه‌ساز محلی را روی history.md اجرا کرده و context.md را بازنویسی می‌کند. الگوریتم مورد استفاده، امتیازدهی TF-IDF (فراوانی کلمه، فراوانی معکوس سند) است که به رتبه‌بندی جملات TextRank داده می‌شود. این فرآیند قطعی (deterministic) و استخراجی است، به این معنی که جملاتی را انتخاب می‌کند که از قبل در لاگ شما وجود دارند. هیچ مدلی فراخوانی نمی‌شود، بنابراین این مرحله رایگان است و به صورت آفلاین روی دستگاه کار می‌کند.

پیکربندی Recall برای یک پروژه

پیکربندی در یک فایل recall.config.json در ریشه پروژه قرار دارد. مقادیر پیش‌فرض ارائه‌شده به شرح زیر است:

{
  "output_dir": ".recall",
  "capture_history": true,
  "summary_sentences": 8,
  "redact": true,
  "include_git": true,
  "max_input_chars": 200000
}

• output_dir محل قرارگیری دو فایل را تعیین می‌کند. آن را داخل پروژه نگه دارید.
• capture_history لاگ history.md را فعال یا غیرفعال می‌کند.
• auto_save_context مقادیر off یا on_end را می‌پذیرد و مقدار پیش‌فرض آن off است.
• summary_sentences مشخص می‌کند چند جمله در context.md باقی می‌مانند. افزایش این مقدار منجر به خلاصه‌ای طولانی‌تر و بارگذاری کمی سنگین‌تر در شروع نشست (session) می‌شود.
• redact الگوهای رایج حاوی اطلاعات حساس (secret) را پیش از نوشتن روی دیسک حذف می‌کند.
• include_git diff فعلی و commitهای اخیر را به خلاصه اضافه می‌کند.
• max_input_chars محدودیت میزان خواندن history.md توسط خلاصه‌ساز در هر مرحله را تعیین می‌کند.

برای پروژه‌ای که روی یک VPS قرار دارد، تغییر مفید، فعال‌سازی ذخیره‌سازی خودکار است؛ زیرا نشست روی سرور اغلب با بسته شدن ترمینال به پایان می‌رسد، نه با تصمیم شما برای توقف کار.

{
  "auto_save_context": "on_end",
  "summary_sentences": 12
}

برای توقف موقت ضبط بدون تغییر در فایل پیکربندی، نشانگر توقف (pause marker) را ایجاد کنید. برای شروع مجدد ضبط، آن را حذف کنید.

touch .recall/.capture-paused

این کار را پیش از شروع نشستی که در آن با اعتبارنامه‌های محیط production سروکار دارید انجام دهید، زیرا عمل redaction یک فیلتر است و نه یک تضمین قطعی. همین استدلال دلیل اصلی دور نگه داشتن اطلاعات حساس از عامل‌های هوش مصنوعی به‌طور کلی است: امن‌ترین اطلاعات حساس، آن‌هایی هستند که عامل هوش مصنوعی هرگز آن‌ها را نمی‌بیند.

Recall چقدر در مصرف توکن صرفه‌جویی می‌کند؟

این موضوع به جایگزین آن بستگی دارد. بارگذاری یک خلاصه در ابتدای نشست (session) کم‌هزینه است. آنچه این خلاصه جایگزین آن می‌شود می‌تواند گران باشد، زیرا مدلی که حافظه‌ای از پروژه شما ندارد، با خواندن فایل‌ها دوباره آن را کشف می‌کند.

[
  {
    "label": "Recall context.md",
    "char_count": "4,800",
    "est_tokens": "1,200"
  },
  {
    "label": "Hand-written CLAUDE.md",
    "char_count": "3,200",
    "est_tokens": "800"
  },
  {
    "label": "Re-reading the repo",
    "char_count": "120,000",
    "est_tokens": "30,000"
  },
  {
    "label": "Full transcript replay",
    "char_count": "340,000",
    "est_tokens": "85,000"
  }
]

این‌ها ارقام معمول برای یک پروژه با اندازه متوسط هستند و اندازه‌گیری دقیق پروژه شما نیستند. یک خلاصه Recall تقریباً با 1,200 توکن بارگذاری می‌شود که با ادعای منتشرشده پروژه مبنی بر یک تا دو هزار توکن برای ازسرگیری (resume) مطابقت دارد. بازپخش کامل رونوشت قبلی، کل گفتگو را دوباره بارگذاری می‌کند که در محدوده 85,000 توکن است. اجازه دادن به مدل برای کشف مجدد پروژه از طریق خواندن فایل‌ها، بین این دو مقدار و نزدیک به 30,000 توکن قرار می‌گیرد و این عدد با بزرگ‌تر شدن مخزن (repository) افزایش می‌یابد. ردیف CLAUDE.md برای مقیاس‌سنجی در اینجا قرار دارد: این ردیف ارزان‌تر است زیرا کوتاه و ایستا است و به جای آنچه دیشب اتفاق افتاده، قوانین ثابت شما را به مدل می‌گوید.

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

wc -c .recall/context.md .recall/history.md
echo $(( $(wc -c < .recall/context.md) / 4 ))

در داخل یک نشست، /context نشان می‌دهد که در حال حاضر چه چیزی در پنجره کانتکست بارگذاری شده است و /cost مجموع نشست را گزارش می‌دهد. یک نشست را به‌صورت سرد (بدون حافظه قبلی) شروع کنید، نشست بعدی را با یک خلاصه فعال شروع کنید و مقایسه کنید. برای درک کامل اینکه توکن‌های یک نشست واقعاً کجا صرف می‌شوند، نحوه مصرف توکن توسط Claude Code جزئیات آن را ارائه می‌دهد.

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

بازسازی خلاصه بدون نشست

اگر مخزن را clone کرده‌اید، ابزار خلاصه‌ساز یک نقطه ورود اختصاصی در خط فرمان دارد. این قابلیت در زمان استفاده از VPS، هنگامی که نشست (session) همراه با ترمینال قطع شده و همچنان به خلاصه نیاز دارید، مفید است.

python3 ~/recall/scripts/make_context.py --help

خروجی راهنما، فلگ‌های قابل پذیرش را فهرست می‌کند: --cwd برای ریشه پروژه، --transcript برای تعیین صریح فایل رونوشت (transcript)، --quiet برای سرکوب خروجی، و --harness برای انتخاب بین claude و opencode. آن را به سمت یک پروژه هدایت کنید:

python3 ~/recall/scripts/make_context.py --cwd /srv/projects/api

این ابزار رونوشت نشست و history.md را می‌خواند و سپس context.md را در دایرکتوری که ارسال کرده‌اید، می‌نویسد. اگر از طریق marketplace نصب کرده‌اید، افزونه در دایرکتوری تحت مدیریت Claude Code قرار دارد و /recall:save روش پشتیبانی‌شده برای انجام همین کار است.

چرا هیچ چیزی نوشته نمی‌شود

عدم وجود دایرکتوری .recall/ پس از یک نشست کامل. هوک‌ها هرگز اجرا نشدند. دستور /recall:show را تایپ کنید تا مطمئن شوید پلاگین بارگذاری شده است، سپس python3 -V را اجرا کنید. دستور هوک ابتدا python3 و سپس python را امتحان می‌کند، بنابراین اگر سیستمی هیچ‌کدام را نداشته باشد، چیزی نمی‌نویسد و در این مورد نیز پیامی نمی‌دهد.

فایل history.md رشد می‌کند اما context.md هرگز تغییر نمی‌کند. مقدار auto_save_context به‌صورت پیش‌فرض off است. دستور /recall:save را اجرا کنید، یا کلید را روی on_end تنظیم کنید و اجازه دهید هوک SessionEnd این کار را انجام دهد.

فایل‌ها زیر پروژه اشتباه ظاهر می‌شوند. ابزار Recall نسبت به دایرکتوری‌ای که Claude Code از آن شروع شده است می‌نویسد، بنابراین شروع یک نشست از دایرکتوری home، حافظه را همان‌جا قرار می‌دهد. از ریشه پروژه شروع کنید و از ls -la .recall/ استفاده کنید تا بفهمید فایل‌ها واقعاً کجا ذخیره شده‌اند.

ضبط متوقف شده و هیچ هشداری دریافت نکردید. با استفاده از ls -a .recall/ وجود نشانگر توقف (pause marker) را بررسی کنید. یک فایل .capture-paused که هفته گذشته ایجاد کرده‌اید همچنان در حال انجام وظیفه خود است.

خلاصه پس از یک نشست طولانی بسیار کوتاه است. ابزار max_input_chars ورودی خلاصه‌ساز را به 200000 کاراکتر محدود می‌کند، بنابراین لاگ‌های بسیار طولانی برش می‌خورند. آن را چرخش (Rotate) دهید.

mv .recall/history.md .recall/history-2026-07-30.md

پس از آن یک نشست کوتاه اجرا کنید و دوباره ls -la .recall/ را بررسی کنید تا مطمئن شوید یک history.md جدید ایجاد شده است.

محدودیت‌های Recall

Recall ترکیبی از یک لاگ و یک خلاصه‌ساز است و باید مشخص باشد که چه مواردی را پوشش نمی‌دهد.

خلاصه‌ساز از نوع استخراجی (extractive) است. TextRank جملاتی را انتخاب می‌کند که از قبل در history.md موجود هستند، بنابراین هرگز قضاوت نمی‌کند که آیا یک تصمیم درست بوده است یا خیر. یک مسیر اشتباه که در روز سه‌شنبه ثبت شده، دقیقاً مانند یک تصمیم درست در روز چهارشنبه خوانده می‌شود. وقتی پای مسائل حیاتی در میان است، context.md را بخوانید و آن را به‌صورت دستی اصلاح کنید. این یک فایل markdown است و هیچ محدودیتی برای ویرایش آن ندارید.

قابلیت جستجو وجود ندارد. شما برای هر پروژه یک خلاصهٔ فعلی و یک لاگ در حال رشد دارید، نه یک حافظهٔ قابل پرس‌وجو در میان پروژه‌ها. اگر سؤال این است که سه هفته پیش دربارهٔ دیتابیس چه تصمیمی گرفتید، باید در history.md از دستور grep استفاده کنید. همچنین هیچ ارتباط جانبی وجود ندارد: دو نشست (session) که هم‌زمان روی یک VPS باز هستند، نمی‌توانند لاگ‌های یکدیگر را ببینند؛ بنابراین وقتی یکی نیاز دارد بداند دیگری چه کاری انجام می‌دهد، نشست‌ها می‌توانند هنگام اجرا مستقیماً متن را بین خود رد و بدل کنند.

این ابزار در حین یک نشست کمکی نمی‌کند. پر شدن پنجرهٔ کانتکست (context window) در میانهٔ نشست، مسئله‌ای متفاوت با راه‌حل‌های متفاوت است و مدیریت پنجرهٔ کانتکست در یک نشست، مکمل این راهنماست.

خلاصه به‌طور پیش‌فرض به عنوان ورودی غیرقابل‌اعتماد در نظر گرفته می‌شود. context.md به‌صورت محصور (fenced) و برچسب‌گذاری‌شده تزریق می‌شود و Claude پیش از تکیه بر آن، سؤال می‌پرسد. این طراحی به این دلیل است که دایرکتوری متعهد (committed) .recall/ مکانی است که هر کسی با دسترسی commit می‌تواند متنی بنویسد که ایجنت شما آن را می‌خواند. میزان توقف ایجنت برای پرس‌وجو دربارهٔ آنچه می‌خواند، توسط حالت دسترسی (permission mode) که نشست با آن شروع می‌شود تعیین می‌گردد و حالت auto از تاریخ 14 August 2026 به پیش‌فرض Claude Code تبدیل می‌شود. یک‌بار تصمیم بگیرید که آیا .recall/ شخصی است یا اشتراکی: آن را برای حافظهٔ شخصی به .gitignore اضافه کنید، یا آن را commit کرده و مانند هر مشارکت دیگری بازبینی کنید. اگر ایجنت بدون نظارت اجرا می‌شود، اجرای ایمن Claude Code روی یک VPS مرزهای گسترده‌تر را پوشش می‌دهد.

حذف اطلاعات حساس (Redaction) بر اساس بهترین تلاش (best effort) انجام می‌شود. این قابلیت الگوهای رایج مانند API keyها، توکن‌ها، بلوک‌های PEM و انتساب‌های .env را هدف قرار می‌دهد. پیش از commit کردن، .recall/ را مطالعه کنید.

شمارهٔ نسخه نشان‌دهندهٔ میزان بلوغ ابزار است. در نسخه 0.4.0 در July 2026، کلیدهای پیکربندی و ساختار فایل‌ها همچنان ممکن است بین نسخه‌ها تغییر کنند، بنابراین پیش از ارتقای سیستمی که به آن وابسته‌اید، changelog را بخوانید.

FAQ

آیا Recall کد یا رونوشت‌های من را به جایی ارسال می‌کند؟

خیر. هوک‌های ضبط و خلاصه‌ساز، اسکریپت‌های Python هستند که روی دستگاه خودتان اجرا می‌شوند. این افزونه هیچ API key را نگه نمی‌دارد و هیچ تماس شبکه‌ای برقرار نمی‌کند. خلاصه‌سازی به‌جای استفاده از مدل، از TF-IDF و TextRank استفاده می‌کند؛ بنابراین این مرحله هزینه‌ای ندارد و در حالت آفلاین نیز کار می‌کند. نقطه ضعف این روش آن است که خلاصه به‌صورت استخراجی است: یعنی به‌جای نوشتن جملات جدید، جملات را از لاگ شما انتخاب می‌کند.

چرا .recall/context.md من وجود ندارد یا قدیمی است؟

auto_save_context به‌صورت پیش‌فرض روی off تنظیم شده است، بنابراین خلاصه فقط زمانی بازتولید می‌شود که /recall:save را اجرا کنید. برای اینکه خلاصه در پایان هر نشست بازنویسی شود، "auto_save_context": "on_end" را در recall.config.json تنظیم کنید. اگر history.md نیز وجود ندارد، یعنی هوک‌ها اصلاً اجرا نمی‌شوند: با استفاده از /recall:show تأیید کنید که افزونه بارگذاری شده است، سپس بررسی کنید که آیا python3 -V روی آن سیستم پاسخ می‌دهد یا خیر، زیرا هوک‌ها اسکریپت‌های Python هستند.

Recall در هر نشست چقدر صرفه‌جویی می‌کند؟

بارگذاری یک خلاصه حدود 1,200 توکن هزینه دارد، در حالی که برای مدلی که باید دوباره مخزن شما را بخواند تا بفهمد در چه وضعیتی است، این مقدار حدود 30,000 توکن است. این‌ها ارقام معمول هستند. با استفاده از wc -c .recall/context.md و دستور /context در یک نشست، مقادیر خود را اندازه‌گیری کنید و یک شروع سرد (cold start) را با نشستی که از خلاصه ادامه می‌یابد، مقایسه کنید.

آیا هنوز به فایل CLAUDE.md نیاز دارم؟

بله، این دو وظایف متفاوتی دارند. CLAUDE.md چیزی است که شما آگاهانه می‌نویسید: قوانین ثابت و دستورات ساخت. context.md از آنچه واقعاً در نشست قبل رخ داده تولید می‌شود، بنابراین شامل مهاجرت‌های نیمه‌تمام است که هرگز به فکر نوشتن آن‌ها نمی‌افتید. هر دو را نگه دارید.

آیا یک VPS می‌تواند حافظه چندین پروژه را نگه دارد؟

بله. Recall حافظه را در .recall/ درون دایرکتوری هر پروژه نگه می‌دارد، بنابراین دو پروژه روی یک سرور، لاگ‌ها و خلاصه‌های جداگانه‌ای خواهند داشت. هر بار Claude Code را از ریشه پروژه اجرا کنید، زیرا فایل‌ها از دایرکتوری کاری پیروی می‌کنند، نه از حساب کاربری.