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.

One project, three labels: the product is MIRSAD (مِرصاد); the GitHub repository is Mersad; the PyPI package and its command are mirsad-mcp (Python import: mirsad). All three names refer to this same project.

ذاكرة جماعية واحدة لكل مساعداتك. خادم ذاكرة مبني على رسم معرفي زمني (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 by default; set MIRSAD_TRANSPORT=streamable-http to serve HTTP instead).

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. الخلاصة: لا واحد منها يخزّن «القرار وسببه ودليله ونتيجته» كوحدة أولى جاهزة، وأغلبها يحتاج 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 Mersad
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، version_info.

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

شغّل الخادم المحلي ثم افتح 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.7

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.7
File Size Uploaded Provenance Actions
mirsad_mcp-0.2.7.tar.gz 34.1 kB With provenance Details for mirsad_mcp-0.2.7.tar.gz

Built distribution (wheel)

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

Total release size: 64.7 kB

Release files / mirsad_mcp-0.2.7.tar.gz

Download URL mirsad_mcp-0.2.7.tar.gz
Size 34.1 kB
Tags Source
SHA-256 checksum
How to use checksums
f9f7b576df2ba706b6be4b0822ba3947830ffcea0003186d897362a27aa8fb71
BLAKE2b-256 checksum
How to use checksums
e1f7d97989b9a0906a3ae35106665bd52cb1809936eb595975d1eaccff7133ef
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 17, 2026.

Transparency log

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

Download URL mirsad_mcp-0.2.7-py3-none-any.whl
Size 30.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6e384b0d02a069931abd943c963d8f1e8c1a686d081c19cf63c5cb7df0b4810c
BLAKE2b-256 checksum
How to use checksums
b270c23ffacd0aba48905e2972444a48f198fd7553418bf306011a0ccbc1c040
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 17, 2026.

Transparency log

Security for mirsad-mcp 0.2.7

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.7.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 17, 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