📘 תיעוד 7

כיצד Claude Code משתמש ב-prompt caching

Claude Code מנהל prompt caching באופן אוטומטי. ראה מדוע החלפת מודל מפעילה תור איטי ללא מטמון, מה העלות של /compact, מדוע עריכות ב-CLAUDE.md אינן חלות באמצע הפעלה, וכיצד לבדוק את שיעור הפגיעות במטמון שלך.

שמירת הנחיות במטמון (prompt caching) הופכת את Claude Code למהיר יותר וחסכוני יותר בעלויות. ללא מטמון, ה-API היה מעבד מחדש את כל ההיסטוריה שלך בכל תור (turn). באמצעות מטמון, הוא עושה שימוש חוזר במה שכבר עיבד, מחייב את הקריאה החוזרת לפי תעריף אסימונים במטמון, ומעבד במלואו רק את מה שהשתנה.

Claude Code מטפל ב-prompt caching עבורך, אלא אם תבחר להשבית אותו. עדיין כדאי לדעת כיצד prompt caching עובד, מכיוון שפעולות מסוימות פוסלות את המטמון והופכות את התגובה הבאה לאיטית ויקרה יותר בזמן שהוא נבנה מחדש. דף זה מכסה אילו פעולות הן אלו, מדוע הגדרות מסוימות ממתינות להפעלה מחדש כדי לחול, וכיצד לבדוק את ביצועי המטמון כאשר השימוש נראה גבוה.

#כיצד המטמון מאורגן

בכל פעם שאתה שולח הודעה ב-Claude Code, מתבצעת בקשת API חדשה. המודל אינו זוכר דבר בין בקשות, ולכן Claude Code שולח מחדש את ההקשר המלא: הנחיית המערכת (system prompt), הקשר הפרויקט שלך, כל הודעה ותוצאת כלי קודמות, וההודעה החדשה שלך. תוכן חדש מתווסף בסוף, מה שאומר שרוב חלקי הבקשה זהים לבקשה שקדמה לה. prompt caching היא הדרך שבה ה-API נמנע מעיבוד מחדש של החלק שלא השתנה.

ה-API שומר במטמון על ידי התאמת תחילת כל בקשה, המכונה קידומת (prefix), מול תוכן שעובד לאחרונה. בתור רגיל, הקידומת היא כל הבקשה הקודמת במלואה, ורק חילופי הדברים האחרונים הם חדשים. ההתאמה היא מדויקת, ולכן שינוי בכל מקום שהוא בקידומת מחשב מחדש את כל מה שבא אחריו. אין שמירה במטמון לפי קובץ או לפי מקטע. ראה כיצד prompt caching עובד במדריך ה-API למנגנון שביסוד הדברים.

כדי להפיק את המרב מהתאמת קידומת, Claude Code מסדר כל בקשה כך שתוכן שלעיתים נדירות משתנה בין תורות מופיע ראשון:

שינוי בשכבת השיחה משאיר את הנחיית המערכת ואת הקשר הפרויקט במטמון. שינוי בהנחיית המערכת פוסל את הכל, מכיוון שכל התוכן המאוחר יותר יושב כעת מאחורי קידומת שונה. העמודה השלישית מציגה גורמים נפוצים ולא רשימה ממצה, והסעיפים שלהלן מכסים את הרשימה המלאה.

כלל התאמת הקידומת מסביר את רוב ההתנהגויות בדף זה. מצב תוכנית (Plan mode) וטעינת מיומנויות (skill loading), למשל, מוסיפים את ההוראות שלהם כהודעות שיחה, כך שהקידומת שבמטמון נשארת שלמה.

שתי הגדרות אינן מופיעות בטבלת השכבות אך עדיין משפיעות על מה שנשאר במטמון:

• מודל (Model): לכל מודל יש מטמון משלו. החלפת מודלים מחשבת מחדש את הבקשה כולה גם כאשר התוכן זהה. ראה החלפת מודלים להלן.
• רמת מאמץ (Effort level): ברוב המודלים, לכל רמת מאמץ יש מטמון משלה, ולכן שינוי מאמץ באמצע הפעלה מחשב מחדש את הבקשה כולה. ב-Fable 5.1 עם מפתח API או מנוי Claude, המטמון נשאר שלם כברירת מחדל. ראה שינוי רמת מאמץ להלן.

טיפ: בחר את המודל ואת רמת המאמץ שלך בתחילת הפעלה, ושמור את /compact להפסקות טבעיות בין משימות. ככל שתבצע פחות שינויים באמצע משימה, כך שיעור הפגיעות במטמון שלך יהיה גבוה יותר.

#היכן המטמון נמצא

שמירה במטמון מתרחשת בצד השרת, בתשתית שמשרתת את המודל שלך. המיקום תלוי באופן האימות שלך:

• מפתח API, מנוי Claude, או Claude Platform on AWS: המטמון נמצא בתשתית של Anthropic, שהגישה אליה נעשית דרך Claude API.
• Amazon Bedrock או Google Cloud's Agent Platform: המטמון נמצא בתשתית ההגשה של ספק הענן שלך.
• Microsoft Foundry: תלוי באפשרות האירוח (hosting option) של הפריסה. פריסות Hosted on Azure מוגשות על תשתית Azure, ופריסות Hosted on Anthropic מוגשות על תשתית Anthropic.
• ANTHROPIC_BASE_URL מותאם אישית או שער LLM (LLM gateway): המטמון נמצא במקום שאליו הבקשות שלך מועברות, והשאלה אם שמירה במטמון עובדת תלויה בשער.

Claude Code גם מוסיף הקשר מערכת באמצע השיחה, כגון הודעות על שינוי קבצים, ומסמן את הבלוק הזה לשמירה במטמון בכל ספק וחיבור, אלא אם הגדרת את CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, ובמקרה זה הבלוק נשלח ללא שמירה במטמון.

