Skip to content

README.ar.md

Latest commit

 

History

History
550 lines (394 loc) · 28.8 KB

README.ar.md

File metadata and controls

550 lines (394 loc) · 28.8 KB
شعار simplemem

ذاكرة مدى الحياة الفعّالة لوكلاء نماذج اللغة الكبيرة — النصوص والوسائط المتعددة

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

يعمل مع أي منصة ذكاء اصطناعي تدعم MCP (ذاكرة نصية) أو تكامل Python (وسائط متعددة كاملة)

Claude Desktop
Claude Desktop 		Cursor
Cursor 		LM Studio
LM Studio 		Cherry Studio
Cherry Studio 		PyPI
حزمة PyPI 		+ أي عميل
MCP

🔥 الأخبار

  • [05/21/2026] 📦 حزمة simplemem الموحّدة — استيراد واحد، توجيه تلقائي! تعيش الآن SimpleMem وOmni-SimpleMem وEvolveMem في حزمة واحدة. from simplemem import SimpleMem يختار تلقائيًا الواجهة الخلفية النصية أو متعددة الوسائط بناءً على أول استدعاء تجريه، وsimplemem.optimize(...) يستغل حلقة التطوّر الذاتي في EvolveMem. ثبّتها في خطوة واحدة بـ pip install -e ..
  • [05/14/2026] 🧬 EvolveMem (v3.0) — ذاكرة تتطور ذاتيًا عبر AutoResearch! تتطور البنية التحتية للاسترجاع ذاتيًا الآن من خلال تشخيص دائري مدفوع بنماذج اللغة الكبيرة. على LoCoMo، تتفوق EvolveMem على أقوى خط أساس بفارق +25.7% نسبي؛ وعلى MemBench بفارق +18.9% نسبي. يكتشف النظام أبعادًا جديدة للاسترجاع لم تكن موجودة في التصميم الأصلي. عرض EvolveMem →
  • [04/02/2026] 🧠 Omni-SimpleMem (v2.0) — الذاكرة متعددة الوسائط هنا! تدعم SimpleMem الآن ذاكرة النصوص والصور والصوت والفيديو. محققةً أفضل أداء جديد على LoCoMo (F1=0.613, +47%) وMem-Gallery (F1=0.810, +51%) مقارنةً بأفضل نتيجة سابقة. عرض Omni-SimpleMem →
  • [02/09/2026] 🚀 ذاكرة عبر الجلسات — تتفوق على Claude-Mem بنسبة 64%! عرض توثيق الذاكرة عبر الجلسات →
  • [01/20/2026] 📦 SimpleMem متوفرة الآن على PyPI! ثبّتها عبر pip install simplemem. عرض دليل استخدام الحزمة →
  • [01/14/2026] 🎉 خادم SimpleMem MCP أصبح مباشرًا! مستضاف سحابيًا على mcp.simplemem.cloud. عرض توثيق MCP →
  • [01/05/2026] نُشرت ورقة SimpleMem على arXiv!

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

🚀 البداية السريعة

🧠 فهم سير العمل الأساسي

على مستوى رفيع، تعمل SimpleMem كنظام ذاكرة طويلة الأمد للوكلاء المبنية على نماذج اللغة الكبيرة. يتكون سير العمل من ثلاث خطوات بسيطة:

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

يتيح هذا التصميم لوكلاء نماذج اللغة الكبيرة الحفاظ على السياق واستدعاء المعلومات السابقة بكفاءة وتجنّب المعالجة المتكررة للتاريخ الزائد.

🎓 الاستخدام الأساسي

تُشحن SimpleMem كحزمة simplemem واحدة. الوضع الافتراضي mode="auto" يكتشف تلقائيًا الواجهة الخلفية التي يجب استخدامها بناءً على ما تستدعيه — دون الحاجة إلى أي إعداد يدوي:

from simplemem import SimpleMem

mem = SimpleMem()  # mode="auto" — backend chosen by first call

أول استدعاء تجريه يحدد الواجهة الخلفية:

