كيفية إضافة ذاكرة لوكيل الذكاء الاصطناعي: أنماط استمرارية الحالة للإنتاج

جدول المحتويات

محدَّث يونيو 2026.

TL;DR: الوكلاء عديمو الحالة — الذين ينسون كل شيء عند إنهاء Worker — مناسبون للمهام الفردية. في اللحظة التي يحتاج فيها الوكيل إلى تذكر ما حدث أمس، أو التعرف على عميل عائد، أو البناء على مخرجات سابقة، فأنت بحاجة إلى ذاكرة. هناك ثلاثة أنماط: ذاكرة العمل (السياق أثناء التشغيل، تعيش في KV طوال مدة التشغيل)، والذاكرة الحلقية (ما حدث ومتى، سجل قابل للاستعلام)، والذاكرة الدلالية (ما تعرفه، يُسترجع عبر البحث الشعاعي أو البيانات المهيكلة). اربط النمط الصحيح بالمهمة الصحيحة.

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

لماذا يستمر الوكلاء عديمو الحالة في الفشل

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

بالنسبة لمهمة تصنيف لمرة واحدة — قراءة تعليق وإعادة فئة — فإن عدم الحالة صحيح. إنه سريع ورخيص ويمكن التنبؤ به.

تظهر سطح الإخفاق في اللحظة التي تحتاج فيها إلى استمرارية:

• وكيل يواجه العملاء لا يتعرف على تاريخ العميل
• وكيل محتوى يوصي بمقالة أوصى بها الأسبوع الماضي
• وكيل إشراف يواصل تصعيد قضية محلولة
• إحاطة يومية تعرض نفس التنبيه القديم إلى أجل غير مسمى

كل هذه أعراض لنفس المشكلة: لا توجد طريقة للوكيل لنقل السياق عبر التشغيلات.

ثلاثة أنواع من الذاكرة

الإطار الذي أجده مفيداً في الإنتاج:

1. ذاكرة العمل — ما يعرفه الوكيل الآن، خلال تشغيل واحد. محفوظة في KV أو في الذاكرة طوال فترة الاستدعاء.
2. الذاكرة الحلقية — ما حدث ومتى. سجل مهيكل يقرأه الوكيل في بداية كل تشغيل لتوجيه نفسه.
3. الذاكرة الدلالية — ما يعرفه عن العالم أو العملاء أو قاعدة المعرفة. يُسترجع عبر استعلامات مهيكلة أو بحث شعاعي عند الحاجة.

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

ذاكرة العمل: السياق أثناء التشغيل

ذاكرة العمل هي الحالة التي تعيش طوال مدة تشغيل وكيل واحد. أبسط شكل هو متغيرات في نطاق الدالة. الشكل الأكثر إثارة للاهتمام هو مفتاح KV مشترك تقرأه وتكتبه المهام الفرعية ضمن نفس التشغيل.

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

// workers/social-reply.ts

async function processComment(
  comment: SocialCommentEvent,
  env: Env
): Promise<void> {
  // تحميل التاريخ الأخير لهذا العميل من KV (ذاكرة العمل)
  const historyKey = `customer:${comment.userId}:history`;
  const rawHistory = await env.AGENT_KV.get(historyKey);
  const history: ConversationTurn[] = rawHistory
    ? JSON.parse(rawHistory)
    : [];

  // بناء موجّه نظام مدرك للسياق من التاريخ
  const systemPrompt = buildSystemPrompt(history);

  const response = await anthropic.messages.create({
    model: "claude-opus-4-8",
    max_tokens: 512,
    system: systemPrompt,
    messages: [{ role: "user", content: comment.text }],
  });

  const reply =
    response.content[0].type === "text" ? response.content[0].text : "";

  // تحديث التاريخ — الاحتفاظ بآخر 10 جولات، TTL 30 يوماً
  const updatedHistory: ConversationTurn[] = [
    ...history.slice(-9),
    { role: "assistant", content: reply, timestamp: comment.timestamp },
  ];
  await env.AGENT_KV.put(historyKey, JSON.stringify(updatedHistory), {
    expirationTtl: 60 * 60 * 24 * 30,
  });

  await postReply(comment, reply, env);
}

