ما الذي ستبنيه؟

ستخطط لنظام وكيل برمجي بـ TypeScript يمكنه استقبال مهمة خاصة بمستودع، وجمع سياق المشروع ذي الصلة، وطلب تنفيذ إجراءات عبر الأدوات، والاحتفاظ بحقائق محددة لاستخدامها في الجلسات اللاحقة. الهدف الأساسي من التصميم ليس حفظ كل محادثة، بل إتاحة المعرفة المفيدة عند بدء المهمة التالية.

هذا التمييز مهم، لأن سياق المحادثة الفوري للنموذج ليس مماثلاً للذاكرة طويلة الأمد. يتعامل الوكيل المدعوم بالذاكرة مع الذاكرة باعتبارها بنية تحتية مستمرة ومنظّمة خارج النموذج. وعند بدء التشغيل، يمكنه تحميل السياق السابق؛ وأثناء العمل، يمكنه استرجاع الحالة والأدوات ذات الصلة؛ وبعد التفاعل، يمكنه استخراج الحقائق أو تحسينها ثم حفظها مجدداً. وهكذا تصبح الذاكرة نظاماً فرعياً مصمماً بعناية، لا نصاً متنامياً بلا نهاية.

لا تثبت الأدلة المتاحة استخداماً محدداً لـ Bun أو مخططاً لقاعدة SQLite أو تطبيق بحث باستخدام FTS٥ أو إصداراً من OpenAI SDK أو عينة مكتملة من شيفرة وكيل برمجي. لذلك، يقدّم هذا الشرح خطة تنفيذ ونقاط تحقق معمارية، وليس برنامجاً جاهزاً للنسخ واللصق. اختر بيئة التشغيل ومحوّل التخزين ومزوّد النموذج وطريقة استخدام API، ثم تحقّق منها عبر وثائقها الرسمية الحالية قبل كتابة شيفرة مخصصة للإنتاج.

المتطلبات المسبقة

• إلمام جيد بـ TypeScript وتدفقات التطبيقات غير المتزامنة ومفاهيم أدوات الوكلاء.
• تعريف واضح بالمستودع أو المشروع الذي صُمم الوكيل لمساعدته.
• قرار يحدد المعلومات التي يمكن الاحتفاظ بها بين الجلسات، وتلك التي يجب عدم تخزينها.
• اختيار مزوّد للنموذج وتقنية للتخزين بالاستناد إلى وثائقهما الحالية، مع إدارة بيانات الاعتماد خارج الشيفرة المصدرية.

الخطوة ١: حدّد عقد الذاكرة الخاص بالوكيل

ابدأ بعقد مكتوب يوضح ما الذي يمكن للوكيل تذكّره، وكيف ستُستخدم هذه الحقائق، وكيف يمكن تصحيحها أو حذفها. تتعامل هندسة الذاكرة مع الذاكرة طويلة الأمد باعتبارها بنية تحتية أساسية: فهي موجودة خارج النموذج ومنظّمة بحيث يستخدمها الوكيل بطريقة مقصودة. وهذه نقطة انطلاق أكثر فائدة من الاحتفاظ بكل رسالة ووضع السجل الكامل في كل Prompt مستقبلي.

بالنسبة إلى المساعد البرمجي، قد تشمل فئات الذاكرة المحتملة اصطلاحات المشروع، والقرارات المعمارية، والمخاطر المعروفة، والأوامر أو الإجراءات التي تم تأكيدها أثناء العمل السابق. هذه أمثلة تصميمية، وليست ادعاءً بأن أي إطار عمل محدد يخزّن هذه الفئات تلقائياً. اجعل العقد محدوداً: احتفظ بالمعلومات الدائمة فقط التي يمكن أن تساعد في مهمة مستقبلية داخل المستودع، وميّز بين الملاحظات المؤكدة والافتراضات.

دوّن الحد الفاصل بين سياق الجلسة والذاكرة طويلة الأمد. قد يكون السؤال المرتبط بمهمة محددة أو تفصيل تصحيح مؤقت مفيداً فقط أثناء المهمة الحالية. وقد تكون قاعدة مؤكدة في المشروع مفيدة لاحقاً. أما السر أو بيانات الاعتماد أو التفصيل الشخصي غير المرتبط بالمشروع، فلا ينبغي أن يتحول إلى ذاكرة دائمة للمشروع. تثبت المصادر الموثّقة قيمة الذاكرة المنظّمة وخطوط استخراج الحقائق، لكنها لا تفرض سياسة موحّدة للاحتفاظ بالبيانات؛ لذا عليك تعريف سياسة تناسب تطبيقك.

