الذاكرة وRAG

مصدر الحقيقة الحي (2026-08). V2 هي مكدّس الذاكرة الوحيد للدردشة.

الذاكرة الشخصية — معتقدات ثنائية الزمن، حلقات من 4 طبقات، PPR، FTS5 + dense (‏sqlite-vec على عقدة واحدة؛ pgvector عند تفعيل Postgres)، طابور دائم.

مكتبة المعرفة — مخزن منفصل؛ دمج منتجي عبر حقن موسوم + بحث موحّد (وليس جدولًا واحدًا).

محوّلات التوسّع — pgvector يُختار تلقائيًا من Postgres DSN؛ Qdrant إن ضبطته؛ كتابة مزدوجة إلى Neo4j؛ مرآة حالة Postgres / دور primary.

‏V1 رباعي الطبقات RRF (Chroma / مفاهيم L1–L4) أُزيل. لا تُحيه في الوثائق أو نصوص الواجهة. الملاحظات القديمة التي تذكر UnifiedMemoryAdapter / VectorMemory باتت ملغاة.

قائمة تشغيل المشغّل: Memory best path. سجل التوسّع: docs/plans/MEMORY_REMAINING.md. تدقيق النظام (2026-08-24، النتائج مغلقة): AUDIT_MEMORY_SYSTEM_2026-08-24.md.

البنية (مسار الدردشة)

User turn
  → recall()  (beliefs + episodes FTS/dense + PPR + session bias)
  → optional federated KB hits  (if merge_knowledge_into_chat)
  → format_untrusted_block  (<kazma:data untrusted>)
  → LLM
  → post-turn: mirror episode, heuristic beliefs, enqueue micro_consolidation

قاعدتا SQLite (فصلٌ حاسم)

قاعدة البيانات	الدور
`memory_state.db`	الساخنة: المعتقدات، الحلقات، الكيانات، `entity_merges` (+ الأرشيف)، رسومات الإجراءات DAGs
`memory_ops.db`	الباردة: طابور المهام، سجل التدقيق

لا تدمجهما — يجب ألا يتنازع التوحيد الخلفي مع قراءات الدردشة على WAL.

المخازن تبقى منفصلة (تميّز منتجي)

المخزن	الدور	الافتراضي
V2 المعرفي	من أنا / ما قلناه	SQLite مصدر الحقيقة على عقدة واحدة
مكتبة المعرفة	مستندات + استشهادات	فهارس KB منفصلة
Neo4j	كتابة مزدوجة اختيارية لثلاثيات المعتقدات	مطفأ ما لم يُضبط
حالة Postgres	مرآة مزدوجة أو `state.role=primary`	مطفأ ما لم يُضبط
المتجهات dense	sqlite-vec (عقدة واحدة) / pgvector (Postgres DSN) / Qdrant	pgvector تلقائيًا عند مغادرة عقدة واحدة

