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 M8ven Score OpenSSF Best Practices

The OpenSSF badge is a best-practices self-attestation by the project, not a security certification or an independent audit.

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 challenges another's fact, the standing value stays current and the challenger waits as a pending candidate until the owner's ruling decides which value stands. Nothing is silently lost, and a machine's version never wins by arriving later.
  • 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.

How MIRSAD compares

MIRSAD's niche is not raw recall quality — it is auditability: who wrote a fact, when it was true, why a decision was taken, and who settled a disagreement. An honest side-by-side with the systems it is most often compared to:

MIRSAD Mem0 Graphiti (Zep's open engine) Official MCP memory server
Storage One SQLite file, local-first Vector store, optional graph add-on Neo4j or FalkorDB graph database A local JSON file
How memory is written Agents write facts and decisions explicitly through MCP tools — no LLM in the write path An LLM extracts facts from conversations, then decides ADD / UPDATE / DELETE / NOOP An LLM extracts entities and edges from raw episodes Agents write entities, relations and observations through tools
Facts over time Bi-temporal (validity + recording windows); superseded facts are invalidated, never deleted Memories are updated or deleted as the LLM decides; each memory keeps a change history Bi-temporal; contradicted edges are invalidated, never deleted Values are overwritten in place
When two sources disagree The conflict is queued for the owner to resolve — a machine's version never silently wins The LLM resolves it automatically at write time The newer fact wins automatically (LLM-checked) No conflict concept
Decisions First-class units: reason, evidence, rejected alternatives, effects, outcomes, supersede chains Not a built-in unit Not a built-in unit (can be modelled as nodes) Not a built-in unit
Recall Keyword full-text search + structural queries — no embeddings Embedding similarity (+ graph queries) Hybrid: embeddings, keyword and graph search Graph traversal over entities

Letta (formerly MemGPT) takes a different shape: it is an agent framework whose agents edit their own memory blocks, rather than a shared store that several independent agents write to.

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

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

المسار بصريًا — كل المكوّنات أعلاه جداول في ملف SQLite واحد:

flowchart LR
    A["AI agents<br/>Claude · ChatGPT · any MCP client"] -->|"remember_fact · record_decision"| S["MIRSAD MCP server<br/>13 tools"]
    S --> F[("Bi-temporal facts<br/>invalidated, never deleted")]
    S --> D[("Decision units<br/>reason · evidence · rejected alternatives · outcome")]
    S --> E[("Episodes<br/>raw provenance")]
    S -->|"another agent overwrites a fact"| Q["Conflict queue"]
    Q -->|"owner resolves"| S
    A -->|"recall · why · timeline"| S

التشغيل

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، subject_brief، 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.3.0

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

Built distribution (wheel)

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

Total release size: 76.1 kB

Release files / mirsad_mcp-0.3.0.tar.gz

Download URL mirsad_mcp-0.3.0.tar.gz
Size 40.4 kB
Tags Source
SHA-256 checksum
How to use checksums
1f1020f9f360c372f2e5d15a797eac7cbc29200a04516f011aa8fc9636dd29d0
BLAKE2b-256 checksum
How to use checksums
d5995055f21c9464031054d00b90e5bd801a577b95ce52782679983aaccb1b9a
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 18, 2026.

Transparency log

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

Download URL mirsad_mcp-0.3.0-py3-none-any.whl
Size 35.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4967e57301bb12d4d4c25d8254a78f389dd5608ba05f02d6ed20b09eb434a7a8
BLAKE2b-256 checksum
How to use checksums
5be47240eadf1bec137277a18a08bf1342c21e840096520830ce68234635e275
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 18, 2026.

Transparency log

Security for mirsad-mcp 0.3.0

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.3.0.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 18, 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