בנקודת הקצה של הספק עצמו, Amazon Bedrock ונקודת הקצה Mantle שלו, Google Cloud's Agent Platform ו-Microsoft Foundry שומרים את הבלוק במטמון באותו אופן שבו ה-API של Claude עושה זאת.

כאשר הבקשות שלך עוברות דרך שער LLM, דרך ANTHROPIC_BASE_URL מותאם אישית, או דרך דריסת כתובת בסיס של ספק ענן כגון ANTHROPIC_BEDROCK_BASE_URL, מה שנשאר במטמון תלוי באופן שבו השער מטפל בסמני cache_control ש-Claude Code שולח:

• מעביר אותם ללא שינוי: הבלוק והשיחה שלך נשמרים במטמון בדיוק כמו בנקודת הקצה של הספק עצמו.
• דוחה את הבקשה המסומנת בשגיאת 400 המציינת את cache_control: Claude Code שולח מחדש את הבקשה כאשר הסמן מועבר מהבלוק אל הודעת השיחה האחרונה שלך, ומשאיר אותו שם למשך שארית השיחה. הבלוק מחויב כקלט ללא מטמון, והשיחה שלך נשארת במטמון.
• מסיר את הסמנים תוך החזרת הצלחה: כל היסטוריית השיחה שלך מחויבת כקלט ללא מטמון בכל תור. שער שממיר תוכן מערכת במבנה בלוק למחרוזת פשוטה משמיט את הסמן באותו אופן.

לגבי מה שכל ספק מאחסן ומעבד, ראה שימוש בנתונים (data usage). בכל מקום שבו המטמון נמצא, רשומות פגות לאחר תקופה של חוסר פעילות, וסעיף משך חיי המטמון להלן מכסה את ה-TTL וכיצד להאריך אותו.

#פעולות שפוסלות את המטמון

פעולות אלו גורמות לבקשה הבאה לפספס חלק מהמטמון או את כולו. אתה רואה תור חד פעמי איטי יותר ויקר יותר, שלאחריו הקידומת החדשה נשמרת במטמון. את רובן ניתן למנוע באמצע משימה ברגע שיודעים שיש להן עלות. החלפת מודל יכולה להרגיש חופשית עד שמבחינים בתור האיטי יותר שבא בעקבותיה.

• החלפת מודלים
• שינוי רמת מאמץ
• הפעלת מצב מהיר (fast mode)
• חיבור או ניתוק של שרת MCP
• הפעלה או השבתה של תוסף (plugin)
• חסימת כלי שלם (Denying an entire tool)
• דחיסת השיחה (Compacting the conversation)
• צבירת תמונות רבות
• שדרוג Claude Code

#החלפת מודלים

לכל מודל יש מטמון משלו. החלפה באמצעות /model פירושה שהבקשה הבאה קוראת את כל היסטוריית השיחה ללא פגיעות במטמון כלל, למרות שהתוכן זהה.

כאשר אתה מריץ /model בטרמינל, Claude Code מבקש ממך לאשר את ההחלפה רק כאשר המטמון עדיין חם והמודל החדש אינו זה שהפיק את התגובה האחרונה. המטמון נשאר חם למשך TTL של המטמון אחד לאחר ש-Claude Code שלח לאחרונה בקשה בשיחה זו או לאחר ש-Claude הגיב לאחרונה. מרגע שזמן זה חולף, תוקף המטמון פג, ולכן Claude Code מחליף ללא בקשת אישור.

לפני גרסה v2.1.238, Claude Code לא בדק את ה-TTL של המטמון וביקש אישור גם לאחר שתוקף המטמון פג.

ניתן גם לדרוש אישור זה או לדלג עליו באמצעות PreModelSwitch hook.

הגדרת המודל opusplan נפתרת ל-Opus במהלך מצב תוכנית ול-Sonnet במהלך ביצוע, כך שכל מעבר של מצב תוכנית הוא החלפת מודל ומתחיל מטמון רענן.

נסיגה אוטומטית למודל חלופי (Automatic model fallback) במודלים מסוג Fable וב-Opus 5 היא גם החלפת מודל. כאשר מסווג בטיחות מסמן בקשה בקטגוריה שיש לה מודל חלופי, Claude Code מריץ מחדש את הבקשה באותו מודל וההפעלה ממשיכה שם.

כאשר ה-frontmatter של מיומנות (skill) או פקודה מציין model שאינו המודל הנוכחי של ההפעלה, תור זה הוא גם החלפת מודל: הבקשה הבאה קוראת את כל היסטוריית השיחה ללא פגיעות במטמון. מודל ההפעלה מתחדש בהנחיה הבאה שלך. מיומנות עם context: fork מגדירה במקום זאת את המודל של תת הסוכן המפוצל (forked subagent).

#שינוי רמת מאמץ

ברוב המודלים, שינוי רמת המאמץ (effort level) באמצע הפעלה פירושו שהבקשה הבאה קוראת את כל היסטוריית השיחה ללא פגיעות במטמון. כל עוד המטמון עדיין חם, Claude Code מבקש ממך לאשר את השינוי תחילה.

ב-Fable 5.1 עם מפתח API או מנוי Claude, שינוי המאמץ שומר על המטמון, ו-Claude Code מחיל את הרמה החדשה ללא בקשת אישור. הדבר אינו חל ב-Amazon Bedrock, ב-Google Cloud's Agent Platform, או ב-Claude apps gateway, או כאשר אתה מגדיר את CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, או כאשר לארגון שלך יש תצורת HIPAA.