الدمج الفيزيائي بجدول واحد للـ KB + المعتقدات wontfix (#79). الدردشة توحّد عبر الحقن؛ المخازن لا.

الإعدادات (أين كل شيء)

‏Settings → Memory (/settings?tab=memory) — العزل، مفاتيح المعرفة + الدردشة، المحوّلات (vector / state / graph)، اختبار/مزامنة Neo4j، والمُغلِّف embeddings (مُدمج في هذا التبويب).

عنصر التحكم	الأثر
وضع المستأجر	`shared` / `per_platform` / `per_user`
حقن المعرفة في الدردشة	`merge_knowledge_into_chat` (مفعّل افتراضيًا)
ترقية نتائج KB إلى حلقات	`promote_kb_to_episodes` (نسخة ناعمة موسومة)
مخزن الرسم	`sqlite` (افتراضي) أو كتابة مزدوجة `neo4j`
المتجهات / المُغلِّف	sqlite-vec على عقدة واحدة؛ pgvector عند ضبط `KAZMA_DATABASE_URL` / state URL ‏(`KAZMA_PGVECTOR=0` للبقاء المحلي)

روابط عميقة قديمة: ?tab=embedder → Memory (تمرير إلى المُغلِّف)؛ ?tab=connectors → LLM Providers → Platform Connectors.

حارس تنزيل المُغلِّف (2026-08-19): المُغلِّف local المُعدّ عمدًا قد ينزّل نموذجه عند أول استخدام، لكن المُغلِّفات الاحتياطية (مزوّد مجهول / إعداد remote معطوب) لا تفعل أبدًا — تتفقد خزنة HuggingFace المحلية وتتدهور إلى “بلا embeddings” مع تحذير قابل للتنفيذ بدل تعليق العملية على تنزيل bge-m3 بحجم ~2GB حيًّا. للسماح قسرًا: KAZMA_EMBED_ALLOW_DOWNLOAD=1.

الاستدعاء وما بعد الدور

`recall()`

المعتقدات السارية (جسر الكيانات + مطابقة نصية + dense)
بحث هجين في الحلقات (FTS5 + dense)
تعزيز PPR لرسم الإيغو المحلي
RRF / اقتطاع بالميزانية
السياج: format_untrusted_block(..., source="memory_v2_recall")

**محرك dense:**‏ sqlite-vec ما دمت على عقدة SQLite واحدة. وعندما تمتلك العملية Postgres DSN بالفعل، يستخدم الاستدعاء pgvector (كتابة مزدوجة هجينة، أو remote-first إذا KAZMA_MEMORY_STATE_ROLE=primary). ‏Postgres-primary هو ILIKE متناثر + pgvector dense مدموجان بـ RRF — وليس ILIKE فقط. Qdrant الصريح في الإعدادات لا يُتجاوز أبدًا. مفتاح الإيقاف: KAZMA_PGVECTOR=0. فعّل CREATE EXTENSION vector على قاعدة البيانات.

ما بعد الدور

مرآة حلقة working/recall
استخراج معتقدات استدلالي (+ طابور LLM اختياري) → mutate_belief
النظافة ترفض مواضيع المكدّس/الإصدارات (مثل kazma_v2_4_0 الخطأ في قراءتها كإصدار منتج)
كتابة مزدوجة: مرآة حالة Postgres الاختيارية + رفع حواف Neo4j
مرساة الإيغو — كل موضوع غير مركزي لا يصل أصلًا إلى user يحصل على user → related_to → <subject> وقت الكتابة (أوراق الحِمل والعناقيد العائمة). كائنات الحِمل (fully_clean، المسارات) لا تُسكك ككيانات مفاهيمية (ذلك السكّ كان يتخطى حافة المركز). إعادة ملء Idempotent على الـ sweep كل 6 ساعات.
الإبطال / الإحلال / مسح الرسم يضعون شواهد القبور في مرآة Postgres ويحذفون حواف Neo4j بجدية محدودة (المسح الشامل يستخدم clear_tenant_edges).

المُجدوِلات (`worker_bootstrap`)

الإيقاع	العمل
~6 ساعات	`macro_sleep` (الاضمحلال / نقل الطبقات) + إعادة ملء مراسى الإيغو + عدّ انحراف FTS ‏(`*_docsize` مقابل الأساس؛ إعادة بناء عند عدم التطابق)
~24 ساعة	النسخ الاحتياطي الأصلي + تصدير JSONL/GraphML/الحلقات/الدموجات/التدقيق + تحذير انحراف المرآة
~24 ساعة	`global_reconsolidation` (إزالة تكرار + إعادة تضمين؛ مُقسَّم للجسام الكبيرة؛ يعيد حساب عدّادات الكيانات)
~15 دقيقة	تنظيف commitment

جسام ضخمة: تقسيم بتجزئة الموضوع + مهام طابور متسلسلة (انظر global_reconsolidation.py).

يكتب التصدير الليلي kazma_beliefs_latest.jsonl وGraphML، إضافة إلى الحلقات وbeliefs_archive وentity_merges (+ الأرشيف) و memory_audit_log (أسماء ملفات لكل مستأجر عندما لا يكون default). تبقى نسخ .db الأصلية مصدر الحقيقة للاستعادة.

انحراف مرآة Postgres (وقائع ميتة ما تزال حية في kazma_beliefs): يسجّل معالج الـ24 ساعة تحذيرًا. صالحح بـ:

python scripts/reconcile_memory_mirror.py --dry-run
python scripts/reconcile_memory_mirror.py

لا تضبط KAZMA_MEMORY_STATE_ROLE=primary حتى ينجح هذا الفحص — القصّ الواصل سيعيد إحياء الوقائع الموبَّقة.

مكتبة المعرفة + الدردشة (الدمج المنتجي)

الحقن — يستطيع المُنسّق إضافة كتل ملاحظات KB موسومة بجوار ذاكرة V2.
البحث الموحّد — POST /api/memory/v2/federated-search و”ابحث في كل المعرفة” بلوحة التحكم (رقاقات MEM / KB).
الترقية — نسخة ناعمة اختيارية لأبرز نتائج KB في الحلقات (وليس SPO ثلاثي بلا أصل).

تعمّق: قاعدة المعرفة وRAG.

‏Neo4j (كتابة مزدوجة اختيارية)

مصدر الحقيقة للمعتقدات يبقى SQLite (ثنائي الزمن، scrub، فلاتر اللوحة).
طوبولوجيا اللوحة تُرسم من SQLite عند تهيئة Neo4j (الأنواع + ثنائية الزمن).
يتلقى Neo4j كتابة مزدوجة عند كل تغيير؛ وSync beliefs → Neo4j يملأ الصفوف القائمة.
الإبطال الناعم / الإحلال / مسح الرسم يحذفون حواف Neo4j بجدية محدودة (بنطاق المستأجر). لا ينبغي أن تحتاج مزامنة يدوية بعد Clear graph.

إعداد المشغّل

شغّل Neo4j (مثلًا docker compose -f deploy/docker-compose.neo4j.yml up -d).
Settings → Memory → Graph store Neo4j، العنوان bolt://localhost:7687، كلمة السر، Save.
Test Neo4j (كلمات السر المقنّعة *** لا تطغى على سر الخزنة).
Sync beliefs → Neo4j.

افتراضي تثبيت البيئة (فاشل-منفتح)

export KAZMA_NEO4J_DEFAULT=1
export KAZMA_NEO4J_PASSWORD=...
# optional: KAZMA_NEO4J_URL=bolt://localhost:7687

إن لم يُضبط، يبقى مزوّد الرسم الافتراضي sqlite. وسقوط الخادم → تعود الطوبولوجيا إلى SQLite.

لوحة التحكم

اللوحة	الدور
الذاكرة والحوكمة	صحة المكوّنات (مكدّس V2، Neo4j، حقن KB، الحزم)
المحرك المعرفي V2	المؤشرات، probe/federated، الطابور، لوحة الطوبولوجيا
الطوبولوجيا	رسم من SQLite؛ تلوين واجهة؛ مسار-من-استعلام؛ طبقة الحلقات؛ PNG/SVG

واجهة إدارة الذاكرة (`/memory`)

سطح مشغّل واحد لطوبولوجيا + كيانات + معتقدات + نظافة (memory.html + memory_console.js + memory.js + memory_api.py).

التخطيط

الرسم والصحة (أعلى) — لوحة معتقدات V2، المؤشرات، probe، النسخ الاحتياطية.
تبويبات العمليات — الكيانات، المعتقدات، الدموجات المعلّقة، النظافة.

قدرات المشغّل (تحديث 2026-08)

القدرة	أين	ملاحظات
ترقيم صفحات + عدّادات حقيقية	كل تبويبات القوائم	”يعرض 1–150 من 3,412” + Load more. يبلّغ الرسم عن `total_nodes`/`truncated` بلافتة كهرمانية عند الاقتطاع — متضمنة الوصلات المخفية بالتقطيع. لا المزيد من سقف 200 صف الصامت.
بحث غير حساس للتشكيل	صناديق بحث الكيانات والمعتقدات	يمر عبر `beliefs_fts` / `entities_fts` ‏(FTS5) — ‏`francais` يطابق `Français`، والأسماء البديلة قابلة للبحث. يعود إلى `LIKE` إذا غاب FTS.
”لماذا استُدعي”	درج المعتقد	انقر معتقدًا → ترى `recalled N× · last <date> · via <method> · from <episode>`، مع زر Probe from this belief →. نقطة النهاية: `GET /beliefs/{id}/recall-trail`.
تراجع	توست الإجراء	إبطال الدُفعات، الربط، التحرير، حذف الكيان تعيد إيصالًا + رمز تراجع للاستخدام الواحد لمدة 60 ثانية؛ التوست فيه زر [Undo]. الدموج يظهر إيصال “N معتقدات أعيد توصيلها” (غير قابل للتراجع — استعد من نسخة احتياطية).
تحرير معتقد مفرد	زر Edit في صف المعتقد	نموذج واحد منبثق (subject/predicate/object)، لا موجّه متعدد الخطوات.
شريط عمليات واحد	شريط Ops بالرسم	أُزيلت بطاقة Link/merge المكررة — شريط Ops في الرسم هو مصدر الحقيقة الوحيد؛ زرا Src/Tgt في الصف + Shift-click يتزامنان معه.
تعدد المستأجرين	متغير بيئة	`KAZMA_MEMORY_ENFORCE_TENANT=1` يقيّد القراءات وتغييرات المعرّف ورموز التراجع ومسح الرسم بالمستأجر المطلوب. مطفأ افتراضيًا (`default` أحادي المستأجر). لا يوجد مسح لكل المستأجرين. ملاحظة: `entities.id` مفتاح أساسي عام، لا لكل مستأجر.
تجميع / فك تجميع	فحص الرسم	عنقودية للعرض فقط (`POST/DELETE /api/memory/v2/graph/groups*`). لا تغيّر المعتقدات. واستقصاء اللوحة كل 30 ثانية يستخدم المجموعات الموجودة أصلًا في `GET /api/memory/v2/graph` (بلا جلب إضافي).

**الأداء:**‏ belief_count / graph_degree للكيان أعمدة مجسَّدة (تُصان على كل كتابة، وتشفى ذاتيًا من قيمة -1 الحارسة)، فتقرأ الصفحة عدّادات محسوبة مسبقًا بدل استعلامات مترابطة O(entities×beliefs) عند كل تحميل — تسريع ~10× لفتح الصفحة عند التوسع.

ثوابت الرسم (مصدر حقيقة اللوحة)

القاعدة	لماذا
معرّفات عقد فريدة في الحِمل	`_v2gIds[id]` في اللوحة last-write-wins؛ المعرّفات المكررة تُيتُم عقدة (خطأ “shipx المزدوج” القديم).
الكيان يتغلب على الواقعة الافتراضية	عندما يساوي نص كائن المعتقد معرّف كيان (`user → has_project → shipx`)، تُصدَّر عقدة كيان حقيقية واحدة — لا توأم `isVirtual` ثانٍ بنفس المعرّف.
لا وصلات معلّقة	مصدر وهدف الوصلة يجب أن ينجوا من الفلاتر (`entity_type`، الحد).
المركز دائمًا `id=user`	تنسيق “أنت” في الوسط؛ واسم العرض من `entities.user.name` (مثل Mubder).
مواضيع الحِمل تلتصق بالمركز	الواقعة التي كائنها حرفي (لا كيان آخر) تحصل مع ذلك على `user → related_to → <subject>` حتى لا يصبح المفهوم مكوّنًا عائمًا.

إعادة التسمية للعرض (لا إعادة كتابة للمعرّف)

الـ API: ‏POST /api/memory/v2/entities/{id}/rename بجسم { "name": "ShipX" }.
المعرّف الكانوني يبقى ثابتًا فتبقى مواضيع/أهداف المعتقدات موصولة.
التسميات السابقة تلج aliases_json (الحل يجد الأسماء القديمة أيضًا).
الواجهة: فحص الرسم Rename، وجدول الكيانات Rename.
تحدّث اللوحة التسميات ناعمًا عند تغيّر الأسماء فقط (لا تُصفّر التخطيط).

هوية الذات / المركز (User → Mubder)

غالبًا ما ينشئ الإعادة-الملء والمستخرجات قشرة شخص (ent_<hash> اسمها User) منفصلة عن المركز التخليقي user. وكلاهما هوية المشغّل نفسها للواجهة:

المفهوم	السلوك
`memory/self_hub.py`	يكشف تسميات الذات (`user` / `you` / الأسماء البديلة) وقشور الأشخاص
إعادة تسمية قشرة الذات → العلامة	يرفع أيضًا `entities.id=user` بذلك الاسم
صف القائمة	`is_self: true` و`graph_id: "user"` — النقر يركّز المركز
رسم اللوحة	يطوي معرّفات الذات على عقدة مركز واحدة؛ التسمية = اسم عرض المركز

فإعادة تسمية User → Mubder على ent_… تجعل مركز اللوحة يعرض Mubder، لا “You” مبرمجة.

جسر القائمة ↔ الرسم

من	إلى
النقر على صف كيان / معتقد	تحديد + تقريب على اللوحة (`_v2gSelectEntity` / `_v2gSelectBelief`)
النقر المزدوج على عقدة الرسم	إبراز صف القائمة المطابق + تمرير العمليات (`kazma:memory-graph-select`)
النقر المفرد / سحب العقدة	تحديد + فحص فقط — لا تقفز الصفحة (استكشاف حر)
سحب العقدة ثم إفلاتها	تُثبَّت العقدة في موضعها (ينجو عبر التحديث / تغيير الفلاتر)
فحص In list	قفزة صريحة إلى القائمة (كالنقر المزدوج)
دموج / ربط / إبطال / إعادة تسمية	تحديث حِمل الرسم؛ المواضع المثبتة تُستعاد من خزنة العميل

تحرير المعتقد للمشغّل

الـ API: ‏PATCH /api/memory/v2/beliefs/{id} بأيٍّ من subject / predicate / object / predicate_type.
المعتقدات النشطة فقط (لا المبطَلة/المُحلّاة).
يضبط extraction_method=user_explicit؛ ويمسح الـ embedding عند تغيّر نص الكائن (محقّنات FTS تبقي البحث متزامنًا).
الواجهة: تبويب Beliefs → Edit (موجّهات للكائن ثم predicate ثم subject).

بقية عمليات الكيانات (العقد نفسها)

الإجراء	المسار
قائمة / فلترة	`GET /api/memory/v2/entities`
دموج القشور	`POST /api/memory/v2/entities/merge`
ربط كيانين	`POST /api/memory/v2/entities/link`
حذف قشرة فارغة	`DELETE /api/memory/v2/entities/{id}` (ليس معرّفات المراكز المحمية). تنسخ صفوف `entity_merges` إلى `entity_merges_archive` أولًا (يُسقط FK صفوف السجل الحية).
إبطال معتقد	`POST /api/memory/v2/beliefs/{id}/invalidate` (+ دفعات)

الوحدات الرئيسية

الوحدة	الغرض
`memory/recall.py`	الاستدعاء الموحّد
`memory/belief_mutation.py` / `belief_extractor.py`	مسار الكتابة + السياج/النظافة؛ INSERT OR IGNORE مع عدّ الصفوف + rollback
`memory/hygiene.py`	المواضيع المحجوبة، شفاء FTS الذاتي، الإبطال + حذف الرسم
`memory/ego_anchor.py`	حواف المركز لمواضيع الأوراق ذات كائنات الحِمل
`memory/fts_health.py`	عدّ دوري لـ `*_docsize` في FTS مقابل الأساس + إعادة بناء
`memory/entity_counts.py`	مصدر حقيقة وحيد لـ SQL ‏belief_count / graph_degree
`memory/self_hub.py`	اسم عرض المركز + طيّ قشور أشخاص الذات
`memory/graph_backend.py`	SQLite افتراضي + كتابة Neo4j المزدوجة + مسح حواف بنطاق المستأجر
`memory/backends.py`	مصنع المتجهات / الحالة / الرسم؛ الاختيار التلقائي لـ pgvector؛ افتراضيات Neo4j من البيئة
`memory/federated_search.py`	بحث موسوم للذاكرة + KB
`memory/global_reconsolidation.py`	إزالة تكرار + إعادة تضمين (مقسّمة)
`memory/worker_bootstrap.py`	معالجات الطابور + المُجدوِلات
`memory/v2_health.py` / `health.py`	واجهات الصحة للوحة التحكم / الحزم
`kazma_ui/memory_api.py`	مسارات إدارة `/memory` (إعادة تسمية، تحرير، دموج، نظافة)
`kazma_ui/static/js/memory_console.js`	لوحة V2 + إعادة تسمية الفحص
`kazma_ui/static/js/memory.js`	قوائم الكيانات/المعتقدات + جسر القائمة↔الرسم

التوسّع (عند الحاجة فقط)

الاحتياج	التتبّع
استدعاء كامل بـ Postgres-primary	#76 — المحوّل صدر؛ فعّله فقط بعد نظافة `reconcile_memory_mirror.py`
تعدد المناطق + التعارضات	#77
أسطول تضمين مُستضاف	#78

المرآة المزدوجة لـ Postgres والمساعدة المتناثرة ILIKE موجودتان أصلًا كأساسين اختياريين. شواهد القبور تنتشر الآن؛ والانحراف الليلي يحذّر إن كانت المرآة ما تزال تحمل وقائع ميتة.

تراجع استدعاء المحادثات السابقة (2026-08)

الوقائع التي تعيش فقط في نصوص محادثات سابقة (قائمة أسماء مختصرة، جدول قرارات) تكون خفية عن استدعاء V2 — فالاستدعاء يقرأ المعتقدات/الحلقات، لا نص الجلسات الخام. وحتى 2026-08-27 عوّض الوكيل ذلك بكتابة SQL يدويًا ضد chat_sessions.db (مهمة واحدة حرق 21 دورة وبوابة YOLO للإجابة على “ماذا قررنا سابقًا؟”).

الآن، عندما يعيد استدعاء V2 لا شيئًا لاستعلام ما، يبحث المُنسّق تلقائيًا في جلسات الدردشة السابقة (العنوان + نص الرسالة؛ أطول المصطلحات وأكثرها تحديدًا تربح، مطابقات العنوان تتصدر، والعربية مدعومة) ويحقن أبرز النتائج كتلةً مسوَّرة غير موثوقة في الـ prompt (بمصدر chat_history) بجوار كتلة الذاكرة — صفر دورات إضافية، بلا أدوات خطرة، بلا صلاحيات. ودورات استدعاء-مكبوت تتخطاه أيضًا.

قراءة فقط، يفتح kazma-data/chat_sessions.db بالمسار، ولا يرفع استثناء أبدًا (غياب المخزن = لا شيء بصمت).
مفتاح الإيقاف: KAZMA_TRANSCRIPT_RECALL=0 في البيئة أو memory.transcript_fallback=false في ConfigStore (يُقرأ حيًّا، مفعّل افتراضيًا).
الوحدة: kazma_core/memory/transcript_recall.py؛ موصولة في graph_supervisor.py (سطر السجل: [Supervisor] transcript fallback: N past-session hit(s)).
نصيحة للوقائع الدائمة: بعد أن يجدها الوكيل، قل له تذكّرها نهائيًا — تخزين المستخدم الصريح يصبح معتقدًا عالي الثقة يستدعيه الاستدعاء أولًا، بلا حاجة للتراجع.