شيئان جديران بالملاحظة. التاريخ محدود بـ 10 جولات — أدخل نافذة منزلقة، ولا تدعه ينمو بلا حدود. ومدة TTL 30 يوماً: إذا صمت عميل لمدة شهر، ينتهي التاريخ ويبدأ الوكيل من جديد. كلاهما مقصود.

الذاكرة الحلقية: ما حدث ومتى

الذاكرة الحلقية هي سجل الوكيل. سجل مهيكل للتشغيلات الماضية يقرأه الوكيل في بداية كل تشغيل جديد لتجنب التكرار.

كان وكيل الإحاطة اليومية الخاص بي يعرض نفس التنبيهات القديمة كل يوم لأن كل تشغيل لم يكن لديه وعي بما تمت الإشارة إليه بالفعل. الحل: سجل مهيكل للتنبيهات السابقة يقرأه الوكيل قبل إنشاء الإحاطة.

// workers/daily-brief.ts

interface AlertLogEntry {
  id: string;
  surfacedAt: string; // طابع زمني ISO
  resolvedAt?: string;
  summary: string;
}

async function buildDailyBrief(env: Env): Promise<void> {
  const [emails, calendar, tasks] = await Promise.all([
    fetchOvernightEmails(env),
    fetchTodayCalendar(env),
    fetchTopTasks(env),
  ]);

  // تحميل الذاكرة الحلقية: ما تمت الإشارة إليه بالفعل
  const rawLog = await env.AGENT_KV.get("brief:alert-log");
  const alertLog: AlertLogEntry[] = rawLog ? JSON.parse(rawLog) : [];

  // التصفية للتنبيهات الحديثة غير المحلولة فقط
  const sevenDaysAgo = new Date(
    Date.now() - 7 * 24 * 60 * 60 * 1000
  ).toISOString();
  const recentAlerts = alertLog.filter(
    (e) => e.surfacedAt > sevenDaysAgo && !e.resolvedAt
  );

  const brief = await synthesizeBrief(
    { emails, calendar, tasks, recentAlerts },
    env
  );

  // تحديث السجل بالتنبيهات الجديدة التي تمت الإشارة إليها في هذا التشغيل
  const newAlerts: AlertLogEntry[] = brief.newAlerts.map((a) => ({
    id: crypto.randomUUID(),
    surfacedAt: new Date().toISOString(),
    summary: a,
  }));

  const updatedLog = [...alertLog, ...newAlerts].slice(-100); // الاحتفاظ بآخر 100
  await env.AGENT_KV.put("brief:alert-log", JSON.stringify(updatedLog));

  await writeToWorkspace(brief.content, env);
}

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

هذا النمط قابل للتعميم: أي وكيل ينتج قرارات أو علامات أو توصيات يستفيد من السجل. السجل رخيص (بضعة كيلوبايت في KV)، والعائد مرتفع (لا مزيد من المخرجات المكررة).

الذاكرة الدلالية: ما تعرفه

الذاكرة الدلالية هي قاعدة المعرفة. تجيب على “ماذا تعرف عن X؟” وقت الاستعلام، بدلاً من حشر كل شيء في موجّه النظام مسبقاً.

أبسط شكل هو بحث مهيكل في KV أو قاعدة بيانات. يبحث وكيل حجز Pickleland الخاص بي عن ملفات تعريف العملاء وتفضيلات الملعب قبل صياغة التأكيدات:

// workers/booking-agent.ts

interface CustomerProfile {
  userId: string;
  preferredCourts: string[];
  experienceLevel: "beginner" | "intermediate" | "advanced";
  specialNotes: string;
}

async function draftConfirmation(
  booking: BookingEvent,
  env: Env
): Promise<string> {
  // الحصول على ملف تعريف العميل من KV (الذاكرة الدلالية — معرفة واقعية)
  const profileKey = `customer:${booking.userId}:profile`;
  const rawProfile = await env.AGENT_KV.get(profileKey);
  const profile: CustomerProfile | null = rawProfile
    ? JSON.parse(rawProfile)
    : null;

  const systemPrompt = profile
    ? `تصيغ تأكيدات حجز مخصصة. يفضل هذا العميل ${profile.preferredCourts.join("، ")} وهو لاعب من مستوى ${profile.experienceLevel}. ${profile.specialNotes}`
    : "تصيغ تأكيدات حجز لمنشأة بيكلبول.";

  const response = await anthropic.messages.create({
    model: "claude-haiku-4-5-20251001",
    max_tokens: 256,
    system: systemPrompt,
    messages: [
      {
        role: "user",
        content: `صِغ تأكيداً لـ: ${JSON.stringify(booking)}`,
      },
    ],
  });

  return response.content[0].type === "text" ? response.content[0].text : "";
}

