# محتوى KV-Cache المُخزَّن مؤقتًا

## ما هو Prompt Caching؟

عندما تتحدث مع Claude، يرسل كل طلب API سياق المحادثة الكامل (system prompt + تعريفات الأدوات + الرسائل السابقة). تقوم آلية prompt caching من Anthropic بتخزين محتوى البادئة المحسوب مسبقًا على الخادم، وإذا كانت البادئة متطابقة في الطلبات اللاحقة، يتم إعادة استخدام النتائج المُخزَّنة مباشرةً وتخطي الحسابات المكررة، مما يقلل بشكل كبير من زمن الاستجابة والتكاليف.

في cc-viewer، يُشار إلى هذه الآلية بـ "KV-Cache"، وهي تُطابق prompt caching على مستوى Anthropic API، وليس ذاكرة key-value الخاصة بطبقات الانتباه في transformer داخل LLM.

## كيفية عمل التخزين المؤقت

يجمع prompt caching من Anthropic مفاتيح الذاكرة المؤقتة بترتيب ثابت:

```
Tools → System Prompt → Messages (حتى نقطة فاصل الذاكرة المؤقتة)
```

طالما أن هذه البادئة متطابقة تمامًا مع أي طلب سابق ضمن نافذة TTL، فإن API يصل إلى الذاكرة المؤقتة (ويعيد `cache_read_input_tokens`)، بدلاً من إعادة الحساب (`cache_creation_input_tokens`).

> **Claude Code لا يعتمد بشكل صارم على خاصية `cache_control`، حيث يتعاون الخادم بإزالة بعض هذه الخصائص، ومع ذلك لا يزال قادرًا على إنشاء ذاكرة مؤقتة بشكل جيد، لذا عدم رؤية خاصية `cache_control` لا يعني عدم وجود تخزين مؤقت**
>
> بالنسبة للعملاء المتخصصين مثل Claude Code، لا يعتمد خادم Anthropic بشكل كامل على خاصية `cache_control` في الطلب لتحديد سلوك التخزين المؤقت. يقوم الخادم تلقائيًا بتنفيذ سياسة التخزين المؤقت لحقول معينة (مثل system prompt وتعريفات الأدوات)، حتى لو لم يحمل الطلب صراحةً علامة `cache_control`. لذلك، عندما لا ترى هذه الخاصية في نص الطلب، لا تقلق — فقد أكمل الخادم عملية التخزين المؤقت خلف الكواليس، لكنه ببساطة لم يكشف هذه المعلومة للعميل. هذا تفاهم ضمني بين Claude Code وAPI من Anthropic.

## ما هو "محتوى KV-Cache المُخزَّن مؤقتًا الحالي"؟

"محتوى KV-Cache المُخزَّن مؤقتًا الحالي" المعروض في cc-viewer هو المحتوى المُستخرج من آخر طلب MainAgent، والواقع قبل حدود التخزين المؤقت (cache breakpoint). يشمل بالتحديد:

- **System Prompt**: تعليمات نظام Claude Code، بما في ذلك تعليمات الوكيل الأساسية، ومواصفات استخدام الأدوات، وتعليمات مشروع CLAUDE.md، ومعلومات البيئة، إلخ.
- **Tools**: قائمة تعريفات الأدوات المتاحة حاليًا (مثل Read و Write و Bash و Agent وأدوات MCP وما إلى ذلك)
- **Messages**: الجزء المُخزَّن مؤقتًا من سجل المحادثة (عادة الرسائل الأقدم، حتى آخر علامة `cache_control`)

## لماذا يجب عرض محتوى الذاكرة المؤقتة؟

1. **فهم السياق**: معرفة ما "يتذكره" Claude حاليًا يساعدك على تحديد ما إذا كان سلوكه يتوافق مع التوقعات
2. **تحسين التكاليف**: تكلفة الوصول إلى الذاكرة المؤقتة أقل بكثير من إعادة الحساب. عرض محتوى الذاكرة المؤقتة يساعدك على فهم سبب تفعيل بعض الطلبات لإعادة بناء الذاكرة المؤقتة (cache rebuild)
3. **تصحيح أخطاء المحادثة**: عندما لا تتوافق إجابة Claude مع التوقعات، يمكنك فحص محتوى الذاكرة المؤقتة للتأكد من صحة system prompt والرسائل السابقة
4. **مراقبة جودة السياق**: أثناء تصحيح الأخطاء وتعديل الإعدادات وضبط الـ prompt، يوفر KV-Cache-Text منظورًا مركزيًا يساعدك على التأكد بسرعة من عدم تدهور السياق الأساسي أو تلوثه بمحتوى غير متوقع — دون الحاجة لمراجعة الرسائل الأصلية واحدة تلو الأخرى

## استراتيجية التخزين المؤقت متعددة المستويات

ذاكرة KV-Cache المُقابلة لـ Claude Code ليست نسخة واحدة فقط. يُنشئ الخادم ذاكرة مؤقتة منفصلة لـ Tools و System Prompt، مستقلة عن ذاكرة Messages. ميزة هذا التصميم هي: عندما تحدث فوضى في مكدس الرسائل (مثل اقتطاع السياق أو تعديل الرسائل) وتتطلب إعادة البناء، لن تتأثر ذاكرة Tools و System Prompt معها، مما يتجنب إعادة حساب كل شيء.

هذه استراتيجية تحسين من جانب الخادم في المرحلة الحالية — لأن تعريفات الأدوات و System Prompt مستقرة نسبيًا أثناء الاستخدام العادي ونادرًا ما تتغير، وتخزينها بشكل مستقل يقلل من تكاليف إعادة البناء غير الضرورية. لذلك عند مراقبة الذاكرة المؤقتة ستلاحظ أنه باستثناء إعادة بناء Tools التي تتطلب تحديث كل الذاكرة المؤقتة، فإن تلف System Prompt أو Messages لا يزال يتيح وجود ذاكرة مؤقتة قابلة للتوريث.

## دورة حياة الذاكرة المؤقتة

- **الإنشاء**: عند الطلب الأول أو بعد انتهاء صلاحية الذاكرة المؤقتة، ينشئ API ذاكرة مؤقتة جديدة (`cache_creation_input_tokens`)
- **الوصول**: في الطلبات اللاحقة ذات البادئة المتطابقة، يتم إعادة استخدام الذاكرة المؤقتة (`cache_read_input_tokens`)
- **انتهاء الصلاحية**: الذاكرة المؤقتة لها TTL (وقت البقاء) مدته 5 دقائق، وتنتهي صلاحيتها تلقائيًا بعد هذه الفترة
- **إعادة البناء**: عندما يتغير system prompt أو قائمة الأدوات أو النموذج أو محتوى الرسائل، لا يتطابق مفتاح الذاكرة المؤقتة، مما يؤدي إلى تفعيل إعادة بناء المستوى المُقابل من الذاكرة المؤقتة