حدّد أيضاً من أو ما الذي يمكنه تحديث الذاكرة. قد تتيح حلقة الحفظ العكسي للوكيل تحديث ذاكرته تلقائياً، لكن هذه القدرة خيار تصميمي، وليست دليلاً على صحة كل حقيقة مقترحة. حدّد كيفية مراجعة التحديثات، وكيفية التعامل مع الحقائق المتعارضة، وكيف يمكن للإنسان فحص المعرفة المخزنة أو تصحيحها.

الخطوة ٢: صمّم دورة حياة الذاكرة

خطط للذاكرة باعتبارها دورة حياة تتألف من أربع مراحل منفصلة: التحميل، والاسترجاع، والدمج، والحفظ العكسي. ويسهّل الفصل بين هذه المراحل فهم المعلومات التي تدخل في طلب النموذج وسبب الاحتفاظ بحقيقة معينة.

1. التحميل عند بدء التشغيل. هيّئ الوكيل بالحالة المستمرة المناسبة لمهمته. الهدف هو البدء بسياق سابق مفيد، لا إعادة تشغيل كل تفاعل سابق عشوائياً.
2. الاسترجاع للمهمة الحالية. اختر الحقائق والأدوات المرتبطة بالمهمة المطروحة. ويستخدم تصميم الوكيل المدعوم بالذاكرة الاسترجاع لتجميع السياق والحالة والأدوات أثناء التنفيذ.
3. الاستخراج والدمج. حوّل أدلة المحادثة إلى حقائق منظّمة، ثم ادمج المعلومات العرضية في معرفة دلالية أكثر قابلية لإعادة الاستخدام عندما يكون ذلك مناسباً. تصف المواد المصدرية هذه الأساليب باعتبارها أنماطاً لهندسة الذاكرة، لكنها لا تقدّم مخططاً موحّداً أو Prompt استخراج عاماً.
4. الحفظ العكسي بصورة مقصودة. خزّن التحديثات المفيدة كي تتمكن جلسة لاحقة من استرجاعها. تعامل مع هذه العملية باعتبارها إجراءً مستقلاً له قواعده الخاصة للتحقق والاحتفاظ، بدلاً من افتراض أن كل استجابة من النموذج تنتمي إلى التخزين طويل الأمد.

توضح دورة الحياة هذه أيضاً الفرق بين السجل والذاكرة المفيدة. فالسجل يوثّق ما قيل، بينما الذاكرة الدائمة هي معلومات منتقاة تهدف إلى مساعدة العمل مستقبلاً. ويتطلب تحويل الأول إلى الثانية الاستخراج والتنظيم والدمج؛ فحفظ مزيد من النصوص لا ينشئ بحد ذاته قدرة أفضل على التذكّر.

الخطوة ٣: قرّر آلية الاسترجاع

يمثل الاسترجاع الجسر بين التخزين المستمر والمهمة الحالية. قد يمتلك الوكيل البرمجي سياقاً مخزناً أو أدوات متاحة أكثر بكثير مما يستطيع استخدامه بفاعلية في طلب واحد. وتبرز وثيقة الدورة التدريبية الموثّقة Semantic Search بوصفه وسيلة لتوسيع نطاق الوصول إلى الأدوات واسترجاع الأدوات المرتبطة فقط وقت الاستدلال، ما يعالج تحدي الوكلاء الذين يملكون مئات الأدوات.

قبل اختيار طريقة البحث، أدرج المعلومات التي يجب أن يعثر عليها الوكيل. فقد تتطلب اصطلاحات المشروع أو قرار معماري أو وصف أداة سلوكاً مختلفاً في الاسترجاع. حدّد معنى الصلة لكل فئة، والنطاق المطبق على النتيجة، وكيف ينبغي للوكيل التصرف عند عدم وجود تطابق مفيد. هذه أسئلة تصميم خاصة بالتطبيق؛ ولا يثبت السياق المتاح ضرورة استخدام قاعدة بيانات أو فهرس بحث أو معادلة ترتيب أو نموذج Embedding محدد.

حافظ على تركيز الاسترجاع على المهمة. فقد يؤدي تقديم كل حقيقة مخزنة إلى إعادة المشكلة نفسها التي يسببها تمرير سجل محادثة متنامٍ باستمرار: يتلقى النموذج مواد أكثر مما يحتاج. ويجمع نظام الذاكرة المفيد السياق المرتبط بالمهمة بدلاً من التعامل مع المستودع بأكمله باعتباره Prompt. افحص العناصر المسترجعة أثناء التطوير، واختبر مدى مساعدتها في مهام تمثيلية، بدلاً من افتراض أن نجاح استدعاء البحث يعني أن النتيجة مفيدة.