أول استدعاء الواجهة الخلفية المختارة السبب
add_dialogue() نصية (SimpleMem) واجهة برمجية قائمة على الحوار ← وضع النص
add_text() / add_image() / add_audio() / add_video() شاملة (Omni-SimpleMem) واجهة برمجية متعددة الوسائط ← الوضع الشامل

📝 تلقائي ← نصي (إدخال نصي خالص)

from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_dialogue() → text backend auto-selected
mem.add_dialogue(
    "Alice",
    "Bob, let's meet at Starbucks tomorrow at 2pm",
    "2025-11-15T14:30:00",
)
mem.add_dialogue(
    "Bob",
    "Sure, I'll bring the market analysis report",
    "2025-11-15T14:31:00",
)
mem.finalize()

answer = mem.ask("When and where will Alice and Bob meet?")
# → "16 November 2025 at 2:00 PM at Starbucks"

🧠 تلقائي ← شامل (إدخال متعدد الوسائط)

from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_image() → omni backend auto-selected
mem.add_text(
    "User loves hiking in the Rocky Mountains.",
    tags=["session_id:D1"],
)
mem.add_image("photo.jpg", tags=["session_id:D1"])
mem.add_audio("voice_note.wav", tags=["session_id:D1"])

result = mem.query("What does the user enjoy?", top_k=5)
for item in result.items:
    print(item["summary"])

mem.close()

💡 نصيحة: يختار الوضع التلقائي أخف واجهة خلفية تناسب بياناتك. لا يزال بإمكانك استخدام mode="text" أو mode="omni" صراحةً إن كنت تفضل ذلك.

🧬 متقدم: تحسين إعداد الاسترجاع

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

import simplemem
from simplemem import SimpleMem, load_config

# mem is a finalized SimpleMem instance with memories already built
dev_questions = [
    ("When is the meeting?", "2pm tomorrow at Starbucks"),
    ("What should Bob prepare?", "market analysis report"),
]
config = simplemem.optimize(mem, dev_questions, max_rounds=3)
config.save("my_config.json")

# Later, deploy with the optimized config
config = load_config("my_config.json")
mem = SimpleMem(config=config)

تشغّل EvolveMem دورة تقييم → تشخيص → اقتراح → حماية مدفوعة بنماذج اللغة الكبيرة على أسئلة التطوير الخاصة بك، مع ضبط أعلام الاسترجاع الشاملة (top_k، وضع الدمج، التحقق من الإجابة، جولات التأمل، ...). للنسخة المستقلة الكاملة مع محوّلات المعايير وتجاوزات لكل فئة، راجع EvolveMem/.

🚄 متقدم: المعالجة المتوازية

لمعالجة الحوارات على نطاق واسع، مكّن الوضع المتوازي:

from simplemem import create

mem = create(
    mode="text",
    clear_db=True,
    enable_parallel_processing=True,  # ⚡ Parallel memory building
    max_parallel_workers=8,
    enable_parallel_retrieval=True,   # 🔍 Parallel query execution
    max_retrieval_workers=4
)

💡 نصيحة احترافية: تقلل المعالجة المتوازية بشكل ملحوظ من زمن الاستجابة لعمليات الدُّفعات!

🌟 نظرة عامة

SimpleMem هي مجموعة ذاكرة موحّدة لوكلاء نماذج اللغة الكبيرة، مبنية على مبدأ واحد: تخزين ذاكرة دلالية بلا فقدان للمعلومات بكثافة معلوماتية عالية، حتى يتذكر الوكيل أكثر مع استهلاك رموز (tokens) أقل بكثير. تجمع الحزمة ثلاثة أعمال تشترك في هذا المبدأ لكنها تعالج أجزاء مختلفة من المشكلة.

📝 SimpleMem: النواة الكفؤة (نصية)

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

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

يحقق هذا على معيار LoCoMo تحسينًا بنسبة 26.4% في متوسط F1 مقارنةً بالأنظمة السابقة مع تقليل استهلاك الرموز في وقت الاستنتاج بمقدار 30x تقريبًا. تفاصيل الآلية (طبقات الفهرس الهجين، أمثلة الضغط، تخطيط الاسترجاع): ذاكرة النص في SimpleMem →.

