MIRSAD

مِرصاد — MIRSAD

_{Live MCP tool calls against a fictional demo workspace — no real data.}

MIRSAD (مِرصاد) is a shared, living memory hub for AI agents — one local store that Claude, ChatGPT and any MCP client can all read and write. Bi-temporal facts (nothing is ever silently overwritten), decisions stored as first-class units with their reasons, evidence and outcomes, and cross-agent conflicts that only the owner resolves. It ships with a live graph view: open the local page and watch your agents' memory grow as a network while they work. Local-first · MCP-native · SQLite/D1 · no heavy infrastructure, no LLM needed in the write path.

Keywords: MCP server, AI agent memory, shared memory, temporal knowledge graph, decision log, Claude, ChatGPT, SQLite, local-first.

ذاكرة جماعية واحدة لكل مساعداتك. خادم ذاكرة مبني على رسم معرفي زمني (Temporal Knowledge Graph) يقرأ منه ويكتب فيه كل مساعداتك وأنت نفسك — عبر بروتوكول MCP نفسه — فلا يضيع قرار اتُّخذ مع مساعدٍ عن بقيّة المساعدين، ولا تُنسى أسبابه وأدلّته ونتائجه.

What is MIRSAD?

MIRSAD is an open-source shared memory server for AI agents, built on the Model Context Protocol (MCP). Instead of every assistant keeping its own private, forgetful memory, MIRSAD gives all of them one collective memory they can read and write: Claude, ChatGPT, or any MCP client.

Features

• Bi-temporal facts — facts carry validity time and recording time; updates invalidate, never delete, so you can ask "what was true then?"
• Decisions as first-class units — every decision is stored with its reasons, evidence, rejected alternatives, effects and outcomes, and can be traced with a single why query.
• Cross-agent conflict queue — when one agent overwrites another's fact, the latest value wins for queries but a conflict is opened for the owner's ruling. Nothing is silently lost.
• Live graph viewer — open the local page and watch the memory as a living network (entities, decisions, values, edges) while agents write; click any node to read its story.
• Arabic + English name resolution — normalization and entity aliases, so a fact stored as "MIRSAD" is found when an agent searches «مِرصاد».
• Zero LLM in the write path — deterministic storage on a single SQLite file; runs anywhere, even on a phone via Termux.

Official MCP Registry

mcp-name: io.github.amkkoussay/mersad

Install from PyPI: pip install mirsad-mcp — then point your MCP client at the mirsad-mcp command (stdio, with MIRSAD_TRANSPORT=stdio).

Quickstart

git clone https://github.com/amkkoussay/Mersad.git
cd Mersad
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
MIRSAD_DB=~/mirsad.db .venv/bin/python -m mirsad.mcp_server
# MCP endpoint: http://127.0.0.1:8765/mcp  ·  Live graph: http://127.0.0.1:8765/

Then add http://127.0.0.1:8765/mcp as a custom MCP connector in your assistant of choice, and it shares this memory with every other client.

لماذا وُجد؟ (ما وجدناه في مراجعة الأنظمة الكبرى)

راجعنا Graphiti وCognee وMem0 وLetta وgraph-agent-memory وMemori (التقارير في research/). الخلاصة: لا واحد منها يخزّن «القرار وسببه ودليله ونتيجته» كوحدة أولى جاهزة، وأغلبها يحتاج LLM مدفوعًا وقاعدة رسوم منفصلة لمجرّد الكتابة، وMem0 الحالي لا يحسم التناقضات أصلًا، وLetta يترك الذاكرة لقرار النموذج. مِرصاد يأخذ أفضل أفكارهم ويصلح أضعف نقاطهم:

الفكرة	من أين	كيف في مِرصاد
حقائق ثنائية الزمن (valid/recorded) تُبطَل ولا تُحذف	Graphiti	نفس النموذج، لكن بلا LLM في طريق الكتابة — الحسم حتمي بالكود
التعارضات سجلّات صريحة لا دمج صامت	Cognee (FactConflict)	أيّ كتابة من وكيل فوق حقيقة نشطة لوكيل آخر تفتح تعارضًا ينتظر قرارك
نسبة كل سجلّ لكاتبه	Mem0	source_agent على كل حقيقة وقرار
مرآة Markdown قابلة للمراجعة والنسخ عبر git	Letta / Basic Memory	export يولّد سجلًّا مقروءًا كاملًا
ذاكرة الاستدلال طبقة أولى	graph-agent-memory	القرار وحدة واحدة: قرار ← أسباب ← أدلّة ← بدائل مرفوضة ← ملفات متأثرة ← نتائج، مع سلسلة استبدال (supersedes)

والفرق العملي الأكبر: ملف SQLite واحد، صفر خدمات خارجية، صفر مفاتيح API — يعمل على أيّ جهاز، حتى هاتفك عبر Termux.

نموذج البيانات

