يوسّع هذا الـ gist نمط LLM Wiki الذي صاغه Karpathy بإضافة تقييم الثقة، ودورة الحياة، والرسوم البيانية المعرفية، والبحث الهجين: و agentmemory هو تطبيق ذلك النمط.

التثبيت • البدء السريع • مقاييس الأداء • مقارنة بالمنافسين • الوكلاء • آلية العمل • MCP • العارض • مدعوم بـ iii • الإعدادات • API

--- ## التثبيت المتطلبات: - يتطلب الأمر Node.js الإصدار 20 أو أحدث مع npm وnpx (تحقّق بـ `node -v` و`npm -v` و`npx -v`). - يحتاج التثبيت الآلي لـ iii-engine على macOS/Linux أيضًا إلى `curl` وصدفة POSIX من نوع `sh` وأداة `tar`. قد لا تتضمنها الصور الدنيا مثل `node:20-slim`. - يتطلب نظام Windows الأصلي تثبيت ملف `iii.exe` الخاص بالإصدار المثبَّت v0.22.1 من iii-engine يدويًا. أما WSL2 أو Docker Desktop فهما المساران المدعومان الآخران. أمر التثبيت الجديد المعياري: ```bash npx -y @agentmemory/agentmemory@latest ``` التشغيل الأول هو إعداد تفاعلي: تختار الوكلاء المراد ربطهم (Claude Code وCursor وCodex وGemini CLI وOpenCode، ...)، وتختار مزوّد LLM أو تبقى بلا مفتاح، فيقوم الإعداد بتوليد ملف التكوين، وتشغيل خادم الذاكرة ومحرك iii المثبَّت الخاص به، ويعرض عليك تثبيته عالميًا بحيث يعمل أمر `agentmemory` المجرد في كل مكان بعد ذلك. تقبل `-y` مطالبة npx بتثبيت الحزمة، وتتجنّب `@latest` إصدارًا قديمًا مخزَّنًا مؤقتًا. يُتيح المزوّد ميزات LLM، لكن ضغط الملاحظات المكتوب بواسطة LLM لا يبدأ إلا عند ضبط `AGENTMEMORY_AUTO_COMPRESS=true` أيضًا. يُعطّل وضع عدم استخدام المفاتيح تضمينات المتجهات. تستخدم `memory_recall` (مسار `mem::search`) خوارزمية BM25، في حين يمكن لـ `memory_smart_search` أيضًا دمج تطابقات الرسم البياني البنيوية عندما تتوفر بيانات رسم بياني مسبقًا. للحصول على استرجاع دلالي مجاني على الجهاز نفسه، اضبط `EMBEDDING_PROVIDER=local` في `~/.agentmemory/.env` وأعد التشغيل. يُنزِّل أول طلب تضمين النموذج `Xenova/all-MiniLM-L6-v2`؛ ويعمل الاستدلال محليًا بعد ذلك التنزيل الأولي للنموذج. تستخدم بيئة التشغيل المحلية أربعة منافذ: `3111` لـ REST/MCP HTTP، و`3112` لتيارات iii، و`3113` للعارض، و`49134` لمقبس WebSocket الخاص بعامل iii. تعيش حالة iii الدائمة في `~/Library/Application Support/agentmemory` على macOS، وفي `$XDG_DATA_HOME/agentmemory` أو `~/.local/share/agentmemory` على Linux، وفي `%APPDATA%\agentmemory` على Windows. استخدم `--data-dir ` أو `AGENTMEMORY_DATA_DIR` لتجاوز ذلك المسار، وأعد استخدام القيمة نفسها في كل إعادة تشغيل. للحفاظ على التوافق مع الإصدارات السابقة، يُعطى `./data/state_store.db` أو `./data/iii-config.yaml` الموجودان مسبقًا الأسبقية على المسار الافتراضي للنظام في النسخة 0؛ وتظل الراية الصريحة أو تجاوز متغيرات البيئة هي الأعلى أسبقية. بعد ذلك، تحقَّق من أن الاسترجاع يعمل، وأعطِ وكيلك مهاراته: ```bash npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory ``` ينبغي أن تُصيب عمليات البحث بالكلمات المفتاحية هدفها في وضع عدم استخدام المفاتيح الافتراضي عبر BM25. أما استعلام العرض التوضيحي `database performance optimization` فهو دلالي بالتصميم، ويمكن أن يعيد صفر نتائج إلى أن يُضبط مزوّد تضمين. تفضّل أن يقوم وكيل ترميز بتنفيذ العملية كاملة؟ أعطه تعليمة واحدة: > Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md اربط وكلاء إضافيين في أي وقت باستخدام `agentmemory connect ` — توجد 20 حزمة توصيل مُدرَجة في [يعمل مع كل وكيل](#works-with-every-agent). المرجع الكامل للأوامر في [البدء السريع](#quick-start).

Windows