🧠 Omni-SimpleMem: ذاكرة متعددة الوسائط (نص، صورة، صوت، فيديو)

تمتد Omni-SimpleMem بفلسفة الضغط أولاً إلى أربع طرائق، مبنيةً على ثلاثة مبادئ: الاستيعاب الانتقائي (تصفية مدفوعة بالإنتروبيا لكل طريقة)، الاسترجاع التدريجي (FAISS + BM25 هجيني مع توسيع هرمي لميزانية الرموز)، وتعزيز الرسم البياني للمعرفة (استدلال متعدد الخطوات عبر الوسائط). بدلاً من أن يكون مصمَّمًا يدويًا، اكتُشفت بنيته بواسطة مسار بحث ذاتي أجرى نحو 50 تجربة عبر معيارين، يشخّص أوجه الفشل ويقترح تغييرات معمارية بل ويصلح أخطاء مسار البيانات دون تدخل بشري في الحلقة الداخلية. والجدير بالذكر أن إصلاحات الأخطاء والتغييرات المعمارية أسهمت أكثر من كل ضبط المعاملات الفائقة مجتمعةً، محوّلةً النظام من خط أساس ساذج إلى أفضل أداء على كل من LoCoMo وMem-Gallery. التوثيق الكامل: Omni-SimpleMem →.

🧬 EvolveMem: استرجاع يتطور ذاتيًا

تسد EvolveMem نقطة عمياء يشاركها تقريبًا كل نظام ذاكرة: المحتوى المخزّن يتطور، لكن آلية الاسترجاع (دوال التسجيل، استراتيجيات الدمج، سياسات توليد الإجابات) تبقى مجمّدة بعد النشر. تشغّل EvolveMem عملية AutoResearch دائرية الحلقة (تقييم ← تشخيص ← اقتراح ← حماية ← تكرار) يشخّص فيها نموذج لغوي كبير إخفاقات كل سؤال ويقترح تغييرات إعداد، محمية بإعادة طرح تلقائية عند الانحدار وحوافز استكشاف خلال الركود. تكتشف أبعادًا جديدة للاسترجاع (تحليل الاستعلام، تبادل الكيانات، التحقق من الإجابة) غير موجودة في التصميم الأصلي، وتحسّن LoCoMo بنسبة 25.7% نسبية على أقوى خط أساس، وإعداداتها المتطورة تنتقل إيجابيًا عبر المعايير. التوثيق الكامل: EvolveMem →.

كيف تتلاءم معًا

from simplemem import SimpleMem يمنحك النواة النصية مع التوجيه التلقائي إلى الواجهة الخلفية متعددة الوسائط، وsimplemem.optimize(...) يستغل EvolveMem لضبط الاسترجاع لبياناتك الخاصة. حزمة واحدة، نموذج ذهني واحد: اضغط بلا فقدان، استرجع بحسب النوايا، ودع النظام يواصل تحسين ذاته.

📦 التثبيت

📝 ملاحظات للمستخدمين لأول مرة

  • تأكد من استخدام Python 3.10+ في بيئتك النشطة، وليس مجرد التثبيت العالمي.
  • يجب تهيئة مفتاح API متوافق مع OpenAI قبل تشغيل أي بناء للذاكرة أو استرجاع، وإلا قد يفشل التهيئة.
  • عند استخدام مزودين من غير OpenAI (مثل Qwen أو Azure OpenAI)، تحقق من اسم النموذج وOPENAI_BASE_URL في config.py.
  • بالنسبة لمجموعات بيانات الحوار الكبيرة، يمكن أن يقلل تمكين المعالجة المتوازية بشكل ملحوظ من وقت بناء الذاكرة.

📋 المتطلبات

  • 🐍 Python 3.10+
  • 🔑 واجهة برمجية متوافقة مع OpenAI (OpenAI، Qwen، Azure OpenAI، إلخ.)

🛠️ الإعداد

# 📥 Clone repository
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem

# 📦 Install dependencies (pinned versions)
pip install -r requirements.txt

# — OR — install as an editable package
pip install -e .                  # default: text + multimodal + evolver
pip install -e ".[server]"        # + MCP / HTTP server (mcp, fastapi, ...)
pip install -e ".[all]"           # everything, including dev tools

