<div align="center">

# MemoTrail

> 🌐 هذه ترجمة تلقائية. تصحيحات المجتمع مرحب بها! · [English](../../README.md)

[🇨🇳 中文](README.zh-CN.md) · [🇹🇼 繁體中文](README.zh-TW.md) · [🇯🇵 日本語](README.ja.md) · [🇵🇹 Português](README.pt.md) · [🇰🇷 한국어](README.ko.md) · [🇪🇸 Español](README.es.md) · [🇩🇪 Deutsch](README.de.md) · [🇫🇷 Français](README.fr.md) · [🇮🇱 עברית](README.he.md) · [🇸🇦 العربية](README.ar.md) · [🇷🇺 Русский](README.ru.md) · [🇵🇱 Polski](README.pl.md) · [🇨🇿 Čeština](README.cs.md) · [🇳🇱 Nederlands](README.nl.md) · [🇹🇷 Türkçe](README.tr.md) · [🇺🇦 Українська](README.uk.md) · [🇻🇳 Tiếng Việt](README.vi.md) · [🇮🇩 Indonesia](README.id.md) · [🇹🇭 ไทย](README.th.md) · [🇮🇳 हिन्दी](README.hi.md) · [🇧🇩 বাংলা](README.bn.md) · [🇵🇰 اردو](README.ur.md) · [🇷🇴 Română](README.ro.md) · [🇸🇪 Svenska](README.sv.md) · [🇮🇹 Italiano](README.it.md) · [🇬🇷 Ελληνικά](README.el.md) · [🇭🇺 Magyar](README.hu.md) · [🇫🇮 Suomi](README.fi.md) · [🇩🇰 Dansk](README.da.md) · [🇳🇴 Norsk](README.no.md)

**مساعد البرمجة الذكي ينسى كل شيء. MemoTrail يحل هذه المشكلة.**

