Skip to main content

مِرصاد — MIRSAD

MIRSAD — one memory for every AI agent

License: MIT Python 3.11+ Protocol: MCP Local-first PyPI Downloads MCP Registry Listed on mcpservers.org Release downloads

MIRSAD demo — an MCP client storing facts, recording a decision with its reasons, and resolving a cross-agent conflict (fictional demo data)

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. بحث دلالي بالتضمينات بجانب البحث النصي والرسمي الحالي.

Metadata

Release files for mirsad-mcp 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mirsad-mcp 0.2.2
File Size Uploaded Provenance Actions
mirsad_mcp-0.2.2.tar.gz 28.5 kB With provenance Details for mirsad_mcp-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mirsad-mcp 0.2.2
File Interpreter ABI Platform Actions
mirsad_mcp-0.2.2-py3-none-any.whl Python 3 none any Details for mirsad_mcp-0.2.2-py3-none-any.whl

Total release size: 53.3 kB

Release files / mirsad_mcp-0.2.2.tar.gz

Download URL mirsad_mcp-0.2.2.tar.gz
Size 28.5 kB
Tags Source
SHA-256 checksum
How to use checksums
9276bbbc63061a4f821fdd52b7920747d8efed80138ed864003d49ff76290811
BLAKE2b-256 checksum
How to use checksums
119e12ffb138f0674066a44b212bd3083061c3ffb937c53a4ceee7fa5dfb43ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / mirsad_mcp-0.2.2-py3-none-any.whl

Download URL mirsad_mcp-0.2.2-py3-none-any.whl
Size 24.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
346e58cd1056a99fddb7e89f3e06f4580c123c920c2b6e028f1f2376c5b8a9c1
BLAKE2b-256 checksum
How to use checksums
9ff424fb6f49ddf5a28b8fb526656982f40b73d2c067d7f94b7cfe2b7ea0aad0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for mirsad-mcp 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mirsad_mcp-0.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page