إنتقل إلى المحتوى الرئيسي

الذاكرة وتحرير السياق

متقدّم

للوكيل طويل التشغيل عدوّان: فهو ينسى ما تعلّمه لحظة انتهاء المحادثة، وتمتلئ نافذة سياقه حتى الفيض بمخرجات الأدوات القديمة. تقدّم Anthropic بدائية واحدة لكلٍّ منهما — أداة memory (الاستمرارية) وتحرير السياق (التقليم) — وهما مصمَّمتان لاستخدامهما معًا.

What you'll learn
  • ما هي أداة memory — مخزن ملفات من جانب العميل عند /memories تنفّذه أنت، وليست Anthropic
  • الأوامر الستة التي يجب أن يجيب عنها معالجك: view و create و str_replace و insert و delete و rename
  • لماذا يُعدّ التحقق من اجتياز المسار غير قابل للتفاوض عند توصيله
  • كيف يمسح تحرير السياق نتائج الأدوات القديمة تلقائيًا بمجرد تجاوز السياق عتبة الرموز
  • كيف تجمع بين الاثنتين تحت رأس بيتا واحد، والمطبّات المتعلقة بالتخزين المؤقت والترتيب

مشكلتان، أداتان​

أبقِ الفكرتين منفصلتين في ذهنك:

  • أداة memory = الاستمرارية عبر الجلسات. يقرأ Claude الملفات ويكتبها؛ أنت تخزّنها.
  • تحرير السياق = التقليم داخل الجلسة. تُسقِط واجهة API نتائج الأدوات القديمة من المُطالبة قبل أن تصل إلى Claude.

تترافق هذه الصفحة مع Prompt Caching واقتصاد الرموز لجانب التكلفة، ومع هندسة السياق وتجهيزات الوكلاء طويلة التشغيل لمعرفة السبب.

مفردات الذاكرة والسياق
اضغط Enter أو مفتاح المسافة لقلب البطاقة. استخدم مفتاحي السهمين الأيسر والأيمن للتنقل بين البطاقات.تم إظهار المصطلح.
1 / 5

أداة memory هي أداة تنفّذها أنت​

هذا ما يربك الناس: تفعيل أداة memory لا يمنحك تخزينًا مستضافًا من Anthropic. إنها أداة من جانب العميل. يُصدِر Claude استدعاءات أدوات مثل view أو create؛ ينفّذها تطبيقك مقابل أي خلفية تختارها — ملفات محلية، قاعدة بيانات، كتل مشفّرة، تخزين سحابي — ويعيد النتيجة. أنت تملك مكان وجود البايتات (وهذا أيضًا سبب أهليتها لـ Zero-Data-Retention).

عند تفعيل الأداة، تحقن Anthropic تعليمة نظام تخبر Claude بأن يتحقق من دليل ذاكرته قبل القيام بأي شيء آخر، وأن يسجّل التقدم أثناء عمله حتى لا يُفقَد شيء إذا أُعيد ضبط السياق.

الخطوة 1 — تفعيل الأداة​

أضِف الأداة إلى طلبك. سلسلة النوع هي الإصدار المؤرّخ memory_20250818.

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "Help me respond to this support ticket."}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

تشحن حِزَم SDK الرسمية مساعِدات للذاكرة حتى لا تصوغ واجهة الأداة يدويًا — اشتق من BetaAbstractMemoryTool (Python و C#)، أو استخدم betaMemoryTool (TypeScript)، أو نفّذ BetaMemoryToolHandler (Java). إنها تمنحك خطافًا نظيفًا تُدخِل فيه تخزينك.

الخطوة 2 — الإجابة عن الأوامر الستة​

يجب أن ينفّذ معالجك هذه الأوامر. السلاسل التي يتوقعها Claude مرة أخرى محددة — طابِقها حتى يفسّر النموذج النتائج بشكل صحيح.

Guided walkthrough1 of 6
  1. أدرِج دليلًا (ملفات حتى مستويين عمقًا، مع أحجام قابلة للقراءة البشرية) أو أعِد محتويات ملف مع أرقام أسطر مفهرسة من 1. خيار view_range لقراءة شريحة.

تُعيد عملية view حقيقية للدليل شيئًا كهذا — لاحظ الترويسة الحرفية والأحجام المفصولة بعلامات جدولة، التي دُرِّب النموذج على تحليلها:

Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:
4.0K	/memories
1.5K	/memories/customer_service_guidelines.xml
2.0K	/memories/refund_policies.xml

الخطوة 3 — أحكِم قفل المسارات (لا تتخطَّ هذا)​

تتيح أداة memory للنموذج إصدار سلاسل مسارات اعتباطية. يمكن لمحادثة مسمومة أو حمولة حقن مُطالبة أن تحاول الإفلات من /memories لقراءة ملفات في مكان آخر على جهازك أو الكتابة فوقها. عامِل كل مسار وارد على أنه عدائي.

Watch out
  • ارفض أي مسار لا يُحَلّ إلى داخل /memories.
  • عيّر المسار إلى صورته القانونية قبل التحقق — في Python، Path(p).resolve() ثم تحقق من أن .relative_to(memories_root) لا تطرح استثناءً.
  • احظر ../ و ..\ والاجتياز المُشفَّر بـ URL مثل %2e%2e%2f.
  • ضع سقفًا لأحجام الملفات وطول القراءة حتى لا يستنزف وكيل جامح القرص أو يُفجِّر المُطالبة التالية.

هذا المُحقِّق هو اللعبة كلها — ثبّته واختبره قبل شحن أي شيء آخر:

حارس اجتياز المسار (Python)

from pathlib import Path

MEMORY_ROOT = Path("/srv/agent/memories").resolve()

def safe_path(requested: str) -> Path:
  # Map the model's /memories/... onto your real root, then prove containment.
  rel = requested.removeprefix("/memories").lstrip("/")
  candidate = (MEMORY_ROOT / rel).resolve()
  candidate.relative_to(MEMORY_ROOT)  # raises ValueError if it escaped
  return candidate

يحفظ تحرير السياق النافذة من الفيض​

تحلّ الذاكرة مشكلة النسيان. المشكلة المعاكسة — نافذة سياق محشوّة بكتل tool_result قديمة من 40 بحثًا على الويب مضى — هي ما يحلّه تحرير السياق. بمجرد تجاوز المُطالبة عتبة الرموز، تمسح واجهة API أقدم نتائج الأدوات (مستبدلةً إياها بعنصر نائب قصير حتى يعرف Claude أنها أُزيلت) قبل إرسال المُطالبة إلى النموذج. يحتفظ عميلك بالتاريخ الكامل غير المُحرَّر؛ ويُقلَّم فقط ما يصل إلى النموذج.

تعتمد على رأس بيتا:

anthropic-beta: context-management-2025-06-27

تضبطها بمصفوفة context_management.edits. الاستراتيجية الرئيسية هي clear_tool_uses_20250919:

message = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    betas=["context-management-2025-06-27"],
    messages=[...],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},  # start clearing past 30k
                "keep": {"type": "tool_uses", "value": 3},            # always keep the last 3
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                "exclude_tools": ["memory"],                          # never clear memory calls
                "clear_tool_inputs": False,                           # keep the call args, drop results
            }
        ]
    },
)