# ⚙️ Configure API settings
cp config.py.example config.py
# Edit config.py with your API key and preferences

⚙️ مثال على الإعداد

# config.py
OPENAI_API_KEY = "your-api-key"
OPENAI_BASE_URL = None  # or custom endpoint for Qwen/Azure

LLM_MODEL = "gpt-4.1-mini"
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B"  # State-of-the-art retrieval

🐳 التشغيل مع Docker

يمكن تشغيل خادم MCP في Docker لبيئة متسقة ومعزولة. تُحفظ البيانات (LanceDB وقاعدة بيانات المستخدم) في وحدة تخزين على المضيف.

المتطلبات الأولية

تشغيل سريع

# From the repository root
docker compose up -d

تُخزَّن البيانات في ./data على المضيف (تُنشأ تلقائيًا).

الإعداد المخصص

  1. انسخ قالب البيئة وعدّله: 
    cp .env.example .env
# Edit .env: set JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, model URLs, etc.
  2. شغّل مع ملف البيئة: 
    docker compose --env-file .env up -d

استخدام Ollama على المضيف

عندما يكون LLM_PROVIDER=ollama ويعمل Ollama على جهازك (ليس في Docker)، عيّن في .env:

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

على Linux، يُمكَّن host.docker.internal تلقائيًا عبر ملف Compose.

أوامر مفيدة

docker compose logs -f simplemem   # Follow logs
docker compose down                 # Stop and remove containers

📖 للاستضافة الذاتية لخادم MCP (Docker أو المعدن المجرد)، راجع توثيق MCP.

🔌 خادم MCP (ذاكرة نصية)

تتوفر SimpleMem كـخدمة ذاكرة مستضافة سحابيًا عبر بروتوكول Model Context Protocol (MCP)، مما يتيح التكامل السلس مع مساعدي الذكاء الاصطناعي مثل Claude Desktop وCursor وعملاء MCP الآخرين المتوافقين.

🌐 الخدمة السحابية: mcp.simplemem.cloud — أو استضف خادم MCP محليًا باستخدام Docker.

الميزات الرئيسية

الميزة الوصف
HTTP قابل للتدفق بروتوكول MCP 2025-03-26 مع JSON-RPC 2.0
عزل متعدد المستأجرين جداول بيانات لكل مستخدم مع مصادقة رمزية
الاسترجاع الهجين بحث دلالي + مطابقة كلمات مفتاحية + تصفية بيانات وصفية
محسَّن للإنتاج أوقات استجابة أسرع مع تكامل OpenRouter

الإعداد السريع

