agentmemory: ذاكرة دائمة لوكلاء الترميز بالذكاء الاصطناعي

ذاكرة دائمة بين جلسات البرمجة والوكلاء.
ذاكرة دائمة لـ Claude Code وGitHub Copilot CLI وCursor وGemini CLI وCodex CLI وHermes وOpenClaw وpi وOh My Pi وDeepSeek Harness وOpenCode، ولأي عميل MCP.

🇬🇧 English • 🇨🇳 简体中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇵🇹 Português • 🇧🇷 Português (Brasil) • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇹 Italiano • 🇳🇱 Nederlands • 🇵🇱 Polski • 🇨🇿 Čeština • 🇷🇴 Română • 🇭🇺 Magyar • 🇬🇷 Ελληνικά • 🇸🇪 Svenska • 🇩🇰 Dansk • 🇳🇴 Norsk • 🇫🇮 Suomi • 🇷🇺 Русский • 🇺🇦 Українська • 🇹🇷 Türkçe • 🇮🇱 עברית • 🇸🇦 العربية • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇹🇭 ไทย • 🇻🇳 Tiếng Việt • 🇮🇩 Bahasa Indonesia • 🇵🇭 Tagalog

rohitg00/agentmemory | Trendshift

Design doc: 1.7k stars / 240 forks on the gist

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

npm version CI License Stars skills.sh installs

54 MCP tools 12 auto hooks 0 external DBs 5,000+ tests passing

عرض agentmemory التجريبي

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