• كيانات (Entities): أشخاص، مشاريع، ملفات، مفاهيم.
• حقائق (Facts): (كيان، علاقة، قيمة) مع أربعة أزمنة: متى صحّت في العالم، متى توقّفت، متى سُجّلت، متى أُبطلت — فيمكن السؤال: «ما الصحيح الآن؟» و«ما الذي كان صحيحًا وقتها؟».
• قرارات (Decisions): الوحدة الكاملة أعلاه، بحالات proposed/accepted/rejected/superseded.
• حلقات (Episodes): النصّ الخام المصدر لكل سجلّ — لا يُحذف أبدًا (الأصل/Provenance).
• تعارضات (Conflicts): خلافات بين الوكلاء تنتظر حكمك، وحكمك نفسه يُحفظ.

التشغيل

cd shared-memory-hub
python3 -m venv .venv && .venv/bin/pip install "mcp[cli]<2"

# خادم MCP عبر HTTP (للموصّلات) — المنفذ 8765 افتراضيًا
MIRSAD_DB=~/mirsad.db .venv/bin/python -m mirsad.mcp_server

# أو عبر سطر الأوامر
.venv/bin/python -m mirsad.cli --db ~/mirsad.db fact "Project" cache_backend Redis --agent agent-a
.venv/bin/python -m mirsad.cli --db ~/mirsad.db why Redis
.venv/bin/python -m mirsad.cli --db ~/mirsad.db export

الأدوات الإحدى عشرة عبر MCP: remember_fact، current_fact، timeline، record_decision، record_outcome، add_alias، why، recall، open_conflicts، resolve_conflict، memory_stats.

خريطة الذاكرة الحية (النسخة المحلية)

شغّل الخادم المحلي ثم افتح http://127.0.0.1:8765/ في المتصفح: شبكة حية لذاكرتك — الكيانات والقرارات والقيم عقدٌ، والحقائق والروابط روابط. تتحدث الخريطة لحظيًا بينما يكتب أي وكيل في الذاكرة (الكتابة الجديدة تنبض وتظهر في مكانها)، والضغط على أي عقدة يفتح قصتها: حقائقها الحالية، خطها الزمني، القرارات التي شاركت فيها ومَن كتب ماذا ومتى. التعارضات المفتوحة تُعلَّم بحلقة حمراء. كل ذلك محلي بالكامل — صفحة واحدة بلا أي اعتماديات خارجية، والمحرك يعرّض البيانات عبر GET /graph.

الاختبارات (قابلة للفشل فعليًا)

.venv/bin/python demo.py       # 23 فحصًا على المحرّك: قرارات، زمن، تعارض بين وكيلين، أسماء بديلة، استبدال
.venv/bin/python test_mcp.py   # خادم حقيقي + عميل MCP رسمي: كتابة من وكيل وقراءة من آخر
.venv/bin/python test_graph.py # 13 فحصًا على خريطة الذاكرة الحية: عقد وروابط وقصص وعدّاد تغييرات

توصيل التطبيقات — الحقيقة كما تحققنا منها (نوفمبر 2026)

• Claude (هاتف وويب): يدعم موصّلات MCP بعيدة على كل الخطط (المجانية: موصّل واحد) بأدوات قراءة وكتابة. أضف الخادم من claude.ai ← Settings ← Connectors، وسيعمل داخل محادثات الهاتف (الاتصال من سحابة Anthropic).
• ChatGPT: إضافة خادم مخصص من الويب فقط، ثم يعمل على الهاتف. لكن على الخطط الفردية (Pro) الصلاحية قراءة فقط — يقرأ الذاكرة المشتركة ولا يكتب فيها؛ الكتابة عبر MCP محفوظة لخطط Business/Enterprise/Edu. (Plus: غير مُتحقق منه بدقة من مصدر OpenAI.)
• شرط تقني لا مفرّ منه: الخادم يجب أن يكون على رابط HTTPS عام ليصل إليه التطبيقان (localhost لا يكفي). خيارات الاستضافة: نفق آمن (مثل Cloudflare Tunnel) من جهازك، أو خدمة سحابية مجانية، أو VPS رخيص — القرار والخطوة التالية عليك (تحتاج حسابك).
• تنبيهان صادقان: (1) الذاكرة عبر MCP «عند الطلب» — المساعد يستدعي الأدوات أثناء المحادثة حين يقرّر أو حين تطلب منه، ليست مرآة حيّة تلتقط كل شيء تلقائيًا. (2) هوية الكاتب (agent) في هذه النسخة يصرّح بها العميل نفسه؛ في نسخة الإنتاج يجب أن تأتي من تسجيل الدخول (OAuth) حتى لا ينتحل وكيلٌ اسم آخر.

خريطة الطريق

1. OAuth حقيقي للخادم (هوية موثّقة لكل مساعد/جهاز).
2. استيراد أرشيف محادثات ChatGPT (conversations.json) وClaude وتحويله لحلقات.
3. استخراج تلقائي اختياري بالـLLM لمن يريده — كطبقة فوق الكتابة اليدوية، لا بديلًا عنها.
4. بحث دلالي بالتضمينات بجانب البحث النصي والرسمي الحالي.