לפני גרסה v2.1.260, שינוי מאמץ ב-Fable 5.1 עם מפתח API או מנוי Claude פסל גם הוא את המטמון.

#הפעלת מצב מהיר (fast mode)

הפעלת מצב מהיר (fast mode) מוסיפה כותרת בקשה (request header) שהיא חלק ממפתח המטמון, כך שהבקשה הראשונה ש-Claude Code שולח כאשר המצב המהיר מופעל קוראת את כל היסטוריית השיחה ללא פגיעות במטמון. Claude Code מגדיר כותרת זו פעם אחת כאשר תור מתחיל ושומר עליה לאורך כל התור, כך שכאשר אתה מפעיל מצב מהיר בזמן ש-Claude עובד, פספוס המטמון הנובע מהכותרת מתרחש בבקשה הראשונה של התור הבא שלך. אסימוני קלט אלה ללא מטמון מחויבים לפי תעריפי מצב מהיר, וזו הסיבה שהפעלתו בתחילת הפעלה עולה פחות מהפעלתו עמוק בתוך הפעלה ארוכה. אם המודל הנוכחי שלך אינו תומך במצב מהיר, הפעלת מצב מהיר גם מחליפה את המודל שלך, והחלפה זו מתחילה מטמון רענן בפני עצמה מהבקשה הבאה בתור הנוכחי.

העלות חלה פעם אחת לכל שיחה. לאחר התור הראשון במצב מהיר, Claude Code ממשיך לשלוח את הכותרת ומשנה רק את הגדרת המהירות של הבקשה, שאינה חלק ממפתח המטמון. כיבוי המצב המהיר, הנסיגה האוטומטית למהירות סטנדרטית לאחר מגבלת קצב, והפעלתו מחדש מאוחר יותר, כולם שומרים על המטמון. אם אזלו לך נקודות זכות לשימוש (usage credits) באמצע הפעלה, Claude Code מנסה שוב כל בקשת מצב מהיר שנדחתה במהירות סטנדרטית באותו אופן, כך שנסיגה זו שומרת גם היא על המטמון. הפקודות /clear ו-/compact מאפסות זאת, מכיוון שהן בונות מחדש את המטמון בנקודות אלו בכל מקרה.

#חיבור או ניתוק של שרת MCP

הגדרות כלים יושבות בשכבת הנחיית המערכת (system prompt), ולכן המטמון נפסל כאשר קבוצת הגדרות הכלים בבקשה משתנה בין תורות. שינוי המצב של כלי היועץ (advisor tool) הוא חריג: ההגדרה שלו יושבת לאחר נקודת העצירה של המטמון (cache breakpoint), ולכן הפעלה או השבתה של /advisor שומרת על הקידומת שבמטמון שלמה. השאלה אם שינוי בשרת MCP עושה זאת תלויה בשאלה האם הכלים שלו נדחים על ידי חיפוש כלים (tool search) או נטענים לתוך הקידומת:

• כלים נדחים (Deferred tools), ברירת המחדל במודלים נתמכים: שרת שמתחבר, מתנתק או משנה את רשימת הכלים שלו רק מוסיף תוכן חדש בסוף ואינו משבש דבר ממה שכבר נשמר במטמון.
• כלים שנטענים לתוך הקידומת: כל שינוי בהם פוסל את המטמון. הדבר קורה כאשר חיפוש כלים אינו זמין או מושבת, כגון במודלים של Google Cloud's Agent Platform המוקדמים יותר מדור Claude 4.5, עם שער ANTHROPIC_BASE_URL מותאם אישית, או בפריסה של Microsoft Foundry המתארחת ב-Azure לאחר ש-Claude Code מזהה שהפריסה דוחה חיפוש כלים. הדבר קורה גם עבור שרת או כלי המסומנים ב-alwaysLoad, ועבור הגדרות שנשמרות מראש באמצעות טעינה מבוססת סף (threshold-based loading).

כאשר כלים נטענים לתוך הקידומת, הגורם הנפוץ ביותר לפסילה הוא שרת שמתחבר או מתנתק באמצע ההפעלה, מה שיכול לקרות ללא שום פעולה מצדך: תהליך של שרת stdio מסתיים, הפעלת HTTP פגה, או שרת מתחבר מחדש אוטומטית לאחר כשל זמני. שרת מחובר יכול גם לדחוף עדכון כלים דינמי שמשנה את רשימת הכלים שלו.

עריכת תצורת ה-MCP שלך אינה משנה כשלעצמה את המטמון. התצורה החדשה נכנסת לתוקף רק לאחר הפעלה מחדש, וזהו הזמן שבו השרת מתחבר או מתנתק.

#הפעלה או השבתה של תוסף (plugin)

כאשר אתה מפעיל או משבית תוסף (plugin), עלות השינוי תלויה בסוגי הרכיבים שהתוסף מספק. המקרים להלן מכסים כל סוג רכיב, מתי Claude Code מחיל את השינוי, ומה קורה כאשר אתה משבית תוסף שוב באותה הפעלה.

#רכיבי תוסף ששומרים על המטמון

Claude Code לעולם אינו פוסל את המטמון עבור מיומנויות (skills), פקודות (commands), סוכנים (agents), נקודות חיבור (hooks), צגים (monitors) או ערכות נושא (themes) של תוסף. הוא מוסיף את התוכן שלהם לאחר השיחה הקיימת, כך שהבקשה הבאה משלמת על תוכן זה ועדיין קוראת את כל מה שלפניו מהמטמון.

#תוספים המספקים שרתי MCP

כאשר אתה מפעיל או משבית תוסף המספק שרתי MCP, Claude Code פועל לפי אותם כללים כמו בעת חיבור או ניתוק של שרת MCP:

• אם Claude Code דוחה את כלי השרת, הוא שומר על המטמון.
• אם Claude Code טוען אותם לתוך הקידומת, הבקשה הבאה קוראת מחדש את כל השיחה.

#תוספי בינה לקוד (Code intelligence plugins)

כאשר אתה מפעיל תוסף בינה לקוד, Claude מקבל את כלי ה-LSP.

#מתי חלים שינויים בתוספים

שינוי שאתה מבצע בתפריט /plugin עובר דרך /reload-plugins, ש-Claude Code מריץ עבורך כאשר אתה סוגר את התפריט. אתה משלם את העלות, בין אם הודעות שנוספו בסוף ובין אם קריאה מחדש מלאה, בתור הראשון לאחר שהשינוי חל. Claude Code יכול גם להחיל שינוי בעצמו:

• עבור תוסף עם מקור command, Claude Code יכול לטעון מחדש את התוסף בעצמו.
• כאשר אתה מתקין תוסף מממשק /plugin, Claude Code יכול להפעיל אותו במהלך ההתקנה. סיכום ההתקנה מציין אם הוא עשה זאת.
• כאשר אתה מעביר את ההפעלה באמצעות /cd בגרסה v2.1.246 ואילך, Claude Code מחיל כחלק מהמעבר את התוספים שהגדרות הספרייה החדשה מאפשרות, ללא אזהרת הקריאה המחדש המלאה שמעכבת /reload-plugins.
• בהפעלות אינטראקטיביות, כאשר אתה מוסיף או מסיר תוסף בתוך תיקיית תוספים שהעברת עם --plugin-dir, השינוי חל מיד. אם החלתו הייתה מפעילה קריאה מחדש מלאה, Claude Code מעכב את השינוי במקום זאת ומציג הודעה להריץ את /reload-plugins. נדרשת גרסת Claude Code v2.1.265 ואילך.

כאשר /reload-plugins רץ והטעינה מחדש הייתה מפעילה קריאה מחדש מלאה, Claude Code מציג אזהרה ואינו מחיל את הטעינה מחדש. הרץ /reload-plugins --force כדי להחיל אותה בכל מקרה.

הפקודה /reload-plugins רצה גם בהפעלות ללא טרמינל אינטראקטיבי, כגון אפליקציית שולחן העבודה, ה-Agent SDK, ומצב לא אינטראקטיבי עם -p, כאשר אתה מקליד אותה ישירות לתוך ההפעלה. נדרשת גרסת Claude Code v2.1.260 ואילך.

בהפעלות אלו הטעינה מחדש מחילה הכל למעט שינויים בשרתי MCP של תוספים, אשר נכנסים לתוקף בהפעלה הבאה שלך ולכן לעולם אינם עולים בקריאה מחדש מלאה באמצע הפעלה.

#תוספים שאתה מפעיל ואז משבית באותה הפעלה

כאשר אתה משבית תוסף שהפעלת מוקדם יותר בהפעלה, Claude Code משחזר את מבנה הבקשה הקודם. אם קידומת זו עדיין נמצאת בתוך משך חיי המטמון שלה, הבקשה הבאה קוראת את רשומת המטמון הישנה יותר במקום לבנות מחדש.

#חסימת כלי שלם (Denying an entire tool)

אם אתה מוסיף שם כלי בלבד כמו Bash או WebFetch ככלל חסימה (deny rule), Claude לא יוכל לקרוא לכלי זה החל מהבקשה הבאה שלך ואילך, בין אם הוספת את הכלל דרך /permissions ובין אם על ידי עריכת קובץ הגדרות ישירות. זה כולל כלל שאתה מוסיף דרך /permissions באמצע תור.

כאשר חיפוש כלים (tool search) פעיל, שזו ברירת המחדל במודלים נתמכים, הגדרות הכלים של הבקשה אינן משתנות והקידומת שבמטמון שורדת. כאשר חיפוש כלים אינו זמין או מושבת, Claude Code מסיר את ההגדרה מהבקשה הבאה, מה שפוסל את המטמון, וכך גם הסרת הכלל מאוחר יותר.

רק כלל חסימה שתואם במיקום שם הכלי חוסם כלי בדרך זו: שם כלי בלבד, המבנה המקביל Bash(*), או תו כללי לשם כלי (tool-name glob) כמו "*". תו כללי שתואם רק לכלי MCP, כגון "mcp__*", חוסם כלים אלה באותו אופן. כללי חסימה בעלי טווח מוגדר כמו Bash(rm *), וכל כללי ה-allow וה-ask, אינם משנים אילו כלים Claude רואה. Claude Code בודק אותם כאשר Claude מנסה לבצע קריאה, מה שמשאיר את הקידומת שלמה.

#דחיסת השיחה (Compacting the conversation)

דחיסה (Compaction) מחליפה את היסטוריית ההודעות שלך בסיכום. כחלק מתכנונה, פעולה זו פוסלת את שכבת השיחה, מכיוון שלבקשה הבאה יש היסטוריה חדשה וקצרה יותר שאינה חולקת קידומת עם הישנה. Claude Code עושה שימוש חוזר בשכבת הנחיית המערכת אלא אם השיחה חודשה תוך שמירה על הנחיית מערכת שהייתה משתנה אחרת; במקרה זה הדחיסה הראשונה עוברת להנחיה הנוכחית ושכבה זו נבנית מחדש פעם אחת. הוא טוען מחדש את הקשר הפרויקט מהדיסק, דבר שפוגע במטמון (cache-hit) רק אם CLAUDE.md והזיכרון לא השתנו מאז תחילת ההפעלה.