--- يسجل AgentMemory أحداث الجلسات المدعومة ويتيح البحث عن القرارات والإصلاحات والدروس عبر الوكلاء. يمكنك فحص الذكريات وتعديلها وتصديرها وحذفها في العارض. يعمل البحث بالكلمات دون مفتاح API؛ وتضيف التضمينات البحث الدلالي. ## التثبيت المتطلبات: - يتطلب الأمر Node.js الإصدار 20 أو أحدث مع npm وnpx (تحقّق بـ `node -v` و`npm -v` و`npx -v`). - يحتاج macOS/Linux أيضًا إلى `curl` وصدفة POSIX `sh` و`tar` لإعداد البيئة تلقائيًا. - في Windows استخدم WSL2 أو [تعليمات التثبيت الأصلي](#windows). أمر التثبيت الجديد المعياري: ```bash npx -y @agentmemory/agentmemory@latest ``` اختر الوكلاء ومزوّدًا أو الوضع دون مفتاح. يحفظ الإعداد التهيئة ويشغّل خادم الذاكرة ويعرض تثبيت أمر `agentmemory` عالميًا. يقبل `-y` مطالبة npm؛ ويختار `@latest` الإصدار الحالي. يتطلب ضغط LLM مزوّدًا و`AGENTMEMORY_AUTO_COMPRESS=true`. يُعطّل وضع عدم استخدام المفاتيح تضمينات المتجهات. تستخدم `memory_recall` (مسار `mem::search`) خوارزمية BM25، في حين يمكن لـ `memory_smart_search` أيضًا دمج تطابقات الرسم البياني البنيوية عندما تتوفر بيانات رسم بياني مسبقًا. للحصول على استرجاع دلالي مجاني على الجهاز نفسه، اضبط `EMBEDDING_PROVIDER=local` في `~/.agentmemory/.env` وأعد التشغيل. يُنزِّل أول طلب تضمين النموذج `Xenova/all-MiniLM-L6-v2`؛ ويعمل الاستدلال محليًا بعد ذلك التنزيل الأولي للنموذج. واجهة API على `http://localhost:3111` والعارض على `http://localhost:3113`. يستمع كلاهما افتراضيًا للاتصالات المحلية فقط. الإعدادات في `~/.agentmemory/.env`؛ ويوضح [تخزين البيانات](#data-storage) مجلدات الذاكرة والمثيلات المنفصلة. بعد ذلك، تحقَّق من أن الاسترجاع يعمل، وأعطِ وكيلك مهاراته: ```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 `. راجع [التكاملات](#works-with-every-agent) و[الأوامر اليومية](#everyday-commands).
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`).
---

Works with every agent

يعمل agentmemory مع أي وكيل يدعم الخطافات أو MCP أو REST API. يتشارك جميع الوكلاء خادم الذاكرة نفسه.
Claude Code
Claude Code
إضافة أصلية + 12 خطافًا + MCP
Codex CLI
Codex CLI
إضافة أصلية + 6 خطافات + MCP
GitHub Copilot CLI
GitHub Copilot CLI
MCP + خطافات/مهارات الإضافة
Cursor
Cursor
إضافة أصلية + خطافات دورة الحياة + MCP
OpenCode
OpenCode
إضافة التقاط + MCP
Devin
Devin
6 خطافات + مهارات + MCP
OpenClaw
OpenClaw
إضافة أصلية + MCP
Hermes
Hermes
إضافة أصلية + MCP
pi
pi
استرجاع أصلي + التقاط + مهارات
OpenHuman
OpenHuman
خلفية أصلية باستخدام Memory trait
Gemini CLI
Gemini CLI
خادم MCP
Antigravity
Antigravity
MCP + خطافات
Claude Desktop
Claude Desktop
خادم MCP
Warp
Warp
الربط + MCP + مهارات
Zed
Zed
خادم MCP
Cline
Cline
خادم MCP
Continue
Continue
خادم MCP
Droid
Droid
خادم MCP
Kiro
Kiro
خادم MCP
Qwen Code
Qwen Code
خادم MCP
DeepSeek Harness
DeepSeek Harness
التقاط أصلي + MCP
Roo Code
Roo Code
خادم MCP
Kilo Code
Kilo Code
خادم MCP
Goose
Goose
خادم MCP
Aider
Aider
REST API
Oh My Pi
استرجاع أصلي + التقاط + مهارات + MCP اختياري

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

--- ### تخزين البيانات تُحفظ الذكريات افتراضيًا خارج المستودع: | المنصة | مجلد البيانات | |---|---| | macOS | `~/Library/Application Support/agentmemory` | | Linux | `$XDG_DATA_HOME/agentmemory` / `~/.local/share/agentmemory` | | Windows | `%APPDATA%\agentmemory` | يعيد المثيل 0 استخدام `./data/state_store.db` الموجود. اختر مجلدًا آخر عبر `--data-dir ` أو `AGENTMEMORY_DATA_DIR`. احتفظ بالمجلد نفسه عند إعادة التشغيل والترقية. ```bash agentmemory --data-dir ~/.agentmemory-projects/main agentmemory --instance 1 ``` يستخدم `--instance 1` المجلد الفرعي `instance-1` ومنفذ API ‏`3211` والعارض `3213`. راجع [دليل التخزين والنسخ الاحتياطي](../docs/reliability/state-storage.md) لمعرفة Redis والترحيل. ملاحظات آخر إصدار: [CHANGELOG.md](../CHANGELOG.md). ---

Benchmarks

نتائج الاسترجاع الحالية، وتعريف المقاييس، وخطوات إعادة الاختبار: [0.9.31 · 2026-10-28 · strict recall-all@5](../docs/benchmarks/2026-10-28-retrieval-evaluation.md) · [eval/README.md](../eval/README.md). ---

vs Competitors

مقارنة محدثة بين المنتجات وخيارات النشر، مع المصادر: [AgentMemory / Mem0 / Supermemory / Zep / Letta / Cognee / claude-mem](../benchmark/COMPARISON.md) · 2026-10-28. ---

Quick Start

### جرّبه في 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` لمشاهدة بناء الذاكرة مباشرةً. ### التحقق من تثبيت جديد واستمرارية البيانات بعد إعادة التشغيل عندما يعمل الخادم، تحقق من الصحة والعارض والحالة: ```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 ``` يعرض `status` صحة الخادم والمزوّدين ووضع التضمين وتسليم الملاحظات والاستعادة. تتطلب طلبات REST المحمية سر الخادم. استخدم قيمة `AGENTMEMORY_SECRET` التي حددتها؛ وإلا فاقرأ السر المحلي المُنشأ: ```bash # Default generated local secret. For an explicit AGENTMEMORY_SECRET, use that value instead. read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret" curl -fsS -X POST http://localhost:3111/agentmemory/remember \ -H "Authorization: Bearer $AGENTMEMORY_SECRET" \ -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 "Authorization: Bearer $AGENTMEMORY_SECRET" \ -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 status agentmemory capture agentmemory capture --drain 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 بجانب الجلسات الأصلية. تُفهرس النصوص وتُوسم بقناة المصدر `import`؛ ويمكن أن ينتج عن المعالجة بلورات جلسات ودروس أيضًا. > **تنبيه إذا كنت تعتمد على `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 في مساحة العمل الحالية. انسخ البيانات احتياطيًا واقرأ [دليل الترقية](../docs/upgrades/iii-0.25.md). ### Claude Code (كتلة واحدة، الصقها) ```text Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. 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 ``` يضبط هذا الأمر خادم MCP ويدمج الخطافات المضمّنة في إعدادات مستخدم Claude Code. عندما لا يكون `CLAUDE_CONFIG_DIR` مضبوطًا أو تكون قيمته فارغة أو مؤلفة من مسافات بيضاء فقط، يستخدم `~/.claude.json` لإعدادات MCP و`~/.claude/settings.json` للخطافات. تُستخدم قيم الأدلة الأخرى كما هي تمامًا، بما في ذلك المسافات البيضاء في البداية والنهاية. لاستخدام دليل مخصص، اضبط `CLAUDE_CONFIG_DIR` على القيمة غير الفارغة نفسها عند تشغيل هذا الأمر وClaude Code؛ وعندها يكون الملفان `$CLAUDE_CONFIG_DIR/.claude.json` و`$CLAUDE_CONFIG_DIR/settings.json`، على الترتيب. يجب أن يتلقى Claude Code هذه القيمة في بيئة تشغيله، حتى إذا قرأها الموصل من ملف `.env` الخاص بـ AgentMemory. أنشئ الدليل المخصص قبل تشغيل هذا الأمر؛ وإلا فسيتجاوز الموصل Claude Code باعتباره غير مكتشف. إذا كانت قيمة المتغير في بيئة shell مؤلفة من مسافات بيضاء فقط، فألغِ تعيين `CLAUDE_CONFIG_DIR` قبل تشغيل Claude Code ليستخدم الإعدادات الافتراضية أيضًا. استخدم مسارًا مطلقًا. تُحل المسارات النسبية انطلاقًا من دليل العمل، لذا يجب تشغيل الأمرين من الدليل نفسه. تستخدم أوامر الخطافات مسارات مطلقة إلى دليل `plugin/` المضمّن في الحزمة المثبّتة. أعد تشغيل الأمر بعد ترقية 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`. ثبّت الإضافة أيضًا إذا رغبت في تجربة الخطافات/المهارات الكاملة. ### Cursor ```bash agentmemory connect cursor ``` بعد ذلك، من **Settings → Plugins → Add marketplace** اختر مجلد agentmemory الذي يحتوي على `.cursor-plugin/plugin.json`، وفعّل إضافة **agentmemory** وأعد تحميل النافذة. توفر الإضافة التقاط دورة الحياة وإسناد المشروع حسب مساحة العمل والمهارات وMCP. فعّل خطافات الإضافة أو الخطافات اليدوية في `~/.cursor/hooks.json` لتجنب التسجيل المكرر. [Cursor](../integrations/cursor/) ### Pi, Oh My Pi, DeepSeek Harness ```bash agentmemory connect pi --with-mcp agentmemory connect omp --with-mcp agentmemory connect dsh --with-hooks ``` اختر أمر العميل الذي تستخدمه. يثبت Pi وOMP الاسترجاع والتقاط الأحداث وإعادة إرسال البيانات غير المتصلة والمهارات؛ ويضيف `--with-mcp` جميع الأدوات. شغّل `/reload` في Pi أو أعد تشغيل OMP، ثم تحقق من `/agentmemory-status`. يثبت DSH ‏MCP وإضافة الالتقاط المرفقة؛ أعد تشغيل DSH بعد الربط. يدعم Pi أيضًا الحزمة القابلة للتثبيت `@agentmemory/pi`. يوضح [دليل Pi](../integrations/pi/) التثبيت المحلي وتوفر npm. استخدم طريقة تثبيت واحدة لكل عميل. [Pi](../integrations/pi/) · [Oh My Pi](../integrations/omp/) · [DSH](../docs/dsh.md)
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 https://github.com/rohitg00/agentmemory 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. يثبت Hermes وOpenClaw وPi وOh My Pi التكامل الأصلي والمهارات افتراضيًا؛ ويمكن تفعيل MCP باستخدام `--with-mcp`. - يثبت `npx skills add rohitg00/agentmemory` المهارات للوكلاء الذين لا تتضمن حزمهم مهارات أصلية. تخطّ هذه الخطوة مع Hermes وOpenClaw وPi وOh My Pi؛ فموصلاتها تثبت المهارات بالفعل. بالنسبة للوكلاء القليلين الذين لا تغطيهم واجهة سطر الأوامر 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/` | توفر الإضافة خطافات دورة الحياة وتحديد مساحة العمل والمهارات وMCP في Cursor IDE و`cursor-agent`. راجع [إعداد Cursor](#cursor). | | **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 --with-mcp`. استرجاع أصلي + التقاط + مهارات. `/reload`, `/agentmemory-status`. [Pi](../integrations/pi/). | | **Oh My Pi** | `~/.omp/agent` | `agentmemory connect omp --with-mcp`. استرجاع أصلي + التقاط + مهارات. [Oh My Pi](../integrations/omp/). | | **وكيل 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` و`lesson` و`commit-context` و`commit-history` و`session-history`) أصليًا في لوحة أوامر الشرطة في Warp. | | **Cline (CLI)** | `~/.cline/data/settings/cline_mcp_settings.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` الموجود. بالنسبة إلى YAML موجود، يعرض الكتلة لإضافتها تحت `mcpServers:` للحفاظ على التعليقات والمراسي. يستخدم Continue مصفوفة لا كائنًا. | | **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` أدوات MCP. أضف `--with-hooks` لتحميل إضافة الالتقاط الأصلية المضمّنة مع AgentMemory، دون حزمة إضافية. [DSH](../docs/dsh.md). | | **Goose** | واجهة إعدادات MCP في Goose | نفس كتلة `mcpServers`؛ استخدم `goose configure` ← Add Extension ← MCP. يُدعم التعديل المباشر لملف YAML في `~/.config/goose/config.yaml`، لكن المخطط يستخدم `extensions:` + `cmd` (وليس `mcpServers:` + `command`). | | **Aider** | لا ينطبق | استخدم [أمثلة REST الموثّقة](#validate-a-fresh-install-and-restart-persistence) للحفظ والبحث من السكربتات. | | **الوكلاء المدعومون** | المهارات فقط | `npx skills add rohitg00/agentmemory`; اختر المهارات والوكلاء الذين تريد تثبيتها لديهم. | **عملاء MCP المحتجزون في بيئة معزولة (sandbox)** (Flatpak / Snap / الحاويات المقيَّدة) الذين لا يمكنهم الوصول إلى `localhost` الخاص بالمضيف: اضبط أيضًا `"AGENTMEMORY_FORCE_PROXY": "1"` في كتلة `env`، ووجِّه `AGENTMEMORY_URL` إلى مسار يمكن للبيئة المعزولة الوصول إليه فعليًا (مثل عنوان IP على شبكتك المحلية). ### الوصول البرمجي (Python / Rust / Node) استخدم [REST API](#api) من أي لغة أو [أدوات MCP](#mcp-server) من وكيل. يستخدم REST ‏JSON ومصادقة bearer؛ راجع [مثال الحفظ والبحث](#validate-a-fresh-install-and-restart-persistence). للتكامل المباشر مع بيئة التشغيل، راجع [أمثلة Python](../examples/python/). ### من المصدر ```bash git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory npm install && npm run build && npm start ``` يشغّل `npm start` الخادم المحلي نفسه الذي يشغّله CLI المثبّت. المتطلبات في [التثبيت](#install)؛ ويستمع API والعارض على `127.0.0.1`. ### Windows يعمل agentmemory على Windows 10/11. يتبع WSL2 مسار Linux ويمكنه تثبيت المحرك المثبّت تلقائيًا. يتطلب Windows الأصلي تثبيت ملف iii-engine 0.25.1 المثبّت يدويًا؛ نزّل الأرشيف المطابق من [صفحة إصدار iii 0.25.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.25.1)، وتحقق من بصمته، وضع `iii.exe` على `PATH` (مثل `%USERPROFILE%\.local\bin\iii.exe`). لا يستخرج CLI ملف ZIP الخاص بـ Windows تلقائيًا. لا يدعم الربط الآلي لـ MCP على Windows الأصلي إلا `agentmemory connect copilot-cli`. أما وكلاء Windows الأصليون الآخرون، فاستخدم كتلة MCP اليدوية من [وكلاء آخرون](#other-agents). شغّل `connect` داخل WSL فقط عندما يكون الوكيل المستهدف مثبتًا في بيئة WSL نفسها. **MCP القائم بذاته فقط (من دون المحرك).** إذا كنت تحتاج إلى أدوات MCP فقط ولا تحتاج إلى REST API أو العارض أو خدمات runtime: ```powershell npx -y @agentmemory/agentmemory@latest mcp # or npx -y @agentmemory/mcp ``` شغّل `agentmemory doctor` أو أعد التشغيل مع `--verbose`. إذا كانت المنافذ مشغولة، استخدم `--port ` أو `--instance `. يوضح [دليل الترقية](../docs/upgrades/iii-0.25.md) التوافق والاستعادة. ---

