createAgent({ memory }) بما يلي:
- تسترجع في بداية كل run (
send()،stream()، كل turn في session): في أول model call في الـ run، توضع أحدث العناصر في الـ system prompt داخل بلوك<memory name="...">. يبقى البلوك حتى نهاية الـ run. لا يحتفظ به الـ transcript المخزَّن الخاص بالـ session (session.messages)، لكن الـ transcript الخاص بالـ run نفسه يحتفظ به:result.messagesمنsend()/stream()، والـ checkpoints الخاصة بالـ run (التي يسترجع منها الـ run الذي يكمل بعد approval)، تحتوي على رسالة الـ system مع العناصر المسترجَعة. لا تسجّلها في السجل (log) ولا تصدّرها على أنها خالية من الذاكرة. - تعطي الـ model أداة
remember_<name>(input{ text }، أو الـitemSchemaالخاص بك) يخزّن بها عنصرًا جديدًا، وأداةrecall_<name>(input{ query?, limit? }، والحد الأقصى لـlimitهو 100) يبحث بها في الـ slot، الأحدث أولًا. يحتوي كل عنصر مُرجَع علىidوtextوcreatedAt، إضافةً إلىscoreمن الـ vector provider، وفي الـ slot التي لا تحتوي علىitemSchemaبقية الـmetadataالخاصة به. يخبر وصفremember_<name>الـ model بمدة بقاء العناصر: في المحادثات القادمة ('global')، أو لاحقًا في المحادثة نفسها ('session')، أو في المحادثات القادمة مع المستخدم نفسه أو الـ key نفسه (دالة scope). وتُطبَّق escape على وسوم الذاكرة داخل نص العنصر (<memory،</memory) لكي لا يستطيع عنصر فتح بلوك أو إغلاقه. - مع
expose: { forget: true }، تعطيه أيضًا أداةforget_<name>(input{ id }) يحذف بها عنصرًا خاطئًا أو قديمًا. راجع تصحيح الذاكرة.
الذاكرة في الكود
البادئةvendor/ في اسم الـ model هي التي تحدد الـ provider؛ مع OpenRouter استخدم openrouter/<vendor>/<model> (مثال: openrouter/openai/gpt-4o-mini).
Scopes
يقرأ الـ run ويكتب عناصر الـ scope key الخاص به. داخل الـ provider، تُخزَّن العناصر تحت<slot name>#<scope key> (notes#global، prefs#session:s1)، لذا يحتفظ slotان لهما الـ scope نفسه بقائمتين منفصلتين — يمكنك مشاركة provider واحد (وSqliteStore واحد) بين الـ slots بأمان. تُرجع memoryKey(slot, ctx) هذا المفتاح لسياق run معيّن (أو undefined عندما يكون الـ slot معطّلًا)؛ استخدمها عندما تملأ عناصر slot أو تقرؤها أو تنظّفها من الكود.
ترى دالة الـ scope قيمة
sessionId الخاصة بالـ run والـ metadata التي مُرِّرت إلى send() / stream()، لذا يمكنك الاحتفاظ بذاكرة واحدة لكل مستخدم عبر كل الـ sessions الخاصة به:
lousho dev وlousho chat تمرير metadata إلى الـ run، لذا تكون دالة الـ scope التي تقرأ metadata.userId معطّلة هناك. لتجربة ذاكرة لكل مستخدم في الـ terminal، اشتق الـ scope من sessionId أيضًا (مثلًا `user:${metadata?.userId ?? sessionId}`، مع lousho chat --session <id> بوصفه “المستخدم”)، أو جرّبها من سكربت باستخدام send(..., { metadata }).
عندما لا يكون للـ run أي scope key (slot من نوع 'session' في send() بدون sessionId، أو دالة scope تُرجع undefined أو null)، يكون الـ slot معطّلًا لذلك الـ run: لا يُسترجع أي شيء ولا تُعرض الـ tools الخاصة به.
يجب أن تُرجع دالة الـ scope قيمة string غير فارغة (أو undefined / null). أي قيمة أخرى تُفشل الـ run بالخطأ LOUSHO_MEMORY_INVALID مع اسم الـ slot، لأنها لولا ذلك ستضع عناصر كل المستخدمين تحت key واحد مشترك: رقم أو object، أو string فارغ، أو key مبني من قيمة ناقصة مثل user:undefined أو user:null أو user:[object Object]. ودالة الـ scope التي ترمي خطأً تُفشل الـ run بالكود نفسه. وترفض defineMemory() أي scope ليس 'global' أو 'session' أو دالة.
ترى دالة الـ scope أيضًا principal، وهو المستخدم الذي تحقّق منه auth المسار، وبناء الـ key عليه أكثر أمانًا من metadata لأن المستخدم يستطيع إرسال أي metadata: راجع قراءة الـ principal في الـ run.
عناصر من قبل مفاتيح اسم الـ slot
حتى1.0.0-alpha.19، كانت العناصر تُخزَّن تحت الـ scope key وحده (global، session:s1، user:u-42)، ويتشاركها كل slot له الـ scope نفسه. لا تزال هذه العناصر موجودة في الـ provider لكن لا يوجد slot يقرؤها. تنسخها migrateMemoryKeys(slot) إلى المفتاح الحالي الخاص بالـ slot، الأقدم أولًا. ومن الآمن تشغيلها مع كل بداية: يزيل add() التكرار حسب النص، فلا يُنسخ أي شيء مرتين. تحتفظ كل نسخة بـ text وmetadata وتأخذ id وcreatedAt جديدين.
'session' أو دالة scope، مرّر السياقات التي تريد نقلها ({ sessionId }، { metadata }، { principal })؛ ويُتخطّى السياق الذي لا يعطيه الـ slot أي key. تبقى العناصر القديمة ما لم تمرّر removeLegacy: true. أبقِها طالما يوجد slot آخر بالـ scope نفسه لم يُنقل بعد: فقد كانت مشتركة. وتسرد النتيجة كل مفتاح قديم كان يحتوي على عناصر، ومفتاحه الجديد، والعدد.
خيارات الإعداد
تُرجعdefineMemory(options) قيمة MemorySlot:
expose: { remember: false } تكون للقراءة فقط (read-only) بالنسبة إلى الـ model: تملؤها أنت من الكود باستخدام provider.add(memoryKey(slot)!, { text }). ولـ scope من نوع 'session' أو دالة، مرّر سياق الـ run: memoryKey(slot, { sessionId, metadata }). بدونه تُرجع memoryKey() القيمة undefined، وترفض الـ providers المدمجة الـ scope key الناقص أو الفارغ بالخطأ LOUSHO_MEMORY_INVALID بدلًا من تخزين العناصر تحت المفتاح undefined.
تصحيح الذاكرة
افتراضيًا تنمو الذاكرة فقط: عندما تتذكّر حقيقة تغيّرت يُضاف عنصر آخر، ويُسترجع الاثنان. يوجد خياران يجعلان الـ slot يستبدل العناصر أو يزيلها.itemKey يجعل الحالة المنظّمة تُجري upsert. مع itemSchema، سمِّ الحقل (أو الحقول) الذي يعرّف العنصر. عندما يستلم remember_<name> عنصرًا تساوي حقول مفتاحه حقول عنصر مخزَّن، يستبدل ذلك العنصر بدلًا من إضافة نسخة أخرى. يحتفظ العنصر بالـ id الخاص به، ويصبح الأحدث، ويُرجع remember_<name> القيمة { remembered: id, replaced: true }:
expose: { forget: true } يضيف forget_<name>({ id })، الذي يحذف عنصرًا، وبعد ذلك يُظهر كل عنصر في بلوك <memory> المسترجَع الـ id الخاص به (- The user wants answers in French. (id: 3f…))، لذا يستطيع الـ model أن ينسى حقيقة لم تعد صحيحة ويتذكّر الجديدة. يُرجع الـ id المجهول { forgotten: null, reason } ولا يغيّر أي شيء. يحمل forget_<name> الـ annotations readOnlyHint: false, destructiveHint: true، لذا لا يُعامَل كـ read-only (مثلًا في plan mode).
يستخدم الاستبدال upsert(scopeKey, { id, text, metadata }) الخاصة بالـ provider، وهي موجودة في كل provider مدمج. أما الـ provider المخصّص الذي لا يحتوي على upsert فيستخدم بدلًا منها remove() ثم add(): يأخذ العنصر id جديدًا، والاستدعاءان ليسا atomic.
عندما يفشل الاسترجاع
الاسترجاع في بداية الـ run لا يُفشل الـ run. إذا رمى الـ provider خطأً (ملف ذاكرة تالف، أو انقطاع في قاعدة البيانات أو الـ KV)، يكمل الـ run بدون بلوك<memory> الخاص بذلك الـ slot، ويذكر console.warn اسم الـ slot (مرة واحدة لكل slot في كل process). واستدعاء recall_<name> الذي يفشل يُرجع الخطأ إلى الـ model بوصفه tool error.
Providers
تحتفظ الـ providers الثلاثة الأولى بحد أقصى
maxItems عنصرًا لكل scope key (الافتراضي 1000؛ وعند تجاوزه يُحذف الأقدم)، وتطابق الـ query بالكلمات المفتاحية: يطابق العنصر إذا شارك الـ query كلمة كاملة، بدون تمييز بين الأحرف الكبيرة والصغيرة ومع تجاهل s الجمع (cat تجد “has two cats” لكنها لا تجد “education”). لا تُحتسب إلا كلمات الـ query التي يبلغ طولها 3 أحرف أو أكثر، ما لم تخلُ منها الـ query ("AI"). تأتي العناصر التي تطابق عددًا أكبر من كلمات الـ query أولًا، ثم الأحدث. والـ query التي لا تشارك أي كلمة مع أي عنصر لا تُرجع شيئًا. المطابقة بالكلمات المفتاحية لا تعرف المترادفات: إذا أردت الاسترجاع بالمعنى، فاستخدم vector provider.
يزيل كل provider مدمج التكرار حسب text: إضافة عنصر نصّه مخزَّن من قبل تُرجع العنصر المخزَّن بدلًا من نسخة مكرّرة (لذا يحتفظ الـ agent الذي يتذكّر الحقيقة نفسها مرتين بنسخة واحدة).
أكثر من كاتب
تحتفظ استدعاءاتadd() / remove() المتزامنة على provider واحد بكل العناصر. أما بين أكثر من provider فيعتمد الأمر على التخزين:
fileMemory: أكثر من provider على الـdirنفسه، في process واحد أو أكثر (processان للـ agent، أو worker وCLI)، تحتفظ بكل العناصر. يمسك كل تغيير ملف قفل،<key file>.lock، أثناء قراءة ملف المفتاح وإعادة كتابته؛ والقفل الذي تركه process انهار يُسحب منه بعد 30 ثانية، والقفل المحجوز لأكثر من 10 ثوانٍ يُفشل الاستدعاء بالخطأLOUSHO_STORAGE_FAILED. وتُعاد محاولة أخطاء Windows المؤقتةEPERM/EACCES/EBUSYعند القراءة والاستبدال. أنظمة الملفات الشبكية التي لا تدعم الإنشاء الحصري الـ atomic لا تحصل على هذا الضمان.sqliteMemory: كل تغيير هو write transaction واحدة، لذا تحتفظ عدة providers وprocesses على قاعدة البيانات نفسها بكل العناصر.kvMemoryوsqliteVectorMemoryوالـ providers الخاصة بك: التغييرات مرتّبة داخل object provider واحد فقط. شارك object provider واحدًا بين الـ agents في الـ process نفسه؛ فقد يُضيّع processان يكتبان الـ scope key نفسه في الوقت نفسه عنصرًا (الكتابة الأخيرة هي التي تبقى).
SQLite
مرّر الـSqliteStore نفسه إلى الـ agent وإلى الـ provider، لكي تتشارك الـ sessions والـ checkpoints والذاكرة ملف قاعدة بيانات واحدًا. يحصل الملف الموجود على الجدول عندما يُفتح. أبقِ الـ store مفتوحًا طالما يعمل الـ agent. وإذا أردت الاسترجاع بالمعنى بدلًا من الكلمات المفتاحية، فاستخدم sqliteVectorMemory(): راجع Semantic recall.
MemoryProvider:
upsert(scopeKey, { id?, text, metadata? }) اختيارية. أضفها لكي تستبدل العنصر في مكانه (الـ id نفسه، وcreatedAt جديد، والأحدث أولًا) لـ slots الـ itemKey؛ وبدونها يستبدل الـ slot باستخدام remove() ثم add().
اختبار الذاكرة
معmockModel، تحقّق من الـ system prompt الخاص بأول request، وشغّل الـ tools باستخدام tool calls مكتوبة في السكربت:
القيود
- ذاكرة الـ agent خاصة به: لا تُشارَك الـ slots الخاصة بالـ lead مع الـ sub-agents التابعة له، ولا تُشارَك الـ slots الخاصة بالـ sub-agent مع الـ lead. الـ sub-agent الذي يحتوي على
memoryيحصل على الاسترجاع وtools الذاكرة الخاصة به عندما تشغّله أداةtaskالخاصة بالـ lead، كما في الـ runs التي يشغّلها وحده، وتُؤخذ الـ scope keys الخاصة به من run الـ lead (الـsessionIdوالـmetadataوالـprincipalالخاصة به)، لذا يتبع الـ slot من نوع'session'في الـ sub-agent session الـ lead. ويحتفظ هدف الـ handoff بذاكرة الـ lead (البلوكات المسترجَعة والـ tools، تحت الـ scope keys نفسها)؛ ولا تُستخدم الـ slots الموجودة فيmemoryالخاصة بالهدف نفسه. وعندما يكملagent.approvals.resolve()run بعد توقف بانتظار approval، يبقى البلوك المسترجَع في الـ prompt لكن tools الذاكرة لا تُعرض لبقية ذلك الـ run. - مجلد
memory/في الـ agent directory جزء من الـ agent: راجع Agent directories.
Semantic recall
لا تجد الـ providers القائمة على الكلمات المفتاحية المذكورة أعلاه عنصرًا إلا إذا شارك الـ query كلمة. أما الـ vector provider فيجده بالمعنى: يحوّل كل عنصر وكل query إلى vector باستخدام embedding model، ويرتّب العناصر حسب cosine similarity — فالسؤال “what does the user like to eat?” يجد “Sam is vegetarian”. يحوّل الـ embedder (EmbeddingProvider) النصوص إلى vectors. وتغلّف aiSdkEmbedder(model) أي embedding model في AI SDK، عن طريق embedMany من حزمة ai المثبّتة (4 أو 6 أو 7؛ ابنِ الـ model بحزمة الـ provider التي تلائم الـ major version الخاصة بـ ai لديك، وهي القاعدة نفسها المتبعة مع نماذج اللغة). ولا تضيف dependency: فـ ai أصلًا peer dependency، وحزمة الـ provider من اختيارك.
- يحتفظ
inMemoryVectorMemory({ embedder, maxItems?, minScore? })بالعناصر في هذه العملية. - يحتفظ بها
sqliteVectorMemory(store, { embedder, maxItems?, minScore? })(منlousho/sqlite) في ملف SQLite الخاص بالـ agent، في جدولmemory_vectorsيُضاف إلى الملف الموجود عندما يُفتح. وتبقى الـ vectors بعد إعادة التشغيل.
list() عليها embed، وتعطي عناصر ذلك الـ scope key درجات، وتستبعد ما هو أقل من minScore (cosine similarity، الافتراضي 0.2)، وترتّب حسب الدرجة (الأحدث أولًا عند التعادل) وتُرجع limit منها. يحمل كل عنصر مُرجَع درجته في metadata.score. وبدون query، أو مع query فارغة، تسرد الأحدث أولًا مثل أي provider. عندها يصبح وصف tool الـ recall_<name> هو “Search the “<name>” memory by meaning, most relevant first.”
إذا أردت الاسترجاع بالمعنى في بداية الـ run، فاضبط recall: { query: 'last-input' } على الـ slot: تصبح آخر رسالة مستخدم في الـ run هي الـ query، لذا يحتوي بلوك <memory> على العناصر الأقرب إليها بدلًا من الأحدث. وبدونها، يحتوي البلوك على أحدث maxItems عنصرًا، ولا يحدث الترتيب إلا عن طريق tool الـ recall_<name>.
لا تُقارَن العناصر إلا داخل الـ scope key الخاص بها، وفقط إذا كان الـ embedder نفسه (الـ id الخاص به) هو الذي أنشأها. يُخزَّن الـ id مع كل vector: بعد أن تغيّر الـ model أو الـ id، تُتخطّى العناصر القديمة عند الترتيب (لكنها تظل تظهر في السرد بدون query) إلى أن تستدعي await provider.reindex()، الذي يعيد إجراء الـ embed لها على دفعات ويُرجع عدد ما غيّره.
وتعالج reindex(providerKey) مفتاحًا واحدًا فقط — لمفتاح slot، مرّر memoryKey(slot, ctx).
hashEmbedder() من lousho/testing هو embedder حتمي يعمل offline للاختبارات: bag من جذوع الكلمات بعد الـ hash، لذا تظهر النصوص التي تتشارك كلمات قريبة من بعضها. وهو ليس نموذجًا دلاليًا ولا يعرف أن “vegetarian” و”eat” مرتبطتان.
- يُجري كل
addاستدعاء embedding واحدًا وكذلك كل query، لذا تكلّف كتابات الذاكرة والاسترجاع model calls وتضيف latency. استدعاء الـ embedding الفاشل لا يخزّن أي شيء؛ وتُبلغ tool الـremember_<name>الـ model بالخطأ. - التقييم brute force في JavaScript على عناصر scope key واحد، بدون vector index. انتبه إلى
maxItems(الافتراضي 5000 لكل scope key؛ أي عنصر زائد يحذف الأقدم): آلاف العناصر لكل key أمر مقبول، أما مئات الآلاف فلا. - لا تدعم
fileMemory()وsqliteMemory()وstore الـ Cloudflare KV الـ vectors. اكتبMemoryProviderخاصًا بك لقاعدة بيانات vectors.