mirsad-mcp 0.2.0__tar.gz

mirsad_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koussay Mehdouani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mirsad_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: mirsad-mcp
+Version: 0.2.0
+Summary: A shared, living memory hub for AI agents - bi-temporal facts, first-class decisions, and owner-resolved conflicts, served over MCP. Local-first.
+Author: Koussay Mehdouani
+License: MIT
+Project-URL: Homepage, https://github.com/amkkoussay/Mersad
+Project-URL: Repository, https://github.com/amkkoussay/Mersad
+Keywords: mcp,model-context-protocol,ai-agents,ai-memory,knowledge-graph,sqlite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]<2
+Dynamic: license-file
+
+# مِرصاد — MIRSAD
+
+![MIRSAD — one memory for every AI agent](assets/banner.svg)
+
+![License: MIT](https://img.shields.io/badge/License-MIT-E8C268.svg)
+![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-8FC1F0.svg)
+![Protocol: MCP](https://img.shields.io/badge/Protocol-MCP-DBE7F5.svg)
+![Local-first](https://img.shields.io/badge/Local--first-yes-58D68A.svg)
+
+> **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.
+
+### Quickstart
+
+```bash
+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):** خلافات بين الوكلاء تنتظر حكمك، وحكمك نفسه يُحفظ.
+
+## التشغيل
+
+```bash
+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`.
+
+## الاختبارات (قابلة للفشل فعليًا)
+
+```bash
+.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. بحث دلالي بالتضمينات بجانب البحث النصي والرسمي الحالي.

mirsad_mcp-0.2.0/README.md

@@ -0,0 +1,132 @@
+# مِرصاد — MIRSAD
+
+![MIRSAD — one memory for every AI agent](assets/banner.svg)
+
+![License: MIT](https://img.shields.io/badge/License-MIT-E8C268.svg)
+![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-8FC1F0.svg)
+![Protocol: MCP](https://img.shields.io/badge/Protocol-MCP-DBE7F5.svg)
+![Local-first](https://img.shields.io/badge/Local--first-yes-58D68A.svg)
+
+> **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.
+
+### Quickstart
+
+```bash
+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):** خلافات بين الوكلاء تنتظر حكمك، وحكمك نفسه يُحفظ.
+
+## التشغيل
+
+```bash
+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`.
+
+## الاختبارات (قابلة للفشل فعليًا)
+
+```bash
+.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. بحث دلالي بالتضمينات بجانب البحث النصي والرسمي الحالي.

mirsad_mcp-0.2.0/mirsad/__init__.py

@@ -0,0 +1,8 @@
+"""MIRSAD (مِرصاد) — a shared temporal knowledge-graph memory for multiple AI agents.
+
+One memory hub that every MCP-capable assistant — and the user himself — can read and
+write through the same tools, so a decision made with one assistant is known —
+with its reasons, evidence and outcome — to all the others.
+"""
+
+__version__ = "0.1.0"

mirsad_mcp-0.2.0/mirsad/cli.py

@@ -0,0 +1,69 @@
+"""MIRSAD command line — the same operations the MCP tools expose.
+
+Examples:
+    python -m mirsad.cli --db ~/mirsad.db fact "Project X" uses_cache Redis --agent agent-a
+    python -m mirsad.cli --db ~/mirsad.db why Redis
+    python -m mirsad.cli --db ~/mirsad.db export > DECISIONS.md
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from .core import Mirsad
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="mirsad")
+    p.add_argument("--db", default="mirsad.db")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    f = sub.add_parser("fact")
+    f.add_argument("subject")
+    f.add_argument("predicate")
+    f.add_argument("value")
+    f.add_argument("--agent", default="user")
+
+    c = sub.add_parser("current")
+    c.add_argument("subject")
+    c.add_argument("predicate")
+
+    t = sub.add_parser("timeline")
+    t.add_argument("subject")
+
+    w = sub.add_parser("why")
+    w.add_argument("topic")
+
+    r = sub.add_parser("recall")
+    r.add_argument("query")
+
+    sub.add_parser("conflicts")
+    sub.add_parser("stats")
+    sub.add_parser("export")
+
+    args = p.parse_args()
+    m = Mirsad(args.db)
+
+    if args.cmd == "fact":
+        out = m.remember_fact(args.subject, args.predicate, args.value, source_agent=args.agent)
+    elif args.cmd == "current":
+        out = m.current_fact(args.subject, args.predicate)
+    elif args.cmd == "timeline":
+        out = m.timeline(args.subject)
+    elif args.cmd == "why":
+        out = m.why(args.topic)
+    elif args.cmd == "recall":
+        out = m.recall(args.query)
+    elif args.cmd == "conflicts":
+        out = m.open_conflicts()
+    elif args.cmd == "stats":
+        out = m.stats()
+    elif args.cmd == "export":
+        print(m.export_markdown())
+        return
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()