# أفضل ممارسات الذاكرة

كيف تُنظَّم الذكريات يحدد مدى فائدتها. يغطي هذا الدليل
أنماط تصنيف ووسم وأولوية الذكريات حتى يستطيع الـ LLM
استدعاء المعلومة الصحيحة في الوقت المناسب.

## الفئات: اختر الأكثر تحديدًا

| الفئة | استخدم لـ | مثال |
|----------|---------|---------|
| `identity` | اسم المستخدم، الدور، معلومات الاتصال | `"user_name": "Michael Schäfer"` |
| `preference` | الإعجابات، عدم الإعجابات، أسلوب العمل | `"communication": "Prefers concise responses"` |
| `fact` | حقائق قابلة للتحقق | `"office_location": "Berlin, Germany"` |
| `project` | حالة المشروع، القرارات | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | مهارات المستخدم | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | أخطاء سابقة يجب تجنبها | `"mistake_npm_version": "Always bump version"` |
| `context` | سياق ذو صلة بالجلسة | `"current_focus": "Working on docs system"` |
| `note` | ملاحظات متفرقة | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> عند الشك، استخدم `fact` للمعلومات القابلة للتحقق و `note` لكل شيء آخر.
> لا تفرط في التصنيف — أفضل أن يكون لديك `fact` واضح من `context` مربك.

## المفاتيح: مُعرّفات ذات معنى

الحقل `key` هو مُعرّف الذاكرة. استخدم مفاتيح ذات معنى وثابتة:

**مفاتيح جيدة:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**مفاتيح سيئة:**
- `mem_001` (ليس ذا معنى)
- `temp` (ليس وصفيًا)
- `2026-06-27-note` (التاريخ لا يساعد الاستدعاء)

### اصطلاحات تسمية المفاتيح

- `snake_case` (أحرف صغيرة مع شرطات سفلية)
- بادئة بالفئة: `preference_*`، `project_*`، `mistake_*`
- استخدم أسماء وصفية، لا أفعالًا
- أبقِها أقل من 50 حرفًا

## الوسوم: للبحث والتصفية

تُمكّن الوسوم التصفية والبحث السريع. أضف 2-5 وسوم لكل ذاكرة:

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",
  "tags": ["synapse", "deployment", "status", "v1.5.0"]
}
```

### أنماط الوسوم

- **أسماء المشاريع**: `synapse`، `synapse-mcp`، `synapse-chat`
- **المواضيع**: `deployment`، `ci`، `database`، `auth`
- **الحالة**: `active`، `completed`، `blocked`
- **مؤشرات الأولوية**: `urgent`، `long-term`

> [!NOTE]
> الوسوم غير حساسة لحالة الأحرف. استخدم أحرفًا صغيرة للاتساق.

## الأولويات: كن واقعيًا

| الأولوية | استخدم لـ | % من الذكريات |
|----------|---------|---------------|
| `critical` | هوية المستخدم، المعلومات القانونية، القرارات غير القابلة للتراجع | ~5% |
| `high` | المشاريع النشطة، التفضيلات المهمة | ~20% |
| `normal` | معظم الحقائق، الملاحظات، السياق | ~65% |
| `low` | عابرة، جيد معرفتها | ~10% |

> [!WARNING]
> لا تعلّم كل شيء `critical`. إذا كان كل شيء حرجًا، فلا شيء كذلك.
> احجز `critical` للأشياء التي تسبب ضررًا حقيقيًا إذا نُسيت.

## متى تخزّن ومتى لا تخزّن

### خزّن دائمًا

- هوية المستخدم (الاسم، البريد، الدور)
- التفضيلات طويلة الأمد
- قرارات المشروع والمبررات
- الأخطاء السابقة والدروس المستفادة
- الالتزامات المقطوعة للمستخدم

### لا تخزّن

- الحالة العابرة (استخدم المتغيرات بدلًا من ذلك)
- سجل المحادثة الحرفي (نظام الدردشة يتولى هذا)
- البيانات الحساسة (كلمات المرور، مفاتيح API)
- الحقائق المشتقة بسهولة (التاريخ الحالي، محتويات الملفات)
- السياق العابر (استخدم فئة `context` بأولوية منخفضة)

## تحديث الذكريات

استدعِ `POST /memory` بنفس `category` + `key` يُحدّث الذاكرة الموجودة:

```python
# التخزين الأول
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# لاحقًا: التحديث بنفس المفتاح
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> استخدم مفاتيح ثابتة حتى تُحدّث دون إنشاء مكررات. على الـ LLM
> إعادة POST لنفس المفتاح مع تغير المعلومات، لا إنشاء ذكريات جديدة.

## دورة حياة الذاكرة

```
Create → Active → Stale → Archive → Delete
```

- **Create**: POST /memory بسياق كامل
- **Active**: استدعِ كثيرًا، حدّث حسب الحاجة
- **Stale**: ما زال ذا صلة لكن غير مستخدم بنشاط (أولوية أقل؟)
- **Archive**: عيّن الأولوية إلى `low`، أبقِ للمرجع التاريخي
- **Delete**: DELETE /memory/:id عندما لا يعود ذا صلة

### تنظيف دوري

```python
# إيجاد الذكريات غير المُحدّثة منذ 90 يومًا
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # إما حذف أو خفض الأولوية
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## نمط: وراثة الذاكرة

للسياق الهرمي (مشروع → مشروع فرعي → مهمة):

```python
# المشروع الأب
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# مشروع فرعي (الوسوم تربط بالأب)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# مهمة محددة (الوسوم تربط بالمشروع الفرعي)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

يستطيع الـ LLM حينها البحث `q=synapse+docs` لإيجاد جميع الذكريات ذات الصلة.

## نمط: سجل القرارات

خزّن القرارات مع المبررات حتى لا يعيد الـ LLM مناقشتها:

```python
store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")
```

## نمط: تجنب الأخطاء

خزّن الأخطاء مع تعليمات تجنب محددة:

```python
store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")
```

## أنماط مضادة يجب تجنبها

> [!WARNING]
> - **تخزين سجلات المحادثة** — نظام الدردشة يتولى هذا
> - **تخزين الملفات الكاملة** — استخدم تخزين السكربتات أو تخزينًا خارجيًا
> - **تخزين الحالة العابرة** — استخدم المتغيرات
> - **تخزين الأسرار** — استخدم متغيرات البيئة
> - **تكرار الذكريات** — استخدم مفاتيح ثابتة
> - **الإفراط في الوسم** — 2-5 وسوم لكل ذاكرة مثالي
> - **كل شيء حرج** — كن واقعيًا مع الأولويات

## الخطوات التالية

- [Memory API](/docs/api/memory)
- [وكيل LLM الدائم](/docs/guides/persistent-llm-agent)
- [استراتيجية وسوم الذاكرة](/docs/llm-cookbook/memory-tagging-strategy)