الذاكرة — المسار الأفضل (دليل المشغّل)

الذاكرة — المسار الأفضل لكاظمه

الطريقة الموصى بها لتشغيل الذاكرة المعرفية V2 + مكتبة المعرفة بعد برنامج الذاكرة. لا تدمج المخازن في جدول واحد. استخدم تجربة دردشة موحّدة على مخازن منفصلة.

البنية المعمارية العميقة: الذاكرة وRAG.

البنية المعمارية (أبقِها كما هي)

Chat turn
  ├─ Personal memory (V2): beliefs + episodes  → memory_state.db
  ├─ Knowledge Library (optional inject)       → knowledge_* stores
  └─ Optional scale adapters
       • pgvector (auto when Postgres DSN is set) / Qdrant
       • Postgres dual-mirror or state.role=primary
       • Neo4j (dual-write; Dashboard still paints SQLite)

المخزن	الدور	الافتراضي
V2 المعرفية	«مَن أنا / ماذا قلنا»	SQLite أساسي على عقدة واحدة
مكتبة المعرفة	«ماذا تقول الوثائق» + استشهادات	مخزن منفصل
المتجهات الكثيفة	تضمينات الحلقات/المعتقدات	sqlite-vec → pgvector عند مغادرة عقدة واحدة
Neo4j	كتابة مزدوجة لثلاثيات المعتقدات	اختياري
Postgres	مرآة حالة متعددة العمليات / أساسي	اختياري

قائمة فحص المشغّل

الذاكرة الشخصية — الافتراضيات؛ اكتب في الدردشة “Remember my favorite color is teal.” ثم “What color?”
الوثائق — حمّل مكتبة المعرفة؛ أبقِ Inject Knowledge into chat مفعّلًا (الإعدادات → الذاكرة).
البحث الاتحادي — لوحة التحكم → Search all knowledge → Federated (رقاقات MEM / KB).
شرح الاسترجاع (مفعّل افتراضيًا) — الإعدادات → الذاكرة → Explain recall؛ صف Memory used في كل دور يسمّي القنوات التي وجدت كل ذاكرة.
بحث المعرفة الذكي (اختياري) — وسّع الحقن إلى كل المكتبات النشطة عند الأسئلة التقنية.
إدارة الذاكرة (/memory) — الرسم + الكيانات/المعتقدات (أدناه).
الفحص الدخاني (Smoke) — pwsh -File scripts/memory_smoke.ps1 · مصفوفة الفحص الدخاني · الميزات الحديثة
Neo4j اختياري — فقط إن أردت الكتابة المزدوجة للرسم (أدناه).
التوسّع — اضبط KAZMA_DATABASE_URL على Postgres يأتي مع pgvector (pgvector/pgvector:pg16، وليس postgres:16-alpine). يصبح pgvector محرك المتجهات الكثيفة تلقائيًا؛ وصفحة الإعدادات → الذاكرة تخبرك إن كان الخادم لا يستطيع حمل المتجهات (KAZMA_PGVECTOR=0 يُبقي sqlite-vec). لا تضبط KAZMA_MEMORY_STATE_ROLE=primary حتى يمرّ python scripts/reconcile_memory_mirror.py --dry-run نظيفًا.

صفحة إدارة الذاكرة (`/memory`)

استخدم هذه الصفحة لتنظيف الطوبولوجيا دون SQL خام.

الهدف	الكيفية
عرض رسم المعتقدات	لوحة Graph & health في الأعلى؛ حدّث إن بدت التسميات قديمة. لافتة الاقتطاع تُبلغ أيضًا عن الاتصالات المخفيّة بحدّ العُقَد.
تجميع عقدة / فك تجميعها	Inspect → Group under→ (انقر الأب) أو Ungroup. عرض فقط — المعتقدات لا تُمَسّ.
إيجاد كيان خارج أعلى 150	صندوق بحث الكيانات → اكتب الاسم/الكنية (FTS5، غير حساس للتشكيل)؛ استخدم Load more إن أظهر “Showing X of Y” المزيد
إعادة تسمية محور «You» إلى اسم العلامة	الكيانات: ابحث عن الشخص User / `ent_…` أو المحور → Rename → مثل `Mubder`. ينبغي أن يعرض محور اللوحة ذلك الاسم.
إعادة تسمية عقدة مشروع	انقر العقدة أو صف الكيان → Rename (يبقى المعرّف `shipx`؛ وتصبح التسمية `ShipX`)
تركيز القائمة ↔ الرسم	انقر صفًا لتقريب اللوحة؛ وانقر عقدة لإبراز القائمة
إصلاح معتقد خاطئ	تبويب المعتقدات → Edit (نافذة واحدة: المفعول / المحمول / الفاعل)
التراجع عن تعديل/إبطال خاطئ	انقر [Undo] على تنبيه الإجراء (نافذة 60 ثانية) — أو استعد من Maintenance → النسخ الاحتياطية للأخطاء الأقدم
دمج الأصداف المكررة	اضبط Src + Tgt → Merge (يُعاد توصيل المعتقدات بالهدف؛ ويعرض الإيصال العدد)
ربط كيانين	Src + Tgt + محمول → Link
إسقاط المعتقدات الرديئة	حدّد → Invalidate
لماذا استُخدم معتقد ما؟	انقر معتقدًا → يعرض الدرج “recalled N× · last … · from `episode`”؛ وProbe from this belief لرؤية الجيران