لقواعد المعرفة الأكبر — وثائق المنتج، قاعدة معرفة الدعم، أي شيء كبير جداً بحيث لا يتناسب مع نافذة السياق — تحتاج إلى مخزن شعاعي. سير العمل هو: تضمين الاستعلام، استرداد أكثر k أجزاء ذات صلة، حقنها في السياق. Cloudflare Vectorize يتعامل مع هذا بشكل أصلي إذا كنت تعمل على Workers بالفعل. للفهارس الأكبر استخدمت Upstash Vector. الاختيار يعتمد على الحجم وليس المبدأ.

الملاحظة الصريحة حول الذاكرة الدلالية: إنها الأصعب في البناء والصيانة من بين الثلاثة. يجب أن يبقى الفهرس محدثاً. تتفاوت جودة الاسترداد. ابدأ بالبحث المهيكل — KV، جدول في D1 — ولا تلجأ إلى البحث الشعاعي إلا عندما لا يستطيع النهج المهيكل تغطية سطح المعرفة الذي تحتاجه.

إطار قرار الذاكرة

قبل إضافة أي ذاكرة لوكيل، أجب على ثلاثة أسئلة:

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

2. هل يكرر الوكيل نفسه أو يتصرف بشكل أعمى تجاه تاريخه الخاص؟ إذا كان الجواب نعم، أضف أولاً الذاكرة الحلقية. إنها الإصلاح الأقل جهداً ويغطي معظم شكاوى “الوكيل يواصل فعل X”.

3. هل يعامل الوكيل كل مستخدم أو كيان بشكل متطابق عندما لا ينبغي له ذلك؟ إذا كان الجواب نعم، أضف ذاكرة العمل (تاريخ العميل، ملف تعريف المستخدم) أو الذاكرة الدلالية (نظام بحث أو استرداد).

الخطأ الذي أراه في أغلب الأحيان: يضيف شخص ما قاعدة معرفة ضخمة (ذاكرة دلالية) لوكيل كان يفشل في الحقيقة لأنه لم يكن لديه ذاكرة حلقية — لا سجل بما فعله بالفعل. التعقيد لا يتطابق مع المشكلة.

ما أستخدمه فعلاً في الإنتاج

عبر أكثر من 30 وكيلاً:

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

Cloudflare KV هو مخزني الافتراضي لذاكرة العمل والذاكرة الحلقية. إنه سريع ورخيص ومتكامل بشكل أصلي في Workers — لا عميل إضافي، لا بيانات اعتماد منفصلة. القيد: KV ذو اتساق نهائي وليس مناسباً جيداً للكتابات عالية التردد. للوكلاء الذين يكتبون الحالة عدة مرات في الثانية، ألجأ إلى Durable Objects أو قاعدة بيانات D1 بدلاً من ذلك.

للذاكرة الدلالية المدعومة بالشعاعيات، أستخدم Cloudflare Vectorize للفهارس الصغيرة إلى المتوسطة (أقل من ~100 ألف شعاع) وUpstash Vector لأي شيء أكبر. كلاهما يملك عملاء JavaScript من الدرجة الأولى.

خلاصة المشغّل

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

ذات صلة: مجموعة الوكلاء التي أستخدمها لتشغيل أكثر من 30 وكيلاً في الإنتاج · الوكلاء المُحفَّزة بالأحداث مقابل المجدولة · كيف أقيس ما إذا كان وكيل الذكاء الاصطناعي يعمل فعلاً

تحتاج مساعدة في تصميم ذاكرة الوكلاء لحالتك الاستخدامية؟ تواصل معي — أصمم أنظمة وكلاء الإنتاج لفرق المشغّلين.