يمكن التعامل مع الأدوات باعتبارها ذاكرة إجرائية: قدرات يسترجعها الوكيل عند الحاجة، بدلاً من قائمة ثابتة تتضخم بلا حدود في كل تفاعل. وتصف الدورة التدريبية الموثّقة هذا النمط باعتباره وسيلة لتوسيع الوصول إلى الأدوات عبر Semantic Search. لكنها لا تحدد تطبيقاً لوكيل برمجي، لذا تعامل مع التفاصيل—مثل بيانات الأدوات الوصفية وقواعد الاختيار وسياسات الاستدعاء—باعتبارها قرارات ينبغي توثيقها والتحقق منها في نظامك.

الخطوة ٤: ابنِ حلقة استخدام الأدوات لدى الوكيل

يحتاج الوكيل البرمجي عموماً إلى نمط تفاعل متكرر. ويعرض الوصف الموثّق لوكلاء البرمجة بالذكاء الاصطناعي الدورة الأساسية التالية: يستقبل الوكيل المدخلات ويجهّز Prompt؛ وقد يجيب النموذج المستخدم أو يطلب استدعاء أداة؛ ثم ينفّذ التطبيق الأداة المطلوبة ويعيد مخرجاتها؛ وبعد ذلك يُستدعى النموذج مجدداً. وتتكرر العملية حتى يقدّم النموذج استجابة نهائية للمساعد بدلاً من طلب إجراء آخر.

استخدم هذه الدورة لتخطيط الحدود بين النموذج وتطبيقك. يستطيع النموذج طلب إجراء، لكن التطبيق مسؤول عن تحديد الأدوات الموجودة وتنفيذها. وبالنسبة إلى المساعد البرمجي، حدّد العمليات المطلوبة للمهمة، ووثّق كيفية التحقق من كل عملية قبل تشغيلها. لا تتعامل مع طلب منشأ من النموذج باعتباره دليلاً على ملاءمة الإجراء أو نجاحه.

أبقِ نتائج الأدوات مرتبطة بالطلب الذي أنتجها كي يتمكن الوكيل من تفسير النتيجة. ولا ينبغي للنموذج أن يدّعي أنه فحص ملفاً أو أجرى تغييراً أو أكمل عملية تحقق، ما لم يُرجع التطبيق دليلاً على تنفيذ ذلك الإجراء. هذا متطلب تصميم عملي لإعداد تقارير صادقة، وليس ضماناً بأن Prompt وحده يستطيع فرض الصحة.

حدّد شروطاً صريحة للإيقاف والمراجعة باعتبارها جزءاً من التصميم. لا يفرض السياق الموثّق حداً معيناً لعدد التكرارات أو مهلة زمنية أو نظام صلاحيات أو Sandbox للوصول إلى الملفات. ويجب اختيار هذه الضوابط التشغيلية واختبارها للتطبيق، لا تقديمها باعتبارها متاحة مسبقاً من إطار عمل الوكيل أو مزوّد النموذج.

الخطوة ٥: اختر إطار TypeScript أو ابنِ بيئة التشغيل الخاصة بك

إذا كنت تفضّل استخدام إطار عمل بدلاً من تجميع كل مكوّن بنفسك، فإن السياق الموثّق يصف Mastra بأنه إطار TypeScript حديث للتطبيقات والوكلاء المدعومين بالذكاء الاصطناعي. وتشمل قدراته المذكورة Workflows والذاكرة والبث والتقييمات والتتبع وStudio، وهي واجهة تفاعلية للتطوير والاختبار. وأمر بدء المشروع المذكور هو:

npm create mastra@latest

استخدم الوثائق الحالية للإطار لتأكيد الملفات التي يتم إنشاؤها والإعدادات وتهيئة مزوّد النموذج ومحوّلات الذاكرة وخيارات النشر المدعومة. ولا تثبت المعلومات الموثّقة واجهات API أو إعدادات محددة لربط Mastra بـ Bun أو SQLite أو نموذج OpenAI معين. لا تستنتج هذه التكاملات من قائمة الميزات؛ بل تحقّق منها عبر وثائق الإطار والمزوّد المحدثة.