{
  "mcpServers": {
    "simplemem": {
      "url": "https://mcp.simplemem.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

📖 للحصول على تعليمات الإعداد التفصيلية ودليل الاستضافة الذاتية، راجع توثيق MCP

📊 إعادة إنتاج نتائج الورقة

أعد إنتاج أرقام LoCoMo / MemBench / Mem-Gallery من الأوراق البحثية. لكل ركيزة منشغلها الخاص بالمعايير في مجلدها الخاص. ثبّت إضافات المعيار أولاً: pip install -e ".[benchmark]".

📝 SimpleMem (نصية) — LoCoMo

شغّل من جذر المستودع:

python test_locomo10.py                       # full LoCoMo benchmark
python test_locomo10.py --num-samples 5       # quick subset
python test_locomo10.py --result-file my_results.json

🧬 EvolveMem — التطور الذاتي + LoCoMo / MemBench

شغّل من مجلد EvolveMem/ (راجع EvolveMem/README.md):

cd EvolveMem
python run_evolution.py --data data/locomo10.json --max-rounds 7
python run_benchmark.py locomo --sample 0 --initial weak --max-rounds 3
python run_benchmark.py membench --agent FirstAgent --max-rounds 3

🧠 Omni-SimpleMem — LoCoMo / Mem-Gallery

شغّل من مجلد OmniSimpleMem/ (راجع OmniSimpleMem/README.md):

cd OmniSimpleMem
python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o

🗺️ خارطة الطريق

القدرة الحالية حسب قناة التكامل:

القدرة Python (pip install) خادم MCP (Claude Desktop، Cursor، ...)
ذاكرة نصية ✅ ✅
وسائط متعددة (صورة / صوت / فيديو) ✅ ⬜ مخطط
optimize() الاسترجاع المتطور ذاتيًا ✅ ⬜ مخطط

العمل المخطط لسد الفجوة (خادم MCP هو خدمة نصية مستقلة متعددة المستأجرين؛ هذه ميزات حقيقية، وليست إصلاحات توثيق):

  • وسائط متعددة عبر MCP. إضافة أدوات memory_add_image / memory_add_audio / memory_add_video. يحتاج إلى مسار رفع ملفات (base64 أو URL، إذ لا يمكن لـ MCP تمرير مسارات الملفات المحلية)، وتكيّف متعدد المستأجرين لواجهة تخزين Omni-SimpleMem الخلفية، والوصول من جانب الخادم إلى نماذج الرؤية والصوت.
  • EvolveMem عبر MCP. كشف optimize() كأداة MCP. أكثر قابليةً للتنفيذ من الوسائط المتعددة (نص دخل، JSON إعداد خرج، دون نقل ملفات)، لكن مسترجع MCP يدعم حاليًا فقط semantic_top_k / keyword_top_k من أصل ~10 أبعاد تطوّرها EvolveMem. يتطلب توسيع مسترجع MCP لدعم المقابض المتبقية (structured top_k، وضع/أوزان الدمج، تبادل الكيانات، تحليل الاستعلام، التحقق من الإجابة)، ومحوّل لتشغيل حلقة التطور على الذكريات المخزّنة للمستأجر، وثبات الإعداد لكل مستأجر، والتنفيذ غير المتزامن (الحلقة ثقيلة على نماذج اللغة وستتجاوز مهلة الطلب المتزامن).
  • Docker يرث كليهما تلقائيًا بمجرد دعم خادم MCP لهما (إضافة تبعيات الوسائط المتعددة إلى الصورة وحجم تخزين Omni).

للوسائط المتعددة والاسترجاع المتطور ذاتيًا اليوم، استخدم واجهة Python البرمجية (راجع البداية السريعة).

📝 الاستشهاد

إذا استخدمت SimpleMem في بحثك، يرجى الاستشهاد بـ:

@article{simplemem2026,
  title={SimpleMem: Efficient Lifelong Memory for LLM Agents},
  author={Liu, Jiaqi and Su, Yaofeng and Xia, Peng and Zhou, Yiyang and Han, Siwei and  Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu},
  journal={arXiv preprint arXiv:2601.02553},
  year={2026},
  url={https://arxiv.org/abs/2601.02553}
}
@article{evolvemem2026,
  title={EvolveMem: Self-Evolving Memory Architecture via AutoResearch for LLM Agents},
  author={Liu, Jiaqi and Ye, Xinyu and Xia, Peng and Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu},
  journal={arXiv preprint arXiv:2605.13941},
  year={2026},
  url={https://arxiv.org/abs/2605.13941}
}
@article{omnisimplemem2026,
  title   = {Omni-SimpleMem: Autoresearch-Guided Discovery of Lifelong Multimodal Agent Memory},
  author  = {Liu, Jiaqi and Ling, Zipeng and Qiu, Shi and Liu, Yanqing and Han, Siwei and Xia, Peng and Tu, Haoqin and Zheng, Zeyu and Xie, Cihang and Fleming, Charles and Ding, Mingyu and Yao, Huaxiu},
  journal = {arXiv preprint arXiv:2604.01007},
  year    = {2026},
}

📄 الرخصة

هذا المشروع مرخّص بموجب رخصة MIT - راجع ملف LICENSE للتفاصيل.

🙏 شكر وتقدير

نودّ أن نشكر المشاريع والفرق التالية:

  • 🔍 نموذج التضمين: Qwen3-Embedding - أداء استرجاع متطور
  • 🗄️ قاعدة بيانات المتجهات: LanceDB - تخزين عمودي عالي الأداء
  • 📊 المعيار: LoCoMo - إطار تقييم الذاكرة طويلة السياق