AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
docs: Arabic and Spanish README translations (#1741)
xerj-org899236e9f955
diff --git a/.gitignore b/.gitignoreindex 8e127ac08..a1c287bf9 100644--- a/.gitignore+++ b/.gitignore@@ -112,6 +112,8 @@ landing/resources/xerj-sales-kit.zip!README.md!/README.zh-CN.md!/README.ja-JP.md+!/README.ar.md+!/README.es.md!CLA.md!LICENSE!LICENSE.mddiff --git a/README.ar.md b/README.ar.mdnew file mode 100644index 000000000..0f0b30630--- /dev/null+++ b/README.ar.md@@ -0,0 +1,425 @@+# XERJ++<a href="https://trendshift.io/repositories/116361?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-116361" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/116361" alt="xerj-org%2Fxerj | Trendshift" width="250" height="55"/></a>++[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md) | [العربية](./README.ar.md) | [Español](./README.es.md)++[](https://github.com/xerj-org/xerj/actions/workflows/ci.yml)+[](https://github.com/xerj-org/xerj/releases)+[](./LICENSE)+[](https://github.com/xerj-org/xerj/stargazers)+[](https://www.rust-lang.org)+[](https://github.com/xerj-org/xerj/discussions)+[](https://discord.com/invite/yetXFusXfs)+[](https://x.com/xerj_org)++[](https://xerj.org/case-studies/reference-coding.html)+[](https://xerj.org/docs/cli.html)+[](https://xerj.org/docs/queries.html)+[](https://xerj.org/docs/recipes/agentic-memory.html)+[](https://xerj.org/llms.txt)+[](https://xerj.org/llms.txt)+[](https://xerj.org/benchmarks)+[](https://xerj.org/docs/install.html)+[](https://xerj.org/docs/vectors.html)+[](https://xerj.org/docs/vectors.html)++<div dir="rtl">++> هذه الصفحة ترجمة عربية لـ [README الإنجليزي](./README.md). عند الاختلاف يُعتد بالنسخة الإنجليزية. أرقام القياس والتكاليف ومخرجات الأمثلة منقولة من الأصل والسجلات التي يستشهد بها، ولم تُعد قياسها في هذه الترجمة.++XERJ بحث محلي بالذكاء الاصطناعي يثق به المجتمع. يفهرس أي مجلد تلقائيا، فيتوقف وكيل البرمجة عن حرق التوكنات بقراءة الملفات واحدا واحدا ويستخرج الشيفرة التي يحتاجها بالضبط. الاستخدام الرئيسي، وأوضح مكسب، هو البرمجة بالمراجع (reference coding): وجّه الوكيل إلى مهمة فينزّل مستودعات المصدر المفتوح الأقرب إليها، ويفهرسها، ويعيد استخدام طريقتها في حل المشكلة قبل أن يكتب شيفرته. في دراسة مضبوطة خفّض ذلك توكنات الإخراج لوكيل برمجة بمقدار 2.7x مع بقاء معدل الحل 16/16+([دراسة حالة](https://xerj.org/case-studies/reference-coding.html))، ويبلّغ الناس عن نحو 5x في العمل اليومي+([تقارير ميدانية](./user-feedback/11-reference-coding-field-reports/2026-08-11-token-savings-reports.md)).+يكفي ذلك ليتفوق نموذج أصغر وأرخص في كتابة الشيفرة على نموذج أغلى يعمل من الذاكرة، ولتقضي وقتا أقل في حلقات الإصلاح. جرّبه الآن بتثبيت من موجّه واحد:++</div>++```text+Install XERJ (docs: https://xerj.org/llms.txt), index this project's sources, and set up+reference coding: clone and index the open-source repos closest to what we're building,+and search how they solved a problem before writing code.+```++<div dir="rtl">++أو شغّله بنفسك:++</div>++```sh+curl -fsSL https://xerj.org/get | sh+xerj --insecure --data-dir ./data &+xerj init # wire XERJ into Claude Code/Cursor (MCP + skill), one command+xerj autoindex ~/my-project+xerj search "how do we rotate the WAL segment" # ranked passages, file:line+xerj def "euler_to_rotationmatrix" # go-to-definition: file:line + signature+xerj gain # what it did for you — counted, not estimated+```++<div dir="rtl">++تثبيت Windows والتثبيت المتحقق منه يدويا تحت [التثبيت اليدوي](#التثبيت-اليدوي).++علم `--insecure` حد ثقة لا إجراء شكلي. يعطل TLS ومصادقة مفتاح API، فكل من يصل إلى المنفذ مستخدم بصلاحيات المشرف الأعلى يستطيع قراءة كل فهرس وحذفه، بما في ذلك كل فضاء أسماء `/_memory`. هو لجهاز تطوير يستخدمه شخص واحد: العقدة الجديدة لا تربط إلا `127.0.0.1`، وربط النص الواضح على أي واجهة أخرى يرفض الإقلاع ما لم تسمح به صراحة. النموذج الكامل في+[docs/SECURITY_MODEL.md](./docs/SECURITY_MODEL.md).++## انضم إلى المجتمع++تنضم إلى XERJ بتشغيله وإعادة تقرير ميداني قصير عما كان عليه الأمر: commit واحد أو PR واحد. ذلك التقرير هو بطاقة العضوية، وهو الشيء الوحيد الذي يطلبه المشروع مقابل ملف ثنائي مجاني برخصة Apache-2.0. هو ما يبقي المحرك يتحسن لمن يشغله بعدك.++البشر ووكلاء الذكاء الاصطناعي مرحّب بهم؛ هذا عمدا ليس مشروعا للوكلاء وحدهم. سواء فهرست مستودعا في استراحة الغداء أو ثبّت وكيل XERJ في منتصف جلسة داخل شيفرة شخص آخر، الطلب واحد: تقرير قصير يقول إلى ماذا وجهته، ولماذا استخدمته، وحكمك الصادق. الحكم السلبي تقرير جيد. إذا انكسر شيء، فذلك issue أو إصلاح منفصل فوق التقرير.++طلبات السحب التي لا تحتوي إلا على تقرير ميداني معفاة من CLA، فتُدمج بلا توقيع. المسار الذي يعمل على أي بناء هو `gh pr create` عادي يضيف ملف markdown واحدا بالضبط تحت+[`user-feedback/16-agent-field-reports/`](./user-feedback/16-agent-field-reports)،+بلا شيء آخر في الفرق. على بناء يتوفر فيه الأمر، يصوغ `xerj feedback` التقرير ويملأ الإصدار ونظام التشغيل وما فُهرس، و`xerj feedback --open-pr` يفتح طلب السحب عنك. راجع `xerj --help` لتعرف إن كان ملفك الثنائي يتضمن الأمر.++## السبب المقيس: البرمجة بالمراجع++الوكيل الذي يستخدم grep يسحب ملفات كاملة إلى سياقه، حتى 1.06M توكن إدخال على متن واحد في قياساتنا، ويظل مضطرا إلى قراءتها. الوكيل الذي يستعلم XERJ يحصل على المقطع. قيس من الطرف إلى الطرف على شيفرة لم يحفظها النموذج+([دراسة حالة](https://xerj.org/case-studies/reference-coding.html): 8 مهام، 4 لغات، 16 تشغيلا لكل ذراع، أعداد توكنات حقيقية من `claude -p`):++| | توكنات الإخراج | التكلفة | المحلول |+|---|---:|---:|---:|+| من الذاكرة فقط | 260,916 | $11.18 | 11/16 |+| وكيل يقوده grep | 26,477 | $3.27 | 16/16 |+| XERJ | 9,982 | $1.58 | 16/16 |++ذلك 2.7x توكنات إخراج أقل من grep و26x أقل من الذاكرة وحدها بمعدل الحل نفسه، وحتى 278x أقل في مهمة Java واحدة. في التطوير الفعلي يبلغ المستخدمون عن نحو 5x توكنات أقل من الطرف إلى الطرف+([تقارير ميدانية](./user-feedback/11-reference-coding-field-reports/2026-08-11-token-savings-reports.md)).+القيمة مشروطة بالحفظ: يفوز على الشيفرة الخاصة أو الداخلية أو المتخصصة أو اللاحقة لقطع التدريب، ويكون محايدا إلى ضار على المكتبات العامة الشائعة التي يعرفها النموذج سلفا. الحدود الصادقة في+[دراسة الحالة](https://xerj.org/case-studies/reference-coding.html).++## مرر إليه أي مجلد++البرمجة بالمراجع استخدام واحد للأمر الأولي نفسه: `xerj autoindex <folder>` يجعل الوكيل يعرف المتن بدل أن يمر عليه بـ grep. أمر واحد يفهرس الشيفرة والمستندات والسجلات وPDF وSQLite وملفات CSV الصعبة في فهارس ذات أنواع قابلة للاستعلام، للبحث وRAG وتدقيق الأمن وذاكرة الوكيل، بلا مخطط تكتبه وبلا خط أنابيب تضبطه.++</div>++```sh+xerj --insecure --data-dir ./data & # start it+xerj autoindex ~/my-project # point it at anything+```++<div dir="rtl">++`--insecure` هنا أيضا يعني بلا TLS وبلا مصادقة، وكل مستدعٍ مشرف أعلى. هو حد الثقة نفسه: مستخدم واحد على جهاز تطوير+([نموذج الأمان](./docs/SECURITY_MODEL.md)).++يتشمم XERJ كل ملف، ويستنتج ما هو، وينشئ فهرسا لكل مجموعة بيانات يجدها. تصل الشيفرة برموزها وأرقام أسطرها عبر tree-sitter، لا كنص مسطح:++</div>++```+phase A: 593 datasets inferred, 1955 junk/skipped files+phase B: indexing 25329 files with 8 workers+done in 158.1s, 593 datasets, 83103 records live, 790 junk records+```++<div dir="rtl">++## ما يوجه الناس إليه++- البرمجة بالمراجع: فهرس مشاريع المصدر المفتوح الأقرب إلى مشكلتك واسترجع كيف حلوها قبل كتابة الشيفرة (الاستخدام المقيس أعلاه).+- أسئلة وأجوبة وRAG على قاعدة الشيفرة: فهرس مستودعا، اسأل عن الآلية، واحصل على المقطع مع `file:line` بدل قائمة دليل.+- تدقيق الأمن: فهرس شجرة الهدف واستعلم عن أنماط المصب والأسرار والاستدعاءات الخطرة عبر كل أنواع الملفات دفعة واحدة.+- تحليل السجلات والحوادث: تصبح الصيغ المختلطة فهارس ذات أنواع مع التجميعات التي تتوقعها من Elasticsearch.+- الذاكرة الطويلة للوكيل: يخزن `/_memory/{namespace}` ما يتعلمه الوكيل ويسترجعه بالمعنى في الجلسة التالية.++## كيف يعمل الموجه++يعطي [llms.txt](https://xerj.org/llms.txt) وكيلك الخطوات مرتبة: التثبيت، تشغيل الخادم، `xerj autoindex .`، الاستعلام بأي عميل Elasticsearch، وحلقة البرمجة بالمراجع (استنسخ مصدرًا مفتوحًا مشابهًا، فهرسه، استرجع الآلية قبل الكتابة، انسب ما تستخدمه، واحترم التراخيص).++سبب الفائدة: الوكيل الذي يعمل من الذاكرة يدور في إعادة المحاولة على أي API لم يحفظها، وgrep لا يقول له إلا أين ينظر؛ والاستدراك يظل قراءة المصدر إلى السياق، حتى 1.06M توكن إدخال على متن واحد في قياساتنا. الوكيل الذي يستعلم XERJ يقرأ المقطع نفسه. نقص توكنات الإخراج بمقدار 2.7x عن grep (26x مقابل الذاكرة وحدها، وأرخص بمقدار 2.1x) مع معدل الحل 16/16 نفسه موجود في+[السبب المقيس](#السبب-المقيس-البرمجة-بالمراجع) أعلاه، مع تشغيل مرافق سجّل 9/9 بالاسترجاع مقابل 0/9 من الذاكرة على مكتبة Rust لم يرها النموذج قط.++موجهات أخرى تعمل على تثبيت جديد:++- *"اقرأ https://xerj.org/llms.txt، واضبط XERJ ليكون خلفية بحثك، وفهرس `./docs`، وأرني استعلام مثال لكل فهرس أنشأه."*+- *"شغّل `xerj autoindex map` وقل لي ماذا في هذه البيانات (الأنواع والعدد والمحاذير التي سجّلها)، ثم أجب عن أسئلتي بالبحث بدل قراءة الملفات."*+- *"استخدم واجهة `/_memory/notes` في XERJ ذاكرة طويلة لهذا المشروع: خزن ما تتعلمه وأنت تعمل، واسترجعه بالمعنى في الجلسة التالية."*++أمثلة مشغولة ومتحقق منها لكل قدرة: [xerj.org/docs/recipes](https://xerj.org/docs/recipes/).++<video src="https://xerj.org/xerj-biz-demo.mp4" poster="docs/media/demo-poster.png" controls muted playsinline width="840">+ <a href="https://xerj.org/aise-demo.html"><img src="docs/media/demo-poster.png" width="840" alt="شاهد عرض XERJ: الإقلاع والإدخال والبحث والمتجهات ولوحات المعلومات"></a>+</video>++<sub>إقلاع، إدخال جماعي، بحث، بحث kNN متجهي، لوحات مباشرة، بلا قص.+<a href="https://xerj.org/aise-demo.html">شاهده على xerj.org</a> أو+<a href="https://xerj.org/playground/">جرّب الملعب المباشر</a>.</sub>++## التثبيت اليدوي++</div>++```sh+curl -fsSL https://xerj.org/get | sh+```++<div dir="rtl">++Windows PowerShell:++</div>++```powershell+irm https://xerj.org/get.ps1 | iex+```++<div dir="rtl">++ملف ثنائي ساكن واحد، بلا JVM وبلا تبعيات. مبني مسبقا لـ Linux وmacOS وWindows على x86-64 وarm64. يمكنك أيضا [البناء من المصدر](#البناء-من-المصدر). يتحدث بواجهة Elasticsearch، فيعمل العملاء ولوحات المعلومات والأدوات القائمة عليه بلا تغيير.++أوامر أولى بعد التثبيت (يطبع المثبت أين استقر `xerj`؛ أضفه إلى PATH إن لزم): `xerj --insecure --data-dir ./data &`، انتظر حتى يجيب `http://localhost:9200`، ثم `xerj autoindex ~/my-project`. انظر [فهرسة مجلد](#فهرسة-مجلد).++لمضيف بلا وصول إلى الإنترنت وقت التشغيل، اتبع+[وصفة النشر المعزول](./docs/recipes/air-gapped-deployment.md). المضمّن المعجمي الافتراضي يعمل بلا شبكة؛ الوضع العصبي يحتاج ملفات النموذج الثلاثة مجهزة محليا قبل أول عملية دلالية.++## فهرسة مجلد++شغّل الخادم ثم وجّه `autoindex` إلى أي شيء:++</div>++```sh+xerj --insecure --data-dir ./data & # local dev: no TLS, no auth+xerj autoindex ~/my-project+```++<div dir="rtl">++ذلك حد ثقة جهاز التطوير من أعلى هذا الملف: بلا TLS، بلا مصادقة، وكل مستدعٍ مشرف أعلى. على حاسوب محمول هذا مناسب لأن العقدة الجديدة لا تربط إلا `127.0.0.1` ولا شيء غيره؛ المضيف المشترك يريد إقلاع المصادقة في الفقرة التالية مباشرة.++إذا كانت المصادقة مفعلة على خادمك، وهي الافتراض لكل إقلاع بلا `--insecure` (بما في ذلك أي إقلاع من ملف إعداد)، مرّر إلى `autoindex` المفتاح نفسه. لا يلتقط المفتاح من `xerj.toml`؛ مرّر `--api-key` أو اضبط `XERJ_API_KEY`، وإلا عاد كل طلب بـ `401 Unauthorized`:++</div>++```sh+xerj --data-dir ./data & # auth on: key minted on first boot+export XERJ_API_KEY="$(cat ./data/admin.key)" # <data_dir>/admin.key+xerj autoindex ~/my-project+```++<div dir="rtl">++هذا الإعداد كله. لا مخطط تكتبه ولا خط أنابيب تضبطه. يتشمم XERJ كل ملف، ويستنتج ما هو، وينشئ فهرسا لكل مجموعة بيانات يجدها:++</div>++```+phase A: 593 datasets inferred, 1955 junk/skipped files+phase B: indexing 25329 files with 8 workers+done in 158.1s, 593 datasets, 83103 records live, 790 junk records+```++<div dir="rtl">++تمر ملفات المصدر عبر tree-sitter، فتصل الشيفرة برموزها وأرقام أسطرها لا كنص مسطح. CSV وJSON وJSONL وXML وYAML وSQLite وPDF وDOCX وPowerPoint (`.pptx`، سجل لكل شريحة) وExcel (`.xlsx`، مجموعة بيانات لكل ورقة) وكتب EPUB (سجل لكل فصل) ودفاتر Jupyter (سجل لكل قسم عنوان، أي نواة) وصفحات man (roff، سجل لكل قسم) وHTML والبريد (`.eml` وصناديق mbox، بما في ذلك تصدير Google Takeout) وصيغ السجلات الشائعة كلها معالجة. مشاريع Unity تعامل معاملة من الدرجة الأولى: المشاهد والـ prefabs والأصول المسلسلة نصا تصبح سجلا لكل GameObject/Component، وملفات `.meta` تصبح جدول GUID إلى مسار، وسجلات MonoBehaviour تحمل `script_class`/`script_path` فيكون «أي المشاهد تستخدم هذا السكربت؟» استعلاما واحدا (الأصول المسلسلة ثنائيا تحتاج Force Text لتُقرأ؛ الأدلة المولدة مثل `Library/` تُتخطى تلقائيا وتُسجّل).++## البحث++هذه واجهة Elasticsearch، فهذا الجزء تعرفه:++</div>++```sh+# what did it find?+curl localhost:9200/_cat/indices++# full-text+curl "localhost:9200/ax-*/_search?q=checkout+error"++# structured+curl localhost:9200/ax-orders/_search -H 'content-type: application/json' -d '{+ "query": { "range": { "total": { "gte": 100 } } },+ "aggs": { "by_status": { "terms": { "field": "status" } } }+}'+```++<div dir="rtl">++البحث المتجهي والهجين يستخدمان صياغة `knn` و`semantic` نفسها التي ترسلها إلى Elasticsearch. أي مكتبة عميل لـ Elasticsearch تعمل إذا وجهتها إلى `localhost:9200`.++## تقييم النتائج مع Jev++درجة البحث تقول أي نتيجة فوق أي نتيجة، لا إن كانت النتيجة تجيب عن سؤالك حقا. [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev)، خدمة من TypeSafe AI، يفعل ذلك: أعطه سؤالا ومستندا فيعيد رقما من 0 إلى 1، مدى جودة إجابة المستند. يعمل XERJ معه بطريقتين.++**1. أعد ترتيب نتائجك بـ Jev (اختياري).** أضف `"rerank": {}` إلى `_search` فيرسل XERJ أعلى النتائج إلى Jev ثم يرتبها حسب الأرقام العائدة. على اختبار FiQA العام ترتفع جودة النتيجة من 0.24 إلى 0.36 (nDCG@10)، بنحو $0.64 إجمالا لـ 648 بحثا. عامل الأرقام كطريقة للترتيب لا كنسب مئوية دقيقة: ليست معايرة جيدا. **هذا يرسل نص تلك النتائج إلى خوادم TypeSafe.** يبقى مطفأ حتى تضع مفتاحا، و`[rerank] enabled = false` يمنعه تماما. اقرأ+[`docs/RERANK.md`](./docs/RERANK.md) قبل تشغيله.++**2. احصل على النوع نفسه من الإجابة محليا.** يقبل `POST /v1/systemone` و`POST /_decide` الأسئلة نفسها بالصيغة نفسها، لكن XERJ يجيب بنفسه بالبحث عن أقرب المستندات التي سبق أن وسمتها (مثلا رسائل موسومة مسبقا كبريد مزعج أو غير مزعج). لا شيء يغادر جهازك ولا يلزم مفتاح. لا يعمل إلا إذا كانت لديك أمثلة موسومة؛ على AG News (120k مثالا موسوما) يختار الوسم الصحيح 92% من المرات. عميل Python الرسمي `jev-reranker` يعمل مع عقدة XERJ بلا تغيير+([اختبار](./benchmarks/systemone-gate)). يجيب XERJ باسمه هو، `xerj-history-vote-1`؛ ليس Jev.++القياسات وكيفية إعادتها:+[`benchmarks/beir-hybrid`](./benchmarks/beir-hybrid/results/2026-09-20-rerank-full-fiqa) و+[`benchmarks/decisions-as-retrieval`](./benchmarks/decisions-as-retrieval).++## توصيل وكيل عبر MCP++ليس كل وكيل قادرا على تشغيل أمر shell. تصل المساعدات المكتبية ومضيفات استدعاء الدوال إلى الأدوات عبر Model Context Protocol، والملف الثنائي الذي ثبّته للتو هو خادم MCP. لا شيء آخر لتنزيله ولا شيء لتصريفه:++</div>++```sh+xerj --insecure --data-dir ./data & # 1. the node the tools query+xerj mcp # 2. MCP stdio server (your client runs this)+```++<div dir="rtl">++يتكلم `xerj mcp` بروتوكول MCP عبر stdio ويوكّل إلى العقدة التي يسميها `XERJ_URL` (الافتراضي `http://localhost:9200`). لا يشغّل عقدة؛ الخطوة 1 شرط سابق. خادم MCP لا يضيف ثقة من عنده: هو الملف الثنائي نفسه يتكلم stdio مع عميلك وHTTP العادي مع العقدة، فحد العقدة هو الحد الذي يُعتد به، والخطوة 1 أعلاه تقلع عقدة التطوير `--insecure` نفسها. ضع هذا في إعداد عميل MCP:++</div>++```json+{+ "mcpServers": {+ "xerj": {+ "command": "/home/you/.local/bin/xerj",+ "args": ["mcp"],+ "env": { "XERJ_URL": "http://localhost:9200" }+ }+ }+}+```++<div dir="rtl">++استخدم مسارا مطلقا. يضع المثبت `xerj` في `~/.local/bin` افتراضيا (`command -v xerj` يؤكد ذلك)، ومضيفات MCP التي تُطلق من أيقونة سطح المكتب لا ترث `PATH` صدفتك. إذا كانت العقدة تعمل بمصادقة (أي شيء غير `--insecure`)، أضف `"XERJ_AUTH": "ApiKey <key>"` إلى جانب `XERJ_URL`؛ المفتاح في `<data-dir>/admin.key`.++تُعرض ثلاث عشرة أداة. إحدى عشرة منها طبقة رفيعة فوق نقطة نهاية يخدمها XERJ سلفا:++| الأداة | ماذا تفعل |+|---|---|+| `xerj_search` | بحث بلغة استعلام ES على فهرس |+| `xerj_semantic_search` | استرجاع بالمعنى على حقل `semantic_text`، والاستعلام يُضمَّن في الخادم (المضمّن الافتراضي تجزئة سمات معجمية لا عصبية، ما لم تعمل العقدة بـ `--embed-mode neural`) |+| `xerj_vector_search` | kNN على حقل `dense_vector` |+| `xerj_hybrid_search` | دمج RRF أو خطي لاستعلامات فرعية |+| `xerj_memory_store` / `xerj_memory_recall` | ذاكرة وكيل دائمة في فضاء أسماء، تُسترجع بالنص أو المعنى أو المتجه |+| `xerj_brain_overview` / `xerj_brain_ego` / `xerj_brain_link` / `xerj_brain_unlink` | فهرس روابط الدماغ الثاني: التوجه، وتوسيع جوار عقدة مدعوم بالدليل، وإثبات الروابط وإحالتها إلى التقاعد |+| `xerj_plan` | مرشح بكلمات عادية داخلا، ولغة استعلام متحققة خارجا (`POST /_ask`؛ حتمي وقائم على قواعد، ليس LLM) |++أداتان أخريان ليستا مجرد تمرير بسيط: `xerj_map` يعيد خريطة الحقول لكل فهرس من كتالوج autoindex (مقصوص عند حد بايتات، وغير ذلك حرفي)، و`xerj_code_search` يشغّل خط أنابيب البرمجة بالمراجع في `xerj code`+([`tools/xerj-code/`](tools/xerj-code/)) ويعيد نصه المعروض.++يطبع `xerj mcp --help` كتلة الإعداد نفسها وقائمة الخيارات كاملة. مخططات الأدوات القابلة للقراءة آليا منشورة في+[xerj.org/docs/agents/schemas/mcp-tools.json](https://xerj.org/docs/agents/schemas/mcp-tools.json)،+مولدة من `tools/list` حي لا مكتوبة باليد، ومحروسة في CI+(`scripts/mcp-schema-check.sh`) مع اختبار وحدة، فلا تنحرف القائمة المنشورة عن القائمة المخدومة.++## لماذا يوجد++يحرق الوكلاء نافذة السياق بقراءة الملفات. PHP في نواة WordPress نحو 5.2 مليون توكن، أو 26 نافذة سياق كاملة، فلا يستطيع الوكيل أن يقرأه ببساطة. grep لا يحل هذا أيضا، لأن إصابة grep سطر، والحكم على ذلك السطر يعني فتح الملف كله.++الاستعلام عن فهرس يكلف كيلوبايتات لكل سؤال. في+[تدقيق أمني بالذكاء الاصطناعي لنواة WordPress](https://xerj.org/use-cases/code-security-audit.html)+عمل وكيل عبر 1,492 ملف PHP على نحو 26,000 توكن، وهو ما يلزم لتحميل نحو نصف بالمئة من الشجرة.++## حالات الاستخدام++- [البرمجة بالمراجع](https://xerj.org/case-studies/reference-coding.html): يسترجع وكيل البرمجة كيف حلّت المشاريع النظيرة المسألة بدل إعادة اشتقاقها. المقيس 2.7x توكنات إخراج أقل من البرمجة التي يقودها grep (26x مقابل الذاكرة وحدها)؛ يبلغ المستخدمون عن ~5x في التطوير الفعلي.+- [بحث الشيفرة وتدقيق الأمن](https://xerj.org/use-cases/code-security-audit.html): فهرسة واعية بشجرة الصياغة، فيجد الوكيل دالة لا سطرا.+- [البحث بالذكاء الاصطناعي وRAG](https://xerj.org/use-cases/ai-search-retrieval.html): استرجاع نصي كامل ومتجهي وهجين في استعلام واحد، بلا قاعدة متجهات منفصلة.+- [ذاكرة الوكيل](https://xerj.org/use-cases/second-brain.html): استرجاع دائم مع شبكة معرفة فوق مستنداتك.+- [تحليل السجلات والرصد](https://xerj.org/use-cases/unified-observability.html): سجلات ومقاييس وآثار في محرك واحد.+- [بديل Elasticsearch](https://xerj.org/use-cases/elasticsearch-replacement.html): بروتوكول السلك نفسه، ملف ثنائي واحد.++الأمثلة القابلة للتشغيل في [`recipes/`](./recipes) و[`docs/examples/`](./docs/examples).++## التوافق مع Elasticsearch++ينفذ XERJ واجهة REST لـ Elasticsearch: الفهارس والمستندات والـ bulk والبحث والتجميعات والـ mappings وkNN وscroll وreindex ونقاط `_cat`. يتصل Kibana ومكتبات العميل الرسمية به مباشرة. حد يستحق أن تعرفه قبل توجيه أدوات التصدير إليه: scroll لقطة محدودة تُحسب مقدما لا مؤشرا يمشي على المقاطع، فاستعلام يتجاوز مجموعه الدقيق نافذة اللقطة يُرفض بـ `400` بدل أن يُبتر بصمت. استخدم `search_after` لمجموعات نتائج بأي حجم+([السقف](https://xerj.org/docs/api-es-compat.html#scroll-cap)).++تعمل حزمة المطابقة على كل commit وتنجح الآن في 1366 من 1369 حالة. تعيش في+[`engine/tests/es-compat-yaml`](./engine/tests/es-compat-yaml)، والفجوات الباقية مدرجة هناك لا مخفية. XERJ متوافق مع الواجهة. ليس إعادة تنفيذ لداخليات Elasticsearch، وليس تفرعا.++## القياسات المقارنة++يُقاس XERJ رأسا برأس مقابل Elasticsearch 8.13.4 في الإدخال والبحث النصي الكامل والتجميعات والبحث المتجهي والقراءات الصادرة تحت فيضان كتابة متزامن. آخر تشغيل مغلق الحلقة يسجل 55 فوزا و26 تعادلا و4 خسائر، منها 1.72x إنتاجية إدخال وبصمة على القرص أصغر بمقدار 1.61x.++الخسائر الأربع الفجوة نفسها: p99 للقراءة بينما يعمل كاتب عالي المعدل. هي+[مكتوبة كاملة](./demo/playbooks/MIXED_READ_UNDER_WRITE_FINDING_2026-07-08.md) لا متروكة. النتائج والمنهجية والعدة في+[xerj.org/benchmarks](https://xerj.org/benchmarks) وفي+[`demo/playbooks`](./demo/playbooks)، لتعيد تشغيلها بنفسك. عامل أي رقم لا تستطيع إعادة إنتاجه بشك، بما في ذلك أرقامنا.++### فهرسة الشيفرة++تُحلل ملفات المصدر بـ tree-sitter وتُفهرس بوعي لشجرة الصياغة — الرموز مع النص الكامل — فيسترجع الوكيل دالة لا سطرا. على نسخة Apache Lucene (6,113 ملف مصدر، 51 MB) يجري الاستخراج داخل العملية بخيط واحد بسرعة **~1,500 ملف/ث (13 MB/ث)**؛ تحليل tree-sitter نحو 72% من ذلك وهو أرضية كل ملف. أعد إنتاجه بـ:++</div>++```sh+XERJ_EXTRACT_BENCH=/path/to/repo cargo test -p xerj-autoindex --release \+ extract_bench -- --nocapture --ignored+```++<div dir="rtl">++إعادة الفهرسة **تزايدية**: الملف الذي يطابق محتواه بايتا بايت آخر جيل مفهرس يتخطى التحليل تماما ويحمل نتيجته المثبتة إلى الأمام، فإعادة التشغيل بعد تعديل حفنة من الملفات تعمل بمقدار ما تغير لا بمقدار المستودع كله — حالة التعديل ثم إعادة التشغيل أو CI الشائعة، وعادة أكثر من 95% بلا تغيير. تجزئة المحتوى الكاملة ما زالت تجري لاكتشاف التغيير، فزمن إعادة الفهرسة كله أرضيته التجزئة لا التحليل.++## البناء من المصدر++تحتاج سلسلة أدوات Rust مستقرة.++</div>++```sh+git clone https://github.com/xerj-org/xerj+cd xerj/engine+cargo build --release -p xerj-server+./target/release/xerj --insecure --data-dir ./data+```++<div dir="rtl">++لتشغيل حزمة المطابقة ضد خادم يعمل:++</div>++```sh+cargo run --release -p es-yaml-runner -- --dir tests/es-compat-yaml/yaml+```++<div dir="rtl">++## التوثيق++- [الأدلة ومرجع الواجهة](https://xerj.org/docs/)+- [وصفات](https://xerj.org/docs/recipes/) للمهام الشائعة+- [خارطة الطريق](./ROADMAP.md): ما يُشحن اليوم مقابل ما هو قادم، متحقق منه مقابل ملف الإصدار الثنائي. عرض إصدارا بإصدار:+ [المعالم](https://github.com/xerj-org/xerj/milestones)؛ الحالة الحية:+ [لوحة المشروع](https://github.com/users/xerj-org/projects/1)؛ المؤشر الثابت:+ [issue خارطة الطريق المثبت](https://github.com/xerj-org/xerj/issues/298)+- [سجل التغييرات](./CHANGELOG.md)++صفحات مرجع لأنظمة فرعية بعينها، مكتوبة على المصدر وتتضمن الحدود التي لا يرفعها كل واحد:++- [الدماغ الثاني](./docs/SECOND_BRAIN.md) لطبقة العلاقات فوق المستندات المفهرسة: مسارات `/_graph`، والدليل على الروابط، والكواشف الثمانية، وسقف القفزتين.+- [قارئ لوحة التحكم](./docs/CONSOLE_READER.md) لموطن المتن في اللوحة، وقارئ أي سجل (بريد بمرفقاته، صفحة PDF) ووضع الضيف للقراءة فقط، مع قواعد العرض التي تبقي المستند العدائي خاملا وما لا تعرضه.+- [البرمجة النصية](./docs/SCRIPTING.md) لمجموعة Painless الفرعية، وأين تعمل النصوص، وحدود الموارد التي تقيدها.+- [اللقطة والاستعادة](./docs/SNAPSHOT_AND_RESTORE.md) للمجموعة الفرعية المدعومة من واجهة اللقطات، وما تستبدله الاستعادة.+- [المشاركة](./docs/SHARING.md) لأمر `xerj share`: وصول ضيف للقراءة فقط إلى مجلد مفهرس عبر رابط ورمز مرور، وما يبلغه الضيف وما لا يبلغه، ونموذج التهديد.+- [نموذج الأمان](./docs/SECURITY_MODEL.md) للمصادقة، وفضاء الأسماء المحجوز `.xerj-memory-*`، ومفاتيح API، وما لا يُفرض.+- [إعادة الترتيب](./docs/RERANK.md) لمرحلة البحث الاختيارية `rerank`: قاض خارجي يعيد ترتيب أعلى الإصابات باحتمال معاير. هي ميزة وقت البحث الوحيدة التي ترسل نص المستندات خارج العقدة (تضمينات البروكسي والتقاط WAL يرسلان النص أيضا حين يضبطهما مشغل؛ الصفحة تسرد كل اتصال صادر تستطيع العقدة فتحه)، وتحتاج مفتاح مزود يضبطه المشغل، وجودة ترتيبها بالنموذج الحقيقي غير متحققة.+- [XERJ مقابل Lucene 10.3.1](./docs/XERJ_VS_LUCENE.md) لمقارنة مثبتة على المصدر، على ستة محاور، لتصميمي التخزين والبحث.++## المساهمة++طلبات السحب مرحّب بها من البشر ووكلاء الذكاء الاصطناعي على السواء؛ انظر+[انضم إلى المجتمع](#انضم-إلى-المجتمع) أعلاه. المساهمة الأساسية تقرير ميداني قصير: `gh pr create` عادي يضيف ملف markdown واحدا تحت+[`user-feedback/16-agent-field-reports/`](./user-feedback/16-agent-field-reports).+طلبات السحب التي لا تحتوي إلا على تقرير ميداني معفاة من CLA، فتُدمج بلا توقيع.++لتغييرات الشيفرة، انظر [CONTRIBUTING.md](./CONTRIBUTING.md) لمجرى العمل و+[CLA.md](./CLA.md) لاتفاقية ترخيص المساهم، وهي توقيع واحد لكل مساهم لا توقيع لكل طلب سحب. على الوكيل الذي يفتح طلبا أن يصرح أن وكيلا كتبه وأن يتبع [AGENTS.md](./AGENTS.md) /+[.github/AI_CONTRIBUTIONS.md](./.github/AI_CONTRIBUTIONS.md).++الأخطاء وطلبات الميزات تذهب إلى [issues على GitHub](https://github.com/xerj-org/xerj/issues).++## الرخصة++[Apache 2.0](./LICENSE).++</div>diff --git a/README.es.md b/README.es.mdnew file mode 100644index 000000000..adbc91f72--- /dev/null+++ b/README.es.md@@ -0,0 +1,548 @@+# XERJ++<a href="https://trendshift.io/repositories/116361?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-116361" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/116361" alt="xerj-org%2Fxerj | Trendshift" width="250" height="55"/></a>++[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md) | [العربية](./README.ar.md) | [Español](./README.es.md)++[](https://github.com/xerj-org/xerj/actions/workflows/ci.yml)+[](https://github.com/xerj-org/xerj/releases)+[](./LICENSE)+[](https://github.com/xerj-org/xerj/stargazers)+[](https://www.rust-lang.org)+[](https://github.com/xerj-org/xerj/discussions)+[](https://discord.com/invite/yetXFusXfs)+[](https://x.com/xerj_org)++[](https://xerj.org/case-studies/reference-coding.html)+[](https://xerj.org/docs/cli.html)+[](https://xerj.org/docs/queries.html)+[](https://xerj.org/docs/recipes/agentic-memory.html)+[](https://xerj.org/llms.txt)+[](https://xerj.org/llms.txt)+[](https://xerj.org/benchmarks)+[](https://xerj.org/docs/install.html)+[](https://xerj.org/docs/vectors.html)+[](https://xerj.org/docs/vectors.html)++> Esta página es la traducción al español del [README en inglés](./README.md). Si hay diferencias, prevalece la versión en inglés. Las cifras, los costes y las salidas de ejemplo se toman del original y de los registros que cita; esta traducción no los volvió a medir.++XERJ es una búsqueda local de IA en la que confía la comunidad. Indexa cualquier carpeta+de forma automática, así que tu agente de programación deja de gastar tokens leyendo+archivos uno por uno y recupera el código exacto que necesita. Su uso principal, y donde+más se nota la diferencia, es la programación por referencia (reference coding): le das+una tarea al agente, descarga los repositorios de código abierto más cercanos, los indexa+y reutiliza cómo resolvieron el problema antes de escribir su propio código. En un estudio+controlado eso redujo los tokens de salida de un agente de programación 2.7x, con la misma+tasa de resolución de 16/16+([caso de estudio](https://xerj.org/case-studies/reference-coding.html)), y en el trabajo+diario la gente informa de unas 5x+([informes de campo](./user-feedback/11-reference-coding-field-reports/2026-08-11-token-savings-reports.md)).+Basta para que un modelo más pequeño y barato supere en código a uno más caro que trabaja+de memoria, y para que pases menos tiempo en bucles de corrección. Pruébalo ahora con una+instalación de un solo prompt:++```text+Install XERJ (docs: https://xerj.org/llms.txt), index this project's sources, and set up+reference coding: clone and index the open-source repos closest to what we're building,+and search how they solved a problem before writing code.+```++O ejecútalo tú mismo:++```sh+curl -fsSL https://xerj.org/get | sh+xerj --insecure --data-dir ./data &+xerj init # wire XERJ into Claude Code/Cursor (MCP + skill), one command+xerj autoindex ~/my-project+xerj search "how do we rotate the WAL segment" # ranked passages, file:line+xerj def "euler_to_rotationmatrix" # go-to-definition: file:line + signature+xerj gain # what it did for you — counted, not estimated+```++Windows y una instalación comprobada a mano están en [Instalación manual](#instalación-manual).++Esa opción `--insecure` es un límite de confianza, no un formalismo. Desactiva TLS y la+autenticación por clave de API, así que quien pueda llegar al puerto es un superusuario+que puede leer y borrar cada índice, incluido cada espacio de nombres `/_memory`. Está+pensada para un usuario en una máquina de desarrollo: un nodo recién creado solo escucha+en `127.0.0.1`, y un enlace en claro sobre cualquier otra interfaz se niega a arrancar+salvo que lo permitas de forma explícita. El modelo completo está en+[docs/SECURITY_MODEL.md](./docs/SECURITY_MODEL.md).++## Únete a la comunidad++Te unes a XERJ ejecutándolo y devolviendo un informe de campo corto sobre cómo fue: un+solo commit o PR. Ese informe es la credencial de ingreso, y es lo único que el proyecto+pide a cambio de un binario gratuito con licencia Apache-2.0. Es lo que hace que el motor+siga mejorando para quien lo ejecute después.++Las personas y los agentes de IA son bienvenidos; esto no es, a propósito, un proyecto+solo para agentes. Da igual si indexaste un repositorio a la hora de comer o si un agente+instaló XERJ a mitad de sesión en el código de otra persona: lo que se pide es lo mismo,+un informe corto que diga a qué lo apuntaste, para qué lo usaste y tu veredicto honesto.+Un veredicto negativo es un buen informe. Si algo se rompió, eso es un issue o una+corrección aparte, encima del informe.++Los PR que solo contienen un informe de campo están exentos del CLA, así que se fusionan+sin firma. El camino que funciona en cualquier build es un `gh pr create` normal que añada+exactamente un archivo markdown bajo+[`user-feedback/16-agent-field-reports/`](./user-feedback/16-agent-field-reports), sin+nada más en el diff. En un build que lo tenga, `xerj feedback` redacta el informe y+rellena la versión, el sistema operativo y lo que se indexó, y `xerj feedback --open-pr`+abre el PR por ti. Mira `xerj --help` para saber si tu binario tiene el comando.++## El motivo medido: programación por referencia++Un agente que usa grep mete archivos enteros en su contexto, hasta 1.06M tokens de entrada+en un corpus de nuestras mediciones, y aun así tiene que leerlos. Un agente que consulta+XERJ recibe el pasaje. Medido de extremo a extremo sobre código que el modelo no tenía+memorizado+([caso de estudio](https://xerj.org/case-studies/reference-coding.html): 8 tareas, 4 idiomas,+16 ejecuciones por rama, conteos reales de tokens de `claude -p`):++| | tokens de salida | coste | resueltas |+|---|---:|---:|---:|+| solo de memoria | 260,916 | $11.18 | 11/16 |+| agente guiado por grep | 26,477 | $3.27 | 16/16 |+| XERJ | 9,982 | $1.58 | 16/16 |++Eso es 2.7x menos tokens de salida que grep y 26x menos que la memoria sola, con la misma+tasa de resolución, y hasta 278x menos en una sola tarea de Java. En el desarrollo real,+los usuarios informan de unas 5x menos tokens de extremo a extremo+([informes de campo](./user-feedback/11-reference-coding-field-reports/2026-08-11-token-savings-reports.md)).+El valor depende de la memorización: gana en código privado, interno, de nicho o posterior+al corte de entrenamiento, y va de neutro a perjudicial en bibliotecas públicas populares+que el modelo ya conoce. Los límites honestos están en el+[caso de estudio](https://xerj.org/case-studies/reference-coding.html).++## Pásale cualquier carpeta++La programación por referencia es un uso de la misma primitiva: `xerj autoindex <folder>`+hace que un agente conozca un corpus en lugar de hacerle grep. Un comando indexa código,+documentación, logs, PDF, SQLite y CSV incómodos en índices tipados y consultables para+búsqueda, RAG, auditorías de seguridad y memoria de agentes, sin esquema que escribir y+sin pipeline que configurar.++```sh+xerj --insecure --data-dir ./data & # start it+xerj autoindex ~/my-project # point it at anything+```++`--insecure`, otra vez, significa sin TLS y sin autenticación: cada llamador es un+superusuario. Es el mismo límite de un usuario en una máquina de desarrollo de arriba+([modelo de seguridad](./docs/SECURITY_MODEL.md)).++XERJ olfatea cada archivo, deduce qué es y crea un índice por cada conjunto de datos que+encuentra. El código llega con sus símbolos y números de línea a través de tree-sitter, no+como texto plano:++```+phase A: 593 datasets inferred, 1955 junk/skipped files+phase B: indexing 25329 files with 8 workers+done in 158.1s, 593 datasets, 83103 records live, 790 junk records+```++## Para qué lo usa la gente++- Programación por referencia: indexa los proyectos de código abierto más cercanos a tu+ problema y recupera cómo lo resolvieron antes de escribir código (el uso medido de+ arriba).+- Preguntas y RAG sobre un código base: indexa un repositorio, pregunta por el mecanismo+ y obtén el pasaje con `file:line` en lugar de un listado de directorio.+- Auditorías de seguridad: indexa un árbol objetivo y consulta patrones de sink, secretos+ y llamadas peligrosas en todos los tipos de archivo a la vez.+- Análisis de logs e incidentes: los formatos mezclados se vuelven índices tipados con las+ agregaciones que esperarías de Elasticsearch.+- Memoria a largo plazo del agente: `/_memory/{namespace}` guarda lo que un agente aprende+ y lo recupera por significado en la sesión siguiente.++## Cómo funciona el prompt++[llms.txt](https://xerj.org/llms.txt) le da a tu agente los pasos en orden: instalar,+arrancar el servidor, `xerj autoindex .`, consultar con cualquier cliente de Elasticsearch,+y el bucle de programación por referencia (clonar OSS parecido, indexarlo, recuperar el+mecanismo antes de escribir, citar lo que uses y respetar las licencias).++Por qué ayuda: un agente que trabaja de memoria entra en un bucle de reintentos con+cualquier API que no tenga memorizada, y grep solo le dice dónde mirar; la recuperación+sigue siendo leer el fuente en el contexto, hasta 1.06M tokens de entrada en un corpus de+nuestras mediciones. Un agente que consulta XERJ lee el pasaje exacto. Las 2.7x menos+tokens de salida que grep (26x frente a la memoria sola, 2.1x más barato) con la misma+tasa de resolución de 16/16 están en+[El motivo medido](#el-motivo-medido-programación-por-referencia), junto con una ejecución+acompañante que puntúa 9/9 con recuperación frente a 0/9 de memoria en una biblioteca de+Rust que el modelo nunca había visto.++Más prompts que funcionan en una instalación recién hecha:++- *"Lee https://xerj.org/llms.txt, configura XERJ como tu backend de búsqueda, indexa+ `./docs` y muéstrame una consulta de ejemplo por cada índice que haya creado."*+- *"Ejecuta `xerj autoindex map` y dime qué hay en estos datos (tipos, recuentos y las+ advertencias que registró); después responde a mis preguntas con búsqueda en lugar de+ leer archivos."*+- *"Usa la API `/_memory/notes` de XERJ como tu memoria a largo plazo para este proyecto:+ guarda lo que aprendas mientras trabajas y recupéralo por significado en la sesión+ siguiente."*++Ejemplos trabajados y validados de cada capacidad: [xerj.org/docs/recipes](https://xerj.org/docs/recipes/).++<video src="https://xerj.org/xerj-biz-demo.mp4" poster="docs/media/demo-poster.png" controls muted playsinline width="840">+ <a href="https://xerj.org/aise-demo.html"><img src="docs/media/demo-poster.png" width="840" alt="Ver la demo de XERJ: arranque, ingesta, búsqueda, vectores, paneles"></a>+</video>++<sub>Arranque, ingesta masiva, búsqueda, kNN vectorial, paneles en vivo, sin cortes.+<a href="https://xerj.org/aise-demo.html">Míralo en xerj.org</a> o+<a href="https://xerj.org/playground/">prueba el entorno en vivo</a>.</sub>++## Instalación manual++```sh+curl -fsSL https://xerj.org/get | sh+```++Windows PowerShell:++```powershell+irm https://xerj.org/get.ps1 | iex+```++Un binario estático, sin JVM y sin dependencias. Precompilado para Linux, macOS y Windows+en x86-64 y arm64. También puedes [compilar desde el código fuente](#compilar-desde-el-código-fuente).+Habla la API de Elasticsearch, así que los clientes, paneles y herramientas que ya tienes+funcionan contra él sin cambios.++Primeros comandos después de instalar (el instalador imprime dónde quedó `xerj`; añádelo a+tu PATH si hace falta): `xerj --insecure --data-dir ./data &`, espera a que+`http://localhost:9200` responda y luego `xerj autoindex ~/my-project`. Véase+[Indexar una carpeta](#indexar-una-carpeta).++En un host sin acceso a internet en tiempo de ejecución, sigue la+[receta de despliegue aislado](./docs/recipes/air-gapped-deployment.md). El embedder+léxico predeterminado funciona sin red; el modo neuronal necesita los tres archivos del+modelo preparados en local antes de la primera operación semántica.++## Indexar una carpeta++Arranca el servidor y apunta `autoindex` a lo que sea:++```sh+xerj --insecure --data-dir ./data & # local dev: no TLS, no auth+xerj autoindex ~/my-project+```++Ese es el límite de confianza de la máquina de desarrollo del principio de este README:+sin TLS, sin autenticación, cada llamador es un superusuario. En un portátil está bien+porque un nodo recién creado solo escucha en `127.0.0.1` y en nada más; un host compartido+quiere el arranque con autenticación de justo debajo.++Si tu servidor tiene la autenticación activada, que es el valor predeterminado de cada+arranque sin `--insecure` (incluido cualquier arranque desde un archivo de configuración),+pásale a `autoindex` la misma clave. Nunca la toma de `xerj.toml`; pasa `--api-key` o+define `XERJ_API_KEY`, o cada petición vuelve con `401 Unauthorized`:++```sh+xerj --data-dir ./data & # auth on: key minted on first boot+export XERJ_API_KEY="$(cat ./data/admin.key)" # <data_dir>/admin.key+xerj autoindex ~/my-project+```++Esa es toda la puesta en marcha. No hay esquema que escribir ni pipeline que configurar.+XERJ olfatea cada archivo, deduce qué es y crea un índice por cada conjunto de datos que+encuentra:++```+phase A: 593 datasets inferred, 1955 junk/skipped files+phase B: indexing 25329 files with 8 workers+done in 158.1s, 593 datasets, 83103 records live, 790 junk records+```++Los archivos fuente pasan por tree-sitter, así que el código llega con sus símbolos y+números de línea en lugar de como texto plano. CSV, JSON, JSONL, XML, YAML, SQLite, PDF,+DOCX, PowerPoint (`.pptx`, un registro por diapositiva), Excel (`.xlsx`, un conjunto de+datos por hoja), libros EPUB (un registro por capítulo), cuadernos Jupyter (un registro por+sección de encabezado, cualquier kernel), páginas man (roff, un registro por sección), HTML,+correo (`.eml` y buzones mbox, incluido un export de Google Takeout) y los formatos de log+habituales están cubiertos. Los proyectos de Unity reciben un trato de primera clase: las+escenas, prefabs y assets serializados como texto se vuelven un registro por+GameObject/Component, los archivos `.meta` se vuelven una tabla de GUID a ruta, y los+registros MonoBehaviour llevan `script_class`/`script_path`, así que «¿qué escenas usan+este script?» es una sola consulta (los assets serializados en binario necesitan Force Text+para poder leerse; los directorios generados como `Library/` se omiten solos y quedan+registrados).++## Buscar++Esta es la API de Elasticsearch, así que esta parte ya la conoces:++```sh+# what did it find?+curl localhost:9200/_cat/indices++# full-text+curl "localhost:9200/ax-*/_search?q=checkout+error"++# structured+curl localhost:9200/ax-orders/_search -H 'content-type: application/json' -d '{+ "query": { "range": { "total": { "gte": 100 } } },+ "aggs": { "by_status": { "terms": { "field": "status" } } }+}'+```++La búsqueda vectorial e híbrida usa la misma sintaxis `knn` y `semantic` que enviarías a+Elasticsearch. Cualquier biblioteca cliente de Elasticsearch funciona si la apuntas a+`localhost:9200`.++## Puntuar los resultados con Jev++Una puntuación de búsqueda te dice qué resultado está por encima de cuál, pero no si un+resultado responde de verdad a tu pregunta. [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev),+un servicio de TypeSafe AI, hace eso: le das una pregunta y un documento y devuelve un+número de 0 a 1, lo bien que el documento responde. XERJ trabaja con él de dos maneras.++**1. Reordena tus resultados con Jev (opcional).** Añade `"rerank": {}` a un `_search` y+XERJ envía los primeros resultados a Jev, y luego los ordena por los números que recibe.+En la prueba pública FiQA, la calidad del resultado pasa de 0.24 a 0.36 (nDCG@10), por unos+$0.64 en total para 648 búsquedas. Trata los números como una forma de ordenar, no como+porcentajes exactos: no están bien calibrados. **Esto envía el texto de esos resultados a+los servidores de TypeSafe.** Sigue apagado hasta que pongas una clave, y+`[rerank] enabled = false` lo prohíbe por completo. Lee+[`docs/RERANK.md`](./docs/RERANK.md) antes de activarlo.++**2. Obtén el mismo tipo de respuesta en local.** `POST /v1/systemone` y `POST /_decide`+aceptan las mismas preguntas en el mismo formato, pero XERJ las responde él mismo, buscando+los documentos más parecidos que ya hayas etiquetado (por ejemplo mensajes ya marcados como+spam o no spam). Nada sale de tu máquina y no hace falta ninguna clave. Solo funciona si+tienes ejemplos etiquetados; en AG News (120k ejemplos etiquetados) elige la etiqueta+correcta el 92% de las veces. El cliente oficial de Python `jev-reranker` funciona contra+un nodo de XERJ sin cambios+([prueba](./benchmarks/systemone-gate)). XERJ responde bajo su propio nombre,+`xerj-history-vote-1`; no es Jev.++Mediciones y cómo reproducirlas:+[`benchmarks/beir-hybrid`](./benchmarks/beir-hybrid/results/2026-09-20-rerank-full-fiqa) y+[`benchmarks/decisions-as-retrieval`](./benchmarks/decisions-as-retrieval).++## Conectar un agente por MCP++No todo agente puede ejecutar un comando de shell. Los asistentes de escritorio y los hosts+de llamada a funciones llegan a las herramientas por el Model Context Protocol, y el binario+que acabas de instalar es el servidor MCP. No hay nada más que descargar ni nada que+compilar:++```sh+xerj --insecure --data-dir ./data & # 1. the node the tools query+xerj mcp # 2. MCP stdio server (your client runs this)+```++`xerj mcp` habla MCP por stdio y hace de proxy hacia el nodo nombrado por `XERJ_URL`+(predeterminado `http://localhost:9200`). No arranca un nodo; el paso 1 es el requisito+previo. El servidor MCP no añade confianza propia: es el mismo binario hablando stdio con+tu cliente y HTTP plano con el nodo, así que el límite que cuenta es el del nodo, y el+paso 1 de arriba arranca el mismo nodo de desarrollo `--insecure`. Suelta esto en la+configuración de tu cliente MCP:++```json+{+ "mcpServers": {+ "xerj": {+ "command": "/home/you/.local/bin/xerj",+ "args": ["mcp"],+ "env": { "XERJ_URL": "http://localhost:9200" }+ }+ }+}+```++Usa una ruta absoluta. El instalador pone `xerj` en `~/.local/bin` de forma predeterminada+(`command -v xerj` lo confirma), y los hosts MCP lanzados desde un icono de escritorio no+heredan el `PATH` de tu shell. Si el nodo corre con autenticación (cualquier cosa que no+sea `--insecure`), añade `"XERJ_AUTH": "ApiKey <key>"` junto a `XERJ_URL`; la clave está+en `<data-dir>/admin.key`.++Se exponen trece herramientas. Once son proxies finos sobre un endpoint que XERJ ya sirve:++| Herramienta | Qué hace |+|---|---|+| `xerj_search` | búsqueda con el DSL de consultas de ES sobre un índice |+| `xerj_semantic_search` | recuperación por significado sobre un campo `semantic_text`; la consulta se embebe en el servidor (el embedder predeterminado es hashing de rasgos léxico, no neuronal, salvo que el nodo corra con `--embed-mode neural`) |+| `xerj_vector_search` | kNN sobre un campo `dense_vector` |+| `xerj_hybrid_search` | fusión RRF o lineal de subconsultas |+| `xerj_memory_store` / `xerj_memory_recall` | memoria durable del agente en un espacio de nombres, recuperada por texto, significado o vector |+| `xerj_brain_overview` / `xerj_brain_ego` / `xerj_brain_link` / `xerj_brain_unlink` | el índice de enlaces del segundo cerebro: orientarse, expandir el vecindario con evidencia de un nodo, afirmar y retirar enlaces |+| `xerj_plan` | entra un filtro en palabras llanas, sale un DSL de consulta validado (`POST /_ask`; determinista y basado en reglas, no un LLM) |++Dos más no son proxies planos: `xerj_map` devuelve el mapa de campos por índice del+catálogo de autoindex (recortado a un tope de bytes, y por lo demás textual), y+`xerj_code_search` ejecuta el pipeline de programación por referencia de `xerj code`+([`tools/xerj-code/`](tools/xerj-code/)) y devuelve su texto renderizado.++`xerj mcp --help` imprime el mismo bloque de configuración y la lista completa de+opciones. Los esquemas de herramientas legibles por máquina están publicados en+[xerj.org/docs/agents/schemas/mcp-tools.json](https://xerj.org/docs/agents/schemas/mcp-tools.json),+generados desde un `tools/list` en vivo, nunca escritos a mano, y vigilados en CI+(`scripts/mcp-schema-check.sh`) más un test unitario, así que la lista publicada no puede+apartarse de la que se sirve.++## Por qué existe++Los agentes queman su ventana de contexto leyendo archivos. El PHP del núcleo de WordPress+son unos 5.2 millones de tokens, o 26 ventanas de contexto completas, así que un agente no+puede simplemente leerlo. Grep tampoco lo resuelve, porque un acierto de grep es una línea,+y juzgar esa línea significa abrir el archivo entero.++Consultar un índice cuesta kilobytes por pregunta. En+[una auditoría de seguridad con IA del núcleo de WordPress](https://xerj.org/use-cases/code-security-audit.html),+un agente trabajó sobre 1,492 archivos PHP con unos 26,000 tokens, que es lo que hace falta+para cargar cerca de medio punto porcentual del árbol.++## Casos de uso++- [Programación por referencia](https://xerj.org/case-studies/reference-coding.html): tu+ agente de programación recupera cómo los proyectos pares ya lo resolvieron en lugar de+ volver a derivarlo. Medido: 2.7x menos tokens de salida que programar guiado por grep+ (26x frente a la memoria sola); los usuarios informan de ~5x en el desarrollo real.+- [Búsqueda de código y auditorías de seguridad](https://xerj.org/use-cases/code-security-audit.html):+ indexación consciente del AST, así que un agente encuentra una función en lugar de una+ línea.+- [Búsqueda con IA y RAG](https://xerj.org/use-cases/ai-search-retrieval.html): recuperación+ de texto completo, vectorial e híbrida en una consulta, sin una base de datos vectorial+ aparte.+- [Memoria del agente](https://xerj.org/use-cases/second-brain.html): recuerdo durable con+ un grafo de conocimiento sobre tus propios documentos.+- [Analítica de logs y observabilidad](https://xerj.org/use-cases/unified-observability.html):+ logs, métricas y trazas en un motor.+- [Sustituto de Elasticsearch](https://xerj.org/use-cases/elasticsearch-replacement.html):+ el mismo protocolo de cable, un binario.++Los ejemplos ejecutables viven en [`recipes/`](./recipes) y [`docs/examples/`](./docs/examples).++## Compatibilidad con Elasticsearch++XERJ implementa la API REST de Elasticsearch: índices, documentos, bulk, búsqueda,+agregaciones, mappings, kNN, scroll, reindex y los endpoints `_cat`. Kibana y las+bibliotecas cliente oficiales se conectan directamente. Un límite que conviene conocer+antes de apuntarle herramientas de exportación: scroll es una instantánea acotada calculada+de antemano, no un cursor que recorre segmentos, así que una consulta cuyo total exacto+supera la ventana de la instantánea se rechaza con un `400` en lugar de truncarse en+silencio. Usa `search_after` para conjuntos de resultados de cualquier tamaño+([el tope](https://xerj.org/docs/api-es-compat.html#scroll-cap)).++La suite de conformidad corre en cada commit y ahora mismo pasa 1366 de 1369 casos. Vive+en [`engine/tests/es-compat-yaml`](./engine/tests/es-compat-yaml), y los huecos que quedan+están listados ahí en lugar de ocultos. XERJ es compatible con la API. No es una+reimplementación de los internos de Elasticsearch, y no es un fork.++## Pruebas comparativas++XERJ se mide cara a cara contra Elasticsearch 8.13.4 en ingesta, búsqueda de texto+completo, agregaciones, búsqueda vectorial y lecturas emitidas bajo una avalancha de+escrituras concurrentes. La última ejecución en bucle cerrado puntúa 55 victorias, 26+empates y 4 derrotas, incluido 1.72x de rendimiento de ingesta y una huella en disco 1.61x+más pequeña.++Las cuatro derrotas son el mismo hueco: el p99 de lectura mientras corre un escritor de+alto ritmo. Está+[escrito por completo](./demo/playbooks/MIXED_READ_UNDER_WRITE_FINDING_2026-07-08.md) en+lugar de omitido. Los resultados, la metodología y el arnés están en+[xerj.org/benchmarks](https://xerj.org/benchmarks) y en+[`demo/playbooks`](./demo/playbooks), para que puedas repetirlos tú. Trata con escepticismo+cualquier número que no puedas reproducir, incluidos los nuestros.++### Indexación de código++Los archivos fuente se parsean con tree-sitter y se indexan con conciencia del AST —+símbolos más el texto completo — así que un agente recupera una función, no una línea. En+un checkout de Apache Lucene (6,113 archivos fuente, 51 MB) la extracción en proceso a un+solo hilo corre a **~1,500 archivos/s (13 MB/s)**; el parse de tree-sitter es ~72% de eso+y es el suelo por archivo. Reprodúcelo con:++```sh+XERJ_EXTRACT_BENCH=/path/to/repo cargo test -p xerj-autoindex --release \+ extract_bench -- --nocapture --ignored+```++La reindexación es **incremental**: un archivo cuyo contenido es idéntico byte a byte a la+última generación indexada se salta el parse por completo y arrastra su resultado ya+confirmado, así que una nueva pasada después de editar un puñado de archivos hace un+trabajo proporcional a lo que cambió, no al repositorio entero — el caso habitual de+editar y volver a correr, o de CI, típicamente más del 95% sin cambios. El hash completo+del contenido sigue ejecutándose para detectar cambios, así que el tiempo total de+reindexación tiene como suelo el hashing, no el parseo.++## Compilar desde el código fuente++Necesitas una cadena de herramientas de Rust estable.++```sh+git clone https://github.com/xerj-org/xerj+cd xerj/engine+cargo build --release -p xerj-server+./target/release/xerj --insecure --data-dir ./data+```++Para correr la suite de conformidad contra un servidor en marcha:++```sh+cargo run --release -p es-yaml-runner -- --dir tests/es-compat-yaml/yaml+```++## Documentación++- [Guías y referencia de la API](https://xerj.org/docs/)+- [Recetas](https://xerj.org/docs/recipes/) para tareas habituales+- [Hoja de ruta](./ROADMAP.md): qué se publica hoy frente a lo que viene, verificado contra+ el binario de la release. Vista release por release:+ [hitos](https://github.com/xerj-org/xerj/milestones); estado en vivo:+ [tablero del proyecto](https://github.com/users/xerj-org/projects/1); puntero fijo:+ [issue anclado de la hoja de ruta](https://github.com/xerj-org/xerj/issues/298)+- [Registro de cambios](./CHANGELOG.md)++Páginas de referencia de subsistemas concretos, escritas contra el fuente e incluyendo los+límites que cada uno no levanta:++- [Segundo cerebro](./docs/SECOND_BRAIN.md) para la capa de relaciones sobre documentos+ indexados: las rutas `/_graph`, la evidencia en los enlaces, los ocho detectores y el+ tope de dos saltos.+- [Lector de la consola](./docs/CONSOLE_READER.md) para el inicio de corpus de la consola,+ el lector de cualquier registro (un correo con sus adjuntos, una página de PDF) y el+ modo invitado de solo lectura, con las reglas de renderizado que mantienen inerte un+ documento hostil y lo que no renderiza.+- [Scripting](./docs/SCRIPTING.md) para el subconjunto de Painless, dónde corren los+ scripts y los límites de recursos que los acotan.+- [Instantánea y restauración](./docs/SNAPSHOT_AND_RESTORE.md) para el subconjunto+ admitido de la API de snapshots, y qué sustituye una restauración.+- [Compartir](./docs/SHARING.md) para `xerj share`: acceso de invitado de solo lectura a+ una carpeta indexada mediante un enlace y un código, qué puede y qué no puede alcanzar+ un invitado, y el modelo de amenazas.+- [Modelo de seguridad](./docs/SECURITY_MODEL.md) para la autenticación, el espacio de+ nombres reservado `.xerj-memory-*`, las claves de API y lo que no se exige.+- [Reordenación](./docs/RERANK.md) para la etapa de búsqueda `rerank` opcional: un juez+ externo reordena los primeros aciertos por una probabilidad calibrada. Es la única+ función en tiempo de búsqueda que envía texto de documentos fuera del nodo (los+ embeddings por proxy y la toma del WAL también envían texto cuando un operador los+ configura; la página lista cada conexión saliente que un nodo puede abrir), necesita+ una clave de proveedor configurada por el operador, y la calidad de su ordenación con+ el modelo real no está verificada.+- [XERJ frente a Lucene 10.3.1](./docs/XERJ_VS_LUCENE.md) para una comparación fijada al+ fuente, en seis ejes, de sus diseños de almacenamiento y búsqueda.++## Contribuir++Los pull requests son bienvenidos tanto de personas como de agentes de IA; véase+[Únete a la comunidad](#únete-a-la-comunidad) arriba. La contribución de base es un+informe de campo corto: un `gh pr create` normal que añada un archivo markdown bajo+[`user-feedback/16-agent-field-reports/`](./user-feedback/16-agent-field-reports).+Los PR que solo contienen un informe de campo están exentos del CLA, así que se fusionan+sin firma.++Para cambios de código, véase [CONTRIBUTING.md](./CONTRIBUTING.md) para el flujo de+trabajo y [CLA.md](./CLA.md) para el acuerdo de licencia de colaborador, que es una firma+por colaborador y no una por pull request. Los agentes que abran un PR deben decir que lo+escribió un agente y seguir [AGENTS.md](./AGENTS.md) /+[.github/AI_CONTRIBUTIONS.md](./.github/AI_CONTRIBUTIONS.md).++Los bugs y las peticiones de funcionalidad van a las [issues de GitHub](https://github.com/xerj-org/xerj/issues).++## Licencia++[Apache 2.0](./LICENSE).diff --git a/README.ja-JP.md b/README.ja-JP.mdindex 0058007d2..d217b373f 100644--- a/README.ja-JP.md+++ b/README.ja-JP.md@@ -2,7 +2,7 @@<a href="https://trendshift.io/repositories/116361?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-116361" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/116361" alt="xerj-org%2Fxerj | Trendshift" width="250" height="55"/></a>-[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md)+[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md) | [العربية](./README.ar.md) | [Español](./README.es.md)[](https://github.com/xerj-org/xerj/actions/workflows/ci.yml)[](https://github.com/xerj-org/xerj/releases)diff --git a/README.md b/README.mdindex ed8e303b0..1a9c6d696 100644--- a/README.md+++ b/README.md@@ -2,7 +2,7 @@<a href="https://trendshift.io/repositories/116361?utm_source=repository-badge&utm_medium=badge&utm_campaign=badge-repository-116361" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/116361" alt="xerj-org%2Fxerj | Trendshift" width="250" height="55"/></a>-[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md)+[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md) | [العربية](./README.ar.md) | [Español](./README.es.md)[](https://github.com/xerj-org/xerj/actions/workflows/ci.yml)[](https://github.com/xerj-org/xerj/releases)diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 64b3bb0d1..ec117130f 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -1,6 +1,6 @@# XERJ-[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md)+[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md) | [العربية](./README.ar.md) | [Español](./README.es.md)[](https://github.com/xerj-org/xerj/actions/workflows/ci.yml)[](https://github.com/xerj-org/xerj/releases)