ملاحظة هوية المحور

عقدة مركز اللوحة هي دائمًا id=user. تُعامَل الصدفة الشخصية المنفصلة (ent_… باسم User) بوصفها الذات نفسها: إعادة التسمية تحدّث اسم عرض المحور، والنقر على القائمة يركّز المحور (graph_id: user). لا تتوقع عقدة «You» ثانية لتلك الصدفة.

تعمّق أكثر: الذاكرة وRAG — واجهة إدارة الذاكرة.

إعدادات مهمة

الواجهة: الإعدادات → الذاكرة (/settings?tab=memory)
تشمل العزل، ومفاتيح مكتبة المعرفة، والخلفيات، واختبار/مزامنة Neo4j، والمضمِّن (لا يوجد تبويب Embedder منفصل).

الإعداد	الأثر
`merge_knowledge_into_chat`	حقن KB الموسوم في المشرف بجوار ذاكرة V2
`memory.backends.*`	محوّلات المتجهات / الحالة / الرسم + تجاوز الفشل
موفّر الرسم `neo4j`	كتابة مزدوجة للثلاثيات؛ رسم الطوبولوجيا يبقى على SQLite
`tenant_mode`	shared / per_platform / per_user
`KAZMA_MEMORY_ENFORCE_TENANT=1`	حصر كل مسار من مسارات `/api/memory` بمستأجر الطلب — القراءات والعدّ والتعديلات والتراجع والتنظيف ومسح الرسم (مفعّل دائمًا في الإنتاج وتعدد المستخدمين؛ الإيقاف = `default`)

Neo4j اختياري

export KAZMA_NEO4J_PASSWORD=YOUR_PASSWORD_HERE
docker compose -f deploy/docker-compose.neo4j.yml up -d

# Env install default (fail-open if server down):
export KAZMA_NEO4J_DEFAULT=1

اختر كلمة مرور قوية قبل تشغيل Compose؛ يرفض الإقلاع كلمة المرور غير المضبوطة. وترتبط منافذ HTTP وBolt المنشورة بعنوان loopback.

أو عبر الواجهة: مخزن الرسم Neo4j → Save → Test Neo4j → Sync beliefs → Neo4j.

كلمة المرور المقنّعة *** في النموذج لا تمحو سر الخزنة عند الاختبار (Test).
مسح الرسم (Clear graph) يُبطل معتقدات SQLite ويحذف حواف Neo4j الخاصة بذلك المستأجر. لا تلزم مزامنة يدوية إلا إذا كانت الكتابة المزدوجة متوقفة أثناء المسح.
لا تجعل Neo4j تثبيتًا لازمًا للإعدادات أحادية المستخدم.

الصيانة

المهمة	الوتيرة
macro_sleep (طوابق قواعدية + أرشفة؛ الذكريات قيد الاستخدام لا تُؤرشف أبدًا) + تعبئة ego-anchor + إعادة بناء انحراف FTS	~6 ساعات
نسخ احتياطي + تصدير (معتقدات، حلقات، عمليات دمج، أرشيف، JSONL للتدقيق) + تحذير انحراف المرآة	~6 ساعات
إعادة التوحيد الشاملة (إزالة التكرار + إعادة التضمين + إعادة حساب العدّ)	~24 ساعة؛ تقسيم تلقائي للمدوّنات الكبيرة

لوحة التحكم: Run reconsolidation، وإعادة محاولة الطابور retry / Clear failed، ولوحة صحة المكوّنات.

ما لا يجب فعله

لا تفرّغ كتل KB في جدول beliefs كـ SPO خام بلا مصدر (provenance).
لا تشترط Neo4j لتثبيت عادي.
لا تضبط KAZMA_MEMORY_STATE_ROLE=primary حتى يُبلّغ python scripts/reconcile_memory_mirror.py --dry-run بخلوّه من صفوف dead-in-mirror / only-in-mirror.
لا تتعامل مع «memory V2» ككيان إصدار منتج (تنظيف البيانات يحجب فاعلين مثل kazma_v2_4_0).
لا تعيد كتابة معرّفات الفاعل للمعتقدات يدويًا لتصحيح التسميات — استخدم Rename (عرضًا) أو Merge (هويةً).
لا تتوقع ظهور الأصداف الشخصية الفارغة عديمة المعتقدات كعقد رسم إضافية — أصداف الذات تُركّز المحور.