FAVA Trails: ذاكرة مشتركة أصيلة في Git لوكلاء الذكاء الاصطناعي (MCP)

لمن هذه الأداة

FAVA Trails (Federated Agents Versioned Audit Trail) هو نظام ذاكرة أصيل في Git يُعرض لوكلاء الذكاء الاصطناعي عبر MCP: الأفكار والقرارات والملاحظات التي ينتجها الوكلاء تُكتب كملفات Markdown مع frontmatter بصيغة YAML داخل مستودع Git للبيانات تتحكم به أنت، لا في صندوق أسود مستضاف على خوادم الآخرين. يفصل النظام بين «المسودات» و«الملاحظات المرئية لجميع الوكلاء» في مستويين مع بوابة ترقية بينهما؛ الوكلاء عادةً يرون أدوات الذاكرة نفسها فقط ولا يتعاملون مع أوامر إدارة الإصدارات — التفاصيل متروكة للمحرك داخل المستودع، ويبقى التاريخ كله قابلًا للمراجعة في سجل الالتزامات.

• مناسب لـ: الفرق أو الأفراد الذين يريدون عدة وكلاء يتشاركون ذاكرة عمل تتراكم — مثلًا حفظ خلاصات التحقيق الهندسي أو سياق القرارات بين الجلسات كملاحظات قابلة لإعادة الاستخدام؛ المستخدمون الذين يريدون ذاكرة مُدارة بالإصدارات وقابلة للتتبع يمكن فتح ملفاتها مباشرةً في أي وقت؛ من يدير أصوله بـ Git أصلًا ولا يمانع من صيانة مستودع بيانات إضافي.
• المتطلبات المسبقة: أن يعمل pip على جهازك؛ تحديد مسار مستودع البيانات FAVA_TRAILS_DATA_REPO في الإعدادات؛ لترقية مسودة إلى ملاحظة مرئية لجميع الوكلاء يجب إعداد مفتاح OpenRouter API.
• يحتاج تفكيرًا: من لا يريد صيانة مستودع بيانات أو التقدم بطلب مفتاح OpenRouter فليتوخ الحذر — فالمسار الجوهري لذاكرة مشتركة بين الوكلاء يعتمد على الاثنين معًا.
• غير معروف: الأدلة لا توضح أي عملاء MCP مدعومون تحديدًا، ولا متطلبات نظام التشغيل وإصدارات Python، ولا ما إذا كان محرك التخزين Jujutsu (JJ) يحتاج تثبيتًا منفصلًا.

أول تجربة في 3 دقائق

المسار الرئيسي الموصى به واحد فقط: تثبيت المحرك من PyPI ثم تسجيله في إعدادات خوادم عميل MCP. شرطان مسبقان: حدد أولًا موقع مستودع البيانات لأن FAVA_TRAILS_DATA_REPO في الإعدادات يشير إليه؛ وللوصول إلى خطوة الترقية تحتاج مفتاح OpenRouter API.

الخطوة الأولى، تثبيت خادم MCP عديم الحالة هذا بترخيص Apache-2.0:

pip install fava-trails

الخطوة الثانية، إضافة مقطع التسجيل الرسمي إلى إعدادات العميل واستبدال مسار المستودع بموقعك الفعلي:

"fava-trails": {
  "command": "fava-trails-server",
  "env": {
    "FAVA_TRAILS_DATA_REPO": "/path/to/fava-trails-data",
    "OPENROUTER_API_KEY": "sk-or-v1-..."
  }
}

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

save_thought(trail_name="myorg/eng/my-project", content="My finding about X", source_type="observation")

إشارة النجاح: ظهور المسودة في دليل drafts/ داخل مستودع البيانات. ميّز طبيعة العملية: هذه الخطوة كتابة محلية يقع ملفها في مستودعك أنت، وليست استعلامًا للقراءة فقط؛ لا يوجد توثيق رسمي لحذف المسودة أو التراجع عنها، فاكتب محتوى غير ضار في التجربة الأولى. على جانب المحرك يعمل Jujutsu (JJ) محرك تخزين بجانب Git في وضع colocate؛ ويبقى المستودع مستودع Git قياسيًا، ولا تحتاج في هذه الخطوة إلى لمس أي أمر لإدارة الإصدارات. وانتبه أيضًا لحدود مفتاح OpenRouter API: فهو حاضر أصلًا في قالب الإعدادات الرسمي هذا، ويضيف الجدول الرسمي أنه مطلوب لـ propose_truth ويغذي مراجعات LLM لبوابة Trust Gate عبر OpenRouter؛ التجربة الأولى يمكن أن تتوقف عند خطوة المسودة دون حاجة للترقية في الطريق.