المسار الأسرع هو WSL2. يتطلب إعداد المحرك على Windows الأصلي تنزيل أرشيف ZIP الخاص بالإصدار المثبَّت v0.22.1 واستخراج `iii.exe` يدويًا؛ فالواجهة الطرفية CLI لا تستخرجه تلقائيًا. كما يُدعم Docker Desktop أيضًا. راجع [ملاحظات Windows](#windows) للاطلاع على الخطوات التفصيلية.

Global install / EACCES

```bash npm install -g @agentmemory/agentmemory@latest ``` يظل أمر npx أعلاه هو المسار المعياري للتثبيت الجديد، وهو يتجنّب مشكلات أذونات بادئة التثبيت العالمية.

npx يقدّم إصدارًا قديمًا

يخزّن npx كل إصدار على حدة مؤقتًا. فرض استخدام الأحدث عبر `npx -y @agentmemory/agentmemory@latest`، أو مسح الذاكرة المؤقتة مرة واحدة بتشغيل `rm -rf ~/.npm/_npx` (على macOS/Linux؛ وعلى Windows احذف `%LOCALAPPDATA%\npm-cache\_npx`).

لديك محرك iii خاص بك يعمل مسبقًا

يُثبّت agentmemory الإصدار v0.22.1 من iii-engine تحديدًا، ولن يرتبط بإصدار مختلف (لأن العامل لا يستطيع التحدث ببروتوكول محرك آخر). أوقف المحرك الآخر، ثم شغّل `npx -y @agentmemory/agentmemory@latest`. سيثبّت ويشغّل الإصدار المثبَّت v0.22.1 في `~/.agentmemory/bin`، تاركًا نسخة `iii` الخاصة بك دون أي تغيير.

---

يعمل agentmemory مع أي وكيل يدعم الخطافات أو MCP أو REST API. يتشارك جميع الوكلاء خادم الذاكرة نفسه.

Claude Code إضافة أصلية + 12 خطافًا + MCP	Codex CLI إضافة أصلية + 6 خطافات + MCP	GitHub Copilot CLI MCP + خطافات/مهارات الإضافة	Cursor إضافة أصلية + 7 خطافات + MCP	OpenCode إضافة التقاط + MCP
Devin 6 خطافات + مهارات + MCP	OpenClaw إضافة أصلية + MCP	Hermes إضافة أصلية + MCP	pi إضافة أصلية + MCP	OpenHuman خلفية أصلية باستخدام Memory trait
Gemini CLI خادم MCP	Antigravity MCP + خطافات	Claude Desktop خادم MCP	Warp الربط + MCP + مهارات	Zed خادم MCP
Cline خادم MCP	Continue خادم MCP	Droid خادم MCP	Kiro خادم MCP	Qwen Code خادم MCP
DeepSeek Harness خادم MCP	Roo Code خادم MCP	Kilo Code خادم MCP	Goose خادم MCP	Aider REST API

_{يعمل مع أي وكيل يتحدث MCP أو HTTP. خادم واحد، والذكريات مشتركة بين جميعها.}

--- أنت تشرح نفس البنية المعمارية في كل جلسة. وتعيد اكتشاف نفس الأخطاء مرارًا. وتُعلِّم نفس التفضيلات من جديد. تتوقف الذاكرة المدمجة (CLAUDE.md، .cursorrules) عند حد 200 سطر وتصبح قديمة بمرور الوقت. يحل agentmemory هذه المشكلة. فهو يلتقط بصمت ما يفعله وكيلك، ويضغطه في ذاكرة قابلة للبحث، ويحقن السياق المناسب عند بدء الجلسة التالية. أمر واحد فقط. ويعمل عبر الوكلاء كافة. **ما الذي يتغيّر:** في الجلسة 1 تُعِدّ مصادقة JWT. وفي الجلسة 2 تطلب تحديد معدل الطلبات (rate limiting). يعرف الوكيل مسبقًا أن مصادقتك تستخدم وسيط jose في `src/middleware/auth.ts`، وأن اختباراتك تغطي التحقق من الرمز (token)، وأنك اخترت jose بدلًا من jsonwebtoken لتوافقه مع Edge، دون أي إعادة شرح أو نسخ ولصق. ```bash npx -y @agentmemory/agentmemory@latest ``` افتراضيًا، يخزّن agentmemory حالة iii-engine خارج المستودع الذي تشغّله منه: في `~/Library/Application Support/agentmemory` على macOS، وفي `$XDG_DATA_HOME/agentmemory` أو `~/.local/share/agentmemory` على Linux، وفي `%APPDATA%\agentmemory` على Windows. ويُعاد استخدام `./data/state_store.db` أو `./data/iii-config.yaml` القديمين إن وُجدا للنسخة 0 قبل الاعتماد على ذلك المسار الافتراضي للنظام. لاختيار موقع محدد صريحًا، مرّر `--data-dir ` أو اضبط `AGENTMEMORY_DATA_DIR`؛ وأيٌّ من هذين الضبطين الصريحين يسبق آلية الاكتشاف القديمة في الأولوية: ```bash npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest ``` تستخدم عمليات التشغيل الأصلية (native) وعبر Docker نفس دليل المضيف المُحلَّل؛ ويربطه Docker (bind-mount) عند `/data`. يُضيف الخيار `--instance 1` اللاحقة `instance-1` إلى الدليل المُحلَّل، ويختار رباعية المنافذ الافتراضية المستقلة `3211/3212/3213/49234`. ملاحظات آخر إصدار: [CHANGELOG.md](../CHANGELOG.md). ---

### دقة الاسترجاع **coding-agent-life-v1** (مجموعة بيانات داخلية، قابلة لإعادة الإنتاج في بيئة معزولة) | المحوّل | P@5 | R@5 | معدل الإصابة ضمن أفضل 5 | زمن الاستجابة p50 | |---|---|---|---|---| | **agentmemory الهجين** | **0.240** | **1.000** | **15 / 15** | 14 ms | | خط أساس grep | 0.227 | 0.967 | 15 / 15 | 0 ms | معدل إصابة 100% ضمن أفضل 5 عند **سقف P@5 الرياضي** لهذه المجموعة (0.240، راجع بطاقة النتائج). يسترجع النظام الهجين كل جلسة مرجعية (gold)؛ بينما يفوّت grep جلسة واحدة من جلستين مرجعيتين في الاستعلام الزمني متعدد الجلسات. التحسّن هنا في **الاسترجاع + البعد الزمني**، لا في الدقة الكلية. هذا المقياس صغير وقليل الجلسات المرجعية؛ ويميّز المقياس الأكبر LongMemEval-S أدناه بشكل أفضل. التفصيل الكامل حسب النوع وملاحظة التصحيح: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md). **LongMemEval-S** (ICLR 2025، 500 سؤال) | النظام | R@5 | R@10 | MRR | |---|---|---|---| | **agentmemory** | **95.2%** | **98.6%** | **88.2%** | | BM25 فقط (خيار احتياطي) | 86.2% | 94.6% | 71.5% |

### توفير الرموز (Tokens) | الأسلوب | الرموز/سنويًا | التكلفة/سنويًا | |---|---|---| | لصق السياق الكامل | 19.5M+ | غير ممكن (يتجاوز النافذة) | | ملخَّص بواسطة LLM | ~650K | ~$500 | | **agentmemory** | **~170K** | **~$10** | | agentmemory + تضمينات محلية | ~170K | **$0** |

> نموذج التضمين: `all-MiniLM-L6-v2` (محلي، مجاني، بلا مفتاح API). التقارير الكاملة: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md)، [`benchmark/QUALITY.md`](../benchmark/QUALITY.md)، [`benchmark/SCALE.md`](../benchmark/SCALE.md). مقارنة بالمنافسين: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) وتشمل agentmemory في مواجهة mem0 وLetta وKhoj وsupermemory وTencentDB Agent Memory وMemPalace وZep/Graphiti وCognee وHippo. **إعادة الإنتاج محليًا:** [`eval/README.md`](../eval/README.md)، وهو إطار اختبار (harness) قابل لتوصيل المحوّلات لـ LongMemEval `_s` (500 سؤال علنية) + `coding-agent-life-v1` (مجموعة داخلية من 15 جلسة). تُقيَّم محوّلات grep / المتجهات / agentmemory جنبًا إلى جنب، بمخرجات NDJSON، وتُنشر بطاقات النتائج في [`docs/benchmarks/`](../docs/benchmarks/). **يتكامل مع [codegraph](https://github.com/colbymchenry/codegraph) و[Understand Anything](https://github.com/Lum1104/Understand-Anything) و[Graphify](https://github.com/safishamsi/graphify).** فهرسة الرسم البياني للشفرة (code-graph)، وخطوط بناء متعددة الوكلاء، ورسوم بيانية معرفية أوسع تمتد عبر المستندات/ملفات PDF/الصور/الفيديوهات. يتذكّر agentmemory العمل؛ وتُضيء هذه المشاريع الثلاثة بقية طبقة السياق. الوصفات وجدول توجيه الأسئلة: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md). ---

	agentmemory	mem0 (63K ⭐)	Letta / MemGPT (24K ⭐)	Khoj (36K ⭐)	supermemory (29K ⭐)	TencentDB Agent Memory (22K ⭐)	MemPalace (54K ⭐)	oracleagentmemory	Hippo	مدمج (CLAUDE.md)
النوع	محرك ذاكرة + خادم MCP	واجهة برمجية لطبقة الذاكرة	بيئة تشغيل كاملة للوكيل	ذكاء اصطناعي شخصي	واجهة برمجية للذاكرة + تطبيق	محور ذاكرة جماعي (وكيل LLM وسيط)	ذاكرة متجهية (مفتوحة المصدر)	محرك ذاكرة (قاعدة بيانات Oracle)	نظام ذاكرة	ملف ثابت
دقة الاسترجاع R@5	95.2%	68.5% (LoCoMo)	83.2% (LoCoMo)	غير متوفر	مُعلَن من الشركة نفسها	PersonaMem 76% (مُعلَن من الشركة نفسها)	~96.6% (مُعلَن من الشركة نفسها)	94.4% (مُعلَن من الشركة نفسها)	غير متوفر	غير متوفر (grep)
الالتقاط التلقائي	12 خطافًا (بلا أي جهد يدوي)	استدعاءات add() يدوية	تعديلات ذاتية من الوكيل	يدوي	استخراج من جانب الواجهة البرمجية	اعتراض عبر وكيل وسيط (باستبدال base-URL)	يدوي	استخراج عبر API	يدوي	تعديل يدوي
البحث	BM25 + المتجهات + الرسم البياني (دمج RRF)	المتجهات + الرسم البياني	متجهات (أرشيفية)	دلالي	متجهات + RAG	4 أنواع من الأصول (محادثة / مهارة / Wiki / CodeGraph)	متجهات فقط	متجهات + دلالي	مرجَّح بالتلاشي	يحمّل كل شيء إلى السياق
تعدد الوكلاء	MCP + REST + حجوزات (leases) + إشارات	API (بلا تنسيق)	داخل بيئة تشغيل Letta فقط	لا	لا	أدوار جماعية + أصول مشتركة	لا	محدود النطاق فقط	مشترك بين وكلاء متعددين	ملفات لكل وكيل على حدة
الارتهان لإطار عمل محدد	لا يوجد (أي عميل MCP)	لا يوجد	مرتفع (يجب استخدام Letta)	مستقل	لا يوجد	وكيل وسيط يتقدّم كل استدعاء للنموذج	لا يوجد	Oracle Database	لا يوجد	تنسيق خاص بكل وكيل
الاعتماديات الخارجية	لا يوجد (SQLite + iii-engine)	Qdrant / pgvector	Postgres + قاعدة بيانات متجهية	متعددة	سحابة مُدارة	حزمة Docker (Core + Hub + Proxy)	مخزن متجهات	Oracle AI Database	لا يوجد	لا يوجد
دورة حياة الذاكرة	توحيد رباعي المستويات + تلاشي + نسيان تلقائي	استخراج سلبي (passive)	يديرها الوكيل	يدوي	نسيان تلقائي	مراجعة يدوية؛ والتوجيه التلقائي قيد التطوير	لا يوجد	غير مُحدَّد	تلاشي + توحيد	تقليم يدوي
كفاءة استخدام الرموز	~1,900 رمز/جلسة (10$/سنويًا)	يتفاوت حسب التكامل	الذاكرة الأساسية داخل السياق	متفاوت	تسعير سحابي	غير مُحدَّد	بلا حد لعدد الرموز	معتمد على LLM (متفاوت)	متفاوت	أكثر من 22K رمز عند 240 ملاحظة
العارض اللحظي	نعم (المنفذ 3113)	لوحة تحكم سحابية	لوحة تحكم سحابية	واجهة ويب	لوحة تحكم سحابية	واجهة ويب للمحور (Hub)	لا	لا	لا	لا
استضافة ذاتية	نعم (افتراضيًا)	اختياري	اختياري	نعم	لا (سحابي فقط)	نعم (Docker)	نعم	نعم (Oracle DB)	نعم	نعم

_{ملاحظة على المقياس: نتيجة R@5 الخاصة بـ agentmemory فقط هي قياسنا الفعلي (LongMemEval-S، قابلة لإعادة الإنتاج من benchmark/COMPARISON.md). أما أرقام mem0 وLetta فهي أرقامهما المنشورة على LoCoMo (مجموعة بيانات مختلفة)؛ وأرقام MemPalace وsupermemory وTencentDB (PersonaMem) وoracleagentmemory هي ادعاءات مُعلَنة من الشركات نفسها لم نُعِد إنتاجها بشكل مستقل (استخدمت عملية تشغيل oracleagentmemory نموذج GPT-5.5 مقابل قاعدة بيانات Oracle AI Database). عُرضت جنبًا إلى جنب للمقارنة التقريبية فقط، لا كمواجهة مباشرة على بيانات متطابقة. أعداد النجوم تقريبية وتتغير مع الوقت.} **داخلون جدد** تستحق المعرفة، مع مقارنة تفصيلية في [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md): | النظام | ⭐ | الزاوية | |--------|---|-------| | Zep / Graphiti | 30K | رسم بياني معرفي زمني؛ يملك أقوى نتائج منشورة للاستعلامات الزمنية (LongMemEval 63.8%)، لكن بناء الرسم البياني يتم بشكل غير متزامن، فقد تتأخر الحقائق الجديدة | | Cognee | 30K | استيعاب يحوّل المستندات إلى رسم بياني معرفي، مخصص لـ Python فقط، ومبني لاستخراج الكيانات البنيوية لا لالتقاط الجلسات | لا يلتقط أي منها تلقائيًا من خطافات وكيل الترميز، ولا يقدّم عارضًا يُبنى أولاً للتشغيل المحلي، ولا يعمل بلا مفتاح — وهذا المزيج هو ما بُني agentmemory حوله. ---

التوافق: يستهدف هذا الإصدار `iii-sdk` بالإصدار 0.22.1، ويثبّت iii-engine على الإصدار v0.22.1. ### جرّبه في 30 ثانية ```bash # Terminal 1: start the server npx -y @agentmemory/agentmemory@latest # Terminal 2: seed sample data and see recall in action npx -y @agentmemory/agentmemory@latest demo ``` يُنشئ أمر `demo` ثلاث جلسات واقعية (مصادقة JWT، إصلاح استعلام N+1، تحديد معدل الطلبات) ويُجري عمليات بحث عليها. تُعطّل عمليات التثبيت بلا مفاتيح المتجهات، لذا ينبغي أن تُصيب استعلامات `mem::search` بالكلمات المفتاحية هدفها عبر BM25، في حين يمكن أن يعيد `database performance optimization` صفر نتائج. وقد يُعيد `smart-search` أيضًا تطابقات الرسم البياني البنيوية عندما تتوفر بيانات رسم بياني. لجعل الاستعلام الدلالي يعثر على إصلاح N+1 عبر المتجهات، اضبط `EMBEDDING_PROVIDER=local`، وأعد التشغيل، واسمح لأول تنزيل للنموذج بأن يكتمل. افتح `http://localhost:3113` لمشاهدة بناء الذاكرة مباشرةً. ### التحقق من تثبيت جديد واستمرارية البيانات بعد إعادة التشغيل مع تشغيل الخادم، تحقّق من REST، والحالة الصحية (health)، والعارض، وحالة بيئة التشغيل المعتمدة على iii: ```bash curl -fsS http://localhost:3111/agentmemory/livez curl -fsS http://localhost:3111/agentmemory/health curl -fsS -o /dev/null http://localhost:3113/ npx -y @agentmemory/agentmemory@latest status ``` تغطي لوحة الجاهزية عند بدء التشغيل جميع المنافذ الأربعة: REST/MCP HTTP على 3111، وتيارات iii على 3112، والعارض على 3113، ومقبس WebSocket الخاص بعامل iii على 49134. يؤكد أمر `status` سلامة agentmemory ووضع المزوّد/التضمين النشط. احفظ عيّنة اختبار (probe) وتأكّد من إمكانية البحث عنها: ```bash curl -fsS -X POST http://localhost:3111/agentmemory/remember \ -H 'Content-Type: application/json' \ -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}' curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \ -H 'Content-Type: application/json' \ -d '{"query":"restart persistence probe","limit":5}' ``` ثم شغّل `npx -y @agentmemory/agentmemory@latest stop`، وأعد تشغيل الأمر المعياري من جديد في الطرفية 1، وانتظر استجابة `/agentmemory/livez`، وكرِّر عملية البحث. يجب أن تظل عيّنة الاختبار مُستردَّة. إذا اخترت مسار `--data-dir` مخصصًا، مرّر الدليل نفسه عند إعادة التشغيل. ### أوامر الاستخدام اليومي تعليمات التثبيت والإعداد موجودة في [التثبيت](#install) أعلاه (يرشدك التشغيل الأول خلالها). في الاستخدام اليومي: ```bash agentmemory # start the server agentmemory stop # stop it cleanly agentmemory connect # wire another agent agentmemory doctor # interactive diagnostics + fix prompts agentmemory remove # uninstall everything we created ``` ### إعادة تشغيل الجلسة (Session Replay) كل جلسة يسجّلها agentmemory قابلة لإعادة التشغيل. افتح العارض، واختر تبويب **Replay**، وتجوّل عبر خط الزمن: تُعرض المطالبات، واستدعاءات الأدوات، ونتائجها، والردود كأحداث منفصلة مع إمكانية تشغيل/إيقاف مؤقت، والتحكم بالسرعة (من 0.5x إلى 4x)، واختصارات لوحة المفاتيح (مسافة للتبديل، والأسهم للتنقل خطوة بخطوة). لاستيراد محاضر JSONL أقدم من Claude Code: ```bash # Import everything under the default ~/.claude/projects npx -y @agentmemory/agentmemory@latest import-jsonl # Or import a single file npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl ``` تظهر الجلسات المستوردة في قائمة اختيار Replay جنبًا إلى جنب مع الجلسات الأصلية. تحت الغطاء، يمر كل إدخال عبر دوال iii: `mem::replay::load` و`mem::replay::sessions` و`mem::replay::import-jsonl`، دون أي خوادم جانبية. تُفهرس كل محضر مستورد للبحث، ويُختم بقناة المصدر `import`، ويُستخرج منه بلورة جلسة (crystal) ودروس مستفادة (lessons). > **تنبيه إذا كنت تعتمد على `import-jsonl` كمسارك الأساسي للالتقاط:** يحذف إعداد `cleanupPeriodDays` الخاص بـ Claude Code (في `~/.claude/settings.json`، والافتراضي **30**) تلقائيًا محاضر JSONL الأقدم من تلك النافذة الزمنية من `~/.claude/projects/`. إذا ثبّت agentmemory حديثًا على سجل Claude Code يمتد لعدة أشهر، فإن كل ما هو أقدم من 30 يومًا يكون قد اختفى مسبقًا قبل أول استيراد. إما أن تشغّل `import-jsonl` عبر مهمة cron، أو ترفع قيمة `cleanupPeriodDays` إلى رقم أعلى، أو تربط خطافات الالتقاط التلقائي (مسار تثبيت الإضافة الافتراضي) حتى تصل كل مداولة إلى agentmemory والجلسة لا تزال نشطة، فلا يعود تنظيف JSONL ذا أهمية. ### الترقية / الصيانة استخدم أمر الصيانة عندما تريد عمدًا تحديث بيئة التشغيل المحلية لديك: ```bash npx -y @agentmemory/agentmemory@latest upgrade ``` تحذير: يُغيّر هذا الأمر مساحة العمل/بيئة التشغيل الحالية. فقد يُحدِّث اعتماديات JavaScript ويسحب صورة Docker المثبَّتة `iiidev/iii:0.22.1`. ولن يُثبّت مطلقًا محرك iii غير مثبَّت الإصدار أو أحدث منه. تفاصيل التنفيذ موجودة في `src/cli.ts` (راجع `runUpgrade` حول نطاق `src/cli.ts:544-595`). ### Claude Code (كتلة واحدة، الصقها) ```text Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall. ``` #### Claude Code بدون تثبيت الإضافة (مسار MCP القائم بذاته) إذا ربطت خادم MCP الخاص بـ agentmemory عبر `~/.claude.json` مباشرة بدلًا من استخدام `/plugin install`، فإن Claude Code لن يحلّ `${CLAUDE_PLUGIN_ROOT}` مطلقًا، وستحتاج إلى توجيه نصوص الخطافات إلى مسارات مطلقة في `~/.claude/settings.json`. وتُضمِّن تلك المسارات عادة إصدار agentmemory (مثل `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`)، فتنكسر جميع الخطافات بصمت عند الترقية التالية. الحل البديل: ```bash agentmemory connect claude-code --with-hooks ``` يُدمج هذا الأمر نفس أوامر الخطافات في `~/.claude/settings.json` بمسارات مطلقة تُحلَّل إلى دليل `plugin/` المُضمَّن في حزمة `@agentmemory/agentmemory` المثبَّتة حاليًا. أعد تشغيل الأمر بعد ترقية agentmemory لتحديث المسارات. تُحفظ إدخالات المستخدم في نفس الملف؛ ويُستبدل إدخالات agentmemory السابقة فقط. يظل استخدام مسار `/plugin install` هو الأسلوب المُوصى به. بالنسبة للنشر عن بُعد أو المحمي، شغّل Claude Code مع ضبط `AGENTMEMORY_URL` و`AGENTMEMORY_SECRET`. تُمرّر الإضافة كلتا القيمتين إلى خادم MCP المُضمَّن بها؛ وعندما يكون `AGENTMEMORY_URL` فارغًا، يستخدم وسيط MCP (shim) عنوان `http://localhost:3111`. ### Codex CLI (منصة إضافات Codex) ```bash # 1. start the memory server in a separate terminal npx -y @agentmemory/agentmemory@latest # 2. register the agentmemory marketplace and install the plugin codex plugin marketplace add rohitg00/agentmemory codex plugin add agentmemory@agentmemory ``` تُشحن إضافة Codex من نفس دليل `plugin/` الذي تُشحن منه إضافة Claude Code. وهي تُسجِّل: - جسر MCP مُضمَّن من نوع stdio إلى العفريت (daemon) العامل، دون تنزيل npm أو مخزن احتياطي (fallback). راجع [دليل Codex المحلي](../docs/plugins/codex-local.md) لاختبار إصدار (build) غير منشور. - 6 خطافات لدورة الحياة: `SessionStart` و`UserPromptSubmit` و`PreToolUse` و`PostToolUse` و`PreCompact` و`Stop` - 9 مهارات قابلة للاستدعاء: `/recall` و`/remember` و`/session-history` و`/forget` و`/recap` و`/handoff` و`/lesson` و`/commit-context` و`/commit-history`، بالإضافة إلى 8 مهارات مرجعية يُحمّلها الوكيل عند الطلب (انضباط الذاكرة، وأدوات MCP، وواجهة REST API، والإعدادات، والوكلاء، والخطافات، والبنية المعمارية، ودليل تأليف المهارات) يحقن محرك خطافات Codex متغيّر `CLAUDE_PLUGIN_ROOT` في العمليات الفرعية للخطافات (حسب [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs))، لذا تعمل نصوص الخطافات نفسها على كلتا البيئتين دون تكرار. أما أحداث Subagent وSessionEnd وNotification وTaskCompleted وPostToolUseFailure فهي خاصة بـ Claude Code فقط، ولا تُسجَّل في Codex. #### ثقة خطافات Codex والتوافق تم التحقق من إرسال خطافات الإضافة الأصلية (native) مع Codex CLI 0.150.1. ثِق بخطافات الإضافة قبل أن تتوقع الالتقاط (capture). يعتمد سلوك Desktop على وقت التشغيل (runtime) المُضمَّن فيه؛ تحقّق من `/hooks` وتأكّد من التقاط حدث قبل تفعيل حل بديل. إذا كان المضيف (host) الخاص بك يتطلب خطافات عامة (global)، فاعكس الأوامر إلى `~/.codex/hooks.json`. وعندما يكون MCP موصولًا بالفعل، يحتاج المحوّل الحالي إلى `--force` للوصول إلى تثبيت الخطافات: ```bash agentmemory connect codex --with-hooks --force ``` يدمج هذا الخطافات العامة (global) ويعيد كتابة إدخال agentmemory MCP، مع الحفاظ على الإدخالات غير المرتبطة. راجع أي إعدادات نقطة نهاية (endpoint) مخصصة لـ agentmemory قبل استخدام `--force`. أعد التشغيل بعد الترقية لتحديث مسارات النصوص. فعِّل خطافات الإضافة الأصلية أو النُّسخ العامة لتجنّب الالتقاط المكرر. ### GitHub Copilot CLI لوضع الوكيل (agent mode) في VS Code، استخدم [دليل Copilot MCP والالتقاط التلقائي](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions). لا يضبط محوّل CLI إعدادات VS Code. ```bash # MCP-only wiring agentmemory connect copilot-cli # Alternatively, full hooks/skills plugin from the GitHub subdir copilot plugin install rohitg00/agentmemory:plugin ``` يُدمج أمر `agentmemory connect copilot-cli` مفتاح `mcpServers.agentmemory` في `~/.copilot/mcp-config.json` (أو في `$COPILOT_HOME/mcp-config.json` عند ضبط `COPILOT_HOME`)، ويحافظ على الخوادم الموجودة مسبقًا. على Windows الأصلي، هذا هو محوّل `connect` الآلي الوحيد؛ أما بقية وكلاء Windows الأصليين فيجب ضبطهم يدويًا. ولا يُدعم `connect` عبر WSL إلا عندما يكون الوكيل المستهدف مثبَّتًا في بيئة WSL نفسها. يلتقط Copilot خادم MCP عند التشغيل التالي أو بعد تنفيذ `/mcp`. ثبّت الإضافة أيضًا إذا رغبت في تجربة الخطافات/المهارات الكاملة.

OpenClaw (الصق هذا الموجّه)

```text Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools: { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`. ``` الدليل الكامل: [`integrations/openclaw/`](../integrations/openclaw/)

وكيل Hermes (الصق هذا الموجّه)

```text Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools: mcp_servers: agentmemory: command: npx args: ["-y", "@agentmemory/mcp"] memory: provider: agentmemory Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory. ``` الدليل الكامل: [`integrations/hermes/`](../integrations/hermes/)

### وكلاء آخرون شغّل خادم الذاكرة: `npx -y @agentmemory/agentmemory@latest` #### المهارات الأصلية عبر `npx skills add` (أكثر من 50 وكيلًا) يشحن agentmemory 17 مهارة بتنسيق `/SKILL.md` على طراز Claude Code: 9 مهارات فعل قابلة للاستدعاء (`remember` و`recall` و`recap` و`handoff` و`forget` و`lesson` و`commit-context` و`commit-history` و`session-history`) و8 مهارات مرجعية يُحمّلها الوكيل عند الطلب (`memory-discipline` و`agentmemory-mcp-tools` و`agentmemory-rest-api` و`agentmemory-config` و`agentmemory-agents` و`agentmemory-hooks` و`agentmemory-architecture` و`write-agentmemory-skill`). تحمل المهارات المرجعية جداول بيانات مُولَّدة من المصدر، فلا تنحرف عنه أبدًا. تقوم واجهة سطر الأوامر [`skills`](https://npmjs.com/package/skills) من vercel-labs بتثبيتها آليًا في دليل المهارات الأصلي للوكيل المستدعي عبر أكثر من 50 وكيلًا (Claude Code وCursor وCline وContinue وDroid وWarp وCodex وAntigravity وKiro وOpenCode وGoose وRoo وTrae وWindsurf، وغيرها): ```bash npx skills add rohitg00/agentmemory -y # auto-detects the calling agent npx skills add rohitg00/agentmemory -y -a warp # explicit agent npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent ``` هذا **مُكمِّل** لأمر `agentmemory connect `: - يكتب `agentmemory connect ` إعدادات خادم MCP بحيث تصبح الأدوات متاحة. - يُثبّت `npx skills add rohitg00/agentmemory` المهارات بحيث يعرف الوكيل متى يستدعيها. بالنسبة للوكلاء القليلين الذين لا تغطيهم واجهة سطر الأوامر skills بعد (Zed بالإصدار v1.3.x وما قبله)، ضع ملفات SKILL.md الـ17 بنفسك تحت دليل المهارات الأصلي للوكيل؛ فالتنسيق نفسه يعمل في كل مكان. #### كتلة MCP القياسية إدخال agentmemory هو **كتلة خادم MCP نفسها** في كل مضيف يستخدم شكل `mcpServers` (Cursor وClaude Desktop وCline وRoo Code وGemini CLI وOpenClaw): ```json "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "${AGENTMEMORY_URL}", "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}" } } ``` **ادمج هذا الإدخال في كائن `mcpServers` الموجود مسبقًا** في ملف إعدادات المضيف؛ لا تستبدل الملف بالكامل. إذا كان الملف يحتوي على خوادم أخرى مسبقًا، أضف `agentmemory` بجانبها كمفتاح آخر داخل `mcpServers`. وإذا كان `mcpServers` غير موجود بالمرة، الصق الكتلة داخل `{ "mcpServers": { ... } }`. تستمد العناصر النائبة `${VAR}` قيم `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` من الصدفة (shell) عند تشغيل خادم MCP؛ وتُمرِّر المتغيرات غير المضبوطة نصًا فارغًا، فيعود الوسيط (shim) إلى `http://localhost:3111`. يغطي إدخال واحد مُهيَّأ كلًا من النشر المحلي والبعيد (k8s / عبر وكيل عكسي). | الوكيل | ملف الإعدادات | ملاحظات | |---|---|---| | **Cursor (MCP فقط)** | `~/.cursor/mcp.json` | ادمج داخل `mcpServers`، أو استخدم `agentmemory connect cursor`. يتوفر أيضًا رابط تفعيل بنقرة واحدة (deeplink) على الموقع. | | **Cursor (الإضافة الكاملة)** | `.cursor-plugin/` | قائمة في Cursor Marketplace (الطلب قيد المراجعة) أو عبر Cursor Settings ← Plugins ← نسخة محلية. تُسجِّل 7 خطافات التقاط تلقائي (sessionStart و beforeSubmitPrompt و preToolUse و postToolUse و postToolUseFailure و stop و sessionEnd) + 17 مهارة + خادم MCP، مع إدارة `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` من لوحة إضافات Cursor. يعمل في بيئة Cursor IDE وفي واجهة `cursor-agent` CLI؛ وتُستكمل مطالبات وضع الطباعة في CLI من محضر الجلسة عند انتهائها. | | **Claude Desktop** | `claude_desktop_config.json` (في Application Support) | ادمج داخل `mcpServers`. أعد تشغيل Claude Desktop بعد التعديل. | | **Cline / Roo Code / Kilo Code** | إعدادات MCP في Cline (واجهة Settings ← MCP Servers ← Edit) | نفس كتلة `mcpServers`. | | **Devin CLI (MCP + خطافات)** | `~/.config/devin/config.json` | يدمج `agentmemory connect devin` إدخال MCP؛ ويضيف `--with-hooks` ستة خطافات التقاط تلقائي أصلية (SessionStart و UserPromptSubmit و PreToolUse و PostToolUse و Stop و SessionEnd) مع مطابقات أدوات Devin بالحروف الصغيرة. تحقّق باستخدام `devin mcp list` وأمر `/hooks` داخل devin. | | **Devin CLI (الإضافة الكاملة)** | `plugin/.devin-plugin/` | يُسجِّل أمر `devin plugins install ./plugin` من نسخة محلية جميع المهارات الـ17 كأوامر شرطة `/agentmemory:` إضافة إلى خادم MCP. لا يمكن لخطافات إضافة Devin إطلاق `SessionStart`/`SessionEnd`، فاجمعها مع `connect devin --with-hooks` للحصول على التقاط كامل للجلسة. | | **Devin (السحابة)** | Settings ← Connections ← MCP servers | أضف MCP مخصصًا (STDIO): الأمر `npx`، والوسائط `-y @agentmemory/mcp@latest`، ومتغير البيئة `AGENTMEMORY_URL` يشير إلى نشر agentmemory يمكن الوصول إليه عبر الشبكة، إضافة إلى `AGENTMEMORY_SECRET` (لا يمكن لجلسات السحابة الوصول إلى localhost — راجع [`deploy/`](../deploy/)). خزّن السر في Devin Secrets، ثم استخدم "Test listing tools" للتحقق من ظهور جميع الأدوات الـ54. | | **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (يدمج تلقائيًا). | | **GitHub Copilot CLI (MCP فقط)** | `~/.copilot/mcp-config.json` | يدمج `agentmemory connect copilot-cli` مفتاح `mcpServers.agentmemory`؛ ويلتقطه Copilot عند التشغيل التالي أو عبر `/mcp`. | | **GitHub Copilot CLI (الإضافة الكاملة)** | تثبيت إضافة Copilot | `copilot plugin install rohitg00/agentmemory:plugin` لتثبيت الإضافة من الدليل الفرعي على GitHub. | | **OpenClaw** | إعدادات MCP في OpenClaw | نفس كتلة `mcpServers`. للتكامل الأعمق: يستحوذ `openclaw plugins install ./integrations/openclaw` على فُتحة الذاكرة (memory slot) في OpenClaw (ينتقل تلقائيًا من `memory-core`)؛ اضبط `plugins.entries.agentmemory.hooks.allowConversationAccess=true` وإلا يُحجب التقاط المداولة بصمت. راجع [`integrations/openclaw`](../integrations/openclaw/). | | **Codex CLI (MCP فقط)** | `.codex/config.toml` | بصيغة TOML: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`، أو أضف `[mcp_servers.agentmemory]` يدويًا. | | **Codex CLI (الإضافة الكاملة)** | سوق إضافات Codex | `codex plugin marketplace add rohitg00/agentmemory` ثم `codex plugin add agentmemory@agentmemory`. يُسجِّل MCP + 6 خطافات دورة حياة + 17 مهارة. ثِق بالخطافات وتحقّق من الالتقاط في مضيفك (host)؛ راجع [إعداد Codex والتحقق منه](../docs/plugins/codex-local.md). | | **OpenCode (MCP فقط)** | `opencode.json` | بصيغة مختلفة: مفتاح `mcp` على المستوى الأعلى، والأمر كمصفوفة: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. | | **OpenCode (الإضافة الكاملة)** | `plugin/opencode/` | 22 خطاف التقاط تلقائي تغطي دورة حياة الجلسة والرسائل والأدوات والأخطاء. ويُحدَّد المشروع لكل جلسة على حدة، فعملية OpenCode واحدة تمتد عبر عدة مستودعات تُسجِّل كل جلسة تحت مشروعها الخاص بها. أمرا شرطة اثنان (`/recall` و`/remember`). انسخ `plugin/opencode/` إلى مساحة عمل OpenCode الخاصة بك وأضف إدخال الإضافة إلى `opencode.json`. راجع [`plugin/opencode/README.md`](../plugin/opencode/README.md) للحصول على جدول الخطافات الكامل وتحليل الثغرات. | | **pi** | `~/.pi/agent/extensions/agentmemory` | يُثبّت `agentmemory connect pi` الإضافة المُضمَّنة في دليل الاكتشاف التلقائي لـ pi (استرجاع عند بدء الوكيل، والتقاط عند انتهائه، وأدوات `memory_search` / `memory_save` / `memory_health`، و`/agentmemory-status`). يلتقطها أمر `/reload` في pi قيد التشغيل. كما أن [`integrations/pi`](../integrations/pi/) حزمة pi أيضًا (`pi install ./integrations/pi` من نسخة محلية). | | **وكيل Hermes** | `~/.hermes/config.yaml` | يمنحك `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory` مزوّد ذاكرة بستة خطافات (جلب مسبق، والتقاط المداولة، وانتهاء الجلسة، وما قبل الضغط، ومرآة لـ MEMORY.md، وكتلة موجّه النظام). تحقّق باستخدام `hermes plugins doctor` و`hermes memory status`. راجع [`integrations/hermes`](../integrations/hermes/). | | **Qwen Code** | `~/.qwen/settings.json` | يكتب `agentmemory connect qwen` كتلة `mcpServers` القياسية. حمولة الخطاف متوافقة الحقول مع Claude Code، فتعمل نصوص الخطافات الـ12 الموجودة دون أي تعديل؛ اربطها عبر قسم `hooks` في نفس ملف `settings.json`. | | **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | يُثبِّت `agentmemory connect antigravity --with-hooks` خطافات MCP والالتقاط في دليل التخصيص (customization) المشترك. راجع [إعداد Antigravity وحدوده](../docs/plugins/antigravity.md). | | **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | يستخدم `agentmemory connect antigravity-cli --with-hooks` نفس إعدادات MCP والخطافات المستخدمة في إصدارات IDE الحالية. ينبغي للتثبيتات الحالية التحديث باستخدام `--force`؛ راجع [ملاحظات الترقية](../docs/plugins/antigravity.md). | | **Kiro** | `~/.kiro/settings/mcp.json` | يكتب `agentmemory connect kiro` الإعدادات على مستوى المستخدم. وتوضع تجاوزات مساحة العمل في `.kiro/settings/mcp.json` بجانب شفرتك. | | **Warp** | `~/.warp/.mcp.json` | يكتب `agentmemory connect warp` كتلة `mcpServers` القياسية. يكتشف Warp أيضًا المهارات تلقائيًا من `.claude/skills/`؛ وبمجرد تثبيت إضافة Claude Code، تظهر مهارات agentmemory الثماني (`remember` و`recall` و`recap` و`handoff` و`forget` و`commit-context` و`commit-history` و`session-history`) أصليًا في لوحة أوامر الشرطة في Warp. | | **Cline (CLI)** | `~/.cline/mcp.json` | يكتب `agentmemory connect cline` كتلة `mcpServers` القياسية. لمستخدمي إضافة VS Code: الصق الكتلة نفسها عبر Cline Settings ← MCP Servers ← Edit JSON. | | **Continue.dev** | `~/.continue/config.yaml` (مفضّل) أو `config.json` (قديم) | يُنشئ `agentmemory connect continue` ملف `config.yaml` من الصفر إن لم يوجد أي منهما، أو يُعدِّل `config.json` الموجود مسبقًا. **إذا كان لديك `config.yaml` مسبقًا**، يطبع المحوّل الكتلة الدقيقة لتلصقها تحت `mcpServers:`؛ ولن يُعيد كتابة ملف yaml بصمت لأن الحفاظ الآمن على التعليقات والمراسي يتطلب مُحلِّل YAML لا تشحنه الحزمة. يستخدم Continue الصيغة المصفوفية (لا الكائنية) لـ `mcpServers`. | | **Zed** | `~/.config/zed/settings.json` | يكتب `agentmemory connect zed` تحت `context_servers` (مفتاح Zed الخاص، وليس `mcpServers`). يمكن ربط خوادم MCP البعيدة بدلًا من ذلك عبر `{"url": "..."}`. | | **Droid (Factory.ai)** | `~/.factory/mcp.json` | يكتب `agentmemory connect droid` كتلة `mcpServers` القياسية. وتوضع تجاوزات نطاق المشروع في `/.factory/mcp.json`. مرّر `--with-hooks` لالتقاط تلقائي أصلي. | | **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | يُضيف `agentmemory connect dsh` صفًا من نوع `@deepseek-ai/dsh-mcp-client` إلى طبقة الترقيع على مستوى الدليل الرئيسي التي يحمّلها كل ملف تعريف في Harness؛ وتُسجَّل الأدوات بصيغة `mcp__agentmemory__*`. مرّر `--with-hooks` لربط الالتقاط التلقائي أيضًا: تعمل نصوص خطافات Claude Code المُضمَّنة عبر جسر `@deepseek-ai/dsh-hooks-claude-code` الأصلي الخاص بـ Harness (SessionStart و UserPromptSubmit و PreToolUse و PostToolUse و Stop) من خلال بيان يُكتب في `$DSH_HOME/agentmemory.hooks.json`. يُستخدم `~/.dsh` افتراضيًا عندما لا يكون `DSH_HOME` مضبوطًا. | | **Goose** | واجهة إعدادات MCP في Goose | نفس كتلة `mcpServers`؛ استخدم `goose configure` ← Add Extension ← MCP. يُدعم التعديل المباشر لملف YAML في `~/.config/goose/config.yaml`، لكن المخطط يستخدم `extensions:` + `cmd` (وليس `mcpServers:` + `command`). | | **Aider** | لا ينطبق | تحدَّث مباشرة مع REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. | | **أي وكيل (أكثر من 32)** | لا ينطبق | يكتشف `npx skillkit install agentmemory` المضيف تلقائيًا ويدمج الإعدادات. | **عملاء MCP المحتجزون في بيئة معزولة (sandbox)** (Flatpak / Snap / الحاويات المقيَّدة) الذين لا يمكنهم الوصول إلى `localhost` الخاص بالمضيف: اضبط أيضًا `"AGENTMEMORY_FORCE_PROXY": "1"` في كتلة `env`، ووجِّه `AGENTMEMORY_URL` إلى مسار يمكن للبيئة المعزولة الوصول إليه فعليًا (مثل عنوان IP على شبكتك المحلية). ### الوصول البرمجي (Python / Rust / Node) يُسجِّل agentmemory عملياته الأساسية كدوال iii (`mem::remember` و`mem::observe` و`mem::context` و`mem::smart-search` و`mem::forget`). يمكن لأي لغة تملك SDK لـ iii استدعاءها مباشرة عبر `ws://localhost:49134`، دون الحاجة إلى عميل REST منفصل لكل لغة. ```bash pip install iii-sdk # Python cargo add iii-sdk # Rust npm install iii-sdk # Node ``` ```python from iii import register_worker iii = register_worker("ws://localhost:49134") iii.connect() iii.trigger({ "function_id": "mem::smart-search", "payload": {"project": "demo", "query": "how do tokens refresh"}, }) ``` مثال عملي: [`examples/python/`](../examples/python/) (بدء سريع + مسار الملاحظة/الاسترجاع). تظل REST على `:3111` متاحة للمضيفين الذين لا تتوفر لديهم بيئة تشغيل iii. ### من المصدر ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` يُشغِّل هذا agentmemory مع `iii-engine` محلي إذا كان الملف التنفيذي المثبَّت مُثبَّتًا مسبقًا، أو يستخدم Docker Compose عند اختياره. ترتبط REST والتيارات والعارض بـ `127.0.0.1` افتراضيًا. ويتطلب مسار الملف التنفيذي الآلي على macOS/Linux وجود `curl` وصدفة POSIX من نوع `sh` وأداة `tar`. ثبّت `iii-engine` يدويًا. **يُثبّت agentmemory حاليًا `iii-engine` على الإصدار `v0.22.1`**، وهو نفس إصدار اعتمادية `iii-sdk` الخاصة به؛ فالعامل يتحدث بروتوكول الاتصال الخاص بذلك المحرك، وقد أعاد الإصدار 0.20.0 تنظيم سطح SDK، فيتحرك الاثنان معًا في إصدارات agentmemory. تجاوز ذلك باستخدام `AGENTMEMORY_III_VERSION=` إذا كنت تُشغِّل محركك الخاص وتعرف أنه متوافق. - **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii` - **macOS x64:** استبدل `aarch64-apple-darwin` بـ `x86_64-apple-darwin` - **Linux x64:** استبدل بـ `x86_64-unknown-linux-gnu` - **Linux arm64:** استبدل بـ `aarch64-unknown-linux-gnu` - **Windows:** نزِّل `iii-x86_64-pc-windows-msvc.zip` من [إصدارات iii-hq/iii v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1) واستخرج `iii.exe` إلى `%USERPROFILE%\.agentmemory\bin\iii.exe` يملك كل أرشيف ملف `.sha256` مطابقًا على صفحة الإصدار؛ وعند تبديل النظام الأساسي، استخدم بصمة ذلك الملف (hash) في عملية التحقق أعلاه (على Windows: `Get-FileHash`). يُثبِّت المُثبِّت الآلي في `npx @agentmemory/agentmemory` هذه البصمات ويرفض أي أرشيف لا يطابقها. أو استخدم Docker (يسحب ملف `docker-compose.yml` المُضمَّن الصورة `iiidev/iii:0.22.1`). المستندات الكاملة: [iii.dev/docs](https://iii.dev/docs). ### Windows يعمل agentmemory على Windows 10/11، لكن حزمة Node.js وحدها لا تكفي؛ فأنت تحتاج أيضًا إلى بيئة تشغيل iii-engine المثبَّتة v0.22.1 كعملية خلفية. لا تستخرج الواجهة الطرفية CLI أرشيف ZIP الخاص بـ Windows تلقائيًا، فيجب على مستخدمي Windows الأصليين تثبيت `iii.exe` يدويًا، أو استخدام WSL2، أو اختيار Docker Desktop. لا يدعم الربط الآلي لـ MCP على Windows الأصلي إلا `agentmemory connect copilot-cli`. أما بالنسبة لـ Claude Code وCodex وCursor وكل وكيل Windows أصلي آخر، فانسخ كتلة MCP اليدوية من [وكلاء آخرون](#other-agents) إلى إعدادات Windows لذلك الوكيل. وتشغيل `connect` في WSL مناسب فقط عندما يكون الوكيل المستهدف مثبَّتًا أيضًا في بيئة WSL نفسها؛ فهو لا يُعدِّل إعدادات وكيل يستضيفه Windows. **الخيار أ: ملف تنفيذي جاهز لـ Windows (مُوصى به)** ```powershell # 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser # (agentmemory pins the engine to the same release as its iii-sdk; # v0.22.1 is the current pair) # 2. Download iii-x86_64-pc-windows-msvc.zip # (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine) # 3. Extract iii.exe to agentmemory's private engine directory: New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin" # Copy iii.exe to $HOME\.agentmemory\bin\iii.exe # 4. Verify: & "$HOME\.agentmemory\bin\iii.exe" --version # Should print: 0.22.1 # 5. Then run agentmemory as usual: npx -y @agentmemory/agentmemory@latest ``` **الخيار ب: Docker Desktop** ```powershell # 1. Install Docker Desktop for Windows # 2. Start Docker Desktop and make sure the engine is running # 3. Select Docker explicitly and run agentmemory: $env:AGENTMEMORY_USE_DOCKER = "1" npx -y @agentmemory/agentmemory@latest ``` **الخيار ج: MCP قائم بذاته فقط (بلا محرك).** إذا كنت تحتاج فقط إلى أدوات MCP لوكيلك ولا تحتاج إلى REST API أو العارض أو مهام cron، تجاوز المحرك كليًا: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or via the shim package: npx -y @agentmemory/mcp ``` **تشخيص الأعطال على Windows:** إذا فشل `npx -y @agentmemory/agentmemory@latest`، أعد تشغيله مع `--verbose` لرؤية مخرجات stderr الفعلية للمحرك. أنماط الفشل الشائعة: | العارض | الإصلاح | |---|---| | `The engine process started but the REST API never responded.` | تأكّد من أن المنافذ الأربعة المُستمَدَّة كلها خالية، وتحقَّق من بقاء `iii.exe` المثبَّت على قيد العمل، ثم أعد التشغيل مع `--verbose` وافحص stderr المُسجَّل للمحرك | | `Could not start iii-engine` | لا `iii.exe` ولا Docker مثبَّتان. راجع الخيار أ أو ب أعلاه | | تعارض في المنفذ | استخدم `netstat -ano \| findstr :3111` لمعرفة ما هو مرتبط بالمنفذ، ثم أنهِ تلك العملية أو استخدم `--port ` | | تجاوز الرجوع إلى Docker رغم تثبيت Docker | تأكّد من أن Docker Desktop يعمل فعليًا (أيقونة في علبة النظام) | > ملاحظة: **محرك** iii هو ملف تنفيذي جاهز مسبقًا، وليس صندوق (crate) من cargo، فلا تحاول تثبيته بأمر `cargo install`. (تُنشر **حِزم SDK** الخاصة بـ iii على crates.io وnpm وPyPI، لكن agentmemory لا يحتاج إليها.) جميع طرق تثبيت المحرك المدعومة مثبَّتة على الإصدار v0.22.1: الملف التنفيذي الجاهز أعلاه، ومسار التثبيت الآلي لـ agentmemory على macOS/Linux (يتطلب `curl` وصدفة POSIX من نوع `sh` وأداة `tar`)، وصورة Docker `iiidev/iii:0.22.1`. أما تشغيل سكربت المصدر الأساسي العاري `install.sh | sh` فيُثبّت أحدث المحرك، وهو ما لا يدعمه agentmemory. استخدم `npx -y @agentmemory/agentmemory@latest`؛ فهو يجلب المحرك المثبَّت على macOS/Linux إلى `~/.agentmemory/bin`. ---

النشر

قوالب نشر بنقرة واحدة للمضيفين المُدارين. يشحن كل قالب ملف Dockerfile قائمًا بذاته يسحب `@agentmemory/agentmemory` من npm، وينسخ الملف التنفيذي لمحرك iii من صورة `iiidev/iii` الرسمية على Docker Hub؛ فلا حاجة إلى صورة agentmemory مبنية مسبقًا. يُركَّب التخزين الدائم عند `/data`؛ ويستبدل سكربت الدخول (entrypoint) في أول تشغيل إعدادات iii المُضمَّنة في npm (التي ترتبط بـ `127.0.0.1`) بإعدادات مضبوطة للنشر ترتبط بـ `0.0.0.0` وتستخدم مسارات `/data` المطلقة، وتُولِّد سر HMAC، ثم تتنازل عن الصلاحيات من `root` إلى `node` عبر `gosu` قبل تنفيذ واجهة agentmemory CLI.

يتطلب زر نشر Render بنقرة واحدة وجود `render.yaml` في جذر المستودع، وهو ما نتركه نظيفًا عمدًا. استخدم مسار Render Blueprint المُوثَّق في [`deploy/render/`](.././deploy/render/README.md) للإشارة يدويًا إلى المخطط الموجود في المستودع. تفاصيل الإعداد الكاملة (التقاط HMAC، ونفق SSH للعارض، والتدوير، والنسخ الاحتياطي، والحدود الدنيا للتكلفة) موجودة في [`deploy/`](.././deploy/README.md): - [`deploy/fly`](.././deploy/fly/README.md): جهاز واحد مع `auto_stop_machines = "stop"`؛ الأرخص عند الخمول. - [`deploy/railway`](.././deploy/railway/README.md): رسم ثابت لخطة Hobby، والحجم التخزيني من لوحة التحكم. - [`deploy/render`](.././deploy/render/README.md): مسار Blueprint، لقطات قرص تلقائية في الخطط المدفوعة. - [`deploy/coolify`](.././deploy/coolify/README.md): استضافة ذاتية على خادمك الخاص عبر [Coolify](https://coolify.io/self-hosted)؛ نفس حزمة Docker Compose، وأنت من يملك المضيف والبيانات. لا يُنشر إلا المنفذ `3111`. ويبقى العارض على `3113` مرتبطًا بعنوان loopback داخل الحاوية؛ ويوثِّق ملف README لكل قالب نمط نفق SSH للوصول إليه. ---

ينسى كل وكيل ترميز كل شيء عند انتهاء الجلسة، وتبدأ كل جلسة جديدة بإعادتك شرح مكدّسك التقني من جديد. يعمل agentmemory في الخلفية ويُزيل تلك الخطوة. ```text Session 1: "Add auth to the API" Agent writes code, runs tests, fixes bugs agentmemory silently captures every tool use Session ends -> observations compressed into structured memory Session 2: "Now add rate limiting" Agent already knows: - Auth uses JWT middleware in src/middleware/auth.ts - Tests in test/auth.test.ts cover token validation - You chose jose over jsonwebtoken for Edge compatibility Zero re-explaining. Starts working immediately. ``` ### مقابل ذاكرة الوكيل المدمجة يشحن كل وكيل ترميز بذكاء اصطناعي بذاكرة مدمجة: فـ Claude Code يملك `MEMORY.md`، وCursor يملك notepads، وCline يملك memory bank. تعمل هذه كملاحظات لاصقة (sticky notes). أما agentmemory فهو قاعدة البيانات القابلة للبحث التي تقف خلف تلك الملاحظات اللاصقة. | | مدمج (CLAUDE.md) | agentmemory | |---|---|---| | الحجم | حد 200 سطر | غير محدود | | البحث | يحمّل كل شيء إلى السياق | BM25 + متجهات + رسم بياني (أفضل K فقط) | | تكلفة الرموز | أكثر من 22K عند 240 ملاحظة | ~1,900 رمز (أقل بنسبة 92%) | | بين الوكلاء | ملفات لكل وكيل | MCP + REST (أي وكيل) | | التنسيق | لا يوجد | حجوزات، وإشارات، وإجراءات، ومسارات عمل (routines) | | قابلية الرصد | قراءة الملفات يدويًا | عارض لحظي على :3113 | ---

### مسار الذاكرة ```text PostToolUse hook fires -> SHA-256 dedup (5min window) -> Privacy filter (strip secrets, API keys) -> Store raw observation -> Synthetic compression by default (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true) -> Vector embedding when an embedding provider is active -> Index in BM25, plus vectors when enabled Stop / SessionEnd hook fires -> Summarize session -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true) -> Slot reflection (if SLOT_REFLECT_ENABLED=true) SessionStart hook fires -> Load project profile (top concepts, files, patterns) -> Hybrid search (BM25 + vector + graph) -> Token budget (default: 2000 tokens) -> Inject into conversation ``` ### توحيد الذاكرة الرباعي المستويات مصمَّم على غرار كيفية معالجة العقل البشري للذاكرة، بما في ذلك التوحيد أثناء النوم. | المستوى | المحتوى | المثيل البشري | |------|------|---------| | **العاملة (Working)** | ملاحظات خام من استخدام الأدوات | الذاكرة قصيرة المدى | | **الحدثية (Episodic)** | ملخصات مضغوطة للجلسات | "ما الذي حدث" | | **الدلالية (Semantic)** | حقائق وأنماط مستخرجة | "ما الذي أعرفه" | | **الإجرائية (Procedural)** | مسارات عمل وأنماط قرارات | "كيف يتم ذلك" | تتلاشى الذكريات بمرور الوقت (منحنى إبنغهاوس). وتتقوّى الذكريات التي يُرجَع إليها كثيرًا. ويُطرَد تلقائيًا الذكريات القديمة البائتة. ويُكتشف التضارب ويُحل. ### ما الذي يُلتَقط | الخطاف | يلتقط | |------|----------| | `SessionStart` | مسار المشروع، ومعرّف الجلسة | | `UserPromptSubmit` | مطالبات المستخدم (مُرشَّحة للخصوصية) | | `PreToolUse` | أنماط الوصول إلى الملفات + سياق مُغنًى | | `PostToolUse` | اسم الأداة، والمدخل، والمخرج | | `PostToolUseFailure` | سياق الخطأ | | `PreCompact` | يُعيد حقن الذاكرة قبل الضغط (compaction) | | `SubagentStart/Stop` | دورة حياة الوكيل الفرعي | | `Stop` | ملخص نهاية الجلسة | | `SessionEnd` | علامة اكتمال الجلسة | ### القدرات الأساسية | القدرة | الوصف | |---|---| | **الالتقاط التلقائي** | يُسجَّل كل استخدام للأدوات عبر الخطافات، دون أي جهد يدوي | | **البحث الدلالي** | BM25 + متجهات + رسم بياني معرفي بدمج RRF | | **تطوّر الذاكرة** | إصدارات، وإحلال (supersession)، ورسوم بيانية للعلاقات | | **نظافة الاسترجاع** | تخرج نسخ الذاكرة المُستبدَلة من فهارس البحث؛ وتحتفظ سلسلة الإصدارات في KV بالتاريخ الكامل | | **تلميحات شبه التكرار** | يُسجِّل الحفظ تطابق `similarTo` استشاريًا عندما يشبه المحتوى الجديد ذكرى موجودة مسبقًا بشكل وثيق | | **تحديد النطاق لكل وكيل** | يمر `agentId` عبر الحفظ والاسترجاع في REST وMCP وفهرس البحث، في الوضع المشترك أو المعزول | | **المصدرية عند الكتابة** | تحمل كل ملاحظة وذكرى قناة أصل ثابتة (مستخدم، وكيل، أداة، استيراد، أو مشترك) تُختم عند الالتقاط والحفظ والاستيراد | | **النسيان التلقائي** | انتهاء صلاحية TTL، وكشف التضارب، وطرد حسب الأهمية | | **الخصوصية أولًا** | تُحذف مفاتيح API والأسرار ووسوم `` قبل التخزين | | **الإصلاح الذاتي** | قاطع دائرة (circuit breaker)، وسلسلة احتياطية للمزوّدين، ورصد صحي | | **جسر Claude** | مزامنة ثنائية الاتجاه مع MEMORY.md | | **الرسم البياني المعرفي** | استخراج الكيانات + تجوال BFS | | **ذاكرة الفريق** | مشترك وخاص مُقسَّم بمساحات أسماء بين أعضاء الفريق | | **مصدرية الاستشهاد** | تتبّع أي ذكرى رجوعًا إلى الملاحظات المصدرية | | **لقطات Git** | إصدار، وتراجع، ومقارنة فروقات لحالة الذاكرة | ---

استرجاع ثلاثي التيار يجمع بين ثلاث إشارات: | التيار | ما يفعله | متى يعمل | |---|---|---| | **BM25** | مطابقة كلمات مفتاحية بعد التجذيع (stemming) مع توسيع بالمرادفات | يعمل دائمًا | | **المتجهات** | تشابه جيب التمام (cosine) عبر تضمينات كثيفة | عند ضبط مزوّد تضمين | | **الرسم البياني** | تجوال في الرسم البياني المعرفي عبر مطابقة الكيانات | عند اكتشاف كيانات في الاستعلام | تُدمج بخوارزمية Reciprocal Rank Fusion (RRF، k=60) وتُنوَّع حسب الجلسة (3 نتائج كحد أقصى لكل جلسة). عندما يكون فهرس المتجهات مُعبَّأً، يستخدم `mem::search` (الذي يقف خلف `memory_recall`) المُصنِّف الهجين BM25 + المتجهات. وبدون تضمينات يستخدم BM25. ويمكن لـ `smart-search` أيضًا دمج تطابقات الرسم البياني البنيوية عندما تتوفر بيانات رسم بياني، حتى في وضع عدم استخدام المفاتيح. ويعمل استرجاع الدروس المستفادة على فهرس BM25 مخصص في الذاكرة بدلًا من مسح المجموعة الكاملة في كل استعلام. وتُستبعد نسخ الذاكرة المُستبدَلة من كل مسار استرجاع؛ وتحتفظ سلسلة الإصدارات بتاريخها. تنجو المتجهات من الانهيار أو الإيقاف القسري. ويُحفظ فهرس المتجهات في حُزَم مرة واحدة على الأكثر كل `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS` (10 دقائق). ويُكتب أيضًا كل متجه يُضاف أو يُحذف بين ذلك فورًا في سجل انتظار صغير في مخزن الحالة، ويُعاد تشغيله عند البدء التالي دون استدعاء مزوّد التضمين. ويُفرَّغ السجل عند كل حفظ ناجح. وتُعاد تضمين المستندات التي لا تزال بلا متجه بعد إعادة التشغيل في الخلفية على دفعات بحجم `AGENTMEMORY_VECTOR_BACKFILL_MAX` (500) إلى أن لا يبقى منها شيء، ويستكمل أي ملء رجعي (backfill) متوقف في البدء التالي. يُظهر `/agentmemory/status` والعارض حجم سجل الانتظار وحالة الملء الرجعي. ولا تكتب التثبيتات بلا مفاتيح أي شيء. يُجزِّئ BM25 إلى رموز (tokens) اليونانية والسيريلية والعبرية والعربية واللاتينية المُشكَّلة جاهزًا دون أي إعداد. وبالنسبة لذكريات الصينية/اليابانية/الكورية، ثبّت المُجزِّئات (segmenters) الاختيارية (`npm install @node-rs/jieba tiny-segmenter`) لتقسيم سلاسل CJK إلى رموز على مستوى الكلمة؛ وبدونها، يتراجع agentmemory بسلاسة إلى تجزيء السلسلة كاملةً ويطبع تلميحًا لمرة واحدة على stderr. ### مزوّدو التضمين تُعطّل التثبيتات بلا مفاتيح تضمينات المتجهات: يستخدم `mem::search` خوارزمية BM25، في حين يمكن لـ `smart-search` أيضًا استخدام بيانات الرسم البياني البنيوية الموجودة مسبقًا. للانضمام الاختياري إلى تضمينات دلالية مجانية على الجهاز نفسه، أضف هذا إلى `~/.agentmemory/.env` وأعد تشغيل agentmemory: ```env EMBEDDING_PROVIDER=local ``` يتضمن تثبيت npm العادي بيئة تشغيل `@huggingface/transformers` الاختيارية. يُنزِّل أول طلب تضمين النموذج `Xenova/all-MiniLM-L6-v2`، لذا يحتاج إلى الوصول إلى الشبكة وقد يستغرق وقتًا أطول؛ ويعمل الاستدلال اللاحق على الجهاز نفسه. ويُكتشف المزوّدون البعيدون تلقائيًا من مفاتيحهم إلا إذا تجاوزهم `EMBEDDING_PROVIDER`. | المزوّد | النموذج | التكلفة | ملاحظات | |---|---|---|---| | **محلي (مُوصى بتفعيله)** | `all-MiniLM-L6-v2` | مجاني | على الجهاز نفسه بعد أول تنزيل للنموذج، وبزيادة 8 نقاط نسبة مئوية في الاسترجاع عن BM25 فقط | | Gemini | `gemini-embedding-001` | مستوى مجاني | أكثر من 100 لغة، أبعاد 768/1536/3072 (MRL)، ومدخل حتى 2048 رمزًا. يحل محل `text-embedding-004` ([مُستبعَد، يُغلق في 14 يناير 2026](https://ai.google.dev/gemini-api/docs/deprecations)) | | OpenAI | `text-embedding-3-small` | 0.02$/مليون | أعلى جودة | | Voyage AI | `voyage-code-3` | مدفوع | مُحسَّن للشفرة | | Cohere | `embed-english-v3.0` | نسخة تجريبية مجانية | للاستخدام العام | | OpenRouter | أي نموذج | متفاوت | وكيل متعدد النماذج | ---

54 أداة، و6 موارد، و3 مطالبات، و17 مهارة. > **وسيط MCP (shim) في مقابل الخادم الكامل:** حزمة `@agentmemory/mcp` المنشورة هي وسيط خفيف (shim). ولا يُظهر سطح الأدوات الكامل البالغ 54 أداة **إلا عندما يستطيع الوصول إلى خادم agentmemory يعمل** عبر `AGENTMEMORY_URL` (وضع الوكيل الوسيط proxy). وإذا تعذّر الوصول إلى أي خادم، يرجع الوسيط إلى مجموعة محلية من 7 أدوات (`memory_save` و`memory_recall` و`memory_smart_search` و`memory_sessions` و`memory_export` و`memory_audit` و`memory_governance_delete`). متغير البيئة `AGENTMEMORY_TOOLS=core|all` هو راية *من جانب الخادم*؛ وضبطه في كتلة `env` الخاصة بالوسيط لا يُحدث أي أثر. إذا رأيت 7 أدوات فقط في Cursor / OpenCode / Gemini CLI، شغّل `npx -y @agentmemory/agentmemory@latest` (أو حزمة Docker) واضبط `AGENTMEMORY_URL=http://localhost:3111`. ### 54 أداة ثلاث واجهات للأدوات، من الأصغر إلى الأكبر: يُقلِّص `AGENTMEMORY_TOOLS=core` مجموعة الأدوات الظاهرة إلى 8 أدوات أساسية (`memory_save` و`memory_recall` و`memory_consolidate` و`memory_smart_search` و`memory_sessions` و`memory_diagnose` و`memory_lesson_save` و`memory_reflect`)؛ وتمثل المجموعة الأساسية أدناه الأدوات التأسيسية الـ14 في السجل؛ أما الوضع الافتراضي (`AGENTMEMORY_TOOLS=all`) فيعرض جميع الأدوات الـ54.

الأدوات الأساسية (14)

| الأداة | الوصف | |------|-------------| | `memory_recall` | البحث في الملاحظات السابقة | | `memory_compress_file` | ضغط ملفات Markdown مع الحفاظ على البنية | | `memory_save` | حفظ استبصار، أو قرار، أو نمط | | `memory_file_history` | الملاحظات السابقة المتعلقة بملفات محددة | | `memory_patterns` | اكتشاف الأنماط المتكررة | | `memory_sessions` | سرد الجلسات الأخيرة | | `memory_smart_search` | بحث هجين دلالي + بكلمات مفتاحية | | `memory_vision_search` | البحث في ملاحظات الصور | | `memory_timeline` | الملاحظات مرتبة زمنيًا | | `memory_profile` | ملف تعريف المشروع (مفاهيم، ملفات، أنماط) | | `memory_export` | تصدير جميع بيانات الذاكرة | | `memory_relations` | الاستعلام عن رسم بياني العلاقات | | `memory_commit_lookup` | الجلسات التي تقف خلف commit في git | | `memory_commits` | عمليات الـ commit المسجَّلة لجلسة ما |

الأدوات الموسَّعة (54 أداة إجمالًا، السطح الافتراضي)

| الأداة | الوصف | |------|-------------| | `memory_patterns` | اكتشاف الأنماط المتكررة | | `memory_timeline` | الملاحظات مرتبة زمنيًا | | `memory_relations` | الاستعلام عن رسم بياني العلاقات | | `memory_graph_query` | تجوال الرسم البياني المعرفي | | `memory_consolidate` | تشغيل التوحيد الرباعي المستويات | | `memory_claude_bridge_sync` | مزامنة مع MEMORY.md | | `memory_team_share` | المشاركة مع أعضاء الفريق | | `memory_team_feed` | العناصر المشتركة الأخيرة | | `memory_audit` | مسار تدقيق العمليات | | `memory_governance_delete` | الحذف مع مسار تدقيق | | `memory_snapshot_create` | لقطة مُؤرَّخة بـ Git | | `memory_action_create` | إنشاء عناصر عمل مع تبعيات | | `memory_action_update` | تحديث حالة إجراء | | `memory_frontier` | الإجراءات غير المحظورة مرتبة حسب الأولوية | | `memory_next` | الإجراء التالي الأهم فقط | | `memory_lease` | حجوزات إجراء حصرية (لتعدد الوكلاء) | | `memory_routine_run` | إنشاء نُسخ من مسارات العمل (routines) | | `memory_signal_send` | التراسل بين الوكلاء | | `memory_signal_read` | قراءة الرسائل مع إيصالات استلام | | `memory_checkpoint` | بوابات شروط خارجية | | `memory_mesh_sync` | مزامنة نظير إلى نظير (P2P) بين النُّسخ | | `memory_sentinel_create` | رُصَد (watchers) مُفعَّلة بالأحداث | | `memory_sentinel_trigger` | تفعيل الرُّصَد خارجيًا | | `memory_sketch_create` | رسوم تخطيطية مؤقتة للإجراءات | | `memory_sketch_promote` | ترقية إلى دائم | | `memory_crystallize` | ضغط سلاسل الإجراءات | | `memory_diagnose` | فحوصات الحالة الصحية | | `memory_heal` | إصلاح تلقائي للحالة المتوقفة | | `memory_facet_tag` | وسوم بُعد:قيمة | | `memory_facet_query` | الاستعلام عبر وسوم الأبعاد | | `memory_verify` | تتبّع المصدرية |

### 6 موارد · 3 مطالبات · 17 مهارة | النوع | الاسم | الوصف | |------|------|-------------| | مورد | `agentmemory://status` | الحالة الصحية، وعدد الجلسات، وعدد الذكريات | | مورد | `agentmemory://project/{name}/profile` | معلومات ذكية خاصة بكل مشروع | | مورد | `agentmemory://project/{name}/recent` | الملاحظات الأخيرة لمشروع ما | | مورد | `agentmemory://memories/latest` | أحدث 10 ذكريات نشطة | | مورد | `agentmemory://graph/stats` | إحصاءات الرسم البياني المعرفي | | مورد | `agentmemory://team/{id}/profile` | ملف تعريف مشترك للفريق | | مطالبة | `recall_context` | البحث + إعادة رسائل السياق | | مطالبة | `session_handoff` | تسليم البيانات بين الوكلاء | | مطالبة | `detect_patterns` | تحليل الأنماط المتكررة | | مهارة | `/recall` | البحث في الذاكرة | | مهارة | `/remember` | الحفظ في الذاكرة طويلة المدى | | مهارة | `/session-history` | ملخصات الجلسات الأخيرة | | مهارة | `/forget` | حذف الملاحظات/الجلسات | يُظهر الجدول المهارات الأساسية الأربع. والمجموعة الكاملة هي 9 مهارات قابلة للاستدعاء إضافة إلى 8 مهارات مرجعية؛ راجع قسم المهارات الأصلية أعلاه. ### MCP القائم بذاته يُشغَّل دون الخادم الكامل، لأي عميل MCP. يعمل كلاهما: ```bash npx -y @agentmemory/agentmemory@latest mcp # canonical (always available) npx -y @agentmemory/mcp # shim package alias ``` أو أضف إلى إعدادات MCP الخاصة بوكيلك: معظم الوكلاء (Cursor وClaude Desktop وCline وRoo Code وGemini CLI): ```json { "mcpServers": { "agentmemory": { "command": "npx", "args": ["-y", "@agentmemory/mcp"], "env": { "AGENTMEMORY_URL": "http://localhost:3111" } } } } ``` ادمج إدخال `agentmemory` في كائن `mcpServers` الموجود مسبقًا في مضيفك بدلًا من استبدال الملف. وبالنسبة للعملاء المحتجزين في بيئة معزولة والذين لا يمكنهم الوصول إلى `localhost` الخاص بالمضيف، أضف `"AGENTMEMORY_FORCE_PROXY": "1"` إلى كتلة env واضبط `AGENTMEMORY_URL` على مسار يمكن للبيئة المعزولة الوصول إليه. OpenCode (`opencode.json`): ```json { "mcp": { "agentmemory": { "type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true } }, "plugin": ["./plugins/agentmemory-capture.ts"] } ``` انسخ ملف الإضافة من المستودع: ```bash mkdir -p ~/.config/opencode/plugins cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/ cp plugin/opencode/commands/*.md ~/.config/opencode/commands/ ``` ---

يبدأ تلقائيًا على المنفذ `3113`. يحمّل العارض لقطة واحدة (snapshot) عند الاتصال (`GET /agentmemory/viewer/snapshot`)، ثم يطبّق أحداث التيار المباشر: تظهر الذكريات الجديدة، والدروس المستفادة، والملاحظات، وإدخالات التدقيق، وتغييرات الرسم البياني، وتحديثات الحالة الصحية دون أي استقصاء دوري أو إعادة تحميل للصفحة. والطلبات الأخرى الوحيدة هي الإجراءات التي تنقر عليها، وصفحات "تحميل المزيد"، وعمليات البحث. وعند انقطاع التيار، يُظهر العارض مدى قِدَم أرقامه، ويعيد الاتصال بتراجع تدريجي (backoff)، ويعيد المزامنة من لقطة واحدة. - **12 تبويبًا في أربع مجموعات** مع عدادات حية، وروابط عميقة (`#memories/`، و`#sessions/?obs=`، و`#graph/`، و`#health/consolidation`)، واختصارات لوحة المفاتيح، وقائمة للهاتف المحمول. - **الذكريات:** بحث من جانب الخادم، ومرشِّحات حسب المشروع والوكيل والنوع، ولوحة تفاصيل تضم سلسلة الإصدارات ومقارنة فروق الكلمات (word diff)، وروابط المصدرية، وأزرار نسخ للمعرّف، واستدعاء MCP، وأمر curl، وتعديل (ينشئ إصدارًا جديدًا)، ونسيان مع تأكيد، ونسيان جماعي، وتصدير JSON. - **الجلسات:** خط زمني مضمَّن للملاحظات بمدخلات ومخرجات أدوات قابلة للقراءة، ومرشِّحات وتصفّح بالصفحات، والذكريات والدروس المستفادة التي أنتجتها كل جلسة. - **الرسم البياني:** بحث، وتفاصيل العُقَد مع العلاقات والمصادر، ومفتاح توضيحي (legend) لا يعتمد على اللون وحده، وأدوات تحكم بالتقريب (zoom). - **الحالة الصحية:** النسخة المباشرة من `GET /agentmemory/status`. تأتي كل مشكلة مع إصلاحها، إضافة إلى خلفية الحالة، وحالة حفظ الفهرس، وتقدّم ضغط مصدرية الرسم البياني، وشرح للتوحيد يضم العتبات الفعلية. - صفحات **التدقيق، والنشاط، وملف التعريف، وإعادة التشغيل، والدروس المستفادة، والإجراءات، والبلورات (Crystals)**، وكل صفحة منها لها حالة فراغ تشرح ما هو هذا القسم، ولماذا هو فارغ، والأمر الذي يملؤه، إضافة إلى تلميح مسرد (glossary) بعلامة `?` عند كل مصطلح وعدد. ```bash open http://localhost:3113 ``` يرتبط خادم العارض بـ `127.0.0.1` افتراضيًا، ويُرفق سر الخادم عند تمرير الطلبات إلى REST API، فلا يحتاج إلى أي إعداد. وتتبع نقطة النهاية `/agentmemory/viewer` المُقدَّمة عبر REST القواعد العادية لرمز الحامل (bearer token)، وتُعيد توجيه المتصفحات التي لا تحمل رمزًا إلى منفذ العارض. وتستخدم ترويسات CSP قيمة nonce خاصة بالنص البرمجي لكل استجابة، وتُعطِّل سمات المعالج المضمَّنة inline (`script-src-attr 'none'`). ---

يُظهر العارض على `:3113` ما **تذكّره** وكيلك. أما [لوحة تحكم iii](https://iii.dev/docs/console) فتُظهر ما **فعله** وكيلك: كل عملية ذاكرة كتتبع OpenTelemetry، وكل إدخال KV قابل للتعديل، وكل دالة قابلة للاستدعاء، وكل تيار قابل للاستماع إليه. نافذتان على الذاكرة نفسها: واحدة بشكل المنتج، وأخرى بشكل المحرك. شاهد `memory_smart_search` وهو يُطلَق وتابع مسح BM25 ← البحث في التضمينات ← دمج RRF ← إعادة الترتيب (reranker) كشكل شلالي (waterfall). عدِّل مؤقِّت توحيد عالقًا في مستعرض KV. أعد تشغيل خطاف `PostToolUse` بحمولة مُعدَّلة. ثبِّت تيار WebSocket وشاهد الملاحظات وهي تصل لحظيًا. يقدّم agentmemory هذا مجانًا لأن كل استدعاء دالة ومحفِّز يمر عبر iii؛ فلا شيء مخصص، ولا شيء يحتاج إلى تثبيت أدوات قياس (instrumentation).

صفحة العمّال: كل عامل متصل، بما في ذلك agentmemory نفسه، مع PID، وعدد الدوال، وبيئة التشغيل، وآخر ظهور.

**مثبَّت مسبقًا.** تُشحن لوحة التحكم مع محرك `iii` المثبَّت (0.22 وما بعده)؛ فلا حاجة إلى تثبيت أي شيء منفصل. يُنزِّل أول تشغيل الملف التنفيذي للوحة التحكم بجانب المحرك. **التشغيل جنبًا إلى جنب مع agentmemory:** ```bash agentmemory console ``` يُشغِّل هذا أمر `iii console` الخاص بالمحرك المثبَّت على المنافذ التي حلّلها agentmemory (REST، والتيارات، والجسر)، ويقدّمه على منفذ واحد أعلى من العارض، أي `http://localhost:3114` افتراضيًا. يختار `--console-port N` منفذًا آخر؛ ويختار `--port` و`--instance` نسخة agentmemory بنفس الطريقة التي يفعلانها مع `stop`؛ وتُمرَّر أي راية أخرى كما هي، مثل `--enable-flow` لصفحة الرسم البياني المعماري التجريبية. نفس الأمر يدويًا، وهو مفيد عندما لا يكون `agentmemory` موجودًا في PATH: ```bash ~/.agentmemory/bin/iii console --port 3114 \ --engine-port 3111 \ --ws-port 3112 \ --bridge-port 49134 ``` **ما يمكنك فعله من لوحة التحكم:** | الصفحة | استخدمها لـ | |------|-----------| | **العمّال (Workers)** | رؤية كل عامل متصل ومقاييسه الحية، بما في ذلك عامل agentmemory نفسه. | | **الدوال (Functions)** | استدعاء أي من دوال agentmemory مباشرة بحمولة JSON؛ مفيد لاختبار `memory.recall` و`memory.consolidate` و`graph.query` دون ربط عميل. | | **المحفِّزات (Triggers)** | إعادة تشغيل محفِّزات HTTP وcron والأحداث والحالة: تفعيل مهمة cron للتوحيد يدويًا، وإعادة محاولة مسار HTTP، وبث تغيّر حالة. | | **الحالات (States)** | مستعرض KV بعمليات CRUD كاملة على الجلسات، وفُتحات الذاكرة، ومؤقِّتات دورة الحياة، وفهرس التضمينات؛ وتعديل القيم في مكانها. | | **التيارات (Streams)** | مراقب WebSocket مباشر لكتابات الذاكرة، وأحداث الخطافات، وتحديثات الملاحظات أثناء تدفّقها عبر تيارات iii. | | **قوائم الانتظار (Queues)** | مواضيع قوائم انتظار دائمة + إدارة الرسائل المتعطّلة (dead-letter). إعادة تشغيل أو إسقاط مهام التضمين/الضغط الفاشلة. | | **التتبّعات (Traces)** | عروض شلالية (waterfall) / لهبية (flame) / تفصيلية بالخدمة لـ OpenTelemetry. رشِّح حسب `trace_id` لمعرفة بالضبط أي الدوال، واستدعاءات قاعدة البيانات، وطلبات التضمين التي أنتجها استدعاء واحد لـ `memory.search`. | | **السجلات (Logs)** | سجلات OTEL البنيوية مُرشَّحة ومرتبطة بمعرِّفات trace/span. | | **الإعدادات (Config)** | إعدادات بيئة التشغيل: رؤية بالضبط أي عمّال ومزوّدين ومنافذ يعمل محركك بها. | | **التدفّق (Flow)** | (اختياري، `--enable-flow`) رسم بياني معماري تفاعلي لكل عامل، ومحفِّز، وتيار. |

التتبّعات: عرض شلالي / لهبي / تفصيلي بالخدمة لكل عملية ذاكرة.

**التتبّعات مُفعَّلة مسبقًا:** يُشحن `iii-config.yaml` مع تفعيل عامل `iii-observability` (`exporter: memory`، و`sampling_ratio: 0.1`، ومقاييس + سجلات). ولا حاجة إلى أي إعداد إضافي؛ فمنذ لحظة تشغيل agentmemory، تُصدِر كل عملية ذاكرة سجلًا بنيويًا يمكن لوحة التحكم قراءته، وتُصدِر واحدة من كل عشر عمليات (`sampling_ratio: 0.1`) مدى تتبّع (trace span) أيضًا. إذا رغبت في التصدير إلى Jaeger/Honeycomb/Grafana Tempo بدلًا من ذلك، غيّر `exporter: memory` إلى `exporter: otlp` واضبط نقطة نهاية المُجمِّع (collector) وفقًا لمستندات المراقبة في iii. > **تنبيه:** لا تُفرَض أي مصادقة على لوحة التحكم نفسها؛ احتفظ بارتباطها بـ `127.0.0.1` (الافتراضي) ولا تُعرِّضها علنًا مطلقًا. ---

agentmemory هو **فعليًا نسخة تشغيل من [iii](https://iii.dev)**. تُؤلِّف ثلاث بنى أساسية (العامل، والدالة، والمحفِّز) بيئة التشغيل؛ وتأتي حالة KV، والتيارات، وتتبّعات OTEL من عمّال iii-state وiii-stream وiii-observability المُشحونة مع iii. أنت لم تُثبِّت Postgres أو Redis أو Express أو pm2 أو Prometheus، لأن iii يحل محلها. وهذا يعني أن أمرًا واحدًا إضافيًا يمنح agentmemory قدرة جديدة كاملة. ### توسيع agentmemory بمزيد من العمّال العمّال المُضمَّنون (builtins) اللازمون لـ agentmemory موجودون مسبقًا في `iii-config.yaml` ويُقلعون معه: `iii-state` (KV)، و`iii-queue` (إعادة محاولات دائمة لمشتركي الأحداث)، و`iii-pubsub`، و`iii-cron`، و`iii-stream`، و`iii-observability` (تتبّعات OTEL، ومقاييس، وسجلات على كل دالة). وأي شيء آخر من [سجل عمّال iii](https://workers.iii.dev) يتوصّل بالمحرك نفسه: انسخ `iii-config.yaml` إلى `~/.agentmemory/iii-config.yaml` (تُفضِّل الواجهة الطرفية CLI هذا الملف على الملف المُضمَّن، وتظل تُصيِّر المنافذ ومسارات البيانات فيه)، وأضف الإدخال، وثبِّت بيئة تشغيل العامل مرة واحدة بأمر `~/.agentmemory/bin/iii update worker`، وأعد تشغيل agentmemory. ```yaml workers: # ...the bundled entries... - name: database # SQL-backed state adapter when you outgrow the KV defaults - name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM - name: mcp # extra MCP servers next to agentmemory's, same engine ``` | العامل | ما تحصل عليه إضافة إلى agentmemory | |---|---| | [`database`](https://workers.iii.dev/workers/database) | محوِّل حالة مدعوم بـ SQL عندما تتجاوز احتياجاتك إعدادات KV الافتراضية في الذاكرة | | [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | تشغيل الشفرة التي تخرج من `memory_recall` داخل جهاز افتراضي مؤقت، لا في صدفتك الخاصة | | [`mcp`](https://workers.iii.dev/workers/mcp) | إقامة خوادم MCP إضافية بجانب خادم agentmemory، بمشاركة المحرك نفسه | على المحرك 0.22.x، احتفظ بالأسماء المُضافة لها بادئة `iii-` للعمّال المُضمَّنين أعلاه؛ أما الإدخالات غير المُسبَّقة بادئةً `http` و`state` و`queue` و`pubsub` و`cron` فهي عمّال السجل المستقلون التي ينتقل إليها agentmemory مع ترحيل 0.23. السجل الكامل: [workers.iii.dev](https://workers.iii.dev). ويُؤلَّف كل عامل هناك من خلال البنى الأساسية نفسها التي يستخدمها agentmemory، وagentmemory الذي تملكه مسبقًا هو واحد منها. ### إعدادات المحرك وعنوان الارتباط يقرأ `agentmemory start` إعدادات المحرك من أول ملف موجود: `AGENTMEMORY_III_CONFIG`، ثم `./iii-config.yaml` في الدليل الحالي، ثم `~/.agentmemory/iii-config.yaml`، ثم ملف `iii-config.yaml` المُضمَّن. وفي كل تشغيل، يُصيِّر ذلك الملف (مسارات البيانات، والمنافذ، وخلفية الحالة) إلى `~/.agentmemory/data/iii-config.runtime.yaml` ويُشغِّل المحرك بالنسخة المُصيَّرة، فعدِّل ملف المصدر، لا الملف المُصيَّر. وتُحفظ قيم `host:` في ملف المصدر كما كُتبت. يرتبط `iii-config.yaml` المُضمَّن بـ `127.0.0.1` عمدًا، وينطبق ذلك الافتراضي أيضًا داخل الحاوية. وتستمع الواجهة الطرفية CLI المُشغَّلة داخل حاوية إلى عنوان loopback الخاص بالحاوية، فلا تصل المنافذ المنشورة إلى أي شيء. ولتقديم واجهة طرفية مُحوسَبة في حاويات عبر منافذ منشورة، اضبط `AGENTMEMORY_III_CONFIG` على إعدادات ترتبط بـ `0.0.0.0`. ويُعدّ `iii-config.docker.yaml` المُعبَّأ أحد هذه الإعدادات: فهو يربط `iii-http` و`iii-stream` ومنفذ المحرك بـ `0.0.0.0` ويخزِّن الحالة تحت `/data`، فاربط (mount) حجمًا (volume) قابلًا للكتابة هناك. حافظ على ضبط `AGENTMEMORY_SECRET`، ولا تنشر إلا المنافذ التي تحتاجها، على `127.0.0.1` أو خلف وكيل عكسي تثق به. لا يمر ملف `docker-compose.yml` الخاص بهذا المستودع عبر آلية بحث الواجهة الطرفية CLI عن الإعدادات: فهو يربط `iii-config.docker.yaml` عند `/app/config.yaml`، وتُشغَّل حاوية `iii-engine` بأمر `--config /app/config.yaml`. أما [قوالب النشر](../deploy/) بنقرة واحدة فتكتب إعداداتها الخاصة بـ `0.0.0.0` في سكربتات دخولها. ### خلفية التخزين: ملف (افتراضي) في مقابل redis يفترض `iii-state` و`iii-stream` مخزن KV المستنِد إلى الملفات المُضمَّن في iii-engine: ملف JSON واحد لكل نطاق، محفوظ في ذاكرة عملية المحرك ويُعاد كتابته على القرص بمؤقِّت. وهذا هو الافتراضي الصحيح لتثبيت محلي بمستخدم واحد؛ أما خادم عفريتي (daemon) مشترك بعدة كُتّاب متزامنين فيحصل بدلًا من ذلك على كتابات فعلية لكل مفتاح من Redis، بتكلفة رحلة شبكة ذهابًا وعودة لكل عملية (لا يزال كل استدعاء `state::*` يتسلسل على اتصال Redis واحد، فهذا يستبدل قفل مخزن الملفات بمقبس (socket)، لا بتوازٍ حقيقي). اضبط `AGENTMEMORY_STATE_BACKEND=redis` (مع `AGENTMEMORY_REDIS_URL`) لتبديل كلا العاملين إلى محوِّل `redis` المدمج في iii-engine، والذي يخزِّن كل مفتاح كحقل تجزئة (hash) في Redis (`HSET`) بدلًا من إعادة كتابة نطاق كامل عند كل كتابة: ```env # ~/.agentmemory/.env AGENTMEMORY_STATE_BACKEND=redis AGENTMEMORY_REDIS_URL=redis://localhost:6379 ``` يكون `AGENTMEMORY_STATE_BACKEND` بقيمة `file` افتراضيًا؛ وتركه بلا ضبط يحافظ على السلوك الحالي دون تغيير، وأي قيمة غير معروفة (أي شيء غير `file` أو `redis`) تُسبِّب خطأ عند البدء بدلًا من رجوع صامت. يُعلِن `/agentmemory/status` وصفحة الحالة الصحية في العارض (صف مخزن الحالة) عن الخلفية النشطة وهل تستجيب أم لا، ولا يُعلِنان العنوان مطلقًا. **`redis://` العادي فقط.** يبني المحرك المثبَّت (0.22.1) عميل Redis الخاص به دون دعم TLS، فيفشل الاتصال بعنوان `rediss://` (تفترض معظم خدمات Redis المُدارة، مثل Upstash وRedis Cloud وElastiCache بتشفير أثناء النقل، استخدام TLS فقط). الاتصال غير مُشفَّر، فتعبر كلمة مرور Redis وكل ذكرى مخزَّنة السلك نصًا صريحًا: وجِّهه إلى Redis محلي أو إلى واحد على شبكة خاصة تثق بها. وبالنسبة لأي Redis آخر، شغِّل نفقًا مُشفَّرًا (stunnel أو SSH أو VPN) على مضيف agentmemory، بحيث تبقى قفزة `redis://` العادية على ذلك المضيف ويكون اتصال النفق الصاعد (upstream) مُشفَّرًا ومُصادَقًا عليه. وإذا كانت كلمة مرور Redis تحتوي على علامة اقتباس مفردة، شفِّرها بترميز النسبة المئوية (`%27`)؛ فالمحرك يُوسِّع العنوان في إعدادات YAML الخاصة به قبل تحليله. **خادم Redis واحد لكل `--instance`.** بادئات مفاتيح Redis الخاصة بالمحرك (`state:`، و`stream::`) ثابتة، فإذا أشارت نسختان من agentmemory (`--instance 1`، و`--instance 2`، ...) إلى قاعدة البيانات نفسها، تتداخل بيانات كل منهما مع الأخرى وتُستبدَل. يُبقي فهرس قاعدة بيانات منفصل (`redis://localhost:6379/1`) البيانات المخزَّنة متفرقة، لكن المحرك يُرحِّل أحداث العارض الحية عبر قناة واحدة من نوع Redis pub/sub (`stream::events`)، ويتجاهل Redis pub/sub فهرس قاعدة البيانات، فسيظل عارض كل نسخة يُظهر الأحداث الحية للنسخة الأخرى. أعطِ كل نسخة خادم Redis خاصًا بها (أو منفذًا خاصًا) عندما تُشغِّل أكثر من نسخة واحدة. **ما يبقى كما هو، وما يختلف.** تعمل كل ميزة في agentmemory على Redis: الجلسات، والملاحظات، والذكريات (الحفظ، والإحلال، والتطور، والنسيان)، والبحث وحُزَم الفهرس، والدروس المستفادة، والرسم البياني، وسجل التدقيق ونطاقاته الشهرية، والتصدير والاستيراد، وعمليات الحذف الإدارية (governance)، وحالة التوحيد، ولقطة العارض وتيارها المباشر، ومراقب الحالة الصحية. ويخزِّن المحرك كل نطاق كتجزئة Redis واحدة (`HSET`/`HGET`/`HGETALL`) ويُطلِق محفِّزات الحالة نفسها التي يُطلقها مخزن الملفات. وتُعالَج ثلاثة اختلافات في المحرك داخل agentmemory: - يُعيد Redis سجلات النطاق دون ترتيب ثابت. يُرتِّبها agentmemory من الأقدم إلى الأحدث (بحسب وقت الإنشاء في معرّف السجل، ثم طابعه الزمني) بحيث تعود القوائم، والصفحات، وكُتل التصدير بالترتيب نفسه الموجود على مخزن الملفات. - يطبِّق المحرك التحديثات الجزئية على Redis بسكربت Lua يُحوِّل المصفوفات الفارغة إلى كائنات فارغة. يطبِّق agentmemory تلك التحديثات بنفسه على Redis (قراءة، وتغيير، وكتابة تحت قفل لكل مفتاح)، فتبقى حقول مثل `tags: []` مصفوفات. - يقرأ فحص سجل التدقيق القديم النطاق القديم من Redis بدلًا من البحث عن ملف مخزن الملفات على القرص. هناك اختلاف واحد يحتاج تدخّلك: **بعد إعادة تشغيل Redis، يتوقف المحرك عن ترحيل الأحداث الحية** إلى العارض إلى أن يُعاد تشغيل agentmemory. ولا تزال البيانات تُحفظ وتُقرأ بشكل طبيعي. يرسل مراقب الحالة الصحية حدثًا اختباريًا عبر Redis كل 30 ثانية؛ وعندما لا يعود، يُظهر `/agentmemory/status` وصفحة الحالة الصحية في العارض "التحديثات الحية لا تصل إلى العارض" مع الإصلاح: أعِد تشغيل agentmemory. وإذا كان Redis متوقفًا، يُظهر تقرير الحالة "مخزن الحالة لا يستجيب" وكيفية التحقق من ذلك (`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`). ويقرأ سرد نطاق كبير جدًا التجزئة كاملةً في `HGETALL` واحد، بنفس تكلفة احتفاظ مخزن الملفات به في الذاكرة. **إعدادات Redis المُوصى بها.** قد تُفقد سياسة اللقطات الافتراضية `save 3600 1 300 100 60 10000` دقائق من الكتابات عند الانهيار، وهذا أسوأ من نافذة التفريغ البالغة 5 ثوانٍ في مخزن الملفات. اضبط `appendonly yes` لأي شيء يهمك ألا تفقده. واضبط `maxmemory-policy noeviction`؛ فسياسة `allkeys-lru` أو ما شابهها تُسقِط الذكريات بصمت بمجرد أن يصل Redis إلى حد ذاكرته. يقرأ التشغيل الأصلي (غير Docker)، وكل [قالب نشر](../deploy/) بنقرة واحدة (فهي تستبدل `iii-config.yaml` المُضمَّن وتُشغَّل أصليًا)، `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL` ويُصيِّرانها في `iii-config` المُشغَّل. ولا يُكتب العنوان نفسه في ذلك الملف المُصيَّر مطلقًا، بل فقط مرجع `${AGENTMEMORY_REDIS_URL}` تُوسِّعه عملية المحرك من بيئتها الخاصة عند الإقلاع. ولا يربط `iii-config.docker.yaml` للقراءة فقط دون تصيير إلا مسار Docker Compose الخاص بهذا المستودع (`AGENTMEMORY_USE_DOCKER=1`، أو استئناف محرك بدأ بتلك الطريقة مسبقًا)؛ ويُحذِّر `agentmemory start` عندما يكتشف هذا المزيج. بدِّل ذلك الملف يدويًا، باتباع نفس شكل `name: redis` / `config: redis_url: ...` الموضَّح في مستندات عمّال [iii-state](https://workers.iii.dev/workers/iii-state) و[iii-stream](https://workers.iii.dev/workers/iii-stream)، ووجِّه `redis_url` إلى Redis يمكن الوصول إليه من الحاوية. ويُمرِّر `docker-compose.yml` متغير `AGENTMEMORY_REDIS_URL` إلى حاوية المحرك، فتعمل `redis_url: '${AGENTMEMORY_REDIS_URL}'` هناك وتُبقي العنوان خارج الملف المربوط. تُبقي الإعدادات المُصيَّرة العنوان خارج `~/.agentmemory/data/iii-config.runtime.yaml`، لكن عامل الإعدادات الخاص بالمحرك نفسه لا يزال يُثبِّت القيمة *المُوسَّعة* في `~/.agentmemory/config/iii-state.yaml` و`iii-stream.yaml` بمجرد إقلاعه (يحدث توسيع `${VAR}` الخاص بـ iii-engine قبل أن يخزِّن ذلك العامل بذرته، ويخزِّن القيمة المحلولة، لا المرجع). تعامل مع ذلك الدليل بصفته يحمل بيانات اعتماد: استخدم `chmod 700 ~/.agentmemory` على أي مضيف مشترك، وفضِّل مستخدم ACL لـ Redis مُحدَّد النطاق بما يحتاجه agentmemory فقط على بيانات اعتماد مسؤول قاعدة البيانات. **الترحيل ليس آليًا.** يبدأ تبديل `AGENTMEMORY_STATE_BACKEND` من مخزن فارغ على أي من الجانبين؛ ولا شيء يُنسِّخ البيانات الموجودة من الملف إلى Redis أو بالعكس. صدِّر من الخلفية التي تتركها واستورد إلى التي تنتقل إليها. يعمل هذا بشكل متطابق تحت bash وzsh (بما في ذلك `bash -u`). أما مصفوفة مثل `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` فلا تعمل بالمثل: يحتفظ zsh بالترويسة كَكلمة واحدة مُشوَّهة حيث يقسِّمها bash إلى كلمتين، فيعيد كل من الطلبين الرمز 401 في كل مرة يكون `AGENTMEMORY_SECRET` مضبوطًا فيها: ```bash # 0. Use the generated secret when none is exported: AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}" # 1. On the old backend, while agentmemory is still running on it: if [ -n "${AGENTMEMORY_SECRET:-}" ]; then curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json else curl -fsS http://localhost:3111/agentmemory/export > backup.json fi # 2. Confirm backup.json is a usable export before switching backends: jq -e '.version and .exportedAt' backup.json > /dev/null || { echo "backup.json is not a valid export; do not switch backends" >&2 exit 1 } # 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed), # restart agentmemory against the new backend, then: if [ -n "${AGENTMEMORY_SECRET:-}" ]; then jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \ curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \ -H 'Content-Type: application/json' -d @- else jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \ curl -fsS -X POST http://localhost:3111/agentmemory/import \ -H 'Content-Type: application/json' -d @- fi ``` يقبل `/agentmemory/export` أيضًا `?maxSessions=` و`?offset=` لتقسيم مجموعة كبيرة عبر عدة استدعاءات؛ وتكون `strategy` عند الاستيراد إما `merge` (الآمن افتراضيًا)، أو `replace`، أو `skip`. ### ما الذي يحل iii محله | المكدّس التقليدي | ما يستخدمه agentmemory | |---|---| | Express.js / Fastify | محفِّزات HTTP في iii | | SQLite / Postgres + pgvector | حالة KV في iii + فهرس متجهات في الذاكرة | | SSE / Socket.io | تيارات iii (WebSocket) | | pm2 / systemd | إشراف المحرك على العمّال في iii | | Prometheus / Grafana | OTEL في iii + مراقب الحالة الصحية | | أنظمة إضافات مخصصة | `iii worker add ` | **219 ملف مصدري · ~52,000 سطر برمجي · 2,500+ اختبار · 311 دالة · 60 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه. ---

### مزوّدو LLM يكتشف agentmemory المزوّدين تلقائيًا من بيئتك. يُتيح المزوّد العمليات المعتمدة على LLM، لكن ضبط المزوّد وحده لا يُفعِّل ضغط الملاحظات المكتوب بواسطة LLM. فذلك المسار يتطلب مزوّدًا و`AGENTMEMORY_AUTO_COMPRESS=true` معًا. | المزوّد | الإعداد | ملاحظات | |----------|--------|-------| | **بلا عملية (No-op، الافتراضي)** | لا حاجة إلى إعداد | الضغط/التلخيص المعتمد على LLM مُعطَّل. ولا يزال الضغط التركيبي واسترجاع BM25 يعملان. راجع `AGENTMEMORY_ALLOW_AGENT_SDK` أدناه إذا كنت تعتمد سابقًا على الرجوع لاشتراك Claude. | | Anthropic API | `ANTHROPIC_API_KEY` | فوترة لكل رمز (token) | | MiniMax | `MINIMAX_API_KEY` | متوافق مع Anthropic | | Gemini | `GEMINI_API_KEY` | يُفعِّل التضمينات أيضًا | | OpenRouter | `OPENROUTER_API_KEY` | أي نموذج | | OpenAI API | `OPENAI_API_KEY` | الافتراضي `gpt-5.6-luna`، تجاوزه بـ `OPENAI_MODEL` | | **محلي (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) أو `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | أي شيء متوافق مع OpenAI API. بلا تكلفة، ويعمل على جهازك. راجع [النماذج المحلية](#local-models-ollama--lm-studio--vllm) أدناه. | | الرجوع لاشتراك Claude | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | اختياري الانضمام فقط. يُولِّد جلسات `@anthropic-ai/claude-agent-sdk`؛ وكان يتسبب سابقًا في تكرار (recursion) غير محدود لخطاف Stop، فلم يعد الافتراضي. | ### النماذج المحلية (Ollama / LM Studio / vLLM) يتحدّث agentmemory مع أي خادم متوافق مع OpenAI API، فأي خادم يُعرِّض `/v1/chat/completions` يعمل دون أي تعديل في الشفرة. لا مفاتيح مدفوعة، ولا سحابة، ولا حدود لمعدل الطلبات؛ ويعمل بالكامل على جهازك. **Ollama** (المنفذ الافتراضي `11434`): ```bash ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc. ollama serve ``` ```env # ~/.agentmemory/.env OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_MODEL=qwen3:8b ``` **LM Studio** (المنفذ الافتراضي `1234`): افتح LM Studio ← تبويب Local Server ← Start Server. اختر أي نموذج محادثة من القائمة (Qwen 3، وgpt-oss، وDeepSeek R1، وغيرها). ```env # ~/.agentmemory/.env OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it OPENAI_BASE_URL=http://localhost:1234/v1 OPENAI_MODEL=qwen3-8b # match the model name from LM Studio ``` **vLLM / llama.cpp / Text Generation Inference**: نفس الصيغة. وجِّه `OPENAI_BASE_URL` إلى أي عنوان يُعرِّضه خادمك، واضبط `OPENAI_MODEL` على اسم يقبله خادمك. **اختيارات النماذج لعمل الذاكرة**: الضغط والتلخيص مهمتان قصيرتان (أقل من 2K رمز مدخل، وأقل من 500 رمز مخرج) يكفيهما نموذج instruct بحجم 7B. التوصيات: | النموذج | الحجم | السبب | |-------|------|-----| | `qwen3:8b` | ~5.2 جيجابايت | افتراضي متوازن على جهاز بـ16 جيجابايت؛ قوي في الاستخراج والنصوص الشبيهة باستدعاءات الأدوات | | `qwen3:4b` | ~2.6 جيجابايت | أصغر خيار منطقي؛ مناسب للضغط، وأضعف في استخراج الرسم البياني | | `qwen3-coder:30b` | ~19 جيجابايت | أفضل خيار محلي للجلسات الشبيهة بالشفرة (30B MoE، بـ3.3B نشطة) على أجهزة بـ24-32 جيجابايت | | `gpt-oss:20b` | ~14 جيجابايت | نموذج عام قوي يُناسب ذاكرة 16 جيجابايت | | `deepseek-r1:8b` | ~5.2 جيجابايت | تقطير استدلالي (reasoning distill)؛ أبطأ لكن استخراجاته أنظف | تُفكِّر نماذج Qwen 3 افتراضيًا، وقد تستهلك موازنة الرموز كاملةً في الاستدلال قبل أي مخرج. اضبط `AGENTMEMORY_LLM_NOTHINK=1` لإلحاق `/no_think` بمطالبات استخراج الرسم البياني، وارفع `MAX_TOKENS` (تعمل قيمة 16384) إذا عادت الاستخراجات فارغة. يمكن لنماذج فئة الاستدلال (على طراز `o1` بكتل ``) أن تُعيد `content` فارغًا مع حقل `reasoning` قد لا يُظهره خادمك المحلي. إذا عادت الاستخراجات فارغة، جرِّب نموذجًا غير استدلالي أولًا. ويمكن لمتغير البيئة `OPENAI_REASONING_EFFORT=none` أيضًا تعطيل التفكير على نماذج Ollama Cloud المُفكِّرة التي تُحاكي مخطط استدلال OpenAI. تُشحن التضمينات المحلية كاعتمادية اختيارية لكنها غير مُفعَّلة افتراضيًا. اضبط `EMBEDDING_PROVIDER=local` للانضمام إلى `Xenova/all-MiniLM-L6-v2` (384 بُعدًا). يُنزِّل أول طلب تضمين النموذج؛ ويكون الاستدلال على الجهاز نفسه بعد ذلك. وبدون ذلك الضبط أو مفتاح تضمين بعيد، تبقى المتجهات مُعطَّلة، ويستخدم `mem::search` خوارزمية BM25، ويمكن لـ `smart-search` أن يُضيف تطابقات الرسم البياني الموجودة مسبقًا. ### اختيار النموذج الواعي بالتكلفة عندما يُفعَّل الضغط الخلفي المكتوب بواسطة LLM بوجود مزوّد و`AGENTMEMORY_AUTO_COMPRESS=true` معًا، فإنه يعمل على كل ملاحظة، فيُغيِّر اختيار النموذج الإنفاق الشهري بشكل ملموس. بيانات حِمل عمل مُسجَّلة: 635 طلبًا / 888 ألف رمز / 35 ساعة استخدام نشط، شُغِّلت مقابل ثلاثة نماذج من OpenRouter بتسعير 2026-05-23. | المستوى | النموذج | المدخل / مليون | المخرج / مليون | التكلفة لـ35 ساعة المُسجَّلة | ملاحظات | |------|-------|------------|-------------|---------------------------|-------| | مُوصى به | `deepseek/deepseek-v4-flash-0731` | 0.07$ | 0.14$ | ~0.07$ (تقديري) | أحدث DeepSeek؛ الخيار الأرخص المُوصى به لأعمال الضغط. | | مُوصى به | `deepseek/deepseek-v4-pro` | 0.435$ | 0.87$ | ~0.46$ | جودة ضغط وتلخيص جيدة بتكلفة أقل بنحو 10× من Sonnet. | | مُوصى به | `qwen/qwen3-coder` | 0.45$ | 1.80$ | ~0.55$ | استدلال برمجي قوي إذا كانت جلساتك شبيهة بالشفرة بكثافة. | | مميّز | `anthropic/claude-sonnet-5` | 3.00$ | 15.00$ | ~5.02$ (تقديري) | نفس سعر القائمة لتشغيل Sonnet 4.6 المُقاس؛ وتسعير تمهيدي 2$/10$ حتى 2026-08-31. | | مميّز | `openai/gpt-5.6-sol` | 5.00$ | 30.00$ | ~9$ (تقديري) | مستوى رائد؛ مكلف للعمل الخلفي الدائم التشغيل. | | تجنّبه | `anthropic/claude-opus-5` | 5.00$ | 25.00$ | ~8.40$ (تقديري) | نموذج من فئة رائدة؛ إنفاق زائد لعمليات الضغط. | تأتي الصفوف المقيسة من التشغيل المُسجَّل؛ وتُحجِّم صفوف (تقديري) نفس مزيج الرموز بسعر قائمة كل نموذج. يطبع agentmemory تحذيرًا وقت التشغيل عندما يطابق `OPENROUTER_MODEL` نمط المستوى المميّز. اضبط `AGENTMEMORY_SUPPRESS_COST_WARNING=1` لإسكاته بعد أن تتخذ قرارًا مدروسًا. مقايضة الجودة في مقابل التكلفة لعمل الذاكرة: الضغط مهمة تلخيص بمعايير جودة فضفاضة نسبيًا (فالوكيل هو من يُعيد قراءة الملخص، لا المستخدم). يحطّ DeepSeek V4 Flash / V4 Pro / Qwen3-Coder ضمن هامش خطأ التقريب لـ Sonnet في هذه المهمة بتكلفة أقل بـ10-70×. احتفظ بالنماذج من المستوى المميّز للاستعلامات التي تقرأها مباشرة. المصادر: [تسعير OpenRouter لـ Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5)، و[DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731)، و[ملاحظات تسعير DeepSeek](https://api-docs.deepseek.com/quick_start/pricing/). ### ذاكرة متعددة الوكلاء (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`) في إعدادات تعدد الوكلاء حيث تتشارك عدة أدوار خادم agentmemory واحدًا (مهندس معماري / مطوّر / مراجع / باحث / وكيل دعم)، يُسجِّل `AGENT_ID` وسمًا على كل كتابة بالدور الذي أجراها. ويتحكّم `AGENTMEMORY_AGENT_SCOPE` في ما إذا كان الاسترجاع يُرشِّح حسب ذلك الوسم. ```env TEAM_ID=company USER_ID=engineering-team AGENT_ID=architect AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared" ``` وضعان: | الوضع | وسم الكتابات | ترشيح الاسترجاع | متى يُستخدم | |------|------------|---------------|-------------| | `shared` (الافتراضي) | نعم | لا | سياق بين الوكلاء مع مسار تدقيق. يمكن للمهندس المعماري رؤية ما لاحظه المطوِّر، لكن كل صف يُسجِّل من قاله. | | `isolated` | نعم | نعم | انفصال صارم. لا يرى المهندس المعماري أبدًا ملاحظات/ذكريات/جلسات المطوِّر. | ما الذي يُوسَم عند ضبط `AGENT_ID`: `Session.agentId`، و`RawObservation.agentId`، و`CompressedObservation.agentId`، و`Memory.agentId`. ويتدفّق الدور من `api::session::start` ← `mem::observe` ← `mem::compress` ← KV. ما الذي يُرشَّح في الوضع المعزول: `mem::smart-search`، و`/agentmemory/memories`، و`/agentmemory/observations`، و`/agentmemory/sessions`. تقبل كل نقطة نهاية `?agentId=` للتجاوز في كل طلب على حدة، و`?agentId=*` للخروج من نطاق متغير البيئة بالكامل. ويقبل `/memories` أيضًا `?includeOrphans=true` لإظهار الذكريات السابقة لـ AGENT_ID التي يكون `agentId` فيها غير مُحدَّد. التجاوز لكل استدعاء على مستوى SDK / REST: تقبل كل نقطة نهاية مُغيِّرة (`/session/start`، و`/remember`) حقل `agentId` في جسم الطلب يتغلّب على متغير البيئة. مفيد لبيئات تشغيل تُوجِّه أدوارًا عديدة عبر عملية خادم واحدة. وتُظهر أداة MCP `memory_save` حقل `agentId` نفسه، ويُمرِّر خادم stdio القائم بذاته كلًا من `agentId` و`project`، وتحمل الذكريات المحفوظة `agentId` إلى فهرس البحث، فيغطي البحث المحدد بالوكيل الذكريات كما يغطي الملاحظات. وعندما يكون `AGENT_ID` غير مضبوط، تبقى الذاكرة بلا نطاق محدد (السلوك القديم، بلا وسوم، بلا ترشيح). ### المنافذ يرتبط agentmemory + iii-engine بأربعة منافذ افتراضيًا. وإذا فشلت إعادة التشغيل برسالة `port in use`، يُخبرك هذا الجدول عن العملية التي يجب البحث عنها. | المنفذ | العملية | الغرض | تجاوز متغير البيئة | |------|---------|---------|--------------| | `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` | | `3112` | iii-engine | عامل التيارات الداخلي (يستهلكه agentmemory + العارض) | `III_STREAM_PORT` (مُفضَّل) أو `III_STREAMS_PORT` القديم | | `3113` | agentmemory | العارض اللحظي (`http://localhost:3113`) | `III_VIEWER_PORT` أو `AGENTMEMORY_VIEWER_URL` للعنوان المُعلَن | | `49134` | iii-engine | WebSocket؛ يُسجِّل العمّال هنا، ويتدفّق قياس OTel عبره | `III_ENGINE_PORT` أو `III_ENGINE_URL` | يُغيِّر `--port ` مرساة REST ويستمد منفذ التيارات `N+1`، والعارض `N+2`، وWebSocket المحرك `N+46023`، فقط حيث يكون المنفذ أو العنوان الصريح المقابل أعلاه غير مضبوط. ولا يُنشئ مساحة أسماء دورة حياة معزولة. استخدم `--instance 1` لعفريت (daemon) ثانٍ؛ فهو يستخدم المرساة 3211، وافتراضيًا `3211/3212/3213/49234`، ويحصل على دليل بيانات ودورة حياة منفصل باسم `instance-1`. وتتبع النُّسخ من 1 إلى 50 النمط نفسه. يبدأ المحرك المثبَّت بخيار `--no-update-check` (بلا أي بحث عن تحديثات أو تنبيهات أمنية مقابل GitHub عند الإقلاع) ومع تعطيل قياس الاستخدام المجهول لـ iii: يضبط agentmemory `III_TELEMETRY_ENABLED=false` للمحرك الذي يُولِّده إلا إذا صدَّرت المتغير بنفسك، ويفعل ملف compose المُضمَّن الشيء نفسه. تنظيف العمليات العالقة عندما تظل المنافذ مربوطة بعد تشغيل منهار: ```bash # macOS / Linux — find whatever is on each port and kill it lsof -i :3111,3112,3113,49134 pkill -f agentmemory || true pkill -f 'iii ' || true # Windows netstat -ano | findstr ":3111 :3112 :3113 :49134" taskkill /F /PID ``` يحصد `agentmemory stop` كلًا من ملف pid الخاص بالعامل والمحرك بنظافة عند الإيقاف الأصلي السَّلِس (graceful). وفي وضع Docker، يُفرِّغ العامل الأصلي، ويُوقِف حاوية المحرك المُصادَق عليها تحديدًا، ويحافظ على كلٍّ من الحاوية وربطها بـ `/data` لإعادة تشغيل بلا فقد بيانات؛ ويتحقق التشغيل التالي من تلك الحاوية نفسها ويستأنفها. ويتطلب إلغاء التثبيت المعتمد على Docker أمر `agentmemory remove --keep-data`: فهو يحذف ملفات agentmemory المُشتركة والمُدارة بينما يحافظ على الحاوية المُصادَق عليها، وربط بياناتها، وسجل دورة الحياة اللازم لاستعادتها. ويُترَك حذف بيانات Docker المدمِّر عمدًا للمُشغِّل بعد نسخة احتياطية. وترفض الواجهة الطرفية CLI أيضًا تبنّي أو إرسال إشارة إلى حائزي منافذ Docker أو الأجهزة الافتراضية (خلفية Docker، أو vpnkit، أو colima) باعتبارهم المحرك الأصلي إلا إذا مُرِّرت `--force`. والتنظيف اليدوي أعلاه مخصص فقط لحالة ما بعد الانهيار التي لا يُترَك فيها أي ملف pid. ### ملف الإعدادات ضع إعدادات بيئة تشغيل agentmemory في `~/.agentmemory/.env` بدلًا من تصدير المتغيرات في كل صدفة. إذا أظهر العارض تلميح إعداد مثل `export ANTHROPIC_API_KEY=...`، انسخه إلى هذا الملف كـ `ANTHROPIC_API_KEY=...` دون بادئة `export`، ثم أعد تشغيل agentmemory. لا تزال متغيرات بيئة العملية تعمل وتسبق في الأولوية القيم الموجودة في الملف. على Windows، يعيش الملف نفسه عند `%USERPROFILE%\.agentmemory\.env`: ```powershell New-Item -ItemType Directory -Force $HOME\.agentmemory notepad $HOME\.agentmemory\.env ``` لتجربته باستخدام اشتراك Claude Code Pro/Max بدلًا من مفتاح API، انضم اختياريًا وبشكل صريح: ```env AGENTMEMORY_ALLOW_AGENT_SDK=true AGENTMEMORY_AUTO_COMPRESS=true ``` يتطلب ضغط الملاحظات المكتوب بواسطة LLM السطرين معًا: الوصول إلى مزوّد LLM (بما في ذلك هذا الرجوع الصريح للاشتراك) و`AGENTMEMORY_AUTO_COMPRESS=true`. ويترك المزوّد وحده مسار الضغط التركيبي الافتراضي كما هو. يكون التوحيد (عُقَد الرسم البياني، والدروس المستفادة، والبلورات) مُفعَّلًا افتراضيًا كلما ضُبط مزوّد LLM. استثنِ نفسك صريحًا بـ `CONSOLIDATION_ENABLED=false` إذا أردت تشغيلًا بلا LLM. واستخراج الرسم البياني راية مستقلة: ```env GRAPH_EXTRACTION_ENABLED=true # CONSOLIDATION_ENABLED=false # opt out of auto-consolidation ``` ### متغيرات البيئة أنشئ `~/.agentmemory/.env`: ```env # LLM provider (pick one — default is the no-op provider: no LLM calls) # ANTHROPIC_API_KEY=sk-ant-... # ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure # GEMINI_API_KEY=... # OPENROUTER_API_KEY=... # MINIMAX_API_KEY=... # OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the # # OpenAI LLM provider (here) AND the OpenAI # # embedding provider (further below). Set # # OPENAI_API_KEY_FOR_LLM=false to scope it # # to embeddings only. # OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies # # Azure: https://.openai.azure.com/openai/deployments/ # # Auto-detected from `.openai.azure.com` hostname; uses # # api-key header + api-version query param. # OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param # OPENAI_MODEL=gpt-5.6-luna # Optional: default model # OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch # # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS # # for back-compat with v0.9.17. New configs should # # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below. # OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none" # # Honored only by OpenAI's reasoning models (o1, o3, # # gpt-*-reasoning) and providers that mirror that # # schema (Ollama Cloud thinking models). Standard # # chat models reject this field with 400. Set to # # "none" for thinking models that return reasoning # # but no content. # OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection # # for LLM (useful if you only want OpenAI for embeddings) # Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk); # leave OFF unless you understand the Stop-hook recursion risk: # AGENTMEMORY_ALLOW_AGENT_SDK=true # Embedding provider (BM25-only when unset; local is an explicit opt-in) # EMBEDDING_PROVIDER=local # VOYAGE_API_KEY=... # OPENAI_API_KEY=sk-... # OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies # OPENAI_EMBEDDING_MODEL=text-embedding-3-small # OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table # OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL # OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set # Outbound LLM / embedding timeout # AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every # raw-fetch provider (Gemini, OpenRouter, MiniMax, # OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter # embedding). For the OpenAI LLM path, the # OpenAI-scoped OPENAI_TIMEOUT_MS alias (above) # takes precedence when set, for back-compat # with v0.9.17. # Increase for slow networks or large batch calls; # decrease to fail-fast on rate-limit holds. # Search tuning # BM25_WEIGHT=0.4 # VECTOR_WEIGHT=0.6 # TOKEN_BUDGET=2000 # Auth (generated into ~/.agentmemory/secret on first start when unset) # AGENTMEMORY_SECRET=your-secret # VIEWER_ALLOWED_ORIGINS=https://memory.example.com # AGENTMEMORY_IMPORT_ROOT=~/projects # Ports (defaults: 3111 API, 3113 viewer) # III_REST_PORT=3111 # Engine usage telemetry (iii). Off unless you set it; true opts in. # III_TELEMETRY_ENABLED=false # Features # AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM # provider as well. When both are on, # every PostToolUse hook calls your # LLM provider to compress the # observation — expect significant # token spend on active sessions. # AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned # memory slots — persona, # user_preferences, tool_guidelines, # project_context, guidance, # pending_items, session_patterns, # self_notes. Size-limited; agent # edits via memory_slot_* tools. # Pinned slots addressable for # SessionStart injection. # AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on. # Stop hook fires mem::slot-reflect: # scans recent observations, auto- # appends TODOs to pending_items, # counts patterns in # session_patterns, records touched # files in project_context. Fire- # and-forget; does not block. # AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on: # - SessionStart may inject ~1-2K # chars of project context into # the first turn of each session # (this is what actually reaches # the model — Claude Code treats # SessionStart stdout as context) # - PreToolUse fires /agentmemory/enrich # on every file-touching tool call # (resource cleanup, not a token # fix — PreToolUse stdout is debug # log only per Claude Code docs) # Observations are still captured via # PostToolUse regardless of this flag. # GRAPH_EXTRACTION_ENABLED=false # AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the # model to skip its hidden thinking pass # during graph extraction. Faster runs; # relation quality can drop slightly. # CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured # LESSON_DECAY_ENABLED=true # OBSIDIAN_AUTO_EXPORT=false # AGENTMEMORY_EXPORT_ROOT=~/.agentmemory # CLAUDE_MEMORY_BRIDGE=false # SNAPSHOT_ENABLED=false # Storage and durability # AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below # AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only # AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk. # A hard kill loses at most this window. # AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves; # shutdown and deletes still save at once. # AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph # provenance; false skips it # Sessions # AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past # the threshold as abandoned. Deletes nothing; # new activity makes the session active again. # AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24 # Capture filters (hooks) # AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs; # when set, only these tools are captured # AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the # defaults: memory_*, toolsearch, # listmcpresources, fetchmcpresource # AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation # AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables # Audit log # AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all # AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup # rows (debugging only) # Team # TEAM_ID= # USER_ID= # TEAM_MODE=private # Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean) # AGENTMEMORY_TOOLS=core ``` ---

138 نقطة نهاية على المنفذ `3111`. ترتبط REST API بـ `127.0.0.1` افتراضيًا. تتطلب نقاط النهاية المحمية ترويسة `Authorization: Bearer `، وتتطلب نقاط نهاية مزامنة mesh ضبط `AGENTMEMORY_SECRET` صريحًا على كلا الطرفين. **المصادقة مُفعَّلة افتراضيًا.** عندما لا يكون `AGENTMEMORY_SECRET` مضبوطًا (في الصدفة أو في `~/.agentmemory/.env`)، يُولِّد الخادم سرًا عشوائيًا عند أول تشغيل ويخزِّنه في `~/.agentmemory/secret` بوضع صلاحيات `0600`. ويقرؤه كل عميل مُضمَّن من هناك عند التحدث إلى خادم محلي: الواجهة الطرفية CLI، والعارض، والخطافات تحت `plugin/scripts`، وخادم MCP والوسيط `@agentmemory/mcp`، والإعدادات التي يكتبها `agentmemory connect`، وتكاملات OpenCode وPi وOpenClaw وHermes ومراقب نظام الملفات (filesystem-watcher) المُضمَّنة. ولا يُرسَل السر المخزَّن إلا إلى عناوين loopback (`localhost`، و`127.0.0.0/8`، و`::1`). ويتغلّب `AGENTMEMORY_SECRET` الصريح دائمًا، ولا يزال العملاء البعيدون بحاجة إلى ضبطه. وتُولِّد Docker وقوالب [`deploy/`](../deploy/) سرها الخاص وتُصدِّره مسبقًا. ولاستدعاء الواجهة البرمجية يدويًا: ```bash curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health ``` **قواعد الطلبات للكتابة.** يجب أن تُرسِل طلبات `POST` و`PUT` و`PATCH` و`DELETE` إلى REST API والعارض ترويسة `Content-Type: application/json` (مُعامل `charset` مقبول) كلما حملت جسمًا، وترويسة `Origin`، عند وجودها، يجب أن تكون أصلًا من نوع loopback لمنفذ REST أو العارض المضبوط، أو مُدرَجة في `VIEWER_ALLOWED_ORIGINS` (مفصولة بفواصل، مثل `https://memory.example.com`). أما العملاء الذين لا يُرسلون ترويسة `Origin` (CLI، والخطافات، وMCP، وcurl، ومن خادم إلى خادم) فلا يتأثرون. ويقبل العارض أيضًا أصله الخاص. **مسارات الملفات.** لا تقبل نقاط النهاية التي تقرأ أو تكتب ملفات (`/compress-file`، و`/replay/import-jsonl`، و`/graph/import-graphify`) إلا مسارات تحت `~/.agentmemory`، أو دليل بيانات النسخة، أو دليل مُدرَج في `AGENTMEMORY_IMPORT_ROOT` (فصل عدة مسارات بـ `:`، أو بـ `;` على Windows). ويقبل `/replay/import-jsonl` أيضًا مساره الافتراضي `~/.claude/projects`. ويبقى `/obsidian/export` داخل `AGENTMEMORY_EXPORT_ROOT` و`/migrate` داخل `~/.agentmemory`. وتُحلّ الروابط الرمزية (symlinks) قبل كل فحص. **تنقية الأسرار.** تُحذف مفاتيح API، ورموز الحامل (bearer tokens)، وكتل مفاتيح PEM الخاصة، وبيانات الاعتماد المُضمَّنة في العناوين (`scheme://user:password@host`) قبل تخزين النص، في كل مسار كتابة: الملاحظات، والحفظ، والتطور، والفُتحات (slots)، والدروس المستفادة، والإجراءات، والرسوم التخطيطية، والإشارات، ونقاط التحقق، والاستيرادات، وإعادة تشغيل jsonl، ومزامنة mesh، ومشاركات الفريق، ومخرجات الضغط والتلخيص، والبلورات، وعُقَد الرسم البياني.

نقاط النهاية الأساسية

| الطريقة | المسار | الوصف | |--------|------|-------------| | `GET` | `/agentmemory/health` | فحص الحالة الصحية (عام دائمًا) | | `GET` | `/agentmemory/status` | ما الخطأ وكيفية إصلاحه (HTML للمتصفحات، JSON في الحالات الأخرى) | | `GET` | `/agentmemory/viewer/snapshot` | كل ما يُظهره العارض، في استجابة واحدة | | `POST` | `/agentmemory/session/start` | بدء الجلسة + الحصول على السياق | | `POST` | `/agentmemory/session/end` | إنهاء الجلسة | | `POST` | `/agentmemory/observe` | التقاط ملاحظة (راجع تسليم الالتقاط أدناه) | | `GET` | `/agentmemory/capture` | صندوق وارد الالتقاط، والرسائل المتعطّلة، والتخزين المؤقت دون اتصال | | `POST` | `/agentmemory/capture/retry` | إعادة محاولة الالتقاطات المتعطّلة | | `POST` | `/agentmemory/capture/drain` | إرسال التخزين المؤقت المحلي دون اتصال الآن | | `POST` | `/agentmemory/smart-search` | بحث هجين | | `POST` | `/agentmemory/context` | توليد السياق | | `POST` | `/agentmemory/remember` | الحفظ في الذاكرة طويلة المدى | | `POST` | `/agentmemory/forget` | حذف الملاحظات | | `POST` | `/agentmemory/enrich` | سياق الملف + الذكريات + الأخطاء | | `GET` | `/agentmemory/profile` | ملف تعريف المشروع | | `GET` | `/agentmemory/export` | تصدير جميع البيانات | | `POST` | `/agentmemory/import` | الاستيراد من JSON | | `POST` | `/agentmemory/graph/query` | استعلام الرسم البياني المعرفي | | `POST` | `/agentmemory/graph/compact` | تقليص مصدرية الرسم البياني المتضخمة | | `POST` | `/agentmemory/team/share` | المشاركة مع الفريق | | `GET` | `/agentmemory/audit` | مسار التدقيق | قائمة نقاط النهاية الكاملة: [`src/triggers/api.ts`](../src/triggers/api.ts)

**تسليم الالتقاط.** تُرسل الخطافات كل ملاحظة مرة واحدة إلى `POST /agentmemory/observe` مع `eventId`. وهو معرّف المضيف الخاص بالاستدعاء عندما تحمله الحمولة (مثل `tool_use_id` في Claude Code)، وإلا فهو بصمة (hash) للجلسة، ونوع الخطاف، واسم الأداة، والمدخل، والمخرج، والطابع الزمني للمضيف. يكتب الخادم الحدث إلى صندوق وارد الالتقاط في مخزن الحالة، ويخزِّن الملاحظة، ثم يحذف إدخال صندوق الوارد. ويُخبرك رمز الحالة بما حدث: | رمز الحالة | حقل `status` | المعنى | |---|---|---| | `201` | `accepted` | تم التخزين. `observationId` هو الملاحظة الجديدة. | | `202` | `accepted` (`state: "retrying"`) | تم القبول، لكن التخزين فشل. يعيد الخادم محاولته، أيضًا بعد إعادة التشغيل. | | `200` | `duplicate` | تم قبول `eventId` هذا مسبقًا. `observationId` هو الملاحظة الموجودة؛ ولا يُخزَّن أي شيء جديد. | | `400` / `422` | `rejected` | حمولة غير صالحة، أو فشل التخزين نهائيًا (يُحفظ الحدث كرسالة متعطّلة). | | `503` | `rejected` (`retryable: true`) | صندوق الوارد ممتلئ (`AGENTMEMORY_CAPTURE_INBOX_MAX`). تُخزِّن الخطافات الحدث مؤقتًا وترسله لاحقًا. | تُعاد محاولة الأحداث الفاشلة كل `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 ثوان) بتراجع تدريجي مُضاعِف، حتى `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS` (5). وتبقى الأحداث التي لا تزال تفشل في صندوق الوارد كرسائل متعطّلة، وتُسرَد في `/agentmemory/status` وصفحة الحالة الصحية في العارض، ويمكن إعادة محاولتها بـ `POST /agentmemory/capture/retry` (`{"eventId": "..."}` أو `{"all": true}`). وتُتذكَّر معرّفات الأحداث المقبولة لمدة `AGENTMEMORY_CAPTURE_DEDUP_HOURS` (168 ساعة، وبحد أقصى `AGENTMEMORY_CAPTURE_EVENTS_MAX` معرّفًا)، فيُخزَّن خطاف أُعيد تشغيله بعد انتهاء مهلة أو إعادة تشغيل مرة واحدة فقط، بينما يُخزَّن استدعاءا أداة منفصلان بمعرّفي مضيف خاصين بهما مرتين حتى لو كان محتواهما متطابقًا. وعندما تُحذف ملاحظة (نسيان، أو حذف جلسة، أو طرد، أو نسيان تلقائي، أو استيراد يستبدل المخزن)، يُوسَم حدثها بأنه محذوف قبل إزالة الملاحظة، فتُجاب إعادة تشغيل ذلك الحدث داخل النافذة الزمنية نفسها باعتبارها تكرارًا ولا تُخزِّن شيئًا. يكتب مخزن الحالة إلى القرص كل ثانيتين، فقد تبقى إجابة حدث مُجاب في الذاكرة فقط للحظة. ولتغطية ذلك، تحمل كل إجابة من فئة `2xx` أيضًا `bootId` الخادم (جديد في كل بدء تشغيل)، و`acceptedAt`، و`durableAfterMs` (مدة الحفظ زائد 1.5 ثانية على مخزن الملفات، و1.5 ثانية على redis، حيث يكون الاستمرار من ضبط المُشغِّل). تحتفظ الخطافات بالحدث في التخزين المؤقت المحلي إلى أن تنقضي تلك النافذة الزمنية، وتحذفه في استدعاء لاحق دون طلب آخر. وإذا تغيَّر `bootId` بحلول ذلك الوقت، فهذا يعني أن الخادم أعاد التشغيل، فيُرسِل الخطاف الحدث مرة أخرى بنفس `eventId`؛ ولا يُخزَّن حدث وصل فعلًا إلى القرص مرتين. ويُرسِل الخادم نفسه أيضًا تلك الأحداث عند البدء وفي كل فاصل إعادة محاولة، فلا تفقد إعادة التشغيل أي شيء حتى لو لم يعمل أي خطاف بعد ذلك. وتتجاهل الخطافات القديمة الحقول الإضافية، وتتخلى الخطافات الجديدة عن الحدث عند `2xx` مقابل خادم أقدم كما كان الحال سابقًا. وعندما يكون الخادم متوقفًا، أو لا يُجيب في الوقت المناسب، أو يُعيد 5xx، يُلحق الخطاف الملاحظة بملف تخزين مؤقت محلي، `/capture-spool/-.jsonl` (تجاوز المجلد بـ `AGENTMEMORY_CAPTURE_SPOOL_DIR`). الملف خاص بمستخدمك (وضع صلاحيات 600)، وتُحذف الأسرار منه بنفس الطريقة التي يحذفها الخادم بها، ويحمل بحد أقصى `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 ميبيبايت)، ويُسقِط الإدخالات الأقدم من `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). وعندما يكون ممتلئًا، تُسقَط الإدخالات الجديدة وتُعَدّ، ويُسجِّل `/agentmemory/status` ذلك. ولا يزال الخطاف يخرج بالرمز 0 ضمن حده الزمني ولا يُضيف أي طلب عندما يكون الخادم سليمًا. ويُرسَل التخزين المؤقت عند البدء التالي وبواسطة أول خطاف يصل إلى الخادم مرة أخرى، في عملية خلفية حتى لا ينتظر الوكيل. ومعرّفات الأحداث تجعل ذلك آمنًا: فالملاحظة التي وصلت فعلًا قبل انتهاء المهلة لا تُخزَّن مرتين. يُظهر أمر `npx @agentmemory/agentmemory capture` التخزين المؤقت وصندوق وارد الخادم، ويرسل `--drain` التخزين المؤقت الآن، ويُعيد `GET /agentmemory/capture` الشيء نفسه كـ JSON. اضبط `AGENTMEMORY_CAPTURE_SPOOL=false` لتعطيل التخزين المؤقت. **ضغط مصدرية الرسم البياني.** تحتفظ كل عقدة وحافة في الرسم البياني المعرفي بمعرّفات أحدث 32 ملاحظة أتت منها. وقد تحمل المخازن المكتوبة قبل ذلك الحد آلاف المعرّفات لكل عقدة نشطة، وهذا يُبطئ بحث الرسم البياني والعارض أو يُسقِط العامل. ويُصلح agentmemory ذلك بنفسه: في أول تشغيل بعد الترقية، يُقلِّص كل عقدة، وحافة، وحافة مُستبدَلة (تاريخ الرسم البياني الزمني)، واللقطة المخبَّأة إلى الحد في الخلفية، في شرائح صغيرة مع توقّف بينها، بحيث يستمر البحث والالتقاط والعارض في العمل. ويحفظ تقدّمه، ويستأنف بعد إعادة التشغيل، ولا يعمل مرة أخرى أبدًا بعد أن ينتهي. ويُظهره `/agentmemory/status` وصفحة الحالة الصحية في العارض بصفته معلَّقًا، أو قيد التشغيل (مع النطاق والموضع الحاليين)، أو مكتملًا، أو فاشلًا. اضبط `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` لتعطيله. لتشغيله يدويًا، استدعِ `POST /agentmemory/graph/compact`. فهو يتجوّل عبر فهارس الأسماء ومفاتيح الحواف بدلًا من سرد كل عقدة وحافة، وهو آمن لإعادة التشغيل. وعندما يُقلِّص المعرّفات، يكتب إدخال تدقيق `graph_compact`. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}' ``` في مخزن كبير، أو عندما يُعيد الاستدعاء 504، شغِّله على شرائح. أرسل `scope` (`nodes` أو `edges` أو `history`)، و`offset`، و`limit`، ثم استدعِ مجددًا بالقيمة المُعادة `nextOffset` إلى أن تصبح `null`. فعل ذلك لـ `nodes` و`edges` و`history`، وأنهِ باستدعاء واحد لـ `{"scope":"snapshot"}`، لأن تشغيلًا على شرائح لا يلمس اللقطة المخبَّأة. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}' curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}' ``` ---

```bash npm run dev # Hot reload npm run build # Production build npm test # 2,500+ tests npm run test:integration # API tests (requires running services) ``` **المتطلبات الأساسية:** Node.js بإصدار 20 أو أحدث مع npm/npx؛ و[iii-engine](https://iii.dev/docs) بالإصدار v0.22.1 أو Docker. ويتطلب تثبيت المحرك الآلي على macOS/Linux أيضًا `curl` وصدفة POSIX من نوع `sh` وأداة `tar`؛ ويستخدم Windows الأصلي ملف `iii.exe` المثبَّت اليدوي، أو WSL2، أو Docker Desktop.

[Apache-2.0](../LICENSE)