بدلاً من ذلك، تمنحك بيئة TypeScript مخصصة مسؤولية مباشرة عن حلقة الوكيل ودورة حياة الذاكرة. وقد يكون ذلك مناسباً عندما تحتاج إلى نظام محدود النطاق، لكنه يعني أيضاً ضرورة تصميم واختبار الاستمرارية والاسترجاع وتنفيذ الأدوات ومعالجة الأخطاء والتقييم بنفسك. ولا يقتصر الاختيار على «إطار عمل مقابل عدم استخدام إطار»: قارن القدرات التي تحتاج إليها بأعمال التنفيذ والصيانة التي أنت مستعد لتحملها.

في كلا الخيارين، دوّن المكوّنات الموجودة فعلياً في التنفيذ الذي اخترته. وقد يتضمن المخطط نقطة إدخال المهمة، وتجميع السياق، والتفاعل مع النموذج، وتنفيذ الأدوات، والذاكرة المستمرة، والتقييم. لا تصف أي مكوّن بأنه آمن أو مستمر أو جاهز للإنتاج لمجرد ظهوره في مخطط أو قائمة ميزات لإطار عمل.

الخطوة ٦: ضع في الحسبان نمو السياق وحدود الوكيل

لا يزال الوكيل المدعوم بالذاكرة يحتاج إلى استراتيجية للمحادثة الفورية. ويشرح التقرير الموثّق حول بنية وكيل البرمجة لدى OpenAI مفاضلة مهمة: عندما يتضمن كل دور جديد السجل الكامل للرسائل السابقة واستدعاءات الأدوات، ينمو Prompt مع استمرار التفاعل، مع ما يترتب على ذلك من آثار في الأداء. كما يصف تصميماً تظل فيه الطلبات عديمة الحالة، ويُرسل السجل مع كل استدعاء لـ API. ويُعد ذلك التقرير دليلاً على نهج Codex الموصوف، وليس تصريحاً عاماً ينطبق على كل API أو نظام وكلاء.

افصل بين سجل المحادثة الفوري هذا وذاكرتك طويلة الأمد. فسجل المحادثة يشرح تسلسل الإجراءات الحالي، بينما تهدف الذاكرة المستمرة إلى نقل المعرفة المحددة عبر الجلسات. وقد يصبح التصميم الذي ينمّي Prompt الكامل بلا حدود أقل كفاءة. وفي المقابل، قد يترك التصميم الذي يحذف الأدلة ذات الصلة الوكيلَ بلا السياق الذي يحتاج إليه. حدّد ما ينبغي أن يبقى ضمن التفاعل النشط وما ينبغي تلخيصه أو تخزينه بدلاً من ذلك كذاكرة منظّمة، ثم قيّم هذه القرارات على مهام حقيقية.

كن واقعياً بشأن أداء وكلاء البرمجة. يشير التقرير الموثّق إلى أن هذه الأدوات قد تكون سريعة في المهام البسيطة لكنها هشة خارج بيانات تدريبها، وأن العمل في بيئة الإنتاج يتطلب إشرافاً بشرياً. ولا يلغي الهيكل الأولي الواعد أعمال تصحيح الأخطاء اللازمة لاستكمال التفاصيل أو معالجة القيود. خطط لمراجعة المطور للتغييرات المقترحة وتأكيد النتائج المهمة.

الخطوة ٧: قيّم سلوك الذاكرة والأدوات

لا تقيّم النظام بمجرد التحقق من تقديمه إجابة سلسة. اختبر قدرته على تحميل المعرفة السابقة ذات الصلة، واسترجاع الحقائق الصحيحة لمهمة جديدة، وتجنب الذاكرة غير المرتبطة، وتحديث المعلومات المخزنة بطريقة تظل مفيدة لاحقاً. ويصف السياق الموثّق التقييمات والتتبع ضمن قدرات إطار Mastra، كما يبرز خطوط الذاكرة التي تستخرج الحقائق المنظّمة وتدمج الذاكرة العرضية وتدعم الحفظ العكسي. لكنه لا يقدّم مجموعة اختبارات لتصميم الوكيل البرمجي هذا تحديداً.

أنشئ مجموعة من المهام التمثيلية المستمدة من أنواع العمل التي يُتوقع أن يدعمها وكيلك. أدرج حالات ينبغي أن تغيّر فيها الذاكرة ذات الصلة الإجابة، وحالات يجب ألا يؤثر فيها السياق المخزن في طلب غير مرتبط، وحالات تكون فيها الاستجابة الصحيحة هي المتابعة دون حقيقة متذكّرة. سجّل الحقائق التي جرى استرجاعها، والأدوات المطلوبة، وما إذا كانت الإجابة النهائية مدعومة بالنتائج المعادة.