ماذا تعني المقابض:

المعاملالافتراضيما يتحكم فيه
trigger100,000 رمز إدخالمتى يبدأ المسح
keep3 استخدامات أدواتكم عدد أزواج استخدام/نتيجة الأدوات الحديثة المحفوظة دائمًا
clear_at_leastلا شيءالحد الأدنى للرموز المُحرَّرة لكل تفعيل — استخدمه حتى يكون إبطال التخزين المؤقت مجديًا فعلًا
exclude_toolsلا شيءالأدوات التي لا تُمسح أبدًا (مثل memory و web_search)
clear_tool_inputsfalseما إذا كان يجب أيضًا إسقاط وسائط استدعاء الأداة، وليس النتيجة فقط

تخبرك الاستجابة بما فعلته، ضمن context_management.applied_edits — مثل cleared_tool_uses و cleared_input_tokens — حتى تتمكن من تسجيل كم استُعيد.

هناك استراتيجية شقيقة، clear_thinking_20251015، تقلّم كتل التفكير الموسّع القديمة. إذا استخدمت الاثنتين، أدرِج clear_thinking_20251015 أولًا في مصفوفة edits.

Pro tip
  • يبطل مسح نتائج الأدوات أي بادئة تخزين مؤقت للمُطالبة عند نقطة المسح — اقرنه بـ clear_at_least حتى لا تدفع ثمن ذلك الإبطال إلا عند تحرير قدر ذي معنى.
  • exclude_tools: ["memory"] هي الخطوة المعتادة: تريد أن تستمر ملاحظات الوكيل الخاصة، لا أن تُكنَس مع نتائج البحث القديمة.
  • تحرير السياق (تقليم من جانب العميل) والضغط (تلخيص من جانب الخادم) ميزتان مختلفتان — للتشغيلات الطويلة جدًا يمكنك تطبيق الاثنتين معًا.

لماذا تقرنهما — الأرقام​

عند استخدامهما معًا، تتيح الميزتان للوكيل التشغيل إلى ما هو أبعد بكثير من نافذة سياق واحدة: يبقي تحرير السياق النافذة الحية رشيقة، ويُكتَب كل ما يهم إلى الذاكرة قبل أن يُمسح. تُفيد Anthropic بأن الجمع بين الذاكرة وتحرير السياق أعطى تحسنًا بنسبة 39% على تقييم بحث وكيلي، وأن تحرير السياق وحده قلّل استخدام الرموز بنسبة 84% في اختبار بحث ويب من 100 دور.

نمط يعمل: سجل المشروع متعدد الجلسات​

أنظف استخدام للذاكرة هو تمهيدها بشكل متعمّد بدلًا من كتابة الملفات بشكل عشوائي:

Guided walkthrough1 of 4
  1. قبل أي عمل حقيقي، اكتب سجل تقدم، وقائمة تحقق للميزات، وملاحظة تشير إلى أي سكربت بدء يحتاجه المشروع.

اختبر فهمك​

Check yourself

0/3
  1. أين تُخزَّن بيانات أداة memory فعليًا؟
  2. ماذا تزيل استراتيجية clear_tool_uses_20250919 الخاصة بتحرير السياق؟
  3. لماذا يجب أن تتحقق من كل مسار تتلقاه أداة memory؟

المصادر وقراءات إضافية​