כדי להפיק את הסיכום, Claude Code שולח בקשה נפרדת עם אותה הנחיית מערכת, אותם כלים ואותה היסטוריה של השיחה שלך, בתוספת הוראת סיכום שנוספה כהודעת משתמש סופית. כל עוד המטמון חם, בקשה זו קוראת את הקידומת שלך מהמטמון, כך ש-/compact באמצע הפעלה עולה שבריר ממה שגודל ההקשר מרמז ומבלה את רוב זמנו ביצירת הסיכום.

לאחר הפסקה ארוכה יותר ממשך חיי המטמון, לא נותר מטמון לקריאה, ולכן בקשת הסיכום מעבדת מחדש את ההיסטוריה המלאה כקלט ללא מטמון. זו הסיבה ש-/compact עולה הכי הרבה כאשר אתה מחדש הפעלה ישנה. הן במקרה החם והן במקרה הקר, התור שלאחר הדחיסה בונה מחדש את מטמון השיחה רק עבור הסיכום הקצר בהרבה, כך שתור זה אינו החלק האיטי.

טיפ: דחיסה פועלת לטובתך כאשר ההקשר שאתה משליך הוא תוכן שאינך זקוק לו עוד. כדי לבחור מתי יתרחש התקורה (overhead) שלה, הרץ /compact בהפסקה טבעית בעבודתך, כגון בין משימות, במקום לחכות לדחיסה אוטומטית שמופעלת באמצע משימה. אם הלכת בנתיב שברצונך לנטוש לחלוטין, בצע /rewind לתור מוקדם יותר במקום זאת. החזרה לאחור (rewinding) קוטמת בחזרה לקידומת שכבר שמורה במטמון, במקום לבנות קידומת חדשה כפי שעושה דחיסה.

#צבירת תמונות רבות

ה-API מגביל את כמות התמונות וקובצי ה-PDF שכל בקשה יכולה לשאת. למספרים הנוכחיים, ראה מגבלות בקשה (Request limits) בתיעוד ה-API. Claude Code גם מגביל את הגודל הכולל של התמונות וקובצי ה-PDF בבקשה, כך שצילומי מסך גדולים מגיעים למגבלה עם פחות תמונות מאשר צילומי מסך קטנים.

כאשר הבקשה הבאה עומדת לחרוג מאחת המגבלות, Claude Code מסיר אצווה (batch) של התמונות וקובצי ה-PDF הישנים ביותר ממה שהוא שולח, מה שמשאיר מקום לתמונות נוספות לפני שיידרש להסיר שוב. Claude כבר אינו יכול לראות את התמונות שהוסרו. אם Claude זקוק שוב לאחת מהן, שתף אותה מחדש.

הסרת תמונות משנה את ההודעות שהכילו אותן, ולכן הבקשה הבאה מעבדת מחדש את השיחה מהמוקדמת שבהודעות אלו ואילך. מכיוון ש-Claude Code מסיר אצווה בכל פעם, אתה רואה תור איטי אחד לכל אצווה ולא תור איטי עם כל צילום מסך חדש.

#שדרוג Claude Code

גרסה חדשה של Claude Code מעדכנת בדרך כלל את הנחיית המערכת או את הגדרות הכלים, כך שהשיחה הראשונה שתתחיל לאחר שדרוג בונה את המטמון שלה מההתחלה. עדכון אוטומטי (Auto-update) מוריד גרסאות חדשות ברקע אך מחיל אותן בהפעלה הבאה, לעולם לא באמצע הפעלה, כך שאתה רואה זאת כתור ראשון ללא מטמון לאחר הפעלה מחדש ולא כהפתעה במהלך הפעלה. הגדר DISABLE_AUTOUPDATER=1 כדי לשלוט מתי שדרוגים מוחלים.

הערה: לגבי העלות של חידוש שיחה שהתחלת לפני השדרוג, ראה חידוש הפעלה.

#פעולות ששומרות על המטמון

פעולות אלו מוסיפות לסוף השיחה או אינן נוגעות בבקשה כלל. חלקן, כגון עריכת CLAUDE.md, שומרות על המטמון מאותה סיבה שהשינוי אינו מגיע להפעלה הפועלת עד לביצוע /clear, /compact, או הפעלה מחדש.

• עריכת קבצים במאגר שלך
• עריכת CLAUDE.md באמצע הפעלה
• שינוי מצב הרשאות
• שינוי סגנון הפלט
• הפעלת מיומנויות ופקודות
• הרצת /recap
• החזרת השיחה לאחור (Rewinding the conversation)
• יצירת תת סוכן (Spawning a subagent)

#עריכת קבצים במאגר שלך

תוכן קבצים נכנס להקשר רק כאשר Claude קורא אותם, וקריאות מתווספות לסוף השיחה. עריכת קובץ ש-Claude קרא בעבר אינה משנה בדיעבד את הקריאה המוקדמת יותר בהיסטוריה. במקום זאת, Claude Code מוסיף <system-reminder> המציין שהקובץ השתנה, ו-Claude קורא אותו מחדש במידת הצורך.

#עריכת CLAUDE.md באמצע הפעלה

קובצי ה-CLAUDE.md ברמת שורש הפרויקט וברמת המשתמש נקראים פעם אחת בתחילת ההפעלה ונשמרים בזיכרון. עריכתם באמצע הפעלה אינה פוסלת את המטמון, אך העריכה גם אינה חלה. Claude ממשיך לעבוד עם הגרסה שנטענה בתחילת ההפעלה. התוכן החדש נטען ב-/clear, ב-/compact, או בהפעלה מחדש הבאים.

קובצי CLAUDE.md מקוננים בספריות משנה וכללים עם paths: ב-frontmatter נטענים מאוחר יותר, כאשר Claude קורא לראשונה קובץ תואם. עריכת אחד מהם לפני שהוא נטען אכן נכנסת לתוקף. לאחר שהוא נטען, התוכן הוא חלק מהיסטוריית השיחה, ולכן עריכה באמצע הפעלה אינה משנה אותו בדיעבד.