حالات الاستخدام

الحالة الأولى: تحويل خلاصة تحقيق إلى ذاكرة مشروع. السيناريو: أنهى الوكيل للتو تحقيقًا وخلاصته تستحق إعادة الاستخدام في جلسات لاحقة. الطريقة: استدعاء save_thought بالوسائط trail_name وcontent وsource_type — مثال الاستدعاء الرسمي أعلاه يصلح كما هو. النتيجة المتوقعة: ينشأ ملف مسودة في drafts/، ويقع المحتوى في مستودعك وحده، ولا يراه الوكلاء الآخرون بعد، فلا يؤثر في أحد؛ والمسودة ملف عادي يمكن فتحه مباشرة في المستودع.

الحالة الثانية: ترقية مسودة موثوقة إلى ملاحظة مشتركة ثم التحقق بالبحث. السيناريو: تم التحقق من ملاحظة وتريد أن يجدها كل الوكلاء لاحقًا. الطريقة: تأكد أولًا من صلاحية مفتاح OpenRouter API، ثم استدعِ propose_truth(trail_name="myorg/eng/my-project", thought_id=thought_id) لترقية المسودة إلى observations/، وابحث بعدها بـ recall(trail_name="myorg/eng/my-project", query="X"). النتيجة المتوقعة: يجد recall الفكرة المرقاة، ويعثر الوكلاء الآخرون المرتبطون بمستودع البيانات نفسه عليها بالاستعلام ذاته. نقطة التحقق: نتيجة الترقية مرئية لجميع الوكلاء ولا يوجد توثيق رسمي للتراجع، فتأكد قبل التنفيذ من أن المحتوى مناسب للمشاركة؛ ودفع التغيير إلى مستودع بعيد فعل مستقل آخر يتطلب استدعاء أداة sync أو jj git push على حدة.

حدود الاستخدام

• طبيعة القراءة والكتابة: save_thought ينشئ مسودة في مستودع البيانات، وpropose_truth يرقّيها إلى observations/ المرئية لجميع الوكلاء — كلاهما كتابة؛ وrecall يبحث عن الأفكار المرقاة. تحدث الكتابة داخل مستودعك أنت، وتقع الترقية أولًا محليًا؛ والدفع إلى مستودع بعيد يجب أن يتم على حدة عبر أداة MCP sync أو jj git push، ومزامنة أو عدم مزامنة قرارك. لا يوجد مسار رسمي للتراجع أو الحذف — لا تتعامل مع الكتابة كعملية يمكن التراجع عنها في أي وقت.
• بيانات الاعتماد والإعدادات: FAVA_TRAILS_DATA_REPO يحدد موقع مستودع البيانات، وOPENROUTER_API_KEY يخدم مراجعة LLM عند الترقية؛ وكلاهما مذكور في قسم env من قالب الإعدادات الرسمي، والتوثيق الرسمي ينص صراحةً على أن الثاني مطلوب لـ propose_truth. أما هل يعمل save_thought وrecall بدون هذا المفتاح فلا تقوله الأدلة.
• بيئة التشغيل ومكان البيانات: محرك التخزين هو Jujutsu (JJ) بجانب Git في وضع colocate؛ ويبقى المستودع مستودع Git قياسيًا ويرى GitHub وCI/CD التزامات عادية. كل المحتوى يُخزن كملفات Markdown مع frontmatter بصيغة YAML في المستودع الذي تتحكم به.
• بنود غير مؤكدة: حصص السعة وحدود حجم المستودعات المتعددة وتفاصيل الخصوصية ومقر البيانات لا تذكرها الأدلة؛ ومعايير حكم Trust Gate ومعالجة الفشل غير موصوفة كذلك، وكذلك ما إذا كان jj يحتاج تثبيتًا منفصلًا وأي العملاء وإصدارات Python مدعومة. لا تفسّر «لم أر توثيقًا» على أنه «لا خطر» — قيّم ما تكتبه بافتراض أنه سيبقى طويلًا في مستودعك.