النشر

للاستضافة الذاتية استخدم Docker Compose أو القوالب أدناه. توجد الذاكرة وبيانات الاعتماد على وحدة `/data`؛ انسخها احتياطيًا وأعد استخدامها عند الترقية. يوضح [دليل النشر](../deploy/README.md) المصادقة والشبكة والنسخ الاحتياطي والترحيل.

Deploy to fly.io Deploy to Railway

يتطلب زر نشر 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، وأنت من يملك المضيف والبيانات. يستخدم REST المنفذ `3111` والعارض `3113`. أبقهما خاصين أو احمهما بالمصادقة وTLS. إعدادات المنصات و[ترحيل Docker القديم](../deploy/README.md#migrating-from-the-legacy-cli-docker-mode) موضحة في دليل النشر. ---

Why agentmemory

تتوزع معرفة المشروع بين المحادثات وملفات التعليمات. يتيح AgentMemory البحث عن القرارات والإصلاحات والدروس السابقة من الوكيل المستخدم حاليًا. ### مقابل ذاكرة الوكيل المدمجة يشحن كل وكيل ترميز بذكاء اصطناعي بذاكرة مدمجة: فـ Claude Code يملك `MEMORY.md`، وCursor يملك notepads، وCline يملك memory bank. تعمل هذه كملاحظات لاصقة (sticky notes). أما agentmemory فهو قاعدة البيانات القابلة للبحث التي تقف خلف تلك الملاحظات اللاصقة. | | مدمج (CLAUDE.md) | agentmemory | |---|---|---| | الصيانة | تعليمات تُدار يدويًا | سجل جلسات وذكريات مفهرسة | | البحث | يحمّل كل شيء إلى السياق | BM25 + متجهات + رسم بياني (أفضل K فقط) | | بين الوكلاء | ملفات لكل وكيل | MCP + REST (أي وكيل) | | التنسيق | لا يوجد | حجوزات، وإشارات، وإجراءات، ومسارات عمل (routines) | | قابلية الرصد | قراءة الملفات يدويًا | عارض لحظي على :3113 | ---

How It Works

### مسار الذاكرة ```text PostToolUse hook fires -> Stable event ID / durable capture inbox / offline spool -> 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 AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true) SessionStart hook fires -> Load project profile (top concepts, files, patterns) -> Hybrid search (BM25 + vector + graph) -> Token budget (default: 2000 tokens) -> Inject context when enabled by the integration ``` ### توحيد الذاكرة الرباعي المستويات مصمَّم على غرار كيفية معالجة العقل البشري للذاكرة، بما في ذلك التوحيد أثناء النوم. | المستوى | المحتوى | المثيل البشري | |------|------|---------| | **العاملة (Working)** | ملاحظات خام من استخدام الأدوات | الذاكرة قصيرة المدى | | **الحدثية (Episodic)** | ملخصات مضغوطة للجلسات | "ما الذي حدث" | | **الدلالية (Semantic)** | حقائق وأنماط مستخرجة | "ما الذي أعرفه" | | **الإجرائية (Procedural)** | مسارات عمل وأنماط قرارات | "كيف يتم ذلك" | تتلاشى الذكريات بمرور الوقت (منحنى إبنغهاوس). وتتقوّى الذكريات التي يُرجَع إليها كثيرًا. ويُطرَد تلقائيًا الذكريات القديمة البائتة. ويُكتشف التضارب ويُحل. ### ما الذي يُلتَقط يصف الجدول خطافات Claude Code. تلتقط التكاملات الأخرى الأحداث التي يوفرها عميلها. حقن السياق التلقائي عبر الخطافات المشتركة اختياري: `AGENTMEMORY_INJECT_CONTEXT=true`. | الخطاف | يلتقط | |------|----------| | `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 مخصص في الذاكرة بدلًا من مسح المجموعة الكاملة في كل استعلام. وتُستبعد نسخ الذاكرة المُستبدَلة من كل مسار استرجاع؛ وتحتفظ سلسلة الإصدارات بتاريخها. [0.9.31: `AGENTMEMORY_VECTOR_BACKFILL=all` / `AGENTMEMORY_VECTOR_BACKFILL_MAX`](../docs/reliability/source-and-vector-recovery.md). يُجزِّئ 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` | مجاني | [`EMBEDDING_PROVIDER=local`](../README.md#embedding-providers) | | 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` | [OpenAI](https://openai.com/api/pricing/) | [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) | | Voyage AI | `voyage-code-3` | مدفوع | مُحسَّن للشفرة | | Cohere | `embed-english-v3.0` | نسخة تجريبية مجانية | للاستخدام العام | | OpenRouter | أي نموذج | متفاوت | وكيل متعدد النماذج | ---

MCP Server

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` (أو اتصل بخادم استضافة ذاتية) واضبط `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/ ``` ---

Real-Time Viewer

يبدأ العارض تلقائيًا على المنفذ `3113`. يحمّل لقطة واحدة عند الاتصال (`GET /agentmemory/viewer/snapshot`)، ثم يطبّق الأحداث الحية عبر SSE عند `/agentmemory/viewer/events` على عامل REST: تظهر الذكريات الجديدة والدروس والملاحظات وإدخالات التدقيق وتغييرات الرسم البياني وتحديثات الحالة الصحية دون استقصاء دوري أو إعادة تحميل للصفحة. والطلبات الأخرى الوحيدة هي الإجراءات التي تنقر عليها وصفحات "تحميل المزيد" وعمليات البحث. عند انقطاع التيار، يُظهر العارض مدى قِدَم بياناته، ويعيد الاتصال بتراجع تدريجي (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. عند الارتباط بعنوان غير loopback، تظل واجهة HTML متاحة للعامة، لكن كل طلب وكيل يتطلب رمز الحامل؛ ويطلبه العارض ويحفظه في تخزين الجلسة. اضبط قوائم سماح صريحة للمضيفين والمنشأات وTLS قبل إتاحة العارض. وتتبع نقطة النهاية `/agentmemory/viewer` المقدمة عبر REST قواعد رمز الحامل المعتادة، وتعيد توجيه المتصفحات التي لا تحمل رمزًا إلى منفذ العارض. تستخدم ترويسات CSP قيمة nonce خاصة بالنص البرمجي لكل استجابة، وتعطّل سمات المعالج المضمّنة (`script-src-attr 'none'`). ---

Configuration

### مزوّدو 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` أن يُضيف تطابقات الرسم البياني الموجودة مسبقًا. ### اختيار النموذج الواعي بالتكلفة ابدأ دون مفتاح لالتقاط الأحداث والبحث بالكلمات. يفعّل `EMBEDDING_PROVIDER=local` البحث الدلالي المحلي بعد تنزيل النموذج. يتطلب ضغط LLM مزوّدًا و`AGENTMEMORY_AUTO_COMPRESS=true`؛ وقد يرسل طلبًا لكل ملاحظة، لذا تحقق من الأسعار الحالية. يعرض العارض و`agentmemory status` المزوّدين النشطين. ### ذاكرة متعددة الوكلاء (`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` غير مضبوط، تبقى الذاكرة بلا نطاق محدد (السلوك القديم، بلا وسوم، بلا ترشيح). ### المنافذ | Port | الغرض | متغير البيئة | |---|---|---| | `3111` | REST API وMCP HTTP وأحداث العارض المباشرة | `III_REST_PORT` | | `3113` | واجهة العارض | `III_VIEWER_PORT` | يضبط `--port ` منفذ REST والعارض افتراضيًا على `N+2`. ينشئ `--instance N` بيئة منفصلة. يجب أن تبقى المنافذ الداخلية خاصة؛ اقرأ [دليل النشر](../deploy/README.md) قبل الوصول عن بُعد. ### التخزين: ملف أو Redis لا يتطلب التخزين الافتراضي بالملفات قاعدة منفصلة. Redis اختياري عبر `AGENTMEMORY_STATE_BACKEND=redis` و`AGENTMEMORY_REDIS_URL`. تغيير الخلفية لا ينقل الذكريات الموجودة. الاستمرارية وقيود Redis والتصدير والاستيراد بالمصادقة موضحة في [دليل التخزين](../docs/reliability/state-storage.md). ### ملف الإعدادات ضع إعدادات runtime الخاصة بـ agentmemory في `~/.agentmemory/.env` بدل تصدير المتغيرات في كل صدفة. إذا عرض العارض تلميح إعداد مثل `export ANTHROPIC_API_KEY=...`، فانسخه إلى هذا الملف كـ `ANTHROPIC_API_KEY=...` دون السابقة `export`، ثم أعد تشغيل agentmemory. اضبط `AGENTMEMORY_ENV_FILE` لاستخدام مسار آخر لملف البيئة. تتقدم متغيرات بيئة العملية على قيم الملف. أعد تشغيل الخادم بعد تغيير الإعدادات. على 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`. حقن السياق والضغط اختياريان؛ ويتطلب الضغط مزوّدًا أيضًا. يحد وضع `core` من أدوات MCP الظاهرة: ```env EMBEDDING_PROVIDER=local # AGENTMEMORY_INJECT_CONTEXT=true # AGENTMEMORY_AUTO_COMPRESS=true # AGENTMEMORY_TOOLS=core # AUTO_FORGET_ENABLED=false # LESSON_DECAY_ENABLED=false # INSIGHT_DECAY_ENABLED=false ``` يشمل المرجع الكامل [`.env.example`](../.env.example) المزوّدين ومرشحات الالتقاط والاحتفاظ والتخزين والفرق والميزات الاختيارية. يختار `AGENTMEMORY_ENV_FILE` ملفًا آخر. لا تُضمّن ملف `.env` ممتلئًا أو سر bearer في أي commit. ---

API

147 نقطة نهاية على المنفذ `3111`. ترتبط REST API بـ `127.0.0.1` افتراضيًا. تتطلب نقاط النهاية المحمية ترويسة `Authorization: Bearer `، وتتطلب نقاط نهاية مزامنة mesh ضبط `AGENTMEMORY_SECRET` صريحًا على كلا الطرفين. **المصادقة مُفعّلة افتراضيًا.** إذا لم يُضبط `AGENTMEMORY_SECRET`، ينشئ CLI عند التشغيل الأول سرًا عشوائيًا في `~/.agentmemory/secret` بصلاحيات `0600` وينسخه أيضًا إلى مجلد البيانات المحدد. يقرأ كل عميل مضمّن هذا السر عند الاتصال بخادم محلي: CLI والعارض والخطافات تحت `plugin/scripts` وخادم MCP ووسيط `@agentmemory/mcp` والإعدادات التي يكتبها `agentmemory connect` وتكاملات OpenCode وPi وOpenClaw وHermes ومراقب نظام الملفات المضمّنة. لا يُرسل السر المحفوظ إلا إلى عناوين loopback (`localhost` و`127.0.0.0/8` و`::1`). وتكون الأولوية دائمًا لقيمة `AGENTMEMORY_SECRET` الصريحة، كما يجب ضبط السر في بيئة العملاء البعيدين. تنشئ عمليات الاستضافة الذاتية عبر Docker من المستودع ونقاط دخول [`deploy/`](../deploy/) سرها وتصدّره. لاستدعاء API يدويًا: ```bash curl -H "Authorization: Bearer " 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` | مسار التدقيق | قائمة نقاط النهاية الكاملة: [مرجع REST المُولّد](../plugin/skills/agentmemory-rest-api/REFERENCE.md)
**تسليم الالتقاط.** تُرسل الخطافات كل ملاحظة مرة واحدة إلى `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` لتعطيل التخزين المؤقت. **ضغط مصدرية الرسم البياني.** يؤجَّل ضغط المصدرية القديمة عند بدء التشغيل لأنه يقرأ النطاقات القديمة كاملة. يعرض `/agentmemory/status` الحالة `deferred`، أو `off` عند ضبط `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`. شغّل الضغط اليدوي أدناه أثناء الصيانة. ترحيل فهرس الاسترجاع عملية منفصلة: استخدم `agentmemory graph-index migrate --allow-legacy-scan` كما يوضح [دليل الصيانة](../docs/reliability/graph-index-migration.md). لتشغيله يدويًا، استدعِ `POST /agentmemory/graph/compact`. فهو يتجوّل عبر فهارس الأسماء ومفاتيح الحواف بدلًا من سرد كل عقدة وحافة، وهو آمن لإعادة التشغيل. وعندما يُقلِّص المعرّفات، يكتب إدخال تدقيق `graph_compact`. ```bash curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -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 "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}' curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{"scope":"snapshot"}' ``` ---

Development

```bash npm run dev # Hot reload npm run build # Production build npm test # 5,000+ tests npm run test:integration # API tests (requires running services) ``` المتطلبات في [التثبيت](#install). قواعد المساهمة وفحوص الإصدار في [CONTRIBUTING.md](../CONTRIBUTING.md).

License

[Apache-2.0](../LICENSE)