#שינוי מצב הרשאות

מעבר בין מצבי הרשאות (permission modes), כגון מ-Manual לקבלת עריכות (accept edits), אינו משנה את הנחיית המערכת או את הגדרות הכלים, ולכן שינויי מצב בטוחים מבחינת המטמון. החריג הוא מצב תוכנית (plan mode) עם הגדרת המודל opusplan, אשר מחליפה את המודל בין Opus ל-Sonnet בעת כניסה או יציאה ממצב תוכנית. הדבר הופך את החלפת המצב להחלפת מודל.

#שינוי סגנון הפלט

כאשר אתה מחליף סגנון פלט (output style) באמצע הפעלה באמצעות /output-style, באמצעות /config, או באמצעות ההגדרה outputStyle, Claude משתמש בסגנון החדש החל מההודעה הבאה שלך. Claude Code מעביר את הוראות הסגנון החדש כהודעה בשיחה, כך שבקשה זו עדיין קוראת את הנחיית המערכת ואת השיחה המוקדמת יותר מהמטמון.

לפני גרסה v2.1.251, החלפת סגנון באמצע הפעלה שמרה על המטמון אך לא חלה עד שהרצת /clear או התחלת הפעלה חדשה.

#הפעלת מיומנויות ופקודות

מיומנויות (Skills) ופקודות (commands) מזריקות את ההוראות שלהן כהודעות משתמש בנקודת ההפעלה. שום דבר מוקדם יותר בשיחה אינו משתנה. מיומנות או פקודה שה-frontmatter שלהן מציין model יכולה להוות החלפת מודל עבור אותו תור.

#הרצת /recap

הפקודה /recap מייצרת סיכום לתצוגה בטרמינל שלך. בשונה מ-/compact, היא מוסיפה את הסיכום כפלט פקודה במקום להחליף את היסטוריית ההודעות שלך, כך שהקידומת שבמטמון נשארת שלמה.

#החזרת השיחה לאחור (Rewinding the conversation)

הפקודה /rewind קוטמת את השיחה שלך בחזרה לתור מוקדם יותר. ההיסטוריה שנותרה היא אותו תוכן שממנו נבנה המטמון באותה נקודה, ושכבות הנחיית המערכת והקשר הפרויקט נותרו ללא שינוי, כך שהבקשה הבאה פוגעת ברשומת המטמון המוקדמת יותר. כל תור מאז קרא דרך אותה קידומת, מה ששמר על הרשומה חמה גם אם התור המקורי התרחש לפני זמן ארוך יותר מה-TTL.

שחזור נקודות ביקורת של קבצים (file checkpoints) לצד השיחה אינו משפיע בנפרד על המטמון. תוכן קבצים נכנס להקשר רק כאשר Claude קורא אותם, בדיוק כמו בעת עריכת קבצים במאגר שלך.

#חידוש הפעלה

כאשר אתה מחדש הפעלה (resume a session), Claude Code שולח את כל השיחה שוב, והבקשה קוראת מהמטמון כל חלק מהקידומת שלה שלא השתנה ועדיין נמצא בתוך משך חיי המטמון. טבלת השכבות בראש דף זה מציינת מה משנה כל שכבה.

הנחיית המערכת עשויה להשתנות לאחר שדרוג Claude Code או עם טקסט שונה ב---append-system-prompt בעת החידוש. כברירת מחדל, השיחה המחודשת שומרת על הנחיית המערכת שאיתה היא התחילה, כך שההיסטוריה שלה עדיין יושבת מאחורי אותה הנחיה, והשינוי נכנס לתוקף ברגע שהשיחה נדחסת או בשיחה חדשה. דגלי הנחיית מערכת בשיחות מחודשות מכסה את המקרים שבהם Claude Code בונה מחדש את ההנחיה בכל בקשה במקום זאת.

#משך חיי המטמון

תוקף קידומות במטמון פג לאחר תקופה של חוסר פעילות. כל בקשה שפוגעת במטמון מאפסת את הטיימר, כך שהמטמון נשאר חם כל עוד אתה ממשיך לעבוד. לאחר מרווח זמן ארוך מספיק, הבקשה הבאה מחשבת מחדש את הקלט המלא ומבססת מחדש את המטמון, וזו הסיבה שהתור הראשון בחזרה לאחר התרחקות עשוי להיות איטי באופן ניכר.

בתוכנית Pro או Max, כאשר אתה מחדש הפעלה גדולה לאחר הפסקה ארוכה, Claude Code מציע לחדש מתוך סיכום כדי שבקשות מאוחרות יותר לא יישאו את ההיסטוריה המלאה.

זמן החיים (TTL) קובע מרווח זמן של כמה זמן המטמון ישרוד. ה-API מציע שניים: TTL של חמש דקות, ו-TTL של שעה אחת ששומר על המטמון חם לאורך הפסקות ארוכות יותר אך מחייב כתיבות למטמון בתעריף גבוה יותר. ה-TTL הארוך יותר עוזר כאשר אתה משאיר הפעלה ללא פעילות וחוזר אליה, מכיוון שאתה מדלג על העיבוד מחדש שקידומת שפג תוקפה עולה. הוא עולה יותר בפרצי עבודה קצרים שלעולם אינם ממתינים ללא פעילות מעבר לחמש דקות, שבהם חל תעריף הכתיבה הגבוה יותר ומשך חיי המטמון הארוך יותר נותר ללא שימוש.

#איזה TTL מקבלת כל בקשה

Claude Code קובע את ה-TTL לכל בקשה, וכל בקשה נופלת לאחד משני דליים (buckets) קבועים:

• שיחה ראשית (Main conversation): התורות האינטראקטיביים שלך, הרצות -p לא אינטראקטיביות, ותורות של Agent SDK, בתוספת רכיבי העזר ש-Claude Code מריץ באופן מוטבע (inline) יחד איתם.
• כל השאר (Everything else): הבקשות ש-Claude Code מבצע מחוץ לאותה שיחה, כגון תת סוכנים (subagents), תהליכי עבודה (workflows), חברי צוות בתוך התהליך (teammates), פיצולים (forks), דחיסה, וכותרות הפעלה.

אלא אם תבחר TTL בעצמך, Claude Code מבקש את ה-TTL של שעה אחת רק במנוי Claude במסגרת השימוש הכלול בתוכנית שלך. שם הוא מבקש את השעה עבור השיחה הראשית, בתוספת קבוצה קטנה של בקשות עזר ש-Anthropic שולטת בהן בצד השרת. טבלה זו מציגה את ה-TTL המוגדר כברירת מחדל של כל דלי תחת שני סוגי החיוב.

ברגע שאתה חורג ממגבלת השימוש בתוכנית שלך ו-Claude Code מושך מתוך נקודות זכות לשימוש (usage credits), אתה מחויב עבור שימוש זה, ולכן Claude Code מוריד את השיחה הראשית ל-TTL הזול יותר של חמש דקות. כדי לשמור על ה-TTL של שעה אחת שם, בחר את ה-TTL בעצמך.

#בחירת ה-TTL בעצמך

באפשרותך להגדיר TTL עבור כל אחד מהדליים. כל פקד מקבל 5m או 1h, ו-Claude Code מתעלם מכל ערך אחר.

• שיחה ראשית: ההגדרה promptCacheTtl, או משתנה הסביבה CLAUDE_CODE_PROMPT_CACHE_TTL.
• כל השאר: ההגדרה subagentPromptCacheTtl, או משתנה הסביבה CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL.

שתי ההגדרות ושני משתני הסביבה דורשים את Claude Code בגרסה v2.1.242 ואילך. אם אתה מתחבר באמצעות מפתח API או משתמש בספק ענן, הגדר את promptCacheTtl ל-1h כדי להעניק לשיחה הראשית מטמון של שעה אחת. בקשות מחוצה לה שומרות על ברירת המחדל של חמש דקות עד שתבחר TTL גם עבור הדלי הזה.

כאשר חל יותר מפקד אחד, Claude Code בוחר את ההתאמה הראשונה לפי סדר זה:

1. FORCE_PROMPT_CACHING_5M=1, אשר כופה חמש דקות עבור שני הדליים
2. משתנה הסביבה של הדלי
3. ההגדרה של הדלי
4. עבור בקשות של תת סוכן, ערך ה-cacheTtl בתוך שדה ה-frontmatter הניסיוני (experimental) של תת הסוכן, הדורש את Claude Code בגרסה v2.1.248 ואילך. Claude Code מתעלם מ-1h שם בזמן שמנוי Claude שלך משתמש בנקודות זכות לשימוש
5. ENABLE_PROMPT_CACHING_1H=1, אשר מבקש שעה אחת עבור שני הדליים
6. ברירת המחדל עבור דלי הבקשה

הגדר FORCE_PROMPT_CACHING_5M=1 כאשר אתה מנפה שגיאות בהתנהגות המטמון, משווה בין שני ה-TTLs, או דורס TTL ארוך יותר שהוגדר בתוך הגדרות מנוהלות (managed settings).

כדי לוודא באיזה TTL השתמשו כתיבות המטמון של השיחה הראשית שלך, הרץ claude -p "hello" --output-format json וקרא את usage.cache_creation בתוצאה. Claude Code מדווח על כתיבות מטמון של שעה אחת תחת ephemeral_1h_input_tokens ועל כתיבות מטמון של חמש דקות תחת ephemeral_5m_input_tokens.

דרך שער LLM שהגדרת עם ANTHROPIC_BASE_URL, חלק מבקשת השעה האחת עובר בכותרת anthropic-beta, לכן הגדר את השער כך שיעביר כותרת זו ללא שינוי. ה-TTL של שעה אחת אינו זמין דרך Claude apps gateway. ב-Amazon Bedrock, התמיכה ב-prompt caching, אורך הקידומת המינימלי הניתן לשמירה במטמון וזמינות ה-TTL של שעה אחת משתנים כולם לפי המודל. אם ספירת אסימוני המטמון נשארת על אפס, בדוק את המודלים הנתמכים, האזורים והמגבלות בתיעוד של Amazon Bedrock.

#היקף המטמון (Cache scope)

ב-Claude Code, המטמון מוגדר בפועל ברמת מכונה אחת וספרייה אחת. כל שיחה נושאת את ספריית העבודה, הפלטפורמה, המעטפת (shell) וגרסת מערכת ההפעלה, והנחיית המערכת מציינת את נתיבי הזיכרון האוטומטי שלך, כך ששתי הפעלות בספריות שונות בונות קידומות שונות ומפספסות את המטמון זו של זו. זה כולל עצי עבודה (worktrees) של אותו מאגר, מכיוון שלכל עץ עבודה יש ספריית עבודה משלו.

הפעלות שאתה מריץ במקביל באותה ספרייה בונות קידומות תואמות וקוראות את המטמון זו של זו. הפעלות עוקבות חולקות את הקידומת רק כאשר תמונת המצב של git status שנלקחה בהפעלה תואמת, מכיוון שכל שיחה נושאת גם את הענף ואת ה-commits האחרונים מאותה תמונת מצב.