راجع تحديثات الذاكرة بعناية توازي مراجعة الاسترجاع. تحقّق من أن الحقائق المستخرجة مدعومة بالتفاعل، وأن الحلقات المختلفة دُمجت بطريقة منطقية، وأن أي تحديث لا يتعارض مع المعلومات المخزنة مسبقاً. قد تكون حلقة الحفظ العكسي مستقلة، لكن ذلك لا يثبت صحة كل عملية حفظ. ضع عملية لتحديد الذكريات الخاطئة وإصلاحها قبل الاعتماد على النظام في الأعمال المؤثرة.

عندما يتوفر التتبع في الإطار أو التطبيق الذي تختاره، استخدمه لفهم كيفية سير العملية. أكّد ميزات الرصد الفعلية والبيانات التي يجري التقاطها في إعدادك المختار؛ فالسياق الموثّق يذكر التتبع والتقييمات باعتبارهما من قدرات Mastra، لكنه لا يحدد صيغة التتبع الدقيقة أو سياسة الاحتفاظ أو سلوك الخصوصية في أي تنفيذ.

الخطوة ٨: أدخل الوكيل بعناية

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

أبقِ المراجعة البشرية ضمن سير العمل عندما يتعلق الأمر بشيفرة مهمة. ويؤكد التقرير الموثّق أن وكلاء البرمجة قد يحتاجون إلى تصحيح أخطاء مرهق، وأنهم يظلون هشّين خارج بيانات تدريبهم. راجع التغييرات أو التوصيات، وشغّل الفحوص المناسبة لمشروعك، واتخذ بنفسك قرار قبول العمل. لا تدّعِ أن الوكيل تحقّق من تغيير ما، ما لم تُنفّذ عملية التحقق المعنية فعلياً وتتوفر نتيجتها.

قبل استخدام الذاكرة المستمرة مع مستودعات حساسة أو مملوكة، حدّد ما يمكن الاحتفاظ به ومن يمكنه الوصول إليه. تثبت المصادر المتاحة أفكاراً معمارية حول الذاكرة المستمرة، لكنها لا تثبت خصائص الخصوصية أو الاحتفاظ أو الأمان أو معالجة البيانات لأي مزوّد تخزين أو تكامل نموذج محدد. تحقّق من هذه الخصائص بشكل مستقل للأدوات التي تختارها.

أهم الخلاصات

• تعامل مع الذاكرة طويلة الأمد باعتبارها بنية تحتية منظّمة خارج النموذج، لا سجلاً متنامياً بلا حدود.
• صمّم دورة حياة لتحميل السياق السابق، واسترجاع الحقائق والأدوات ذات الصلة، واستخراج المعلومات ودمجها، وحفظ التحديثات مجدداً.
• استخدم الاسترجاع لجعل سياق المهمة الحالية وأدواتها مرتبطين بها، بدلاً من كشف مجموعة متنامية باستمرار بصورة افتراضية.
• افهم دورة استدعاء الأدوات، وخذ في الحسبان تكاليف إرسال سجل المحادثة بشكل متكرر وآثاره على الأداء عندما ينطبق هذا التصميم.
• تحقّق من واجهات API الخاصة ببيئة التشغيل والتخزين والمزوّد والأمان والإطار في وثائقها الحالية؛ فالأدلة المتاحة لا تثبت تطبيقاً محدداً باستخدام Bun أو SQLite أو OpenAI.
• قيّم النظام كاملاً، وأبقِ الإشراف البشري على أعمال البرمجة، لا سيما قبل استخدامه في الإنتاج.

المصادر والنطاق

يستند هذا الشرح إلى الوصف الموثّق لدورة Agent Memory من DeepLearning.AI فيما يتعلق بالذاكرة المستمرة والاسترجاع واستخراج الحقائق المنظّمة والدمج والحفظ العكسي؛ وإلى تقارير حول حلقة الوكيل البرمجي ونمو سجل المحادثة؛ وإلى إدراج إطار Mastra الموثّق لقدرات وكلاء TypeScript وأمر بدء المشروع. تدعم هذه المصادر البنية والتحذيرات الواردة هنا، لكنها لا تثبت شيفرة Bun أو SQLite أو OpenAI التفصيلية في المسودة الأصلية، أو التوافق الدقيق بين الحزم، أو ادعاءات الأمان.