ذاكرة الوكيل

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

تتضمن HeroMate ذاكرة مضمّنة حتى يتذكّر الوكيل ما قيل سابقاً — إما ضمن محادثة واحدة أو عبر كل محادثة أجراها المستخدم.

أوضاع الذاكرة

اختر الوضع في حقل Memory لعقدة الوكيل.

كيف تعمل ذاكرة الجلسة

عندما memory_mode = session:

1. تولّد واجهتك (أو تخزّن) session_id لكل محادثة.
2. في كل مرة يرسل المستخدم رسالة، تمرّر session_id نفسه.
3. يحمّل الوكيل الرسائل السابقة لتلك الجلسة ويضيف رسالة المستخدم الجديدة ويستدعي النموذج ويحفظ رد المساعد الجديد.

session_id جديد = محادثة جديدة، دون ذاكرة محمولة. يتولى خطاف useChat() في SDK هذا تلقائياً.

كيف تعمل ذاكرة المستخدم

عندما memory_mode = user:

• لا حاجة لـ session_id. يستخدم الوكيل معرّف المستخدم المصادَق من JWT.
• تُدمَج كل رسالة من ذلك المستخدم في أي مكان في تطبيقك في سجل متدحرج واحد.
• جيد لتجارب «المساعد الشخصي» حيث تريد استمرارية عبر الأيام والأجهزة.

نافذة الذاكرة

تحميل كل الرسائل إلى الأبد سيفجّر نافذة سياق النموذج وفاتورتك للرموز. تتحكم HeroMate بهذا بمقبضين:

يُطبَّق الحدان معاً — أيهما يُفعَّل أولاً يفوز. يرى الوكيل دائماً أحدث الرسائل.

أين تُخزَّن الذاكرة

تعيش الذاكرة في قاعدة بيانات مشروعك، في جدولي نظام:

• system.ai_chats — صف واحد لكل جلسة دردشة، مع id و user_id و endpoint_id وبيانات وصفية
• system.ai_messages — صف واحد لكل رسالة، مع chat_id و role و parts (تنسيق رسالة Vercel AI SDK الكامل)

تُنشأ هذه الجداول تلقائياً أول مرة يعمل وكيل بذاكرة. يمكنك الاستعلام عنها بـ execute_sql كأي جدول آخر — مفيد لبناء واجهات سجل دردشة أو لوحات إشراف.

سرد المحادثات السابقة

يعطيك SDK خطافاً لسرد جلسات المستخدم السابقة. يأخذ useChatList كائن خيارات (وليس سلسلة موضعية):

import { useChatList } from '@dypai-ai/client-sdk/react'

function ConversationsSidebar() {
  const { chats, isLoading, error, deleteChat, renameChat, refetch } =
    useChatList({ endpointId: '<endpoint_id>', limit: 50 })

  return (
    <ul>
      {chats.map(c => (
        <li key={c.id}>
          <a href={`/chat/${c.id}`}>{c.title ?? 'Untitled'}</a>
        </li>
      ))}
    </ul>
  )
}

يُرجع useChatList({ endpointId, limit, enabled }):

• chats — قائمة المحادثات
• isLoading / error — حالة التحميل
• deleteChat(chatId) — حذف محادثة
• renameChat(chatId, title) — إعادة تسمية محادثة
• refetch() — إعادة تحميل القائمة

مدمجاً مع useChat('endpoint', { id })، يعطيك هذا «الشريط الجانبي بكل محادثاتي السابقة» بأسلوب ChatGPT الكلاسيكي مجاناً. (خيار الاستئناف هو id، وليس sessionId.)

مسح الذاكرة

يريد المستخدمون أحياناً بداية جديدة. خياراتك، الأسهل أولاً:

1. حذف محادثة (موصى به): استدعِ deleteChat(chatId) من useChatList. يزيل الدردشة ورسائلها — دون كود خلفية. وصّله بزر «حذف هذه المحادثة».
2. محادثة جديدة: ابدأ دردشة جديدة بـ useChat('endpoint', { id: newId }) (أو دون id). تبقى المحادثة القديمة مخزَّنة لكنها لا تُحمَّل.
3. متقدّم (اختياري): احذف الصف مباشرة من system.ai_chats بـ SQL (يتسلسل إلى الرسائل) — مفيد للتنظيف بالجملة أو أدوات الإدارة.

الذاكرة واستدعاءات الأدوات

تُخزَّن استدعاءات الأدوات كجزء من المحادثة. عند تحميل الذاكرة، يرى النموذج:

• رسائل المستخدم
• ردود المساعد
• استدعاءات الأدوات التي أجراها المساعد
• نتائج الأدوات المُرجَعة

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

ملاحظات الخصوصية

• الذاكرة بنطاق المشروع — لا يمكن لوكلاء في مشروع رؤية محادثات في آخر.
• ذاكرة المستخدم بنطاق المستخدم — لا يمكن للمستخدمين رؤية سجل بعضهم.
• تُخزَّن بيانات الذاكرة في قاعدة بيانات مشروعك بجانب جداولك العادية. تنطبق نسخك الاحتياطية الحالية وضوابط الوصول وتدفقات حذف البيانات.
• للحذف بأسلوب GDPR، احذف الصفوف من system.ai_chats للمستخدم المعني.

الخطوات التالية