מטמון ה-API שביסוד הדברים רחב יותר. מטמונים מבודדים בין ארגונים, ובספקים מסוימים, בין סביבות עבודה (workspaces) בתוך ארגון. בתוך גבולות אלה, כל שתי בקשות עם אותו מודל ואותה קידומת קוראות מאותו מטמון. עבור משתמשי Agent SDK המריצים ציי תהליכים אוטומטיים, ראה שיפור prompt caching בין משתמשים ומכונות כדי לדכא את חלקי הנחיית המערכת הייחודיים לכל מכונה ולשתף את המטמון בין מכונות.

#בדיקת ביצועי המטמון

ביצועי המטמון מופיעים כשתי ספירות אסימונים שה-API מדווח עליהן בכל תגובה. הדרך הישירה ביותר לצפות בהן בזמן אמת היא סקריפט שורת מצב (statusline script) שקורא את האובייקט current_usage:

יחס קריאה לכתיבה גבוה פירושו שהשמירה במטמון פועלת היטב. אם הכתיבה (creation) נשארת גבוהה תור אחר תור, משהו משתנה בקידומת שלך. סעיף פעולות שפוסלות את המטמון מפרט את הגורמים הרגילים לכך.

עבור סיכום לכל הפעלה, הרץ /usage. לאחר התגובה הראשונה של השיחה הראשית, Claude Code מוסיף שורת Prompt cache (main) לבלוק ה-Session, המציגה את יחס הפגיעות (hit ratio) של ההפעלה, מספר הפספוסים (miss count), והאם המטמון חם כעת. סקריפט שורת מצב יכול לקרוא את אותם מספרים מתוך האובייקט prompt_cache. שניהם דורשים את Claude Code בגרסה v2.1.251 ואילך.

שורת ה-Prompt cache (main) מציינת גם את הסיבה הסבירה לפספוס האחרון כאשר Claude Code מצליח לזהות אחת כזו, לדוגמה likely cause: tool definitions changed. טקסט הסיבה הסבירה דורש את Claude Code בגרסה v2.1.260 ואילך.

לנראות ברחבי הארגון, רכיב הייצוא של OpenTelemetry מדווח על אסימוני קריאה וכתיבה של מטמון לכל משתמש והפעלה. ראה ניטור שימוש (Monitor usage) עבור מדריך תכונות המדדים והאירועים.

#תת סוכנים והמטמון

תת סוכן (subagent) מתחיל שיחה משלו עם הנחיית מערכת וקבוצת כלים משלו, בנפרד מאלו של ההורה. הבקשה הראשונה שלו אינה קוראת את המטמון של ההורה, מכיוון ששתי הקידומות שונות, והוא מחמם מטמון משלו לאורך התורות שלו. תת סוכנים נופלים מחוץ לדלי ה-TTL של השיחה הראשית, ולכן הם מקבלים חמש דקות אפילו במנוי עד אשר תבחר ב-TTL ארוך יותר.

המטמון של ההורה אינו מושפע. מהצד של ההורה, הקריאה לתת הסוכן והתוצאה שלו מתווספות לסוף השיחה, מה שמשאיר את הקידומת של ההורה שלמה.

לעומת זאת, פיצול (fork) יורש בדיוק את הנחיית המערכת, הכלים והיסטוריית השיחה של ההורה, ולכן הבקשה הראשונה שלו קוראת את המטמון של ההורה.

בקשות אחרות יכולות גם הן לקרוא קידומת שבקשה מוקדמת יותר שמרה במטמון:

• עותקי הפעלה (Session copies): הפעלה שאתה מעתיק באמצעות /fork מקבלת את הוראת הבידוד שלה כהודעה בסוף השיחה המועתקת, כך שהמטמון שהשיחה המקורית בנתה נשאר שלם.
• דחיסה (Compaction): קריאת הסיכום המתוארת בסעיף דחיסת השיחה משתמשת באותה גישה של שיתוף קידומת.
• תת סוכנים שחודשו (Resumed subagents): כאשר Claude מחדש תת סוכן, הבקשה הראשונה של ההרצה המחודשת יכולה לקרוא את המטמון שההרצה המקורית חיממה.
• פיצול משימות בתהליך עבודה (Workflow fan-outs): בפיצול תהליך עבודה של סוכנים בעלי אותה קידומת, Claude Code מעכב כברירת מחדל את כולם למעט הראשון למשך עד 5 שניות, כדי שהבקשות הראשונות שלהם יוכלו לקרוא את הקידומת שהסוכן הראשון שמר במטמון.

#השבתת prompt caching

השבתת השמירה במטמון שימושית לעיתים בעת ניפוי שגיאות בהתנהגות המטמון עם מודל או ספק ספציפיים. כדי לכבות אותה, הגדר אחד ממשתני סביבה אלה ל-1:

כדי להגדיר מדיניות שמירה במטמון ברחבי הארגון, הצב כל אחד מאלה או את משתני ה-TTL בבלוק ה-env של הגדרות מנוהלות (managed settings). לשימוש רגיל, השאר את השמירה במטמון מופעלת.

#משאבים קשורים

• לקחים מבניית Claude Code: שמירת הנחיות במטמון היא הכל (Prompt caching is everything): הרציונל התכנוני עבור מצב תוכנית (plan mode), טעינת כלים נדחית ודחיסה
• סיור בחלון ההקשר (Explore the context window): מה נטען להקשר ומתי
• הפחתת השימוש באסימונים (Reduce token usage): אסטרטגיות מעבר לשמירה במטמון לניהול גודל ההקשר
• מעקב והפחתת עלויות (Track and reduce costs): מעקב אחר אסימוני מטמון ותצורת TTL עבור משתמשי Agent SDK
• Prompt caching: מנגנון ה-API שביסוד הדברים, נקודות עצירה (breakpoints) ותמחור