[![PyPI version](https://img.shields.io/pypi/v/memotrail?color=blue)](https://pypi.org/project/memotrail/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](../../LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/HalilHopa-Datatent/memotrail?style=social)](https://github.com/HalilHopa-Datatent/memotrail)

طبقة ذاكرة دائمة لمساعدي البرمجة الذكية.
كل جلسة مسجلة، كل قرار قابل للبحث، كل سياق محفوظ.

[البداية السريعة](#البداية-السريعة) · [كيف يعمل](#كيف-يعمل) · [الأدوات المتاحة](#الأدوات-المتاحة) · [خارطة الطريق](#خارطة-الطريق)

</div>

---

## ما الجديد في v0.3.0

- **تلخيص الجلسات تلقائياً** — كل جلسة تحصل على ملخص مولّد بالذكاء الاصطناعي (لا حاجة لمفاتيح API)
- **استخراج القرارات تلقائياً** — يتم اكتشاف القرارات المعمارية من المحادثات باستخدام مطابقة الأنماط
- **بحث BM25 بالكلمات المفتاحية** — أداة `search_keyword` جديدة للمصطلحات الدقيقة ورسائل الخطأ وأسماء الدوال
- **بحث هجين** — يجمع بين النتائج الدلالية والكلمات المفتاحية باستخدام دمج الرتب المتبادل
- **دعم Cursor IDE** — فهرسة سجل محادثات Cursor من ملفات `state.vscdb`
- **مراقبة الملفات في الوقت الفعلي** — فهرسة الجلسات الجديدة فوراً عبر watchdog (لا حاجة لإعادة التشغيل)
- **استراتيجيات التقسيم** — اختر بين التقسيم بالرموز أو بالأدوار أو التقسيم التكراري
- **إضافة VS Code** — البحث والفهرسة وعرض الإحصائيات مباشرة من VS Code
- **69 اختبار** — تغطية شاملة للاختبارات عبر جميع الوحدات

## المشكلة

كل جلسة جديدة في Claude Code تبدأ من الصفر. الذكاء الاصطناعي لا يتذكر جلسة تصحيح الأخطاء التي استمرت 3 ساعات بالأمس، ولا القرارات المعمارية من الأسبوع الماضي، ولا المقاربات التي فشلت بالفعل.

**بدون MemoTrail:**
```
أنت: "لنستخدم Redis للتخزين المؤقت"
AI:   "بالتأكيد، لنقم بإعداد Redis"
         ... بعد أسبوعين، جلسة جديدة ...
أنت: "لماذا نستخدم Redis؟"
AI:   "ليس لدي سياق حول هذا القرار"
```

**مع MemoTrail:**
```
أنت: "لماذا نستخدم Redis؟"
AI:   "بناءً على جلسة 15 يناير — قمت بتقييم Redis مقابل Memcached.
       تم اختيار Redis لدعمه لهياكل البيانات والاستمرارية.
       النقاش في الجلسة رقم 42."
```

## البداية السريعة

```bash
# 1. التثبيت
pip install memotrail

# 2. الاتصال بـ Claude Code
claude mcp add memotrail -- memotrail serve
```

هذا كل شيء. يقوم MemoTrail بفهرسة سجلك تلقائياً عند أول تشغيل.
ابدأ جلسة جديدة واسأل: *"ماذا عملنا الأسبوع الماضي؟"*


<div align="center">
<img src="../../demo.gif" alt="MemoTrail Demo" width="800">
<br>
<sub>Install → Connect → See stats → Search past sessions → Save memory → Duplicate &amp; contradiction detection</sub>
</div>

## كيف يعمل

| الخطوة | ماذا يحدث |
|:----:|:-------------|
| **1. التسجيل** | MemoTrail يفهرس الجلسات الجديدة تلقائياً عند بدء التشغيل + يراقب الملفات الجديدة في الوقت الفعلي |
| **2. التقسيم** | يتم تقسيم المحادثات باستخدام استراتيجيات الرموز أو الأدوار أو التقسيم التكراري |
| **3. التضمين** | كل جزء يُضمّن باستخدام `all-MiniLM-L6-v2` (~80 ميغابايت، يعمل على CPU) |
| **4. الاستخراج** | يتم استخراج الملخصات والقرارات المعمارية تلقائياً |
| **5. التخزين** | المتجهات تذهب إلى ChromaDB، والبيانات الوصفية إلى SQLite — الكل تحت `~/.memotrail/` |
| **6. البحث** | بحث دلالي + بحث BM25 بالكلمات المفتاحية عبر كامل سجلك |
| **7. العرض** | السياق السابق الأكثر صلة يظهر تماماً عندما تحتاجه |

> **محلي 100%** — لا سحابة، لا مفاتيح API، لا بيانات تغادر جهازك.
>
> **متعدد المنصات** — يدعم Claude Code و Cursor IDE، مع المزيد قريباً.

## الأدوات المتاحة

بعد الاتصال، يحصل Claude Code على أدوات MCP هذه:

| الأداة | الوصف |
|------|-------------|
| `search_chats` | بحث دلالي في جميع المحادثات السابقة |
| `search_keyword` | بحث BM25 بالكلمات المفتاحية — ممتاز للمصطلحات الدقيقة وأسماء الدوال ورسائل الخطأ |
| `get_decisions` | استرجاع القرارات المعمارية المسجلة (مستخرجة تلقائياً + يدوية) |
| `get_recent_sessions` | عرض الجلسات الأخيرة مع ملخصات مولّدة بالذكاء الاصطناعي |
| `get_session_detail` | استكشاف محتوى جلسة محددة بالتفصيل |
| `save_memory` | حفظ الحقائق أو القرارات المهمة يدوياً |
| `memory_stats` | عرض إحصائيات الفهرسة واستخدام التخزين |

## أوامر CLI

```bash
memotrail serve                          # تشغيل خادم MCP (فهرسة تلقائية للجلسات الجديدة)
memotrail search "redis caching decision"  # البحث من الطرفية
memotrail stats                          # عرض إحصائيات الفهرسة
memotrail index                          # إعادة فهرسة يدوية (اختياري)
```

## البنية

```
~/.memotrail/
├── chroma/          # تضمينات متجهية (ChromaDB)
└── memotrail.db     # بيانات وصفية للجلسات (SQLite)
```

| المكون | التقنية | التفاصيل |
|-----------|-----------|---------|
| التضمينات | `all-MiniLM-L6-v2` | ~80 ميغابايت، يعمل على CPU |
| قاعدة المتجهات | ChromaDB | تخزين محلي دائم |
| البحث بالكلمات المفتاحية | BM25 | Python خالص، بدون تبعيات إضافية |
| البيانات الوصفية | SQLite | قاعدة بيانات ملف واحد |
| مراقبة الملفات | watchdog | كشف الجلسات في الوقت الفعلي |
| البروتوكول | MCP | Model Context Protocol |

### المنصات المدعومة

| المنصة | الحالة | الصيغة |
|----------|--------|--------|
| Claude Code | مدعوم | ملفات جلسات JSONL |
| Cursor IDE | مدعوم | state.vscdb (SQLite) |
| GitHub Copilot | مخطط | — |

### استراتيجيات التقسيم

| الاستراتيجية | الأفضل لـ |
|----------|----------|
| `token` (افتراضي) | الاستخدام العام — تجميع الرسائل حتى حد الرموز |
| `turn` | محادثات مركزة — تجميع أزواج المستخدم والمساعد |
| `recursive` | محتوى طويل — تقسيم على الفقرات والجمل والكلمات |

## لماذا MemoTrail؟

| | MemoTrail | CLAUDE.md / ملفات القواعد | ملاحظات يدوية |
|---|---|---|---|
| تلقائي | نعم — يفهرس عند كل بداية جلسة | لا — أنت تكتبها | لا |
| قابل للبحث | بحث دلالي | AI يقرأها، لكن فقط ما كتبته | Ctrl+F فقط |
| قابل للتوسع | آلاف الجلسات | ملف واحد | ملفات متناثرة |
| واعي بالسياق | يعيد السياق المناسب | قواعد ثابتة | بحث يدوي |
| الإعداد | 5 دقائق | صيانة مستمرة | صيانة مستمرة |

MemoTrail لا يحل محل `CLAUDE.md` — بل يكمله. ملفات القواعد للتعليمات. MemoTrail للذاكرة.

## خارطة الطريق

- [x] فهرسة جلسات Claude Code
- [x] بحث دلالي عبر المحادثات
- [x] خادم MCP مع 7 أدوات
- [x] CLI للفهرسة والبحث
- [x] فهرسة تلقائية عند تشغيل الخادم
- [x] استخراج القرارات تلقائياً
- [x] تلخيص الجلسات
- [x] جامع Cursor IDE
- [x] بحث BM25 بالكلمات المفتاحية + بحث هجين
- [x] مراقبة الملفات في الوقت الفعلي (watchdog)
- [x] استراتيجيات تقسيم متعددة (token، turn، recursive)
- [x] إضافة VS Code
- [ ] جامع Copilot
- [ ] مزامنة سحابية (Pro)
- [ ] ذاكرة الفريق (Team)

## إضافة VS Code

يتضمن MemoTrail إضافة VS Code للتكامل المباشر مع بيئة التطوير.

**الأوامر المتاحة:**
- `MemoTrail: Search Conversations` — بحث دلالي
- `MemoTrail: Keyword Search` — بحث BM25 بالكلمات المفتاحية
- `MemoTrail: Recent Sessions` — عرض إحصائيات الجلسات
- `MemoTrail: Index Sessions Now` — تشغيل الفهرسة يدوياً
- `MemoTrail: Show Stats` — عرض إحصائيات الفهرسة

**الإعداد:**
```bash
cd vscode-extension
npm install
npm run compile
# ثم اضغط F5 في VS Code لتشغيل مضيف تطوير الإضافات
```

## التطوير

```bash
git clone https://github.com/HalilHopa-Datatent/memotrail.git
cd memotrail
pip install -e ".[dev]"
pytest
ruff check src/
```

## المساهمة

المساهمات مرحب بها! انظر [CONTRIBUTING.md](../../docs/CONTRIBUTING.md) للإرشادات.

## الرخصة

MIT — انظر [LICENSE](../../LICENSE)

---

<div align="center">

**صنعه [Halil Hopa](https://halilhopa.com)** · [memotrail.ai](https://memotrail.ai)

إذا ساعدك MemoTrail، فكّر في إعطائه نجمة على GitHub.

</div>
