+
+---
+
+## Magic Context چیست؟
+
+برای رفع یک باگ، برنامه‌نویس استخدام نمی‌کنی و درست بعد از تحویل راه‌حل اخراجش کنی. آدم‌های خوب را نگه می‌داری. آن‌ها کدبیس را یاد می‌گیرند، دلیل تصمیم‌ها را به خاطر می‌سپارند و هر هفته کاربلدتر می‌شوند.
+
+عامل‌های برنامه‌نویس وضع معکوسی دارند. هر کار مثل استخدام فردی تازه است که چیزی از پروژه‌ات نمی‌داند؛ پایان هر نشست هم او را کنار می‌گذاری و از صفر شروع می‌کنی. وسط کار حتی با مکث‌های «فشرده‌سازی» (compaction) روبه‌رو می‌شوند؛ مکث‌هایی که جریان کار را می‌شکنند و بی‌سروصدا دانسته‌های عامل را از بین می‌برند. این همان فراموشی پیش‌رونده‌ای است که با آسیب‌دیدن هیپوکامپ رخ می‌دهد.
+
+Magic Context برای عامل‌ها هیپوکامپی فراهم می‌کند. این ابزار **هیپوکامپِ** عامل‌های برنامه‌نویس است: بخشی از مغز که خاطره‌ها را شکل می‌دهد، تثبیت می‌کند و به یاد می‌آورد؛ و همهٔ این کارها را در پس‌زمینه انجام می‌دهد. هر نشست از پیمانکاری موقت به هم‌تیمی‌ای بلندمدت تبدیل می‌شود که از آغاز تا پایان پروژه همراهت بوده است:
+
+- **ثبت دانش.** وقتی عامل تاریخ‌نگار (historian) تاریخچه را خلاصه می‌کند، دانسته‌های ماندگار (تصمیم‌ها، محدودیت‌ها و قراردادها) را جدا می‌کند و در حافظهٔ پروژه می‌گذارد. از کاری که همین حالا انجام می‌دهی، بی‌هزینه یک سامانهٔ حافظه به دست می‌آوری.
+- **تثبیت حافظه.** شب‌ها عامل‌های رؤیاپرداز (dreamer) کاری را انجام می‌دهند که خواب برای تو می‌کند: خاطره‌ها را با کدبیس می‌سنجند، موارد تکراری و منسوخ را سامان می‌دهند و دانسته‌های پرتکرار را ارتقا می‌دهند.
+- **بازیابی.** در هر نوبت، خاطره‌های مناسب خودکار ظاهر می‌شوند و عامل می‌تواند هر زمان که بخواهد میان خاطره‌ها، گفت‌وگوهای پیشین و تاریخچهٔ git جست‌وجو کند؛ در نشست‌های مختلف و در OpenCode، Pi و OMP.
+
+دو وعده: عاملت **برای مدیریت زمینه از کار نمی‌ایستد** (نه مکث فشرده‌سازی دارد و نه جریان کارش می‌شکند) و **هیچ‌وقت فراموش نمی‌کند**.
+
+برای هر پروژه یک نشست راه بینداز و هفته‌ها، ماه‌ها یا سال‌ها ادامه‌اش بده. عامل همه‌چیزهایی را که با هم ساخته‌اید به خاطر می‌سپارد.
+
+---
+
+## شروع سریع
+
+```bash
+npx @cortexkit/magic-context@latest setup
+```
+
+ابزار تنظیم به‌طور خودکار محیط‌های اجرایی نصب‌شده‌ات (OpenCode، Pi، OMP یا هر ترکیبی از آن‌ها) را پیدا و پیکربندی می‌کند: افزونه را ثبت می‌کند، فشرده‌سازی داخلی میزبان را خاموش می‌کند، برای عامل‌های تاریخ‌نگار و رؤیاپرداز در انتخاب مدل کمک می‌کند و ناسازگاری با افزونه‌های دیگر مدیریت زمینه را برطرف می‌کند. پس از آن محیط اجرا را دوباره راه‌اندازی کن تا Magic Context بارگذاری شود. برای انتخاب یک محیط مشخص از `--harness opencode`، `--harness pi` یا `--harness omp` استفاده کن.
+
+> **چرا فشرده‌سازی داخلی را خاموش کنیم؟** Magic Context خودش زمینه را مدیریت می‌کند. فشرده‌سازی میزبان با عملیاتِ به‌تعویق‌افتاده و آگاه از کش تداخل می‌کند و تاریخچه را دوبار فشرده می‌سازد.
+
+### تنظیم دستی (OpenCode)
+
+اگر نمی‌توانی راهنمای تنظیم را اجرا کنی، این را به `opencode.jsonc` اضافه کن:
+
+```jsonc
+{
+ "plugin": ["@cortexkit/opencode-magic-context@latest"],
+ "compaction": { "auto": false, "prune": false }
+}
+```
+
+> **به‌روزرسانی افزونه:** پیش از راه‌اندازی مجدد، ورودی سادهٔ افزونه به نسخهٔ دقیق دانلودشده سنجاق می‌شود تا OpenCode بستهٔ فعال را وسط نشست حذف نکند. Magic Context مشخصات دقیقی را که به‌روزرسان تنظیمات نوشته ثبت می‌کند و در بررسی‌های بعدی همان نسخهٔ تحت مدیریت به‌روزرسان را جلو می‌برد. هر مشخصات دقیق دیگری که خودت تعیین کرده باشی ثابت می‌ماند. چون منشأ تنظیم با رشتهٔ دقیق مشخصات سنجیده می‌شود، اگر دستی همان رشته‌ای را وارد کنی که به‌روزرسان آخرین بار نوشته، تشخیص آن از نسخهٔ سنجاق‌شدهٔ به‌روزرسان ممکن نیست و نسخه در بررسی بعدی جلو می‌رود. برای انصراف، `auto_update: false` بگذار یا نسخهٔ دقیق دیگری را سنجاق کن. برای استفادهٔ عمدی از نسخهٔ شناور، `@latest` را صریح بنویس (OpenCode ممکن است بستهٔ فعالِ بدون نسخهٔ سنجاق‌شده را وسط نشست حذف کند).
+
+سپس `magic-context.jsonc` را با تنظیم عامل تاریخ‌نگار OpenCode بساز:
+
+```jsonc
+{
+ "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
+ "historian": {
+ "opencode": { "model": "provider/model-id" }
+ }
+}
+```
+
+- **الزامی:** `historian.opencode.model` باید یک شناسهٔ واقعی به‌شکل `provider/model-id` باشد. اگر نباشد، افزونه بارگذاری می‌شود اما اجرای تاریخ‌نگار شکست می‌خورد، تاریخچهٔ قدیمی خلاصه نمی‌شود و پس از خطاهای تکراری پیام `Magic Context — history comparting needs attention` نمایش داده می‌شود.
+- **اختیاری:** بلوک مدل/غیرفعال‌سازی `dreamer`. اگر نمی‌خواهی تثبیت دوره‌ای حافظه انجام شود، آن را حذف کن.
+- **اختیاری:** `embedding`. اگر حذفش کنی از مدل محلی `Xenova/all-MiniLM-L6-v2` استفاده می‌شود. خاموش‌کردن embedding جست‌وجوی معنایی یا مبتنی بر بردارسازی را غیرفعال می‌کند؛ جست‌وجوی واژه‌ای و مدیریت زمینه همچنان کار می‌کنند.
+
+### مهاجرت از تنظیمات مسطح مدل (پیش و پس از مهاجرت)
+
+تنظیمات مسطح مدل در نخستین بار خواندن پیکربندی به‌طور خودکار مهاجرت می‌شوند. شکل
+مسطح زیر فقط نمونهٔ «پیش از مهاجرت» است؛ برای همهٔ تنظیمات جدید، شکل
+جداگانهٔ هر محیط اجرا را به کار ببر.
+
+**پیش از مهاجرت (ساختار مسطح؛ فقط برای مهاجرت):**
+
+```jsonc
+{
+ "historian": {
+ "model": "provider/model-id",
+ "thinking_level": "medium"
+ }
+}
+```
+
+**پس از مهاجرت (ساختار جداگانه برای هر محیط اجرا):**
+
+```jsonc
+{
+ "historian": {
+ "opencode": { "model": "provider/model-id" },
+ "pi": {
+ "model": "provider/model-id",
+ "thinking_level": "medium"
+ },
+ "omp": {
+ "model": "opencode/provider-model-id",
+ "thinking_level": "auto"
+ }
+ }
+}
+```
+
+OMP از مقادیر `thinking_level` بومی Pi استفاده می‌کند. اگر `historian.omp` یا `dreamer.omp` وجود نداشته باشد، OMP از بلوک متناظر `pi` استفاده می‌کند؛ بنابراین تنظیمات سازگار با Pi به مهاجرت نیاز ندارند. اگر بلوک OMP را صریحاً تعریف کنی، همان ملاک است، حتی اگر در آن مدلی ننوشته باشی.
+
+تنظیمات کاربر در macOS/Linux اینجاست: `~/.config/cortexkit/magic-context.jsonc` و در Windows اینجاست: `%USERPROFILE%\.config\cortexkit\magic-context.jsonc` (یا اگر تنظیم شده باشد، `$XDG_CONFIG_HOME/cortexkit/magic-context.jsonc`). کاربران OpenCode Desktop می‌توانند از ویرایشگر تنظیمات داشبورد استفاده کنند یا فایل را دستی ویرایش کنند؛ نسخهٔ Desktop راهنمای تنظیم خط فرمان را ندارد.
+
+**Pi:** `npx @cortexkit/magic-context@latest setup --harness pi` (نیازمند Pi `>= 0.74.0`). افزونهٔ Pi همان پایگاه دادهٔ OpenCode را به‌کار می‌برد؛ خاطره‌ها و embeddingهای پروژه در هر دو محیط مشترک‌اند.
+
+**Oh My Pi (OMP):** `npx @cortexkit/magic-context@latest setup --harness omp` (نیازمند OMP `>= 17.1.7`). فرایند تنظیم افزونهٔ سازگار با Pi را از راه `omp plugin` نصب می‌کند، فشرده‌سازی بومی و حافظهٔ خودکار OMP را خاموش می‌کند و به پروفایل‌های OMP، `PI_CODING_AGENT_DIR` و ساختارهای ازپیش‌آمادهٔ XDG احترام می‌گذارد.
+
+**عیب‌یابی:** `npx @cortexkit/magic-context@latest doctor` محیط‌های اجرایی را خودکار پیدا می‌کند، ناسازگاری‌های ویژهٔ هر میزبان را بررسی می‌کند، ثبت افزونه و یکپارچگی پایگاه داده را می‌سنجد و هرچه بتواند برطرف می‌کند. برای ساخت گزارش آمادهٔ ارسال، `--issue` را اضافه کن.
+
+در پروژه‌ای تازه یا پروژه‌ای که مدت‌ها در جریان بوده یکسان کار می‌کند: نصب کن، محیط اجرا را دوباره راه‌اندازی کن و Magic Context از همان لحظه شروع به ثبت زمینه می‌کند. نشست‌های OpenCode، Pi یا OMP پیش از نصب را به‌صورت عطف‌به‌ماسبق وارد حافظه نمی‌کند.
+
+
+Compatibility with other context-management plugins
+
+
+
+Magic Context مدیریت زمینه را از ابتدا تا انتها به‌عهده می‌گیرد؛ اگر افزونهٔ دیگری همین کار را انجام دهد، **خودش را غیرفعال می‌کند**. اجرای هم‌زمان دو مدیر زمینه تاریخچه را دوبار فشرده می‌کند و کش پرامپت را به‌هم می‌زند. هنگام راه‌اندازی موارد زیر را بررسی می‌کند. ابزار تنظیم و `doctor` برای رفع هر مورد کمک می‌کنند؛ تا زمان رفع آن‌ها، Magic Context برای ایمنی خاموش می‌ماند و دلیلش را نشان می‌دهد:
+
+- **فشرده‌سازی داخلی OpenCode** (`compaction.auto` / `compaction.prune`) — Magic Context جای آن را می‌گیرد و ابزار تنظیم خاموشش می‌کند.
+- **فشرده‌سازی بومی OMP** (`compaction.enabled`) — Magic Context جای آن را می‌گیرد و تنظیم OMP آن را به‌شکل تراکنشی خاموش می‌کند.
+- **حافظهٔ خودکار OMP** (`memory.backend`) — تزریق‌کنندهٔ حافظهٔ دوم، بازیابی و نگهداشت را تکراری می‌کند. تنظیم OMP آن را روی `off` می‌گذارد؛ داده‌های موجود حذف نمی‌شوند.
+- **DCP** (`opencode-dcp`) — افزونه‌ای جداگانه برای هرس زمینه است. این دو با هم اجرا نمی‌شوند؛ آن را از فهرست `plugin` حذف کن.
+- **oh-my-opencode (OMO)** — فرایند تنظیم پیشنهاد می‌دهد سه hook هم‌پوشان را خاموش کنی:
+ - `preemptive-compaction` — فشرده‌سازی‌ای را آغاز می‌کند که با عامل تاریخ‌نگار تداخل دارد.
+ - `context-window-monitor` — هشدارهای مصرف زمینه را تزریق می‌کند و با یادآوری‌های Magic Context هم‌پوشانی دارد.
+ - `anthropic-context-window-limit-recovery` — فشرده‌سازی اضطراری‌ای را اجرا می‌کند که عامل تاریخ‌نگار را دور می‌زند.
+
+هر زمان خواستی `npx @cortexkit/magic-context@latest doctor` را اجرا کن تا دوباره بررسی و اصلاح خودکار انجام شود.
+
+
+
+---
+
+## بخشی از CortexKit
+
+مغز از یک اندام تشکیل نشده است؛ عامل برنامه‌نویس توانمند هم همین‌طور.
+
+**CortexKit** خانواده‌ای از افزونه‌هاست که هرکدام از ناحیه‌ای متفاوت در مغز الهام گرفته‌اند. یکی را نصب کن تا عاملت کاربلدتر شود؛ هر سه را نصب کن تا مغزی کامل داشته باشد.
+
+| افزونه | ناحیهٔ مغز | کارکرد |
+|---|---|---|
+| **Magic Context** *(همین‌جا هستی)* | هیپوکامپ و لوب گیجگاهی میانی | مدیریت خودکار زمینه و حافظهٔ بلندمدت. نشست‌ها را بی‌وقفه ادامه می‌دهد و دانسته‌های پروژه را در آن‌ها شکل می‌دهد، تثبیت می‌کند و به یاد می‌آورد. |
+| **[AFT](https://github.com/cortexkit/aft)** | قشر حسی‌ـ‌حرکتی | ساختار کد را می‌فهمد و دقیق روی آن عمل می‌کند؛ یک IDE و سیستم‌عامل واقعی برای عامل تو. |
+| **Alfonso** *(به‌زودی)* | قشر پیش‌پیشانی | کنترل اجرایی: کار را برنامه‌ریزی و خرد می‌کند، عامل‌ها و مدل‌ها را برمی‌گزیند و تصمیم می‌گیرد چه زمانی سؤال کند، بررسی کند و commit بزند. |
+
+Magic Context یکی از **سه افزونه‌ای است که به آن‌ها نیاز داری**. Magic Context به یاد می‌سپارد؛ AFT می‌بیند و عمل می‌کند؛ Alfonso تصمیم می‌گیرد. هر سه از یک مخزن CortexKit استفاده می‌کنند، پس حافظه میان محیط‌های اجرا و ابزارها مشترک است.
+
+---
+
+## ⚡ مدیریت زمینه
+
+*نشستی بی‌کران که خودش را اداره می‌کند.* هنگام کار، پنجرهٔ زمینه پر می‌شود و راه‌حل معمول، یعنی فشرده‌سازی، عامل را از حرکت می‌اندازد تا همه‌چیز را دوباره بخواند. Magic Context این کار را پیوسته در پس‌زمینه انجام می‌دهد و نشست بدون توقف ادامه پیدا می‌کند.
+
+- **بخش‌بندی تاریخچه با عامل تاریخ‌نگار**: عامل `historian` در پس‌زمینه تاریخچهٔ خام قدیمی را به **محفظه‌های چندسطحی** تبدیل می‌کند؛ خلاصه‌هایی زمان‌مند که جای پیام‌های قدیمی را می‌گیرند. برای هر محفظه امتیاز اهمیت نگه می‌دارد تا پنجرهٔ زنده کوچک بماند و رشتهٔ بحث از دست نرود. خلاصه‌سازی به توان کدنویسی عامل اصلی نیاز ندارد؛ بنابراین می‌توانی تاریخ‌نگار را با مدلی ارزان یا کاملاً محلی اجرا کنی و عامل اصلی را روی بهترین مدل نگه داری.
+- **نمایش با افت تدریجی جزئیات**: محفظه‌ها با دقت مناسب همان لحظه نمایش داده می‌شوند؛ قاعده‌ای قطعی و بدون LLM که خود را با پنجرهٔ زمینهٔ مدل تنظیم می‌کند. تاریخچهٔ قدیمی به‌آرامی کم‌رنگ می‌شود، نه اینکه ناگهان ناپدید شود. چون قاعده قطعی است، یک تاریخچه همیشه به‌شکل یکسان نمایش داده می‌شود.
+- **عامل خودش پیشنهاد می‌دهد چه چیزی حذف شود، یا اصلاً دخالت نمی‌کند**: وقتی کاهش زمینه با هدایت عامل فعال باشد، عامل `ctx_reduce` را فراخوانی می‌کند تا خروجی ابزارهای منسوخ یا پیام‌های بلند را برای حذف علامت‌گذاری کند. حذف‌ها **در صف قرار می‌گیرند و کش را در نظر می‌گیرند**؛ فقط در زمان‌های امن برای کش اعمال می‌شوند تا به آن آسیب نزنند. اگر این قابلیت را خاموش کنی، عامل اصلاً مدیریت زمینه نمی‌کند: خروجی قدیمی با گذشت زمان خودکار کنار می‌رود و فشرده‌سازی تلگرافی اختیاری متن‌های قدیمی‌تر را کوتاه می‌کند.
+- **چیدمان پایدار برای کش**: کارهای پس‌زمینه طوری ساختاربندی شده‌اند که پیشوند ذخیره‌شدهٔ پرامپت را بی‌اعتبار نکنند. کش تا پایان نشست باقی می‌ماند.
+
+نتیجه: یک نشست ماه‌ها ادامه می‌یابد، بدون مکث‌های فشرده‌سازی و با هزینهٔ کم نزد ارائه‌دهندگانی که برای کش قیمت‌گذاری می‌کنند. در TUIِ OpenCode می‌توانی روند را ببینی: نوار کناری زنده، زمینه را بر پایهٔ منبع تفکیک می‌کند، وضعیت عامل تاریخ‌نگار و شمار خاطره‌ها را نشان می‌دهد و پس از هر پیام به‌روز می‌شود.
+
+> *اختیاری (به‌طور پیش‌فرض خاموش):* **فشرده‌سازی تلگرافی متن** با قاعده‌ای قطعی و چندسطحی، متن‌های قدیمی کاربر و دستیار را به‌تدریج کوتاه می‌کند؛ برای نشست‌هایی که کاهش زمینه با هدایت عامل در آن‌ها خاموش است.
+
+---
+
+## 🧠 ثبت دانش
+
+*حافظه، بی‌هزینه.* عامل تاریخ‌نگار برای فشرده‌کردن تاریخچه باید همهٔ آن را بخواند. پس در همان گذر، دانسته‌هایی را که باید برای همیشه بمانند—تصمیم‌ها، محدودیت‌ها، قراردادها و مقادیر پیکربندی—بیرون می‌کشد و به **حافظهٔ پروژه** می‌افزاید؛ حافظه‌ای دسته‌بندی‌شده که در همهٔ نشست‌های بعدی همراهت می‌آید. حافظه از کاری که همین حالا انجام می‌دهی ساخته می‌شود.
+
+عامل می‌تواند خاطره‌ها را صریحاً هم ثبت کند، هرچند بیشترشان به‌طور خودکار ذخیره می‌شوند:
+
+- **`ctx_memory`**: دانسته‌های ماندگار میان نشست‌ها را مستقیماً بنویس یا حذف کن؛ دسته‌بندی‌ها محدود و مشخص‌اند (`PROJECT_RULES`, `ARCHITECTURE`, `CONSTRAINTS`, `CONFIG_VALUES`, `NAMING`).
+
+```
+ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for orders.")
+```
+
+> **آگاهی از زمان** *(به‌طور پیش‌فرض روشن)* حس زمان را به عامل می‌دهد: فاصله‌هایی مانند `+2h 15m` میان پیام‌ها و محفظه‌های تاریخ‌دار کمک می‌کنند عامل بفهمد یک رویداد چه‌قدر پیش رخ داده است. برای خاموش‌کردن آن، `temporal_awareness: false` بگذار.
+
+---
+
+## 🌙 تثبیت حافظه
+
+*کاری که خواب برای حافظه می‌کند.* عامل **dreamer** اختیاری شب‌ها اجرا می‌شود تا کیفیت حافظه را بالا نگه دارد و برای هر کار نشست فرزندِ موقتی می‌سازد:
+
+- **نقشه‌برداری از خاطره‌ها**: هر خاطره را به فایل‌های پروژه‌ای که پشتیبان آن‌اند پیوند می‌دهد (یا مستقل از فایل علامت می‌زند) تا عامل بررسی بداند چه چیزی را دوباره بسنجد. این کار معمولاً فقط یک بار برای پرکردن داده‌های پیشین انجام می‌شود.
+- **بررسی**: خاطره‌ها را به‌تدریج با کدبیس فعلی (مسیرها، تنظیمات و الگوها) می‌سنجد و واقعیت‌های منسوخ را اصلاح یا حذف می‌کند.
+- **بررسی گسترده**: همهٔ خاطره‌های نگاشت‌شده به فایل را، بدون توجه به دروازهٔ تغییرات، دوباره با کد می‌سنجد تا تغییرات تدریجی‌ای را هم بیابد که بررسی مرحله‌ای از دست می‌دهد.
+- **سامان‌دهی**: کل مخزن خاطره‌ها را می‌کاود تا موارد تکراری را ادغام کند، عبارت‌ها را دقیق‌تر کند و موارد کم‌ارزش یا زائد را بایگانی کند.
+- **دسته‌بندی**: اهمیت، دامنه و امکان اشتراک‌گذاری امن هر خاطره را امتیازدهی می‌کند، بی‌آنکه کش زندهٔ پرامپت را مختل کند.
+- **بازنگری**: از موقعیت‌هایی که مجبور شدی چیزی را اصلاح یا دوباره توضیح دهی درس می‌گیرد و نکتهٔ ماندگار را ثبت می‌کند.
+- **به‌روزرسانی مستندات**: فایل‌های `ARCHITECTURE.md` و `STRUCTURE.md` را بر پایهٔ تغییرات کدبیس به‌روز نگه می‌دارد.
+- **خاطره‌های کاربر**: مشاهده‌های تکرارشونده دربارهٔ شیوهٔ کارت (سبک ارتباط، تمرکز هنگام بازبینی و الگوهای کاری) را در `` ثبت می‌کند تا در هر نشست همراهت باشند.
+- **ارتقای راهنماها**: پرسش‌های تکراری و همیشگی‌ای را که عامل تاریخ‌نگار دیده به راهنماهای ماندگار تبدیل می‌کند.
+- **نوسازی راهنماها**: موضوع راهنماهای منسوخ را با کد فعلی دوباره بررسی و پاسخ‌هایشان را تازه می‌کند.
+- **یادداشت‌های هوشمند**: یادداشت‌های معوقی را که شرط `surface_condition` آن‌ها برقرار شده ارزیابی می‌کند و موارد آماده را نمایش می‌دهد.
+
+از آنجا که عامل رؤیاپرداز هنگام بی‌کاری اجرا می‌شود، مدل‌های محلی—حتی مدل‌های کند—برای آن مناسب‌اند؛ کسی منتظر نمی‌ماند. هر زمان خواستی با `/ctx-dream` اجرايش کن.
+
+---
+
+## 🔎 بازیابی
+
+*خاطرهٔ درست، در زمان درست.* در هر نوبت، خاطره‌های فعال پروژه و تاریخچهٔ فشرده‌شدهٔ نشست، خودکار و با حفظ پایداری کش به پرامپت افزوده می‌شوند. عامل در صورت نیاز می‌تواند سراغ این ابزارها برود:
+
+- **`ctx_search`**: با یک پرس‌وجو در **خاطره‌های** پروژه، تاریخچهٔ خام **گفت‌وگوها**، **commitهای git** فهرست‌شده، **یادداشت‌های کنارگذاشته‌شده** و **راهنماهای ارتقایافته** جست‌وجو می‌کند. از embedding معنایی و در صورت نیاز جست‌وجوی تمام‌متن استفاده می‌شود.
+
+ ```
+ ctx_search(query="why did we pick event sourcing for orders")
+ ```
+
+- **`ctx_expand`**: وقتی عامل به جزئیات دقیق نیاز دارد، یک بازه از تاریخچهٔ فشرده را به رونوشت اصلی `U:`/`A:` برمی‌گرداند.
+- **`ctx_note`**: دفترچه‌ای برای نیت‌های معوق. یادداشت‌ها در زمان‌های طبیعی دوباره ظاهر می‌شوند (پس از commitها، اجرای عامل تاریخ‌نگار یا پایان کارهای فهرست‌شده). **یادداشت‌های هوشمند** شرطی باز دارند که عامل رؤیاپرداز پیگیر آن است.
+
+بازیابی هم **میان نشست‌ها** کار می‌کند (نشست تازه همه‌چیز را به ارث می‌برد) و هم **میان محیط‌های اجرا** (خاطره‌ای را در OpenCode بنویس و در Pi یا OMP بازیابی کن).
+
+> **راهنمای جست‌وجوی خودکار** *(به‌طور پیش‌فرض روشن)* در هر نوبت، `ctx_search` را در پس‌زمینه اجرا می‌کند و اگر مورد مرتبطی باشد با اشاره‌ای مبهم آن را به یاد عامل می‌آورد؛ مثل وقتی که یادداشتی را که نوشته‌ای کم‌وبیش به خاطر می‌آوری. فقط تکه‌های فشرده افزوده می‌شوند، نه محتوای کامل. برای خاموش‌کردن آن `memory.auto_search.enabled: false` بگذار. **فهرست‌سازی commitهای git** *(اختیاری)* تاریخچهٔ پروژه را به منبعی معنایی و اضافه برای `ctx_search` تبدیل می‌کند؛ با `memory.git_commit_indexing.enabled: true` روشنش کن.
+
+### ابزارهای عامل در یک نگاه
+
+| ابزار | بخش | کارکرد |
+|------|-------|-------------|
+| `ctx_reduce` | زمینه | محتوای قدیمیِ برچسب‌خورده را برای حذف در صف می‌گذارد و کش را در نظر می‌گیرد |
+| `ctx_memory` | ثبت دانش | خاطره‌های ماندگار میان نشست‌ها را می‌نویسد یا حذف می‌کند |
+| `ctx_search` | بازیابی | در خاطره‌ها، تاریخچهٔ گفت‌وگو، commitهای git، یادداشت‌ها و راهنماها جست‌وجو می‌کند |
+| `ctx_expand` | بازیابی | یک بازه از تاریخچه را به رونوشت اصلی برمی‌گرداند |
+| `ctx_note` | بازیابی | نیت‌های معوق و یادداشت‌های هوشمندی که عامل رؤیاپرداز ارزیابی می‌کند |
+
+---
+
+## فرمان‌ها
+
+| فرمان | توضیح |
+|---------|-------------|
+| `/ctx-status` | نمای عیب‌یابی: برچسب‌ها، حذف‌های در صف، زمان‌ماندگاری کش، وضعیت یادآوری، پیشرفت عامل تاریخ‌نگار، پوشش محفظه‌ها و بودجهٔ تاریخچه |
+| `/ctx-flush` | همهٔ عملیات در صف را بی‌درنگ اجرا می‌کند و از زمان‌ماندگاری کش عبور می‌کند |
+| `/ctx-recomp` | محفظه‌ها را از تاریخچهٔ خام دوباره می‌سازد (بازهٔ `start-end` می‌پذیرد). اگر وضعیت ذخیره‌شده نادرست به‌نظر می‌رسد از آن استفاده کن |
+| `/ctx-wrapup [messages_to_keep]` | تاریخچهٔ زندهٔ قدیمی را فشرده می‌کند و N پیام تازه را خام نگه می‌دارد؛ فشرده‌سازیِ در صف با پیام بعدی مدل نهایی می‌شود |
+| `/ctx-dream` | نگهداشت عامل رؤیاپرداز را به‌درخواست اجرا می‌کند: بازبینی حافظه، مستندات، یادداشت‌های هوشمند و نمایهٔ کاربر |
+| `/ctx-embed` | وضعیت embedding را نشان می‌دهد یا embedding محفظه‌های تاریخچه را آغاز/متوقف می‌کند (`start` | `pause`) |
+
+---
+
+## برنامهٔ دسکتاپ
+
+یک برنامهٔ دسکتاپ مکمل برای مرور و مدیریت وضعیت Magic Context بیرون از محیط خط فرمان.
+
+
+
+- **مرورگر خاطره‌ها**: خاطره‌های پروژه را بر پایهٔ دسته و پروژه جست‌وجو، فیلتر و ویرایش کن.
+- **تاریخچهٔ نشست**: محفظه‌ها و یادداشت‌های هر نشست را با پیمایش زمانی مرور کن.
+- **عیب‌یابی کش**: خط زمانی زندهٔ برخورد/عدم‌برخورد کش و تشخیص علت بی‌اعتبارشدن آن.
+- **مدیریت عامل رؤیاپرداز**: تاریخچهٔ اجراهای عامل را ببین، اجرا را آغاز کن و نتیجهٔ کارها را بررسی کن.
+- **ویرایشگر تنظیمات**: همهٔ تنظیمات را با فرم ویرایش کن، از جمله زنجیره‌های جایگزین مدل.
+- **نمایشگر گزارش‌ها**: گزارش‌ها را هم‌زمان با ثبت‌شدن ببین و در آن‌ها جست‌وجو کن.
+
+این برنامه مستقیماً پایگاه دادهٔ SQLite مربوط به Magic Context را می‌خواند؛ به سرور یا API اضافی نیاز ندارد و به‌روزرسانی خودکار در آن تعبیه شده است.
+
+---
+
+## پیکربندی
+
+تنظیمات در `magic-context.jsonc` قرار دارند. بیشترشان پیش‌فرض‌های مناسبی دارند، اما مدل عامل تاریخ‌نگارِ محیط اجرایی فعال (`historian.opencode.model`، `historian.pi.model` یا `historian.omp.model`) برای فشرده‌سازی تاریخچه ضروری است. تنظیمات پروژه روی تنظیمات سراسری کاربر اعمال می‌شوند. برای مرجع کامل—از تنظیم زمان‌ماندگاری کش و آستانه‌های اجرا برای هر مدل تا انتخاب مدل‌های تاریخ‌نگار و رؤیاپرداز، ارائه‌دهندگان embedding، تنظیمات حافظه و پیش‌تنظیم‌های سطح پرامپت (`full`/`light`)—به **[CONFIGURATION.md](../../CONFIGURATION.md)** یا **[مرجع پیکربندی در docs.cortexkit.io](https://docs.cortexkit.io/magic-context/reference/configuration/)** مراجعه کن.
+
+> **نکته دربارهٔ تنظیمات هر مدل:** `prompt_surface.models` همیشه مسیر بلوک راهنمای تزریق‌شده را تعیین می‌کند. OpenCode 1.x، Pi و OMP توضیحات ابزار را یک‌بار در هر فرایند ثبت می‌کنند (بر پایهٔ `prompt_surface.default`). OpenCode 2 پنج توضیح `ctx_*` را در هر درخواست و بر پایهٔ مدل پیش‌نویس بازنویسی می‌کند.
+
+**مسیرهای پیکربندی** (یک مسیر مشترک CortexKit؛ تنظیم پروژه بر تنظیم کاربر اولویت دارد):
+1. `/.cortexkit/magic-context.jsonc`
+2. `~/.config/cortexkit/magic-context.jsonc`
+
+از نسخهٔ قدیمی‌تر ارتقا می‌دهی؟ تنظیمات فعلی در نخستین اجرا خودکار به این مسیر منتقل می‌شوند و در محل قبلی نشانهٔ `.MOVED_READPLEASE` باقی می‌ماند.
+
+### پروفایل مدل برای مخزن‌های کاری و شخصی
+
+اگر برای مخزن‌های شخصی و کاری از مجموعه‌مدل‌های جداگانه برای عامل‌های پس‌زمینه استفاده می‌کنی، پروفایل‌ها را در تنظیمات کاربر تعریف کن و در هر مخزن کاری نام پروفایل را انتخاب کن:
+
+```jsonc
+// ~/.config/cortexkit/magic-context.jsonc
+{
+ "profile": "personal",
+ "profiles": {
+ "personal": { "historian": { "opencode": { "model": "anthropic/claude-sonnet-4-6" } } },
+ "work": { "historian": { "opencode": { "model": "openai/gpt-5.2-codex" } } }
+ }
+}
+
+// /.cortexkit/magic-context.jsonc
+{ "profile": "work" }
+```
+
+این همان الگوی جداسازی مخزن‌های کاری از شخصی است که kagbodji درخواست کرده بود. پروفایل‌ها فقط انتخاب مدل عامل‌های پس‌زمینه را جایگزین می‌کنند و تنظیمات پایه‌ای را که در آن‌ها نیامده حفظ می‌کنند؛ تعریفشان فقط در تنظیمات کاربر ممکن است. پروژه می‌تواند یک پروفایل شناخته‌شدهٔ کاربر را انتخاب کند، اما نمی‌تواند محتوای آن را تعیین کند. برای نمونهٔ کامل OpenCode/Pi/OMP، رفتار جایگزین و مرز اعتماد، [CONFIGURATION.md](../../CONFIGURATION.md#per-repository-model-profiles) را ببین.
+
+---
+
+## ذخیره‌سازی
+
+همهٔ داده‌های ماندگار در پایگاه دادهٔ SQLite محلی و در مخزن مشترک CortexKit نگه‌داری می‌شوند (`~/.local/share/cortexkit/magic-context/context.db`؛ در Windows مسیر هم‌ارز XDG به‌کار می‌رود؛ پایگاه‌های دادهٔ قدیمی داخل پوشهٔ OpenCode در نخستین راه‌اندازی مهاجرت می‌کنند). اگر میزبان `XDG_DATA_HOME` را جدا می‌کند، `MAGIC_CONTEXT_STORAGE_DIR` را روی مسیر مطلق و کامل پوشهٔ ذخیره‌سازی Magic Context بگذار؛ این مقدار صریح بر مسیر برگرفته از XDG اولویت دارد. همهٔ فرایندهایی که از این مخزن مشترک استفاده می‌کنند باید همین مقدار صریح را دریافت کنند. میزبان‌ها متغیر را وقتی صریحاً تنظیم شده باشد منتقل می‌کنند، اما Magic Context آن را از مسیر پیش‌فرض خودش تولید نمی‌کند. این جایگزین فقط پایگاه دادهٔ سمت محیط اجرا را جابه‌جا می‌کند؛ وضعیت daemonِ `subc` برای هر کاربر در محل مشترک خودش می‌ماند. فرایندهایی با نسخه‌های متفاوت، تا وقتی همه به‌روز نشوند، مهاجرت را در پوشهٔ مشترک مسدود می‌کنند. اگر پایگاه داده باز نشود، Magic Context خود را غیرفعال می‌کند و به تو اطلاع می‌دهد. خاطره‌ها به **شناسهٔ پایدار پروژه** که از مخزن به دست می‌آید متصل‌اند؛ بنابراین با پروژه میان worktreeها، cloneها و forkها جابه‌جا می‌شوند و به مسیر یک پوشه وابسته نیستند.
+
+Magic Context در چند مسیر دیگر هم داده می‌نویسد:
+
+| مسیر | محتوا | ماندگاری |
+|---|---|---|
+| `~/.local/share/cortexkit/magic-context/context.db` | پایگاه دادهٔ SQLite: برچسب‌ها، محفظه‌ها، خاطره‌ها و همهٔ داده‌های ماندگار (مسیر هم‌ارز XDG در Windows) | **باید ماندگار بماند.** حذف آن به‌معنای ازدست‌رفتن خاطره‌ها و تاریخچه است. |
+| `~/.local/share/cortexkit/magic-context/models/` | نهانگاه مدل embedding محلی (حدود ۹۰ مگابایت، `Xenova/all-MiniLM-L6-v2` با قالب ONNX) که در نخستین استفاده، اگر embedding محلی روشن باشد، دانلود می‌شود | بهتر است ماندگار بماند وگرنه در هر اجرا دوباره دانلود می‌شود. اگر `embedding.provider` روی `"off"` باشد یا backend از نوع `openai_compatible`/`ollama` تنظیم شده باشد استفاده نمی‌شود. خاموش‌کردن `memory.enabled` هم مانعش نیست، چون تاریخچهٔ نشست همچنان embedding می‌شود. |
+| `$MAGIC_CONTEXT_LOG_PATH` (پیش‌فرض: `${TMPDIR}/opencode/magic-context/magic-context.log`؛ برای Pi از `pi/` استفاده می‌شود) | گزارش عیب‌یابی. با `MAGIC_CONTEXT_LOG_PATH` مسیر دیگری تعیین کن (مثلاً مسیری ماندگار در یک container). | موقت؛ نگه‌داشتنش ضروری نیست. |
+
+**محیط‌های محدود یا موقت (Docker، CI و containerهای دورریختنی):** پوشهٔ `~/.local/share/cortexkit/magic-context/` را روی volume ماندگار mount کن تا پایگاه داده و نهانگاه مدل میان اجراها باقی بمانند. اگر فقط نهانگاه مدل موقت باشد، مدل دوباره دانلود می‌شود؛ اما اگر پایگاه داده موقت باشد، خاطره و تاریخچه انباشته نمی‌شوند. برای حذف کامل دانلود مدلِ حدود ۹۰ مگابایتی، `embedding.provider: "off"` بگذار یا `embedding` را به backend راه‌دور `openai_compatible`/`ollama` وصل کن.
+
+---
+
+## تاریخچهٔ ستاره‌ها
+
+
+
+
+
+
+
+
+
+---
+
+## توسعه
+
+**پیش‌نیاز:** [Bun](https://bun.sh) نسخهٔ 1.4.0 یا بالاتر
+
+تفاوت‌های Bun 1.3.x در ارزیابی ماژول‌ها و شکل خطاهای resolver ممکن است تغییرات بی‌ارتباط مشارکت‌کنندگان را به خطاهای پرسر‌وصدا در آزمون‌های موازی و ساخت تبدیل کند (مسئله‌های [#445](https://github.com/cortexkit/magic-context/issues/445) و [#446](https://github.com/cortexkit/magic-context/issues/446)). دروازه‌های مخزن پیش از اجرا نسخه را بررسی می‌کنند تا نسخه‌های پشتیبانی‌نشده به‌جای خطاهای نامربوط، پیام نسخهٔ لازم را نشان دهند.
+
+```sh
+bun install # Install dependencies
+bun run build # Build the plugin
+bun run typecheck # Type-check without emitting
+bun test # Run tests
+bun run lint # Lint (Biome)
+bun run format # Format (Biome)
+```
+
+اجرای Dream به سرور فعال OpenCode نیاز دارد (عامل رؤیاپرداز نشست‌های فرزند موقت می‌سازد). برای نگهداشت درخواستی، داخل OpenCode از `/ctx-dream` استفاده کن.
+
+### فهرست آزمون‌های جهش
+
+قبول‌شدن یک آزمون ایمنی به‌تنهایی چیز زیادی را ثابت نمی‌کند، مگر اینکه دیده باشیم هنگام خرابی هم شکست می‌خورد. [`mutations.toml`](../../mutations.toml) فهرست ثبت‌شدهٔ این آزمون‌هاست: هر ردیف عمداً یکی از محافظ‌های کد تولیدی را از کار می‌اندازد و آزمونی را نام می‌برد که باید در نتیجه شکست بخورد؛ این‌طور هیچ محافظی بی‌سروصدا بی‌اثر نمی‌شود. هر ردیف باید جلوی خرابی خاموش و پرهزینه‌ای را بگیرد: بی‌اعتبارشدن کش پرامپت، رد درخواستی که باید به‌شکل fail-closed عمل کند، نقض قرارداد ارتباطی، ناایمنی هنگام crash، ازدست‌رفتن داده یا مجوز نادرست فایل. هر محافظی که باید دقیقاً یک‌بار اجرا شود (مثل lease یا پاک‌سازی compare-and-set) دست‌کم یک ردیف دارد که مسیر واقعی تولید را می‌پیماید. برای سبک و ظاهر ردیفی تعریف نمی‌شود.
+
+اجرای پین‌شدهٔ [`ck-mutate`](https://github.com/cortexkit/commons/tree/7d08e73722fa3e79bbcc2607753978ab768f1c6b/crates/cortexkit-mutate) فهرست را از درخت کاری پاک اجرا می‌کند: اول بررسی می‌کند آزمون نام‌برده موفق است، سپس خرابی را اعمال می‌کند و انتظار دارد آزمون شکست بخورد؛ در پایان فایل منبع را بایت‌به‌بایت برمی‌گرداند.
+
+```sh
+cargo install --locked --git https://github.com/cortexkit/commons --rev 7d08e73722fa3e79bbcc2607753978ab768f1c6b cortexkit-mutate
+bun install --frozen-lockfile
+ck-mutate check # anchors match exactly once; cargo test names exist
+ck-mutate run --all # every row (slow: the Rust rows rebuild mc-module)
+ck-mutate run --diff origin/master # only the rows a change touches
+ck-mutate run --only ts-schema-fence-refuses-newer-database
+```
+
+هر ردیف باید نتیجهٔ CAUGHT بدهد. [`mutations.yml`](../../.github/workflows/mutations.yml) ردیف‌هایی را که pull request (یا push به `train/**`) لمس می‌کند دوباره اجرا می‌کند؛ با هر push به master کل فهرست را اجرا می‌کند و هر شب نیز کل فهرست را با `--broad` می‌سنجد. هنگام اجرای این فرایند هیچ فایلی را با `git checkout` برنگردان: این کار جهش را حذف می‌کند و نتیجهٔ زنده‌مانده را جعلی جلوه می‌دهد.
+
+برای افزودن یک ردیف:
+
+1. خط تولیدی‌ای را پیدا کن که خودِ محافظ است و مقدار `old` را از فایل بردار، نه از حافظه. `new` را کوچک‌ترین تغییری انتخاب کن که محافظت را حذف کند (`if (false)`، `return true` یا حذف یک شرط)، نه تغییری که کامپایل را خراب کند.
+2. آزمونی را پیدا کن که باید این جهش را بگیرد. تغییر را دستی اعمال کن، فایل آزمون را اجرا کن و مطمئن شو آزمون به‌دلیل همان محافظ ازکارافتاده شکست می‌خورد؛ بعد فایل را برگردان. اگر هیچ آزمونی شکست نخورد، این یک یافته است: اول در commit جداگانه آزمون مفقود را اضافه کن.
+3. ردیف را اضافه کن. آزمون‌های Bun از نوع `command` هستند: یک ردیف موجود را کپی کن و `expect_red` را روی regex لنگرشدهٔ `-t` برای نام کامل آزمون بگذار (نام‌های `describe` و آزمون را با فاصله به هم وصل کن، نویسه‌های ویژهٔ regex را escape کن و هر فاصله را `\s` بنویس). آزمون‌های Rust در mc-module ردیف‌های `command` با اجرای `cargo test --lib -- --exact` هستند؛ هدف‌های کوچک Rust ردیف‌های `cargo` با `only = true` هستند. هرجا آزمون ممکن است به دلیلی نامرتبط هم شکست بخورد، `expect_message` (زیررشته یا `/regex/`) را اضافه کن.
+4. `ck-mutate check` و سپس `ck-mutate run --only ` را اجرا کن. ردیف را فقط وقتی commit کن که نتیجه CAUGHT باشد.
+
+اگر آزمونی دیگر جهش را نگیرد، باید آن را به‌عنوان باگ اصلاح کرد؛ ردیف را حذف نکن.
+
+---
+
+### نشانگر بی‌اعتبارشدن کش
+
+`packages/plugin/scripts/cache-bust-sentinel.ts` درخواست‌های اخیر OpenCode و ارائه‌دهنده‌های Pi/OMP را بررسی می‌کند تا موارد بی‌اعتبارشدن کش را پیدا کند که با قراردادهای fold، refresh، reduction، flush، force-band یا provider/system-prompt در Magic Context توضیح داده نمی‌شوند. هر درخواست ارائه‌دهنده را به نزدیک‌ترین رکورد گذر MC، از ۳۰ ثانیه پیش تا ۵ ثانیه پس از درخواست، وصل می‌کند: داده‌های `transform_decisions`/`scheduler_history` در `context.db` و ردّ `mc_pass_trace`/آینهٔ تصمیم در حالت Rust در `store.db`. اگر رکورد گذر متناظر پیدا نشود، `no_mc_pass_row` گزارش می‌شود. پایگاه دادهٔ MC، پایگاه دادهٔ OpenCode، dumpهای افزونهٔ احراز هویت، فایل‌های JSONLِ Pi/OMP و artifactهای `.pi/pi-llm-debugging`/آرایه‌های سرو‌شده را فقط می‌خواند. تنها چیزی که می‌نویسد فایل وضعیتِ آخرین‌مقدار/جلوگیری از تکرار در `~/.local/share/cortexkit/magic-context/cache-bust-sentinel-state.json` (یا مسیر تعیین‌شده با `MAGIC_CONTEXT_STORAGE_DIR`) است.
+
+برای یک اجرای آزمایشی از ریشهٔ مخزن استفاده کن؛ هر پنجرهٔ تازه و توضیح‌داده‌نشدهٔ بی‌اعتبارشدن کش در یک خط JSON چاپ می‌شود:
+
+```sh
+bun packages/plugin/scripts/cache-bust-sentinel.ts --once
+```
+
+برای اجرای یک‌دقیقه‌ای داخلی، `--once` را حذف کن؛ یا آن را هر ۱ تا ۵ دقیقه با cron/launchd اجرا کن. الگوی `packages/plugin/scripts/launchd/com.cortexkit.magic-context.cache-bust-sentinel.plist` هر پنج دقیقه اجرا می‌شود، `--send` را روشن می‌کند، `RunAtLoad=false` دارد و خودکار نصب نمی‌شود. پیش از بارگذاری، جای‌نگهدارهای `__BUN_PATH__`، `__REPO_ROOT__` و `__LOG_DIR__` را عوض کن. نمونهٔ cron:
+
+```cron
+*/5 * * * * cd /path/to/magic-context && /path/to/bun packages/plugin/scripts/cache-bust-sentinel.ts --once --send >> /path/to/cache-bust-sentinel.jsonl 2>> /path/to/cache-bust-sentinel.log
+```
+
+`--send` خروجی آزمایشیِ خط‌به‌خط JSON را به عملیات `agent.deliver` در ماژول `prefrontal-core` تبدیل می‌کند. به‌طور پیش‌فرض از نام نمایشی `mc-cache-bust-sentinel` یک پیام همتای با اولویت بالا در registry به `agent_b613e5cf2ee55b8c` می‌فرستد؛ نشست فرستنده نیز `health-sentinel-mc` و محیط اجرایش `magic-context` ثبت می‌شود. برای انتخاب گیرنده یا نام نمایشی دیگری از `--wake-agent-id` یا `--wake-from-agent` استفاده کن. پاسخ‌های پذیرفته‌شده و در صف، موفق شمرده می‌شوند؛ سفارش تکراریِ ثبت‌شده با همان شناسهٔ تحویل تکراری شمرده می‌شود. رد فرستنده بدون تلاش دوباره برای همان شناسه ثبت می‌شود و پاسخ نامعتبر یا تعارض idempotency اجرا را ناموفق می‌کند. `--connection-file`، `--wake-module-id`، `--wake-agent-id`، `--wake-from-agent`، `--state-file`، `--db` یا `--rust-store` را فقط وقتی به کار ببر که مسیر runtime مربوطه پیش‌فرض نیست.
+
+### نشانگر تأخیر تبدیل
+
+`packages/plugin/scripts/transform-latency-sentinel.ts` گزارش‌های Magic Context در OpenCode و Pi و گزارش تاریخ‌دار ماژول `ck-mc` را فقط می‌خواند. هر بار اجرا حداکثر ۴ مگابایت **بایت تازه برای هر فایل** می‌خواند؛ watermarkهای inode/اندازه چرخش فایل را تشخیص می‌دهند و خط‌های ناقص انتهایی را دوباره می‌خوانند. تنها نوشتهٔ ماندگارش `transform-latency-sentinel-state.json` در پوشهٔ ذخیره‌سازی Magic Context است. هشدارهای هر نشست این موارد را پوشش می‌دهند: p90 بیش از ۵ ثانیه در ده گذر طی ده دقیقه، هر گذر بیش از ۱۲ ثانیه، پایان مهلت انتقال/ماژول/همگام‌سازی وضعیت، گذارهای park در Rust، ردها و افزایش پیوستهٔ زمان ماژول در دست‌کم بیست گذر. هشدار هم‌نوع دوباره فقط با افزایش شدت ۵۰درصدی یا پس از شش ساعت ارسال می‌شود. هر هشدار شناسهٔ نشست، نام فهرست همتاها (اگر موجود نباشد، شناسهٔ پروژه در `session_projects`)، p50/p90/بیشینهٔ گذر، میانهٔ زمان ماژول و افزونه و میانگین بار سیستم را دارد. `loadSampledAt` زمان نمونه‌برداری بار را ثبت می‌کند؛ بازپخش تاریخی نمی‌تواند بار تاریخی دستگاه را بازسازی کند.
+
+اجرای آزمایشی بدون ارسال: `bun packages/plugin/scripts/transform-latency-sentinel.ts --once`. برای بررسی گذشته از `--replay --since 2026-09-28T17:00:00Z --until 2026-09-28T18:15:00Z` استفاده کن؛ بازپخش داده را در قطعه‌های ۴ مگابایتی می‌خواند، بی‌آنکه watermark بنویسد یا هشداری بفرستد. `--send` در هر اجرا با `agent.deliver` یک پیام همتای با اولویت بالا می‌فرستد. الگوی launchd پنج‌دقیقه‌ای در `packages/plugin/scripts/launchd/com.cortexkit.magic-context.transform-latency-sentinel.plist` از `--once --send` و `RunAtLoad=false` استفاده می‌کند؛ مانند نشانگرهای دیگر، خودکار نصب نمی‌شود. پیش از ثبت به‌عنوان LaunchAgent، `__BUN_PATH__`، `__REPO_ROOT__` و `__LOG_DIR__` را با مسیر فایل اجرایی bun، ریشهٔ مخزن و پوشهٔ گزارش‌ها جایگزین کن. برای مسیرهای غیراستاندارد از `--opencode-log`، `--pi-log`، `--module-log`، `--db`، `--peer-db`، `--state-file` و `--connection-file` استفاده کن.
+
+### نشانگر شکست عامل رؤیاپرداز و تاریخ‌نگار
+
+`packages/plugin/scripts/subagent-failure-sentinel.ts` ردیف‌های کامل‌شدهٔ `subagent_invocations` را از `context.db` با اتصال فقط‌خواندنی SQLite و مهلت انتظار قفل سه‌ثانیه‌ای می‌خواند. وضعیت‌های `failed` و `timed_out` را شکست می‌شمارد؛ `empty` و `aborted` جداگانه شمرده می‌شوند. این ابزار طی هفت روز یک دستهٔ خطای تازه (عامل فرزند، کار، خطای نرمال‌شده)، کاری با دست‌کم هشت اجرا و سهم شکست حداقل ۲۵٪ در ۲۴ ساعت، یا دسته‌ای را گزارش می‌کند که شمارش آن نسبت به ۲۴ ساعت پیش دو برابر شده باشد. شناسه‌ها، عددها، مدت‌ها و مسیرهای متغیر خطاها به دسته‌های باثبات تبدیل می‌شوند. هر اجرای پنج‌دقیقه‌ای حداکثر ۵۰۱ ردیف تازه و ۵٬۰۰۱ ردیف تاریخچهٔ اخیر را می‌خواند (شامل ردیف‌های مرزی)؛ اگر تاریخچه ناقص باشد، قواعدی که بازهٔ کاملشان قابل سنجش نیست اجرا نمی‌شوند. تنها نوشتهٔ محلی فایل watermark/جلوگیری از تکرار `subagent-failure-sentinel-state.json` در پوشهٔ ذخیره‌سازی Magic Context است. ادامهٔ watermark بر پایهٔ `(ended_at, id)` انجام می‌شود؛ ارسال هشدار برای شش ساعت متوقف می‌ماند، مگر اینکه شمار دسته ۵۰٪ رشد کند. آغاز و خلاصهٔ اجرا، از جمله تعداد ردیف‌های بررسی‌شده و محدودبودن اسکن، ثبت می‌شود. در هر اجرا حداکثر یک پیام بیدارباش می‌فرستد که قاعده، کار، دسته، شمار دسته، سهم شکست، نمونهٔ خطا، تازه‌ترین شناسهٔ نشست و تعداد وضعیت‌های empty/aborted را فهرست می‌کند.
+
+اجرای آزمایشی با `bun packages/plugin/scripts/subagent-failure-sentinel.ts --once` انجام می‌شود؛ برای انتخاب پایگاه دادهٔ fixture و فایل وضعیت از `--db` و `--state-file` استفاده کن. بدون `--once` هر دقیقه تکرار می‌شود. الگوی launchd در `packages/plugin/scripts/launchd/com.cortexkit.magic-context.subagent-failure-sentinel.plist` هر پنج دقیقه با `--once --send` اجرا می‌شود، `RunAtLoad=false` دارد و گزارش‌های JSONL/stdout و stderr را جداگانه ذخیره می‌کند. `--send` همان پیام همتای `agent.deliver` با اولویت بالای `prefrontal-core` را، مانند نشانگر بی‌اعتبارشدن کش، به عامل اصلی Magic Context می‌فرستد. برای نصب و فعال‌سازی در macOS، (این کار خودکار انجام نمی‌شود) فرمان‌های زیر را **از ریشهٔ مخزن** اجرا کن:
+
+```sh
+mkdir -p "$HOME/Library/LaunchAgents" "$HOME/Library/Logs/cortexkit"
+sed -e "s|__BUN_PATH__|$(command -v bun)|g" \
+ -e "s|__REPO_ROOT__|$(pwd -P)|g" \
+ -e "s|__LOG_DIR__|$HOME/Library/Logs/cortexkit|g" \
+ packages/plugin/scripts/launchd/com.cortexkit.magic-context.subagent-failure-sentinel.plist \
+ > "$HOME/Library/LaunchAgents/com.cortexkit.magic-context.subagent-failure-sentinel.plist"
+launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.cortexkit.magic-context.subagent-failure-sentinel.plist"
+```
+
+---
+## مشارکت
+
+گزارش باگ و pull request پذیرفته می‌شود. پیش از شروع، [CONTRIBUTING.md](../../CONTRIBUTING.md) را دربارهٔ قواعد مسئله‌های تأییدشده و پوشش محیط‌های اجرا بخوان.
+
+---
+
+## مجوز
+
+[MIT](../../LICENSE)
From 1781cf361f48253ba1548cda45203d7d63652383 Mon Sep 17 00:00:00 2001
From: Danny Shirely <69107616+danialshirali16@users.noreply.github.com>
Date: Sat, 17 Oct 2026 09:53:15 +0330
Subject: [PATCH 2/5] docs: link Persian README
---
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 78ecaf9996..f9053a11ec 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-**English** · [简体中文](docs/i18n/README.zh-CN.md) · [繁體中文](docs/i18n/README.zh-TW.md) · [한국어](docs/i18n/README.ko.md) · [Deutsch](docs/i18n/README.de.md) · [Español](docs/i18n/README.es.md) · [Français](docs/i18n/README.fr.md) · [Italiano](docs/i18n/README.it.md) · [Dansk](docs/i18n/README.da.md) · [日本語](docs/i18n/README.ja.md) · [Polski](docs/i18n/README.pl.md) · [Русский](docs/i18n/README.ru.md) · [Bosanski](docs/i18n/README.bs.md) · [العربية](docs/i18n/README.ar.md) · [Norsk](docs/i18n/README.nb.md) · [Português (Brasil)](docs/i18n/README.pt-BR.md) · [ไทย](docs/i18n/README.th.md) · [Türkçe](docs/i18n/README.tr.md) · [Українська](docs/i18n/README.uk.md) · [বাংলা](docs/i18n/README.bn.md) · [Ελληνικά](docs/i18n/README.el.md) · [Tiếng Việt](docs/i18n/README.vi.md)
+**English** · [简体中文](docs/i18n/README.zh-CN.md) · [繁體中文](docs/i18n/README.zh-TW.md) · [한국어](docs/i18n/README.ko.md) · [Deutsch](docs/i18n/README.de.md) · [Español](docs/i18n/README.es.md) · [Français](docs/i18n/README.fr.md) · [Italiano](docs/i18n/README.it.md) · [Dansk](docs/i18n/README.da.md) · [日本語](docs/i18n/README.ja.md) · [Polski](docs/i18n/README.pl.md) · [Русский](docs/i18n/README.ru.md) · [Bosanski](docs/i18n/README.bs.md) · [العربية](docs/i18n/README.ar.md) · [فارسی](docs/i18n/README.fa.md) · [Norsk](docs/i18n/README.nb.md) · [Português (Brasil)](docs/i18n/README.pt-BR.md) · [ไทย](docs/i18n/README.th.md) · [Türkçe](docs/i18n/README.tr.md) · [Українська](docs/i18n/README.uk.md) · [বাংলা](docs/i18n/README.bn.md) · [Ελληνικά](docs/i18n/README.el.md) · [Tiếng Việt](docs/i18n/README.vi.md)
Magic Context
From 25eb7cddcb2b20c063f1564fc796cb5ca8f3f6ef Mon Sep 17 00:00:00 2001
From: danialshirali16
Date: Thu, 22 Oct 2026 12:57:04 +0330
Subject: [PATCH 3/5] docs: fix Persian README review feedback
Apply the four fixes from the maintainer review, plus the two Greptile
findings that were left unaddressed:
- Escape the pipe in the /ctx-embed row so GitHub no longer splits the
cell and the `pause` option stays visible.
- Translate "opt-in" for git commit indexing as off by default until
explicitly enabled, instead of the ambiguous "optional".
- State that checking out a file during a replay causes the mutation to
be reported as a false survivor, rather than faking a survivor.
- Use anterograde amnesia for the amnesia term.
- Translate the compatibility section's collapsed title.
- Restore the leading hyphen in the four emoji-heading TOC anchors so
they resolve, matching the English README's anchor pattern.
---
docs/i18n/README.fa.md | 18 +++++++++---------
1 file changed, 9 insertions(+), 9 deletions(-)
diff --git a/docs/i18n/README.fa.md b/docs/i18n/README.fa.md
index 9de9dda373..4ebcb689bb 100644
--- a/docs/i18n/README.fa.md
+++ b/docs/i18n/README.fa.md
@@ -26,10 +26,10 @@
Magic Context چیست؟ ·
شروع سریع ·
CortexKit ·
- مدیریت زمینه ·
- ثبت دانش ·
- تثبیت حافظه ·
- بازیابی ·
+ مدیریت زمینه ·
+ ثبت دانش ·
+ تثبیت حافظه ·
+ بازیابی ·
مستندات ·
تنظیمات ·
داشبورد ·
@@ -42,7 +42,7 @@
برای رفع یک باگ، برنامه‌نویس استخدام نمی‌کنی و درست بعد از تحویل راه‌حل اخراجش کنی. آدم‌های خوب را نگه می‌داری. آن‌ها کدبیس را یاد می‌گیرند، دلیل تصمیم‌ها را به خاطر می‌سپارند و هر هفته کاربلدتر می‌شوند.
-عامل‌های برنامه‌نویس وضع معکوسی دارند. هر کار مثل استخدام فردی تازه است که چیزی از پروژه‌ات نمی‌داند؛ پایان هر نشست هم او را کنار می‌گذاری و از صفر شروع می‌کنی. وسط کار حتی با مکث‌های «فشرده‌سازی» (compaction) روبه‌رو می‌شوند؛ مکث‌هایی که جریان کار را می‌شکنند و بی‌سروصدا دانسته‌های عامل را از بین می‌برند. این همان فراموشی پیش‌رونده‌ای است که با آسیب‌دیدن هیپوکامپ رخ می‌دهد.
+عامل‌های برنامه‌نویس وضع معکوسی دارند. هر کار مثل استخدام فردی تازه است که چیزی از پروژه‌ات نمی‌داند؛ پایان هر نشست هم او را کنار می‌گذاری و از صفر شروع می‌کنی. وسط کار حتی با مکث‌های «فشرده‌سازی» (compaction) روبه‌رو می‌شوند؛ مکث‌هایی که جریان کار را می‌شکنند و بی‌سروصدا دانسته‌های عامل را از بین می‌برند. این همان فراموشی پیش‌گستر (anterograde amnesia) است که با آسیب‌دیدن هیپوکامپ رخ می‌دهد.
Magic Context برای عامل‌ها هیپوکامپی فراهم می‌کند. این ابزار **هیپوکامپِ** عامل‌های برنامه‌نویس است: بخشی از مغز که خاطره‌ها را شکل می‌دهد، تثبیت می‌کند و به یاد می‌آورد؛ و همهٔ این کارها را در پس‌زمینه انجام می‌دهد. هر نشست از پیمانکاری موقت به هم‌تیمی‌ای بلندمدت تبدیل می‌شود که از آغاز تا پایان پروژه همراهت بوده است:
@@ -142,7 +142,7 @@ OMP از مقادیر `thinking_level` بومی Pi استفاده می‌کند.
در پروژه‌ای تازه یا پروژه‌ای که مدت‌ها در جریان بوده یکسان کار می‌کند: نصب کن، محیط اجرا را دوباره راه‌اندازی کن و Magic Context از همان لحظه شروع به ثبت زمینه می‌کند. نشست‌های OpenCode، Pi یا OMP پیش از نصب را به‌صورت عطف‌به‌ماسبق وارد حافظه نمی‌کند.
-Compatibility with other context-management plugins
+سازگاری با دیگر افزونه‌های مدیریت زمینه
@@ -245,7 +245,7 @@ ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for
بازیابی هم **میان نشست‌ها** کار می‌کند (نشست تازه همه‌چیز را به ارث می‌برد) و هم **میان محیط‌های اجرا** (خاطره‌ای را در OpenCode بنویس و در Pi یا OMP بازیابی کن).
-> **راهنمای جست‌وجوی خودکار** *(به‌طور پیش‌فرض روشن)* در هر نوبت، `ctx_search` را در پس‌زمینه اجرا می‌کند و اگر مورد مرتبطی باشد با اشاره‌ای مبهم آن را به یاد عامل می‌آورد؛ مثل وقتی که یادداشتی را که نوشته‌ای کم‌وبیش به خاطر می‌آوری. فقط تکه‌های فشرده افزوده می‌شوند، نه محتوای کامل. برای خاموش‌کردن آن `memory.auto_search.enabled: false` بگذار. **فهرست‌سازی commitهای git** *(اختیاری)* تاریخچهٔ پروژه را به منبعی معنایی و اضافه برای `ctx_search` تبدیل می‌کند؛ با `memory.git_commit_indexing.enabled: true` روشنش کن.
+> **راهنمای جست‌وجوی خودکار** *(به‌طور پیش‌فرض روشن)* در هر نوبت، `ctx_search` را در پس‌زمینه اجرا می‌کند و اگر مورد مرتبطی باشد با اشاره‌ای مبهم آن را به یاد عامل می‌آورد؛ مثل وقتی که یادداشتی را که نوشته‌ای کم‌وبیش به خاطر می‌آوری. فقط تکه‌های فشرده افزوده می‌شوند، نه محتوای کامل. برای خاموش‌کردن آن `memory.auto_search.enabled: false` بگذار. **فهرست‌سازی commitهای git** *(نیازمند فعال‌سازی صریح؛ به‌طور پیش‌فرض خاموش)* تاریخچهٔ پروژه را به منبعی معنایی و اضافه برای `ctx_search` تبدیل می‌کند؛ با `memory.git_commit_indexing.enabled: true` روشنش کن.
### ابزارهای عامل در یک نگاه
@@ -268,7 +268,7 @@ ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for
| `/ctx-recomp` | محفظه‌ها را از تاریخچهٔ خام دوباره می‌سازد (بازهٔ `start-end` می‌پذیرد). اگر وضعیت ذخیره‌شده نادرست به‌نظر می‌رسد از آن استفاده کن |
| `/ctx-wrapup [messages_to_keep]` | تاریخچهٔ زندهٔ قدیمی را فشرده می‌کند و N پیام تازه را خام نگه می‌دارد؛ فشرده‌سازیِ در صف با پیام بعدی مدل نهایی می‌شود |
| `/ctx-dream` | نگهداشت عامل رؤیاپرداز را به‌درخواست اجرا می‌کند: بازبینی حافظه، مستندات، یادداشت‌های هوشمند و نمایهٔ کاربر |
-| `/ctx-embed` | وضعیت embedding را نشان می‌دهد یا embedding محفظه‌های تاریخچه را آغاز/متوقف می‌کند (`start` | `pause`) |
+| `/ctx-embed` | وضعیت embedding را نشان می‌دهد یا embedding محفظه‌های تاریخچه را آغاز/متوقف می‌کند (`start` \| `pause`) |
---
@@ -385,7 +385,7 @@ ck-mutate run --diff origin/master # only the rows a change touches
ck-mutate run --only ts-schema-fence-refuses-newer-database
```
-هر ردیف باید نتیجهٔ CAUGHT بدهد. [`mutations.yml`](../../.github/workflows/mutations.yml) ردیف‌هایی را که pull request (یا push به `train/**`) لمس می‌کند دوباره اجرا می‌کند؛ با هر push به master کل فهرست را اجرا می‌کند و هر شب نیز کل فهرست را با `--broad` می‌سنجد. هنگام اجرای این فرایند هیچ فایلی را با `git checkout` برنگردان: این کار جهش را حذف می‌کند و نتیجهٔ زنده‌مانده را جعلی جلوه می‌دهد.
+هر ردیف باید نتیجهٔ CAUGHT بدهد. [`mutations.yml`](../../.github/workflows/mutations.yml) ردیف‌هایی را که pull request (یا push به `train/**`) لمس می‌کند دوباره اجرا می‌کند؛ با هر push به master کل فهرست را اجرا می‌کند و هر شب نیز کل فهرست را با `--broad` می‌سنجد. هنگام اجرای این فرایند هیچ فایلی را با `git checkout` برنگردان: این کار جهش را حذف می‌کند و باعث می‌شود جهش به‌اشتباه زنده‌مانده گزارش شود.
برای افزودن یک ردیف:
From 25b2d6fd668bf6f55f54801b1cf49c02668c052a Mon Sep 17 00:00:00 2001
From: danialshirali16
Date: Thu, 22 Oct 2026 13:00:22 +0330
Subject: [PATCH 4/5] docs: use Persian yeh and LF endings in the Persian
README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- Replace the Arabic yeh in "اجرايش" with the Persian yeh; the only
remaining Arabic yeh is the Arabic locale name in the language
switcher, which is correct there.
- Convert the file from CRLF to LF so it matches every other README in
docs/i18n/ and the root README.
---
docs/i18n/README.fa.md | 900 ++++++++++++++++++++---------------------
1 file changed, 450 insertions(+), 450 deletions(-)
diff --git a/docs/i18n/README.fa.md b/docs/i18n/README.fa.md
index 4ebcb689bb..d9c96b483d 100644
--- a/docs/i18n/README.fa.md
+++ b/docs/i18n/README.fa.md
@@ -1,450 +1,450 @@
-[English](../../README.md) · [简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Dansk](README.da.md) · [日本語](README.ja.md) · [Polski](README.pl.md) · [Русский](README.ru.md) · [Bosanski](README.bs.md) · [العربية](README.ar.md) · **فارسی** · [Norsk](README.nb.md) · [Português (Brasil)](README.pt-BR.md) · [ไทย](README.th.md) · [Türkçe](README.tr.md) · [Українська](README.uk.md) · [বাংলা](README.bn.md) · [Ελληνικά](README.el.md) · [Tiếng Việt](README.vi.md)
-
-*این نسخهٔ فارسی بر پایهٔ README انگلیسی نوشته شده است؛ README انگلیسی مرجع اصلی پروژه است و ممکن است به‌روزتر باشد.*
-
-
Magic Context
-
-
- زمینه‌ای بی‌کران. حافظه‌ای که خودش را اداره می‌کند. یک نشست، برای همیشه.
- هیپوکامپِ عامل‌های برنامه‌نویس و بخشی از CortexKit.
-
-
-
-
-
-
-
-
-
-
-
-
- برای یک کار برنامه‌نویس استخدام نمی‌کنی که به‌محض تحویل کار اخراجش کنی. با عاملت هم همین کار را نکن.
-
-
----
-
-## Magic Context چیست؟
-
-برای رفع یک باگ، برنامه‌نویس استخدام نمی‌کنی و درست بعد از تحویل راه‌حل اخراجش کنی. آدم‌های خوب را نگه می‌داری. آن‌ها کدبیس را یاد می‌گیرند، دلیل تصمیم‌ها را به خاطر می‌سپارند و هر هفته کاربلدتر می‌شوند.
-
-عامل‌های برنامه‌نویس وضع معکوسی دارند. هر کار مثل استخدام فردی تازه است که چیزی از پروژه‌ات نمی‌داند؛ پایان هر نشست هم او را کنار می‌گذاری و از صفر شروع می‌کنی. وسط کار حتی با مکث‌های «فشرده‌سازی» (compaction) روبه‌رو می‌شوند؛ مکث‌هایی که جریان کار را می‌شکنند و بی‌سروصدا دانسته‌های عامل را از بین می‌برند. این همان فراموشی پیش‌گستر (anterograde amnesia) است که با آسیب‌دیدن هیپوکامپ رخ می‌دهد.
-
-Magic Context برای عامل‌ها هیپوکامپی فراهم می‌کند. این ابزار **هیپوکامپِ** عامل‌های برنامه‌نویس است: بخشی از مغز که خاطره‌ها را شکل می‌دهد، تثبیت می‌کند و به یاد می‌آورد؛ و همهٔ این کارها را در پس‌زمینه انجام می‌دهد. هر نشست از پیمانکاری موقت به هم‌تیمی‌ای بلندمدت تبدیل می‌شود که از آغاز تا پایان پروژه همراهت بوده است:
-
-- **ثبت دانش.** وقتی عامل تاریخ‌نگار (historian) تاریخچه را خلاصه می‌کند، دانسته‌های ماندگار (تصمیم‌ها، محدودیت‌ها و قراردادها) را جدا می‌کند و در حافظهٔ پروژه می‌گذارد. از کاری که همین حالا انجام می‌دهی، بی‌هزینه یک سامانهٔ حافظه به دست می‌آوری.
-- **تثبیت حافظه.** شب‌ها عامل‌های رؤیاپرداز (dreamer) کاری را انجام می‌دهند که خواب برای تو می‌کند: خاطره‌ها را با کدبیس می‌سنجند، موارد تکراری و منسوخ را سامان می‌دهند و دانسته‌های پرتکرار را ارتقا می‌دهند.
-- **بازیابی.** در هر نوبت، خاطره‌های مناسب خودکار ظاهر می‌شوند و عامل می‌تواند هر زمان که بخواهد میان خاطره‌ها، گفت‌وگوهای پیشین و تاریخچهٔ git جست‌وجو کند؛ در نشست‌های مختلف و در OpenCode، Pi و OMP.
-
-دو وعده: عاملت **برای مدیریت زمینه از کار نمی‌ایستد** (نه مکث فشرده‌سازی دارد و نه جریان کارش می‌شکند) و **هیچ‌وقت فراموش نمی‌کند**.
-
-برای هر پروژه یک نشست راه بینداز و هفته‌ها، ماه‌ها یا سال‌ها ادامه‌اش بده. عامل همه‌چیزهایی را که با هم ساخته‌اید به خاطر می‌سپارد.
-
----
-
-## شروع سریع
-
-```bash
-npx @cortexkit/magic-context@latest setup
-```
-
-ابزار تنظیم به‌طور خودکار محیط‌های اجرایی نصب‌شده‌ات (OpenCode، Pi، OMP یا هر ترکیبی از آن‌ها) را پیدا و پیکربندی می‌کند: افزونه را ثبت می‌کند، فشرده‌سازی داخلی میزبان را خاموش می‌کند، برای عامل‌های تاریخ‌نگار و رؤیاپرداز در انتخاب مدل کمک می‌کند و ناسازگاری با افزونه‌های دیگر مدیریت زمینه را برطرف می‌کند. پس از آن محیط اجرا را دوباره راه‌اندازی کن تا Magic Context بارگذاری شود. برای انتخاب یک محیط مشخص از `--harness opencode`، `--harness pi` یا `--harness omp` استفاده کن.
-
-> **چرا فشرده‌سازی داخلی را خاموش کنیم؟** Magic Context خودش زمینه را مدیریت می‌کند. فشرده‌سازی میزبان با عملیاتِ به‌تعویق‌افتاده و آگاه از کش تداخل می‌کند و تاریخچه را دوبار فشرده می‌سازد.
-
-### تنظیم دستی (OpenCode)
-
-اگر نمی‌توانی راهنمای تنظیم را اجرا کنی، این را به `opencode.jsonc` اضافه کن:
-
-```jsonc
-{
- "plugin": ["@cortexkit/opencode-magic-context@latest"],
- "compaction": { "auto": false, "prune": false }
-}
-```
-
-> **به‌روزرسانی افزونه:** پیش از راه‌اندازی مجدد، ورودی سادهٔ افزونه به نسخهٔ دقیق دانلودشده سنجاق می‌شود تا OpenCode بستهٔ فعال را وسط نشست حذف نکند. Magic Context مشخصات دقیقی را که به‌روزرسان تنظیمات نوشته ثبت می‌کند و در بررسی‌های بعدی همان نسخهٔ تحت مدیریت به‌روزرسان را جلو می‌برد. هر مشخصات دقیق دیگری که خودت تعیین کرده باشی ثابت می‌ماند. چون منشأ تنظیم با رشتهٔ دقیق مشخصات سنجیده می‌شود، اگر دستی همان رشته‌ای را وارد کنی که به‌روزرسان آخرین بار نوشته، تشخیص آن از نسخهٔ سنجاق‌شدهٔ به‌روزرسان ممکن نیست و نسخه در بررسی بعدی جلو می‌رود. برای انصراف، `auto_update: false` بگذار یا نسخهٔ دقیق دیگری را سنجاق کن. برای استفادهٔ عمدی از نسخهٔ شناور، `@latest` را صریح بنویس (OpenCode ممکن است بستهٔ فعالِ بدون نسخهٔ سنجاق‌شده را وسط نشست حذف کند).
-
-سپس `magic-context.jsonc` را با تنظیم عامل تاریخ‌نگار OpenCode بساز:
-
-```jsonc
-{
- "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
- "historian": {
- "opencode": { "model": "provider/model-id" }
- }
-}
-```
-
-- **الزامی:** `historian.opencode.model` باید یک شناسهٔ واقعی به‌شکل `provider/model-id` باشد. اگر نباشد، افزونه بارگذاری می‌شود اما اجرای تاریخ‌نگار شکست می‌خورد، تاریخچهٔ قدیمی خلاصه نمی‌شود و پس از خطاهای تکراری پیام `Magic Context — history comparting needs attention` نمایش داده می‌شود.
-- **اختیاری:** بلوک مدل/غیرفعال‌سازی `dreamer`. اگر نمی‌خواهی تثبیت دوره‌ای حافظه انجام شود، آن را حذف کن.
-- **اختیاری:** `embedding`. اگر حذفش کنی از مدل محلی `Xenova/all-MiniLM-L6-v2` استفاده می‌شود. خاموش‌کردن embedding جست‌وجوی معنایی یا مبتنی بر بردارسازی را غیرفعال می‌کند؛ جست‌وجوی واژه‌ای و مدیریت زمینه همچنان کار می‌کنند.
-
-### مهاجرت از تنظیمات مسطح مدل (پیش و پس از مهاجرت)
-
-تنظیمات مسطح مدل در نخستین بار خواندن پیکربندی به‌طور خودکار مهاجرت می‌شوند. شکل
-مسطح زیر فقط نمونهٔ «پیش از مهاجرت» است؛ برای همهٔ تنظیمات جدید، شکل
-جداگانهٔ هر محیط اجرا را به کار ببر.
-
-**پیش از مهاجرت (ساختار مسطح؛ فقط برای مهاجرت):**
-
-```jsonc
-{
- "historian": {
- "model": "provider/model-id",
- "thinking_level": "medium"
- }
-}
-```
-
-**پس از مهاجرت (ساختار جداگانه برای هر محیط اجرا):**
-
-```jsonc
-{
- "historian": {
- "opencode": { "model": "provider/model-id" },
- "pi": {
- "model": "provider/model-id",
- "thinking_level": "medium"
- },
- "omp": {
- "model": "opencode/provider-model-id",
- "thinking_level": "auto"
- }
- }
-}
-```
-
-OMP از مقادیر `thinking_level` بومی Pi استفاده می‌کند. اگر `historian.omp` یا `dreamer.omp` وجود نداشته باشد، OMP از بلوک متناظر `pi` استفاده می‌کند؛ بنابراین تنظیمات سازگار با Pi به مهاجرت نیاز ندارند. اگر بلوک OMP را صریحاً تعریف کنی، همان ملاک است، حتی اگر در آن مدلی ننوشته باشی.
-
-تنظیمات کاربر در macOS/Linux اینجاست: `~/.config/cortexkit/magic-context.jsonc` و در Windows اینجاست: `%USERPROFILE%\.config\cortexkit\magic-context.jsonc` (یا اگر تنظیم شده باشد، `$XDG_CONFIG_HOME/cortexkit/magic-context.jsonc`). کاربران OpenCode Desktop می‌توانند از ویرایشگر تنظیمات داشبورد استفاده کنند یا فایل را دستی ویرایش کنند؛ نسخهٔ Desktop راهنمای تنظیم خط فرمان را ندارد.
-
-**Pi:** `npx @cortexkit/magic-context@latest setup --harness pi` (نیازمند Pi `>= 0.74.0`). افزونهٔ Pi همان پایگاه دادهٔ OpenCode را به‌کار می‌برد؛ خاطره‌ها و embeddingهای پروژه در هر دو محیط مشترک‌اند.
-
-**Oh My Pi (OMP):** `npx @cortexkit/magic-context@latest setup --harness omp` (نیازمند OMP `>= 17.1.7`). فرایند تنظیم افزونهٔ سازگار با Pi را از راه `omp plugin` نصب می‌کند، فشرده‌سازی بومی و حافظهٔ خودکار OMP را خاموش می‌کند و به پروفایل‌های OMP، `PI_CODING_AGENT_DIR` و ساختارهای ازپیش‌آمادهٔ XDG احترام می‌گذارد.
-
-**عیب‌یابی:** `npx @cortexkit/magic-context@latest doctor` محیط‌های اجرایی را خودکار پیدا می‌کند، ناسازگاری‌های ویژهٔ هر میزبان را بررسی می‌کند، ثبت افزونه و یکپارچگی پایگاه داده را می‌سنجد و هرچه بتواند برطرف می‌کند. برای ساخت گزارش آمادهٔ ارسال، `--issue` را اضافه کن.
-
-در پروژه‌ای تازه یا پروژه‌ای که مدت‌ها در جریان بوده یکسان کار می‌کند: نصب کن، محیط اجرا را دوباره راه‌اندازی کن و Magic Context از همان لحظه شروع به ثبت زمینه می‌کند. نشست‌های OpenCode، Pi یا OMP پیش از نصب را به‌صورت عطف‌به‌ماسبق وارد حافظه نمی‌کند.
-
-
-سازگاری با دیگر افزونه‌های مدیریت زمینه
-
-
-
-Magic Context مدیریت زمینه را از ابتدا تا انتها به‌عهده می‌گیرد؛ اگر افزونهٔ دیگری همین کار را انجام دهد، **خودش را غیرفعال می‌کند**. اجرای هم‌زمان دو مدیر زمینه تاریخچه را دوبار فشرده می‌کند و کش پرامپت را به‌هم می‌زند. هنگام راه‌اندازی موارد زیر را بررسی می‌کند. ابزار تنظیم و `doctor` برای رفع هر مورد کمک می‌کنند؛ تا زمان رفع آن‌ها، Magic Context برای ایمنی خاموش می‌ماند و دلیلش را نشان می‌دهد:
-
-- **فشرده‌سازی داخلی OpenCode** (`compaction.auto` / `compaction.prune`) — Magic Context جای آن را می‌گیرد و ابزار تنظیم خاموشش می‌کند.
-- **فشرده‌سازی بومی OMP** (`compaction.enabled`) — Magic Context جای آن را می‌گیرد و تنظیم OMP آن را به‌شکل تراکنشی خاموش می‌کند.
-- **حافظهٔ خودکار OMP** (`memory.backend`) — تزریق‌کنندهٔ حافظهٔ دوم، بازیابی و نگهداشت را تکراری می‌کند. تنظیم OMP آن را روی `off` می‌گذارد؛ داده‌های موجود حذف نمی‌شوند.
-- **DCP** (`opencode-dcp`) — افزونه‌ای جداگانه برای هرس زمینه است. این دو با هم اجرا نمی‌شوند؛ آن را از فهرست `plugin` حذف کن.
-- **oh-my-opencode (OMO)** — فرایند تنظیم پیشنهاد می‌دهد سه hook هم‌پوشان را خاموش کنی:
- - `preemptive-compaction` — فشرده‌سازی‌ای را آغاز می‌کند که با عامل تاریخ‌نگار تداخل دارد.
- - `context-window-monitor` — هشدارهای مصرف زمینه را تزریق می‌کند و با یادآوری‌های Magic Context هم‌پوشانی دارد.
- - `anthropic-context-window-limit-recovery` — فشرده‌سازی اضطراری‌ای را اجرا می‌کند که عامل تاریخ‌نگار را دور می‌زند.
-
-هر زمان خواستی `npx @cortexkit/magic-context@latest doctor` را اجرا کن تا دوباره بررسی و اصلاح خودکار انجام شود.
-
-
-
----
-
-## بخشی از CortexKit
-
-مغز از یک اندام تشکیل نشده است؛ عامل برنامه‌نویس توانمند هم همین‌طور.
-
-**CortexKit** خانواده‌ای از افزونه‌هاست که هرکدام از ناحیه‌ای متفاوت در مغز الهام گرفته‌اند. یکی را نصب کن تا عاملت کاربلدتر شود؛ هر سه را نصب کن تا مغزی کامل داشته باشد.
-
-| افزونه | ناحیهٔ مغز | کارکرد |
-|---|---|---|
-| **Magic Context** *(همین‌جا هستی)* | هیپوکامپ و لوب گیجگاهی میانی | مدیریت خودکار زمینه و حافظهٔ بلندمدت. نشست‌ها را بی‌وقفه ادامه می‌دهد و دانسته‌های پروژه را در آن‌ها شکل می‌دهد، تثبیت می‌کند و به یاد می‌آورد. |
-| **[AFT](https://github.com/cortexkit/aft)** | قشر حسی‌ـ‌حرکتی | ساختار کد را می‌فهمد و دقیق روی آن عمل می‌کند؛ یک IDE و سیستم‌عامل واقعی برای عامل تو. |
-| **Alfonso** *(به‌زودی)* | قشر پیش‌پیشانی | کنترل اجرایی: کار را برنامه‌ریزی و خرد می‌کند، عامل‌ها و مدل‌ها را برمی‌گزیند و تصمیم می‌گیرد چه زمانی سؤال کند، بررسی کند و commit بزند. |
-
-Magic Context یکی از **سه افزونه‌ای است که به آن‌ها نیاز داری**. Magic Context به یاد می‌سپارد؛ AFT می‌بیند و عمل می‌کند؛ Alfonso تصمیم می‌گیرد. هر سه از یک مخزن CortexKit استفاده می‌کنند، پس حافظه میان محیط‌های اجرا و ابزارها مشترک است.
-
----
-
-## ⚡ مدیریت زمینه
-
-*نشستی بی‌کران که خودش را اداره می‌کند.* هنگام کار، پنجرهٔ زمینه پر می‌شود و راه‌حل معمول، یعنی فشرده‌سازی، عامل را از حرکت می‌اندازد تا همه‌چیز را دوباره بخواند. Magic Context این کار را پیوسته در پس‌زمینه انجام می‌دهد و نشست بدون توقف ادامه پیدا می‌کند.
-
-- **بخش‌بندی تاریخچه با عامل تاریخ‌نگار**: عامل `historian` در پس‌زمینه تاریخچهٔ خام قدیمی را به **محفظه‌های چندسطحی** تبدیل می‌کند؛ خلاصه‌هایی زمان‌مند که جای پیام‌های قدیمی را می‌گیرند. برای هر محفظه امتیاز اهمیت نگه می‌دارد تا پنجرهٔ زنده کوچک بماند و رشتهٔ بحث از دست نرود. خلاصه‌سازی به توان کدنویسی عامل اصلی نیاز ندارد؛ بنابراین می‌توانی تاریخ‌نگار را با مدلی ارزان یا کاملاً محلی اجرا کنی و عامل اصلی را روی بهترین مدل نگه داری.
-- **نمایش با افت تدریجی جزئیات**: محفظه‌ها با دقت مناسب همان لحظه نمایش داده می‌شوند؛ قاعده‌ای قطعی و بدون LLM که خود را با پنجرهٔ زمینهٔ مدل تنظیم می‌کند. تاریخچهٔ قدیمی به‌آرامی کم‌رنگ می‌شود، نه اینکه ناگهان ناپدید شود. چون قاعده قطعی است، یک تاریخچه همیشه به‌شکل یکسان نمایش داده می‌شود.
-- **عامل خودش پیشنهاد می‌دهد چه چیزی حذف شود، یا اصلاً دخالت نمی‌کند**: وقتی کاهش زمینه با هدایت عامل فعال باشد، عامل `ctx_reduce` را فراخوانی می‌کند تا خروجی ابزارهای منسوخ یا پیام‌های بلند را برای حذف علامت‌گذاری کند. حذف‌ها **در صف قرار می‌گیرند و کش را در نظر می‌گیرند**؛ فقط در زمان‌های امن برای کش اعمال می‌شوند تا به آن آسیب نزنند. اگر این قابلیت را خاموش کنی، عامل اصلاً مدیریت زمینه نمی‌کند: خروجی قدیمی با گذشت زمان خودکار کنار می‌رود و فشرده‌سازی تلگرافی اختیاری متن‌های قدیمی‌تر را کوتاه می‌کند.
-- **چیدمان پایدار برای کش**: کارهای پس‌زمینه طوری ساختاربندی شده‌اند که پیشوند ذخیره‌شدهٔ پرامپت را بی‌اعتبار نکنند. کش تا پایان نشست باقی می‌ماند.
-
-نتیجه: یک نشست ماه‌ها ادامه می‌یابد، بدون مکث‌های فشرده‌سازی و با هزینهٔ کم نزد ارائه‌دهندگانی که برای کش قیمت‌گذاری می‌کنند. در TUIِ OpenCode می‌توانی روند را ببینی: نوار کناری زنده، زمینه را بر پایهٔ منبع تفکیک می‌کند، وضعیت عامل تاریخ‌نگار و شمار خاطره‌ها را نشان می‌دهد و پس از هر پیام به‌روز می‌شود.
-
-> *اختیاری (به‌طور پیش‌فرض خاموش):* **فشرده‌سازی تلگرافی متن** با قاعده‌ای قطعی و چندسطحی، متن‌های قدیمی کاربر و دستیار را به‌تدریج کوتاه می‌کند؛ برای نشست‌هایی که کاهش زمینه با هدایت عامل در آن‌ها خاموش است.
-
----
-
-## 🧠 ثبت دانش
-
-*حافظه، بی‌هزینه.* عامل تاریخ‌نگار برای فشرده‌کردن تاریخچه باید همهٔ آن را بخواند. پس در همان گذر، دانسته‌هایی را که باید برای همیشه بمانند—تصمیم‌ها، محدودیت‌ها، قراردادها و مقادیر پیکربندی—بیرون می‌کشد و به **حافظهٔ پروژه** می‌افزاید؛ حافظه‌ای دسته‌بندی‌شده که در همهٔ نشست‌های بعدی همراهت می‌آید. حافظه از کاری که همین حالا انجام می‌دهی ساخته می‌شود.
-
-عامل می‌تواند خاطره‌ها را صریحاً هم ثبت کند، هرچند بیشترشان به‌طور خودکار ذخیره می‌شوند:
-
-- **`ctx_memory`**: دانسته‌های ماندگار میان نشست‌ها را مستقیماً بنویس یا حذف کن؛ دسته‌بندی‌ها محدود و مشخص‌اند (`PROJECT_RULES`, `ARCHITECTURE`, `CONSTRAINTS`, `CONFIG_VALUES`, `NAMING`).
-
-```
-ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for orders.")
-```
-
-> **آگاهی از زمان** *(به‌طور پیش‌فرض روشن)* حس زمان را به عامل می‌دهد: فاصله‌هایی مانند `+2h 15m` میان پیام‌ها و محفظه‌های تاریخ‌دار کمک می‌کنند عامل بفهمد یک رویداد چه‌قدر پیش رخ داده است. برای خاموش‌کردن آن، `temporal_awareness: false` بگذار.
-
----
-
-## 🌙 تثبیت حافظه
-
-*کاری که خواب برای حافظه می‌کند.* عامل **dreamer** اختیاری شب‌ها اجرا می‌شود تا کیفیت حافظه را بالا نگه دارد و برای هر کار نشست فرزندِ موقتی می‌سازد:
-
-- **نقشه‌برداری از خاطره‌ها**: هر خاطره را به فایل‌های پروژه‌ای که پشتیبان آن‌اند پیوند می‌دهد (یا مستقل از فایل علامت می‌زند) تا عامل بررسی بداند چه چیزی را دوباره بسنجد. این کار معمولاً فقط یک بار برای پرکردن داده‌های پیشین انجام می‌شود.
-- **بررسی**: خاطره‌ها را به‌تدریج با کدبیس فعلی (مسیرها، تنظیمات و الگوها) می‌سنجد و واقعیت‌های منسوخ را اصلاح یا حذف می‌کند.
-- **بررسی گسترده**: همهٔ خاطره‌های نگاشت‌شده به فایل را، بدون توجه به دروازهٔ تغییرات، دوباره با کد می‌سنجد تا تغییرات تدریجی‌ای را هم بیابد که بررسی مرحله‌ای از دست می‌دهد.
-- **سامان‌دهی**: کل مخزن خاطره‌ها را می‌کاود تا موارد تکراری را ادغام کند، عبارت‌ها را دقیق‌تر کند و موارد کم‌ارزش یا زائد را بایگانی کند.
-- **دسته‌بندی**: اهمیت، دامنه و امکان اشتراک‌گذاری امن هر خاطره را امتیازدهی می‌کند، بی‌آنکه کش زندهٔ پرامپت را مختل کند.
-- **بازنگری**: از موقعیت‌هایی که مجبور شدی چیزی را اصلاح یا دوباره توضیح دهی درس می‌گیرد و نکتهٔ ماندگار را ثبت می‌کند.
-- **به‌روزرسانی مستندات**: فایل‌های `ARCHITECTURE.md` و `STRUCTURE.md` را بر پایهٔ تغییرات کدبیس به‌روز نگه می‌دارد.
-- **خاطره‌های کاربر**: مشاهده‌های تکرارشونده دربارهٔ شیوهٔ کارت (سبک ارتباط، تمرکز هنگام بازبینی و الگوهای کاری) را در `` ثبت می‌کند تا در هر نشست همراهت باشند.
-- **ارتقای راهنماها**: پرسش‌های تکراری و همیشگی‌ای را که عامل تاریخ‌نگار دیده به راهنماهای ماندگار تبدیل می‌کند.
-- **نوسازی راهنماها**: موضوع راهنماهای منسوخ را با کد فعلی دوباره بررسی و پاسخ‌هایشان را تازه می‌کند.
-- **یادداشت‌های هوشمند**: یادداشت‌های معوقی را که شرط `surface_condition` آن‌ها برقرار شده ارزیابی می‌کند و موارد آماده را نمایش می‌دهد.
-
-از آنجا که عامل رؤیاپرداز هنگام بی‌کاری اجرا می‌شود، مدل‌های محلی—حتی مدل‌های کند—برای آن مناسب‌اند؛ کسی منتظر نمی‌ماند. هر زمان خواستی با `/ctx-dream` اجرايش کن.
-
----
-
-## 🔎 بازیابی
-
-*خاطرهٔ درست، در زمان درست.* در هر نوبت، خاطره‌های فعال پروژه و تاریخچهٔ فشرده‌شدهٔ نشست، خودکار و با حفظ پایداری کش به پرامپت افزوده می‌شوند. عامل در صورت نیاز می‌تواند سراغ این ابزارها برود:
-
-- **`ctx_search`**: با یک پرس‌وجو در **خاطره‌های** پروژه، تاریخچهٔ خام **گفت‌وگوها**، **commitهای git** فهرست‌شده، **یادداشت‌های کنارگذاشته‌شده** و **راهنماهای ارتقایافته** جست‌وجو می‌کند. از embedding معنایی و در صورت نیاز جست‌وجوی تمام‌متن استفاده می‌شود.
-
- ```
- ctx_search(query="why did we pick event sourcing for orders")
- ```
-
-- **`ctx_expand`**: وقتی عامل به جزئیات دقیق نیاز دارد، یک بازه از تاریخچهٔ فشرده را به رونوشت اصلی `U:`/`A:` برمی‌گرداند.
-- **`ctx_note`**: دفترچه‌ای برای نیت‌های معوق. یادداشت‌ها در زمان‌های طبیعی دوباره ظاهر می‌شوند (پس از commitها، اجرای عامل تاریخ‌نگار یا پایان کارهای فهرست‌شده). **یادداشت‌های هوشمند** شرطی باز دارند که عامل رؤیاپرداز پیگیر آن است.
-
-بازیابی هم **میان نشست‌ها** کار می‌کند (نشست تازه همه‌چیز را به ارث می‌برد) و هم **میان محیط‌های اجرا** (خاطره‌ای را در OpenCode بنویس و در Pi یا OMP بازیابی کن).
-
-> **راهنمای جست‌وجوی خودکار** *(به‌طور پیش‌فرض روشن)* در هر نوبت، `ctx_search` را در پس‌زمینه اجرا می‌کند و اگر مورد مرتبطی باشد با اشاره‌ای مبهم آن را به یاد عامل می‌آورد؛ مثل وقتی که یادداشتی را که نوشته‌ای کم‌وبیش به خاطر می‌آوری. فقط تکه‌های فشرده افزوده می‌شوند، نه محتوای کامل. برای خاموش‌کردن آن `memory.auto_search.enabled: false` بگذار. **فهرست‌سازی commitهای git** *(نیازمند فعال‌سازی صریح؛ به‌طور پیش‌فرض خاموش)* تاریخچهٔ پروژه را به منبعی معنایی و اضافه برای `ctx_search` تبدیل می‌کند؛ با `memory.git_commit_indexing.enabled: true` روشنش کن.
-
-### ابزارهای عامل در یک نگاه
-
-| ابزار | بخش | کارکرد |
-|------|-------|-------------|
-| `ctx_reduce` | زمینه | محتوای قدیمیِ برچسب‌خورده را برای حذف در صف می‌گذارد و کش را در نظر می‌گیرد |
-| `ctx_memory` | ثبت دانش | خاطره‌های ماندگار میان نشست‌ها را می‌نویسد یا حذف می‌کند |
-| `ctx_search` | بازیابی | در خاطره‌ها، تاریخچهٔ گفت‌وگو، commitهای git، یادداشت‌ها و راهنماها جست‌وجو می‌کند |
-| `ctx_expand` | بازیابی | یک بازه از تاریخچه را به رونوشت اصلی برمی‌گرداند |
-| `ctx_note` | بازیابی | نیت‌های معوق و یادداشت‌های هوشمندی که عامل رؤیاپرداز ارزیابی می‌کند |
-
----
-
-## فرمان‌ها
-
-| فرمان | توضیح |
-|---------|-------------|
-| `/ctx-status` | نمای عیب‌یابی: برچسب‌ها، حذف‌های در صف، زمان‌ماندگاری کش، وضعیت یادآوری، پیشرفت عامل تاریخ‌نگار، پوشش محفظه‌ها و بودجهٔ تاریخچه |
-| `/ctx-flush` | همهٔ عملیات در صف را بی‌درنگ اجرا می‌کند و از زمان‌ماندگاری کش عبور می‌کند |
-| `/ctx-recomp` | محفظه‌ها را از تاریخچهٔ خام دوباره می‌سازد (بازهٔ `start-end` می‌پذیرد). اگر وضعیت ذخیره‌شده نادرست به‌نظر می‌رسد از آن استفاده کن |
-| `/ctx-wrapup [messages_to_keep]` | تاریخچهٔ زندهٔ قدیمی را فشرده می‌کند و N پیام تازه را خام نگه می‌دارد؛ فشرده‌سازیِ در صف با پیام بعدی مدل نهایی می‌شود |
-| `/ctx-dream` | نگهداشت عامل رؤیاپرداز را به‌درخواست اجرا می‌کند: بازبینی حافظه، مستندات، یادداشت‌های هوشمند و نمایهٔ کاربر |
-| `/ctx-embed` | وضعیت embedding را نشان می‌دهد یا embedding محفظه‌های تاریخچه را آغاز/متوقف می‌کند (`start` \| `pause`) |
-
----
-
-## برنامهٔ دسکتاپ
-
-یک برنامهٔ دسکتاپ مکمل برای مرور و مدیریت وضعیت Magic Context بیرون از محیط خط فرمان.
-
-
-
-- **مرورگر خاطره‌ها**: خاطره‌های پروژه را بر پایهٔ دسته و پروژه جست‌وجو، فیلتر و ویرایش کن.
-- **تاریخچهٔ نشست**: محفظه‌ها و یادداشت‌های هر نشست را با پیمایش زمانی مرور کن.
-- **عیب‌یابی کش**: خط زمانی زندهٔ برخورد/عدم‌برخورد کش و تشخیص علت بی‌اعتبارشدن آن.
-- **مدیریت عامل رؤیاپرداز**: تاریخچهٔ اجراهای عامل را ببین، اجرا را آغاز کن و نتیجهٔ کارها را بررسی کن.
-- **ویرایشگر تنظیمات**: همهٔ تنظیمات را با فرم ویرایش کن، از جمله زنجیره‌های جایگزین مدل.
-- **نمایشگر گزارش‌ها**: گزارش‌ها را هم‌زمان با ثبت‌شدن ببین و در آن‌ها جست‌وجو کن.
-
-این برنامه مستقیماً پایگاه دادهٔ SQLite مربوط به Magic Context را می‌خواند؛ به سرور یا API اضافی نیاز ندارد و به‌روزرسانی خودکار در آن تعبیه شده است.
-
----
-
-## پیکربندی
-
-تنظیمات در `magic-context.jsonc` قرار دارند. بیشترشان پیش‌فرض‌های مناسبی دارند، اما مدل عامل تاریخ‌نگارِ محیط اجرایی فعال (`historian.opencode.model`، `historian.pi.model` یا `historian.omp.model`) برای فشرده‌سازی تاریخچه ضروری است. تنظیمات پروژه روی تنظیمات سراسری کاربر اعمال می‌شوند. برای مرجع کامل—از تنظیم زمان‌ماندگاری کش و آستانه‌های اجرا برای هر مدل تا انتخاب مدل‌های تاریخ‌نگار و رؤیاپرداز، ارائه‌دهندگان embedding، تنظیمات حافظه و پیش‌تنظیم‌های سطح پرامپت (`full`/`light`)—به **[CONFIGURATION.md](../../CONFIGURATION.md)** یا **[مرجع پیکربندی در docs.cortexkit.io](https://docs.cortexkit.io/magic-context/reference/configuration/)** مراجعه کن.
-
-> **نکته دربارهٔ تنظیمات هر مدل:** `prompt_surface.models` همیشه مسیر بلوک راهنمای تزریق‌شده را تعیین می‌کند. OpenCode 1.x، Pi و OMP توضیحات ابزار را یک‌بار در هر فرایند ثبت می‌کنند (بر پایهٔ `prompt_surface.default`). OpenCode 2 پنج توضیح `ctx_*` را در هر درخواست و بر پایهٔ مدل پیش‌نویس بازنویسی می‌کند.
-
-**مسیرهای پیکربندی** (یک مسیر مشترک CortexKit؛ تنظیم پروژه بر تنظیم کاربر اولویت دارد):
-1. `/.cortexkit/magic-context.jsonc`
-2. `~/.config/cortexkit/magic-context.jsonc`
-
-از نسخهٔ قدیمی‌تر ارتقا می‌دهی؟ تنظیمات فعلی در نخستین اجرا خودکار به این مسیر منتقل می‌شوند و در محل قبلی نشانهٔ `.MOVED_READPLEASE` باقی می‌ماند.
-
-### پروفایل مدل برای مخزن‌های کاری و شخصی
-
-اگر برای مخزن‌های شخصی و کاری از مجموعه‌مدل‌های جداگانه برای عامل‌های پس‌زمینه استفاده می‌کنی، پروفایل‌ها را در تنظیمات کاربر تعریف کن و در هر مخزن کاری نام پروفایل را انتخاب کن:
-
-```jsonc
-// ~/.config/cortexkit/magic-context.jsonc
-{
- "profile": "personal",
- "profiles": {
- "personal": { "historian": { "opencode": { "model": "anthropic/claude-sonnet-4-6" } } },
- "work": { "historian": { "opencode": { "model": "openai/gpt-5.2-codex" } } }
- }
-}
-
-// /.cortexkit/magic-context.jsonc
-{ "profile": "work" }
-```
-
-این همان الگوی جداسازی مخزن‌های کاری از شخصی است که kagbodji درخواست کرده بود. پروفایل‌ها فقط انتخاب مدل عامل‌های پس‌زمینه را جایگزین می‌کنند و تنظیمات پایه‌ای را که در آن‌ها نیامده حفظ می‌کنند؛ تعریفشان فقط در تنظیمات کاربر ممکن است. پروژه می‌تواند یک پروفایل شناخته‌شدهٔ کاربر را انتخاب کند، اما نمی‌تواند محتوای آن را تعیین کند. برای نمونهٔ کامل OpenCode/Pi/OMP، رفتار جایگزین و مرز اعتماد، [CONFIGURATION.md](../../CONFIGURATION.md#per-repository-model-profiles) را ببین.
-
----
-
-## ذخیره‌سازی
-
-همهٔ داده‌های ماندگار در پایگاه دادهٔ SQLite محلی و در مخزن مشترک CortexKit نگه‌داری می‌شوند (`~/.local/share/cortexkit/magic-context/context.db`؛ در Windows مسیر هم‌ارز XDG به‌کار می‌رود؛ پایگاه‌های دادهٔ قدیمی داخل پوشهٔ OpenCode در نخستین راه‌اندازی مهاجرت می‌کنند). اگر میزبان `XDG_DATA_HOME` را جدا می‌کند، `MAGIC_CONTEXT_STORAGE_DIR` را روی مسیر مطلق و کامل پوشهٔ ذخیره‌سازی Magic Context بگذار؛ این مقدار صریح بر مسیر برگرفته از XDG اولویت دارد. همهٔ فرایندهایی که از این مخزن مشترک استفاده می‌کنند باید همین مقدار صریح را دریافت کنند. میزبان‌ها متغیر را وقتی صریحاً تنظیم شده باشد منتقل می‌کنند، اما Magic Context آن را از مسیر پیش‌فرض خودش تولید نمی‌کند. این جایگزین فقط پایگاه دادهٔ سمت محیط اجرا را جابه‌جا می‌کند؛ وضعیت daemonِ `subc` برای هر کاربر در محل مشترک خودش می‌ماند. فرایندهایی با نسخه‌های متفاوت، تا وقتی همه به‌روز نشوند، مهاجرت را در پوشهٔ مشترک مسدود می‌کنند. اگر پایگاه داده باز نشود، Magic Context خود را غیرفعال می‌کند و به تو اطلاع می‌دهد. خاطره‌ها به **شناسهٔ پایدار پروژه** که از مخزن به دست می‌آید متصل‌اند؛ بنابراین با پروژه میان worktreeها، cloneها و forkها جابه‌جا می‌شوند و به مسیر یک پوشه وابسته نیستند.
-
-Magic Context در چند مسیر دیگر هم داده می‌نویسد:
-
-| مسیر | محتوا | ماندگاری |
-|---|---|---|
-| `~/.local/share/cortexkit/magic-context/context.db` | پایگاه دادهٔ SQLite: برچسب‌ها، محفظه‌ها، خاطره‌ها و همهٔ داده‌های ماندگار (مسیر هم‌ارز XDG در Windows) | **باید ماندگار بماند.** حذف آن به‌معنای ازدست‌رفتن خاطره‌ها و تاریخچه است. |
-| `~/.local/share/cortexkit/magic-context/models/` | نهانگاه مدل embedding محلی (حدود ۹۰ مگابایت، `Xenova/all-MiniLM-L6-v2` با قالب ONNX) که در نخستین استفاده، اگر embedding محلی روشن باشد، دانلود می‌شود | بهتر است ماندگار بماند وگرنه در هر اجرا دوباره دانلود می‌شود. اگر `embedding.provider` روی `"off"` باشد یا backend از نوع `openai_compatible`/`ollama` تنظیم شده باشد استفاده نمی‌شود. خاموش‌کردن `memory.enabled` هم مانعش نیست، چون تاریخچهٔ نشست همچنان embedding می‌شود. |
-| `$MAGIC_CONTEXT_LOG_PATH` (پیش‌فرض: `${TMPDIR}/opencode/magic-context/magic-context.log`؛ برای Pi از `pi/` استفاده می‌شود) | گزارش عیب‌یابی. با `MAGIC_CONTEXT_LOG_PATH` مسیر دیگری تعیین کن (مثلاً مسیری ماندگار در یک container). | موقت؛ نگه‌داشتنش ضروری نیست. |
-
-**محیط‌های محدود یا موقت (Docker، CI و containerهای دورریختنی):** پوشهٔ `~/.local/share/cortexkit/magic-context/` را روی volume ماندگار mount کن تا پایگاه داده و نهانگاه مدل میان اجراها باقی بمانند. اگر فقط نهانگاه مدل موقت باشد، مدل دوباره دانلود می‌شود؛ اما اگر پایگاه داده موقت باشد، خاطره و تاریخچه انباشته نمی‌شوند. برای حذف کامل دانلود مدلِ حدود ۹۰ مگابایتی، `embedding.provider: "off"` بگذار یا `embedding` را به backend راه‌دور `openai_compatible`/`ollama` وصل کن.
-
----
-
-## تاریخچهٔ ستاره‌ها
-
-
-
-
-
-
-
-
-
----
-
-## توسعه
-
-**پیش‌نیاز:** [Bun](https://bun.sh) نسخهٔ 1.4.0 یا بالاتر
-
-تفاوت‌های Bun 1.3.x در ارزیابی ماژول‌ها و شکل خطاهای resolver ممکن است تغییرات بی‌ارتباط مشارکت‌کنندگان را به خطاهای پرسر‌وصدا در آزمون‌های موازی و ساخت تبدیل کند (مسئله‌های [#445](https://github.com/cortexkit/magic-context/issues/445) و [#446](https://github.com/cortexkit/magic-context/issues/446)). دروازه‌های مخزن پیش از اجرا نسخه را بررسی می‌کنند تا نسخه‌های پشتیبانی‌نشده به‌جای خطاهای نامربوط، پیام نسخهٔ لازم را نشان دهند.
-
-```sh
-bun install # Install dependencies
-bun run build # Build the plugin
-bun run typecheck # Type-check without emitting
-bun test # Run tests
-bun run lint # Lint (Biome)
-bun run format # Format (Biome)
-```
-
-اجرای Dream به سرور فعال OpenCode نیاز دارد (عامل رؤیاپرداز نشست‌های فرزند موقت می‌سازد). برای نگهداشت درخواستی، داخل OpenCode از `/ctx-dream` استفاده کن.
-
-### فهرست آزمون‌های جهش
-
-قبول‌شدن یک آزمون ایمنی به‌تنهایی چیز زیادی را ثابت نمی‌کند، مگر اینکه دیده باشیم هنگام خرابی هم شکست می‌خورد. [`mutations.toml`](../../mutations.toml) فهرست ثبت‌شدهٔ این آزمون‌هاست: هر ردیف عمداً یکی از محافظ‌های کد تولیدی را از کار می‌اندازد و آزمونی را نام می‌برد که باید در نتیجه شکست بخورد؛ این‌طور هیچ محافظی بی‌سروصدا بی‌اثر نمی‌شود. هر ردیف باید جلوی خرابی خاموش و پرهزینه‌ای را بگیرد: بی‌اعتبارشدن کش پرامپت، رد درخواستی که باید به‌شکل fail-closed عمل کند، نقض قرارداد ارتباطی، ناایمنی هنگام crash، ازدست‌رفتن داده یا مجوز نادرست فایل. هر محافظی که باید دقیقاً یک‌بار اجرا شود (مثل lease یا پاک‌سازی compare-and-set) دست‌کم یک ردیف دارد که مسیر واقعی تولید را می‌پیماید. برای سبک و ظاهر ردیفی تعریف نمی‌شود.
-
-اجرای پین‌شدهٔ [`ck-mutate`](https://github.com/cortexkit/commons/tree/7d08e73722fa3e79bbcc2607753978ab768f1c6b/crates/cortexkit-mutate) فهرست را از درخت کاری پاک اجرا می‌کند: اول بررسی می‌کند آزمون نام‌برده موفق است، سپس خرابی را اعمال می‌کند و انتظار دارد آزمون شکست بخورد؛ در پایان فایل منبع را بایت‌به‌بایت برمی‌گرداند.
-
-```sh
-cargo install --locked --git https://github.com/cortexkit/commons --rev 7d08e73722fa3e79bbcc2607753978ab768f1c6b cortexkit-mutate
-bun install --frozen-lockfile
-ck-mutate check # anchors match exactly once; cargo test names exist
-ck-mutate run --all # every row (slow: the Rust rows rebuild mc-module)
-ck-mutate run --diff origin/master # only the rows a change touches
-ck-mutate run --only ts-schema-fence-refuses-newer-database
-```
-
-هر ردیف باید نتیجهٔ CAUGHT بدهد. [`mutations.yml`](../../.github/workflows/mutations.yml) ردیف‌هایی را که pull request (یا push به `train/**`) لمس می‌کند دوباره اجرا می‌کند؛ با هر push به master کل فهرست را اجرا می‌کند و هر شب نیز کل فهرست را با `--broad` می‌سنجد. هنگام اجرای این فرایند هیچ فایلی را با `git checkout` برنگردان: این کار جهش را حذف می‌کند و باعث می‌شود جهش به‌اشتباه زنده‌مانده گزارش شود.
-
-برای افزودن یک ردیف:
-
-1. خط تولیدی‌ای را پیدا کن که خودِ محافظ است و مقدار `old` را از فایل بردار، نه از حافظه. `new` را کوچک‌ترین تغییری انتخاب کن که محافظت را حذف کند (`if (false)`، `return true` یا حذف یک شرط)، نه تغییری که کامپایل را خراب کند.
-2. آزمونی را پیدا کن که باید این جهش را بگیرد. تغییر را دستی اعمال کن، فایل آزمون را اجرا کن و مطمئن شو آزمون به‌دلیل همان محافظ ازکارافتاده شکست می‌خورد؛ بعد فایل را برگردان. اگر هیچ آزمونی شکست نخورد، این یک یافته است: اول در commit جداگانه آزمون مفقود را اضافه کن.
-3. ردیف را اضافه کن. آزمون‌های Bun از نوع `command` هستند: یک ردیف موجود را کپی کن و `expect_red` را روی regex لنگرشدهٔ `-t` برای نام کامل آزمون بگذار (نام‌های `describe` و آزمون را با فاصله به هم وصل کن، نویسه‌های ویژهٔ regex را escape کن و هر فاصله را `\s` بنویس). آزمون‌های Rust در mc-module ردیف‌های `command` با اجرای `cargo test --lib -- --exact` هستند؛ هدف‌های کوچک Rust ردیف‌های `cargo` با `only = true` هستند. هرجا آزمون ممکن است به دلیلی نامرتبط هم شکست بخورد، `expect_message` (زیررشته یا `/regex/`) را اضافه کن.
-4. `ck-mutate check` و سپس `ck-mutate run --only ` را اجرا کن. ردیف را فقط وقتی commit کن که نتیجه CAUGHT باشد.
-
-اگر آزمونی دیگر جهش را نگیرد، باید آن را به‌عنوان باگ اصلاح کرد؛ ردیف را حذف نکن.
-
----
-
-### نشانگر بی‌اعتبارشدن کش
-
-`packages/plugin/scripts/cache-bust-sentinel.ts` درخواست‌های اخیر OpenCode و ارائه‌دهنده‌های Pi/OMP را بررسی می‌کند تا موارد بی‌اعتبارشدن کش را پیدا کند که با قراردادهای fold، refresh، reduction، flush، force-band یا provider/system-prompt در Magic Context توضیح داده نمی‌شوند. هر درخواست ارائه‌دهنده را به نزدیک‌ترین رکورد گذر MC، از ۳۰ ثانیه پیش تا ۵ ثانیه پس از درخواست، وصل می‌کند: داده‌های `transform_decisions`/`scheduler_history` در `context.db` و ردّ `mc_pass_trace`/آینهٔ تصمیم در حالت Rust در `store.db`. اگر رکورد گذر متناظر پیدا نشود، `no_mc_pass_row` گزارش می‌شود. پایگاه دادهٔ MC، پایگاه دادهٔ OpenCode، dumpهای افزونهٔ احراز هویت، فایل‌های JSONLِ Pi/OMP و artifactهای `.pi/pi-llm-debugging`/آرایه‌های سرو‌شده را فقط می‌خواند. تنها چیزی که می‌نویسد فایل وضعیتِ آخرین‌مقدار/جلوگیری از تکرار در `~/.local/share/cortexkit/magic-context/cache-bust-sentinel-state.json` (یا مسیر تعیین‌شده با `MAGIC_CONTEXT_STORAGE_DIR`) است.
-
-برای یک اجرای آزمایشی از ریشهٔ مخزن استفاده کن؛ هر پنجرهٔ تازه و توضیح‌داده‌نشدهٔ بی‌اعتبارشدن کش در یک خط JSON چاپ می‌شود:
-
-```sh
-bun packages/plugin/scripts/cache-bust-sentinel.ts --once
-```
-
-برای اجرای یک‌دقیقه‌ای داخلی، `--once` را حذف کن؛ یا آن را هر ۱ تا ۵ دقیقه با cron/launchd اجرا کن. الگوی `packages/plugin/scripts/launchd/com.cortexkit.magic-context.cache-bust-sentinel.plist` هر پنج دقیقه اجرا می‌شود، `--send` را روشن می‌کند، `RunAtLoad=false` دارد و خودکار نصب نمی‌شود. پیش از بارگذاری، جای‌نگهدارهای `__BUN_PATH__`، `__REPO_ROOT__` و `__LOG_DIR__` را عوض کن. نمونهٔ cron:
-
-```cron
-*/5 * * * * cd /path/to/magic-context && /path/to/bun packages/plugin/scripts/cache-bust-sentinel.ts --once --send >> /path/to/cache-bust-sentinel.jsonl 2>> /path/to/cache-bust-sentinel.log
-```
-
-`--send` خروجی آزمایشیِ خط‌به‌خط JSON را به عملیات `agent.deliver` در ماژول `prefrontal-core` تبدیل می‌کند. به‌طور پیش‌فرض از نام نمایشی `mc-cache-bust-sentinel` یک پیام همتای با اولویت بالا در registry به `agent_b613e5cf2ee55b8c` می‌فرستد؛ نشست فرستنده نیز `health-sentinel-mc` و محیط اجرایش `magic-context` ثبت می‌شود. برای انتخاب گیرنده یا نام نمایشی دیگری از `--wake-agent-id` یا `--wake-from-agent` استفاده کن. پاسخ‌های پذیرفته‌شده و در صف، موفق شمرده می‌شوند؛ سفارش تکراریِ ثبت‌شده با همان شناسهٔ تحویل تکراری شمرده می‌شود. رد فرستنده بدون تلاش دوباره برای همان شناسه ثبت می‌شود و پاسخ نامعتبر یا تعارض idempotency اجرا را ناموفق می‌کند. `--connection-file`، `--wake-module-id`، `--wake-agent-id`، `--wake-from-agent`، `--state-file`، `--db` یا `--rust-store` را فقط وقتی به کار ببر که مسیر runtime مربوطه پیش‌فرض نیست.
-
-### نشانگر تأخیر تبدیل
-
-`packages/plugin/scripts/transform-latency-sentinel.ts` گزارش‌های Magic Context در OpenCode و Pi و گزارش تاریخ‌دار ماژول `ck-mc` را فقط می‌خواند. هر بار اجرا حداکثر ۴ مگابایت **بایت تازه برای هر فایل** می‌خواند؛ watermarkهای inode/اندازه چرخش فایل را تشخیص می‌دهند و خط‌های ناقص انتهایی را دوباره می‌خوانند. تنها نوشتهٔ ماندگارش `transform-latency-sentinel-state.json` در پوشهٔ ذخیره‌سازی Magic Context است. هشدارهای هر نشست این موارد را پوشش می‌دهند: p90 بیش از ۵ ثانیه در ده گذر طی ده دقیقه، هر گذر بیش از ۱۲ ثانیه، پایان مهلت انتقال/ماژول/همگام‌سازی وضعیت، گذارهای park در Rust، ردها و افزایش پیوستهٔ زمان ماژول در دست‌کم بیست گذر. هشدار هم‌نوع دوباره فقط با افزایش شدت ۵۰درصدی یا پس از شش ساعت ارسال می‌شود. هر هشدار شناسهٔ نشست، نام فهرست همتاها (اگر موجود نباشد، شناسهٔ پروژه در `session_projects`)، p50/p90/بیشینهٔ گذر، میانهٔ زمان ماژول و افزونه و میانگین بار سیستم را دارد. `loadSampledAt` زمان نمونه‌برداری بار را ثبت می‌کند؛ بازپخش تاریخی نمی‌تواند بار تاریخی دستگاه را بازسازی کند.
-
-اجرای آزمایشی بدون ارسال: `bun packages/plugin/scripts/transform-latency-sentinel.ts --once`. برای بررسی گذشته از `--replay --since 2026-09-28T17:00:00Z --until 2026-09-28T18:15:00Z` استفاده کن؛ بازپخش داده را در قطعه‌های ۴ مگابایتی می‌خواند، بی‌آنکه watermark بنویسد یا هشداری بفرستد. `--send` در هر اجرا با `agent.deliver` یک پیام همتای با اولویت بالا می‌فرستد. الگوی launchd پنج‌دقیقه‌ای در `packages/plugin/scripts/launchd/com.cortexkit.magic-context.transform-latency-sentinel.plist` از `--once --send` و `RunAtLoad=false` استفاده می‌کند؛ مانند نشانگرهای دیگر، خودکار نصب نمی‌شود. پیش از ثبت به‌عنوان LaunchAgent، `__BUN_PATH__`، `__REPO_ROOT__` و `__LOG_DIR__` را با مسیر فایل اجرایی bun، ریشهٔ مخزن و پوشهٔ گزارش‌ها جایگزین کن. برای مسیرهای غیراستاندارد از `--opencode-log`، `--pi-log`، `--module-log`، `--db`، `--peer-db`، `--state-file` و `--connection-file` استفاده کن.
-
-### نشانگر شکست عامل رؤیاپرداز و تاریخ‌نگار
-
-`packages/plugin/scripts/subagent-failure-sentinel.ts` ردیف‌های کامل‌شدهٔ `subagent_invocations` را از `context.db` با اتصال فقط‌خواندنی SQLite و مهلت انتظار قفل سه‌ثانیه‌ای می‌خواند. وضعیت‌های `failed` و `timed_out` را شکست می‌شمارد؛ `empty` و `aborted` جداگانه شمرده می‌شوند. این ابزار طی هفت روز یک دستهٔ خطای تازه (عامل فرزند، کار، خطای نرمال‌شده)، کاری با دست‌کم هشت اجرا و سهم شکست حداقل ۲۵٪ در ۲۴ ساعت، یا دسته‌ای را گزارش می‌کند که شمارش آن نسبت به ۲۴ ساعت پیش دو برابر شده باشد. شناسه‌ها، عددها، مدت‌ها و مسیرهای متغیر خطاها به دسته‌های باثبات تبدیل می‌شوند. هر اجرای پنج‌دقیقه‌ای حداکثر ۵۰۱ ردیف تازه و ۵٬۰۰۱ ردیف تاریخچهٔ اخیر را می‌خواند (شامل ردیف‌های مرزی)؛ اگر تاریخچه ناقص باشد، قواعدی که بازهٔ کاملشان قابل سنجش نیست اجرا نمی‌شوند. تنها نوشتهٔ محلی فایل watermark/جلوگیری از تکرار `subagent-failure-sentinel-state.json` در پوشهٔ ذخیره‌سازی Magic Context است. ادامهٔ watermark بر پایهٔ `(ended_at, id)` انجام می‌شود؛ ارسال هشدار برای شش ساعت متوقف می‌ماند، مگر اینکه شمار دسته ۵۰٪ رشد کند. آغاز و خلاصهٔ اجرا، از جمله تعداد ردیف‌های بررسی‌شده و محدودبودن اسکن، ثبت می‌شود. در هر اجرا حداکثر یک پیام بیدارباش می‌فرستد که قاعده، کار، دسته، شمار دسته، سهم شکست، نمونهٔ خطا، تازه‌ترین شناسهٔ نشست و تعداد وضعیت‌های empty/aborted را فهرست می‌کند.
-
-اجرای آزمایشی با `bun packages/plugin/scripts/subagent-failure-sentinel.ts --once` انجام می‌شود؛ برای انتخاب پایگاه دادهٔ fixture و فایل وضعیت از `--db` و `--state-file` استفاده کن. بدون `--once` هر دقیقه تکرار می‌شود. الگوی launchd در `packages/plugin/scripts/launchd/com.cortexkit.magic-context.subagent-failure-sentinel.plist` هر پنج دقیقه با `--once --send` اجرا می‌شود، `RunAtLoad=false` دارد و گزارش‌های JSONL/stdout و stderr را جداگانه ذخیره می‌کند. `--send` همان پیام همتای `agent.deliver` با اولویت بالای `prefrontal-core` را، مانند نشانگر بی‌اعتبارشدن کش، به عامل اصلی Magic Context می‌فرستد. برای نصب و فعال‌سازی در macOS، (این کار خودکار انجام نمی‌شود) فرمان‌های زیر را **از ریشهٔ مخزن** اجرا کن:
-
-```sh
-mkdir -p "$HOME/Library/LaunchAgents" "$HOME/Library/Logs/cortexkit"
-sed -e "s|__BUN_PATH__|$(command -v bun)|g" \
- -e "s|__REPO_ROOT__|$(pwd -P)|g" \
- -e "s|__LOG_DIR__|$HOME/Library/Logs/cortexkit|g" \
- packages/plugin/scripts/launchd/com.cortexkit.magic-context.subagent-failure-sentinel.plist \
- > "$HOME/Library/LaunchAgents/com.cortexkit.magic-context.subagent-failure-sentinel.plist"
-launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.cortexkit.magic-context.subagent-failure-sentinel.plist"
-```
-
----
-## مشارکت
-
-گزارش باگ و pull request پذیرفته می‌شود. پیش از شروع، [CONTRIBUTING.md](../../CONTRIBUTING.md) را دربارهٔ قواعد مسئله‌های تأییدشده و پوشش محیط‌های اجرا بخوان.
-
----
-
-## مجوز
-
-[MIT](../../LICENSE)
+[English](../../README.md) · [简体中文](README.zh-CN.md) · [繁體中文](README.zh-TW.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Dansk](README.da.md) · [日本語](README.ja.md) · [Polski](README.pl.md) · [Русский](README.ru.md) · [Bosanski](README.bs.md) · [العربية](README.ar.md) · **فارسی** · [Norsk](README.nb.md) · [Português (Brasil)](README.pt-BR.md) · [ไทย](README.th.md) · [Türkçe](README.tr.md) · [Українська](README.uk.md) · [বাংলা](README.bn.md) · [Ελληνικά](README.el.md) · [Tiếng Việt](README.vi.md)
+
+*این نسخهٔ فارسی بر پایهٔ README انگلیسی نوشته شده است؛ README انگلیسی مرجع اصلی پروژه است و ممکن است به‌روزتر باشد.*
+
+
Magic Context
+
+
+ زمینه‌ای بی‌کران. حافظه‌ای که خودش را اداره می‌کند. یک نشست، برای همیشه.
+ هیپوکامپِ عامل‌های برنامه‌نویس و بخشی از CortexKit.
+
+
+
+
+
+
+
+
+
+
+
+
+ برای یک کار برنامه‌نویس استخدام نمی‌کنی که به‌محض تحویل کار اخراجش کنی. با عاملت هم همین کار را نکن.
+
+
+---
+
+## Magic Context چیست؟
+
+برای رفع یک باگ، برنامه‌نویس استخدام نمی‌کنی و درست بعد از تحویل راه‌حل اخراجش کنی. آدم‌های خوب را نگه می‌داری. آن‌ها کدبیس را یاد می‌گیرند، دلیل تصمیم‌ها را به خاطر می‌سپارند و هر هفته کاربلدتر می‌شوند.
+
+عامل‌های برنامه‌نویس وضع معکوسی دارند. هر کار مثل استخدام فردی تازه است که چیزی از پروژه‌ات نمی‌داند؛ پایان هر نشست هم او را کنار می‌گذاری و از صفر شروع می‌کنی. وسط کار حتی با مکث‌های «فشرده‌سازی» (compaction) روبه‌رو می‌شوند؛ مکث‌هایی که جریان کار را می‌شکنند و بی‌سروصدا دانسته‌های عامل را از بین می‌برند. این همان فراموشی پیش‌گستر (anterograde amnesia) است که با آسیب‌دیدن هیپوکامپ رخ می‌دهد.
+
+Magic Context برای عامل‌ها هیپوکامپی فراهم می‌کند. این ابزار **هیپوکامپِ** عامل‌های برنامه‌نویس است: بخشی از مغز که خاطره‌ها را شکل می‌دهد، تثبیت می‌کند و به یاد می‌آورد؛ و همهٔ این کارها را در پس‌زمینه انجام می‌دهد. هر نشست از پیمانکاری موقت به هم‌تیمی‌ای بلندمدت تبدیل می‌شود که از آغاز تا پایان پروژه همراهت بوده است:
+
+- **ثبت دانش.** وقتی عامل تاریخ‌نگار (historian) تاریخچه را خلاصه می‌کند، دانسته‌های ماندگار (تصمیم‌ها، محدودیت‌ها و قراردادها) را جدا می‌کند و در حافظهٔ پروژه می‌گذارد. از کاری که همین حالا انجام می‌دهی، بی‌هزینه یک سامانهٔ حافظه به دست می‌آوری.
+- **تثبیت حافظه.** شب‌ها عامل‌های رؤیاپرداز (dreamer) کاری را انجام می‌دهند که خواب برای تو می‌کند: خاطره‌ها را با کدبیس می‌سنجند، موارد تکراری و منسوخ را سامان می‌دهند و دانسته‌های پرتکرار را ارتقا می‌دهند.
+- **بازیابی.** در هر نوبت، خاطره‌های مناسب خودکار ظاهر می‌شوند و عامل می‌تواند هر زمان که بخواهد میان خاطره‌ها، گفت‌وگوهای پیشین و تاریخچهٔ git جست‌وجو کند؛ در نشست‌های مختلف و در OpenCode، Pi و OMP.
+
+دو وعده: عاملت **برای مدیریت زمینه از کار نمی‌ایستد** (نه مکث فشرده‌سازی دارد و نه جریان کارش می‌شکند) و **هیچ‌وقت فراموش نمی‌کند**.
+
+برای هر پروژه یک نشست راه بینداز و هفته‌ها، ماه‌ها یا سال‌ها ادامه‌اش بده. عامل همه‌چیزهایی را که با هم ساخته‌اید به خاطر می‌سپارد.
+
+---
+
+## شروع سریع
+
+```bash
+npx @cortexkit/magic-context@latest setup
+```
+
+ابزار تنظیم به‌طور خودکار محیط‌های اجرایی نصب‌شده‌ات (OpenCode، Pi، OMP یا هر ترکیبی از آن‌ها) را پیدا و پیکربندی می‌کند: افزونه را ثبت می‌کند، فشرده‌سازی داخلی میزبان را خاموش می‌کند، برای عامل‌های تاریخ‌نگار و رؤیاپرداز در انتخاب مدل کمک می‌کند و ناسازگاری با افزونه‌های دیگر مدیریت زمینه را برطرف می‌کند. پس از آن محیط اجرا را دوباره راه‌اندازی کن تا Magic Context بارگذاری شود. برای انتخاب یک محیط مشخص از `--harness opencode`، `--harness pi` یا `--harness omp` استفاده کن.
+
+> **چرا فشرده‌سازی داخلی را خاموش کنیم؟** Magic Context خودش زمینه را مدیریت می‌کند. فشرده‌سازی میزبان با عملیاتِ به‌تعویق‌افتاده و آگاه از کش تداخل می‌کند و تاریخچه را دوبار فشرده می‌سازد.
+
+### تنظیم دستی (OpenCode)
+
+اگر نمی‌توانی راهنمای تنظیم را اجرا کنی، این را به `opencode.jsonc` اضافه کن:
+
+```jsonc
+{
+ "plugin": ["@cortexkit/opencode-magic-context@latest"],
+ "compaction": { "auto": false, "prune": false }
+}
+```
+
+> **به‌روزرسانی افزونه:** پیش از راه‌اندازی مجدد، ورودی سادهٔ افزونه به نسخهٔ دقیق دانلودشده سنجاق می‌شود تا OpenCode بستهٔ فعال را وسط نشست حذف نکند. Magic Context مشخصات دقیقی را که به‌روزرسان تنظیمات نوشته ثبت می‌کند و در بررسی‌های بعدی همان نسخهٔ تحت مدیریت به‌روزرسان را جلو می‌برد. هر مشخصات دقیق دیگری که خودت تعیین کرده باشی ثابت می‌ماند. چون منشأ تنظیم با رشتهٔ دقیق مشخصات سنجیده می‌شود، اگر دستی همان رشته‌ای را وارد کنی که به‌روزرسان آخرین بار نوشته، تشخیص آن از نسخهٔ سنجاق‌شدهٔ به‌روزرسان ممکن نیست و نسخه در بررسی بعدی جلو می‌رود. برای انصراف، `auto_update: false` بگذار یا نسخهٔ دقیق دیگری را سنجاق کن. برای استفادهٔ عمدی از نسخهٔ شناور، `@latest` را صریح بنویس (OpenCode ممکن است بستهٔ فعالِ بدون نسخهٔ سنجاق‌شده را وسط نشست حذف کند).
+
+سپس `magic-context.jsonc` را با تنظیم عامل تاریخ‌نگار OpenCode بساز:
+
+```jsonc
+{
+ "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
+ "historian": {
+ "opencode": { "model": "provider/model-id" }
+ }
+}
+```
+
+- **الزامی:** `historian.opencode.model` باید یک شناسهٔ واقعی به‌شکل `provider/model-id` باشد. اگر نباشد، افزونه بارگذاری می‌شود اما اجرای تاریخ‌نگار شکست می‌خورد، تاریخچهٔ قدیمی خلاصه نمی‌شود و پس از خطاهای تکراری پیام `Magic Context — history comparting needs attention` نمایش داده می‌شود.
+- **اختیاری:** بلوک مدل/غیرفعال‌سازی `dreamer`. اگر نمی‌خواهی تثبیت دوره‌ای حافظه انجام شود، آن را حذف کن.
+- **اختیاری:** `embedding`. اگر حذفش کنی از مدل محلی `Xenova/all-MiniLM-L6-v2` استفاده می‌شود. خاموش‌کردن embedding جست‌وجوی معنایی یا مبتنی بر بردارسازی را غیرفعال می‌کند؛ جست‌وجوی واژه‌ای و مدیریت زمینه همچنان کار می‌کنند.
+
+### مهاجرت از تنظیمات مسطح مدل (پیش و پس از مهاجرت)
+
+تنظیمات مسطح مدل در نخستین بار خواندن پیکربندی به‌طور خودکار مهاجرت می‌شوند. شکل
+مسطح زیر فقط نمونهٔ «پیش از مهاجرت» است؛ برای همهٔ تنظیمات جدید، شکل
+جداگانهٔ هر محیط اجرا را به کار ببر.
+
+**پیش از مهاجرت (ساختار مسطح؛ فقط برای مهاجرت):**
+
+```jsonc
+{
+ "historian": {
+ "model": "provider/model-id",
+ "thinking_level": "medium"
+ }
+}
+```
+
+**پس از مهاجرت (ساختار جداگانه برای هر محیط اجرا):**
+
+```jsonc
+{
+ "historian": {
+ "opencode": { "model": "provider/model-id" },
+ "pi": {
+ "model": "provider/model-id",
+ "thinking_level": "medium"
+ },
+ "omp": {
+ "model": "opencode/provider-model-id",
+ "thinking_level": "auto"
+ }
+ }
+}
+```
+
+OMP از مقادیر `thinking_level` بومی Pi استفاده می‌کند. اگر `historian.omp` یا `dreamer.omp` وجود نداشته باشد، OMP از بلوک متناظر `pi` استفاده می‌کند؛ بنابراین تنظیمات سازگار با Pi به مهاجرت نیاز ندارند. اگر بلوک OMP را صریحاً تعریف کنی، همان ملاک است، حتی اگر در آن مدلی ننوشته باشی.
+
+تنظیمات کاربر در macOS/Linux اینجاست: `~/.config/cortexkit/magic-context.jsonc` و در Windows اینجاست: `%USERPROFILE%\.config\cortexkit\magic-context.jsonc` (یا اگر تنظیم شده باشد، `$XDG_CONFIG_HOME/cortexkit/magic-context.jsonc`). کاربران OpenCode Desktop می‌توانند از ویرایشگر تنظیمات داشبورد استفاده کنند یا فایل را دستی ویرایش کنند؛ نسخهٔ Desktop راهنمای تنظیم خط فرمان را ندارد.
+
+**Pi:** `npx @cortexkit/magic-context@latest setup --harness pi` (نیازمند Pi `>= 0.74.0`). افزونهٔ Pi همان پایگاه دادهٔ OpenCode را به‌کار می‌برد؛ خاطره‌ها و embeddingهای پروژه در هر دو محیط مشترک‌اند.
+
+**Oh My Pi (OMP):** `npx @cortexkit/magic-context@latest setup --harness omp` (نیازمند OMP `>= 17.1.7`). فرایند تنظیم افزونهٔ سازگار با Pi را از راه `omp plugin` نصب می‌کند، فشرده‌سازی بومی و حافظهٔ خودکار OMP را خاموش می‌کند و به پروفایل‌های OMP، `PI_CODING_AGENT_DIR` و ساختارهای ازپیش‌آمادهٔ XDG احترام می‌گذارد.
+
+**عیب‌یابی:** `npx @cortexkit/magic-context@latest doctor` محیط‌های اجرایی را خودکار پیدا می‌کند، ناسازگاری‌های ویژهٔ هر میزبان را بررسی می‌کند، ثبت افزونه و یکپارچگی پایگاه داده را می‌سنجد و هرچه بتواند برطرف می‌کند. برای ساخت گزارش آمادهٔ ارسال، `--issue` را اضافه کن.
+
+در پروژه‌ای تازه یا پروژه‌ای که مدت‌ها در جریان بوده یکسان کار می‌کند: نصب کن، محیط اجرا را دوباره راه‌اندازی کن و Magic Context از همان لحظه شروع به ثبت زمینه می‌کند. نشست‌های OpenCode، Pi یا OMP پیش از نصب را به‌صورت عطف‌به‌ماسبق وارد حافظه نمی‌کند.
+
+
+سازگاری با دیگر افزونه‌های مدیریت زمینه
+
+
+
+Magic Context مدیریت زمینه را از ابتدا تا انتها به‌عهده می‌گیرد؛ اگر افزونهٔ دیگری همین کار را انجام دهد، **خودش را غیرفعال می‌کند**. اجرای هم‌زمان دو مدیر زمینه تاریخچه را دوبار فشرده می‌کند و کش پرامپت را به‌هم می‌زند. هنگام راه‌اندازی موارد زیر را بررسی می‌کند. ابزار تنظیم و `doctor` برای رفع هر مورد کمک می‌کنند؛ تا زمان رفع آن‌ها، Magic Context برای ایمنی خاموش می‌ماند و دلیلش را نشان می‌دهد:
+
+- **فشرده‌سازی داخلی OpenCode** (`compaction.auto` / `compaction.prune`) — Magic Context جای آن را می‌گیرد و ابزار تنظیم خاموشش می‌کند.
+- **فشرده‌سازی بومی OMP** (`compaction.enabled`) — Magic Context جای آن را می‌گیرد و تنظیم OMP آن را به‌شکل تراکنشی خاموش می‌کند.
+- **حافظهٔ خودکار OMP** (`memory.backend`) — تزریق‌کنندهٔ حافظهٔ دوم، بازیابی و نگهداشت را تکراری می‌کند. تنظیم OMP آن را روی `off` می‌گذارد؛ داده‌های موجود حذف نمی‌شوند.
+- **DCP** (`opencode-dcp`) — افزونه‌ای جداگانه برای هرس زمینه است. این دو با هم اجرا نمی‌شوند؛ آن را از فهرست `plugin` حذف کن.
+- **oh-my-opencode (OMO)** — فرایند تنظیم پیشنهاد می‌دهد سه hook هم‌پوشان را خاموش کنی:
+ - `preemptive-compaction` — فشرده‌سازی‌ای را آغاز می‌کند که با عامل تاریخ‌نگار تداخل دارد.
+ - `context-window-monitor` — هشدارهای مصرف زمینه را تزریق می‌کند و با یادآوری‌های Magic Context هم‌پوشانی دارد.
+ - `anthropic-context-window-limit-recovery` — فشرده‌سازی اضطراری‌ای را اجرا می‌کند که عامل تاریخ‌نگار را دور می‌زند.
+
+هر زمان خواستی `npx @cortexkit/magic-context@latest doctor` را اجرا کن تا دوباره بررسی و اصلاح خودکار انجام شود.
+
+
+
+---
+
+## بخشی از CortexKit
+
+مغز از یک اندام تشکیل نشده است؛ عامل برنامه‌نویس توانمند هم همین‌طور.
+
+**CortexKit** خانواده‌ای از افزونه‌هاست که هرکدام از ناحیه‌ای متفاوت در مغز الهام گرفته‌اند. یکی را نصب کن تا عاملت کاربلدتر شود؛ هر سه را نصب کن تا مغزی کامل داشته باشد.
+
+| افزونه | ناحیهٔ مغز | کارکرد |
+|---|---|---|
+| **Magic Context** *(همین‌جا هستی)* | هیپوکامپ و لوب گیجگاهی میانی | مدیریت خودکار زمینه و حافظهٔ بلندمدت. نشست‌ها را بی‌وقفه ادامه می‌دهد و دانسته‌های پروژه را در آن‌ها شکل می‌دهد، تثبیت می‌کند و به یاد می‌آورد. |
+| **[AFT](https://github.com/cortexkit/aft)** | قشر حسی‌ـ‌حرکتی | ساختار کد را می‌فهمد و دقیق روی آن عمل می‌کند؛ یک IDE و سیستم‌عامل واقعی برای عامل تو. |
+| **Alfonso** *(به‌زودی)* | قشر پیش‌پیشانی | کنترل اجرایی: کار را برنامه‌ریزی و خرد می‌کند، عامل‌ها و مدل‌ها را برمی‌گزیند و تصمیم می‌گیرد چه زمانی سؤال کند، بررسی کند و commit بزند. |
+
+Magic Context یکی از **سه افزونه‌ای است که به آن‌ها نیاز داری**. Magic Context به یاد می‌سپارد؛ AFT می‌بیند و عمل می‌کند؛ Alfonso تصمیم می‌گیرد. هر سه از یک مخزن CortexKit استفاده می‌کنند، پس حافظه میان محیط‌های اجرا و ابزارها مشترک است.
+
+---
+
+## ⚡ مدیریت زمینه
+
+*نشستی بی‌کران که خودش را اداره می‌کند.* هنگام کار، پنجرهٔ زمینه پر می‌شود و راه‌حل معمول، یعنی فشرده‌سازی، عامل را از حرکت می‌اندازد تا همه‌چیز را دوباره بخواند. Magic Context این کار را پیوسته در پس‌زمینه انجام می‌دهد و نشست بدون توقف ادامه پیدا می‌کند.
+
+- **بخش‌بندی تاریخچه با عامل تاریخ‌نگار**: عامل `historian` در پس‌زمینه تاریخچهٔ خام قدیمی را به **محفظه‌های چندسطحی** تبدیل می‌کند؛ خلاصه‌هایی زمان‌مند که جای پیام‌های قدیمی را می‌گیرند. برای هر محفظه امتیاز اهمیت نگه می‌دارد تا پنجرهٔ زنده کوچک بماند و رشتهٔ بحث از دست نرود. خلاصه‌سازی به توان کدنویسی عامل اصلی نیاز ندارد؛ بنابراین می‌توانی تاریخ‌نگار را با مدلی ارزان یا کاملاً محلی اجرا کنی و عامل اصلی را روی بهترین مدل نگه داری.
+- **نمایش با افت تدریجی جزئیات**: محفظه‌ها با دقت مناسب همان لحظه نمایش داده می‌شوند؛ قاعده‌ای قطعی و بدون LLM که خود را با پنجرهٔ زمینهٔ مدل تنظیم می‌کند. تاریخچهٔ قدیمی به‌آرامی کم‌رنگ می‌شود، نه اینکه ناگهان ناپدید شود. چون قاعده قطعی است، یک تاریخچه همیشه به‌شکل یکسان نمایش داده می‌شود.
+- **عامل خودش پیشنهاد می‌دهد چه چیزی حذف شود، یا اصلاً دخالت نمی‌کند**: وقتی کاهش زمینه با هدایت عامل فعال باشد، عامل `ctx_reduce` را فراخوانی می‌کند تا خروجی ابزارهای منسوخ یا پیام‌های بلند را برای حذف علامت‌گذاری کند. حذف‌ها **در صف قرار می‌گیرند و کش را در نظر می‌گیرند**؛ فقط در زمان‌های امن برای کش اعمال می‌شوند تا به آن آسیب نزنند. اگر این قابلیت را خاموش کنی، عامل اصلاً مدیریت زمینه نمی‌کند: خروجی قدیمی با گذشت زمان خودکار کنار می‌رود و فشرده‌سازی تلگرافی اختیاری متن‌های قدیمی‌تر را کوتاه می‌کند.
+- **چیدمان پایدار برای کش**: کارهای پس‌زمینه طوری ساختاربندی شده‌اند که پیشوند ذخیره‌شدهٔ پرامپت را بی‌اعتبار نکنند. کش تا پایان نشست باقی می‌ماند.
+
+نتیجه: یک نشست ماه‌ها ادامه می‌یابد، بدون مکث‌های فشرده‌سازی و با هزینهٔ کم نزد ارائه‌دهندگانی که برای کش قیمت‌گذاری می‌کنند. در TUIِ OpenCode می‌توانی روند را ببینی: نوار کناری زنده، زمینه را بر پایهٔ منبع تفکیک می‌کند، وضعیت عامل تاریخ‌نگار و شمار خاطره‌ها را نشان می‌دهد و پس از هر پیام به‌روز می‌شود.
+
+> *اختیاری (به‌طور پیش‌فرض خاموش):* **فشرده‌سازی تلگرافی متن** با قاعده‌ای قطعی و چندسطحی، متن‌های قدیمی کاربر و دستیار را به‌تدریج کوتاه می‌کند؛ برای نشست‌هایی که کاهش زمینه با هدایت عامل در آن‌ها خاموش است.
+
+---
+
+## 🧠 ثبت دانش
+
+*حافظه، بی‌هزینه.* عامل تاریخ‌نگار برای فشرده‌کردن تاریخچه باید همهٔ آن را بخواند. پس در همان گذر، دانسته‌هایی را که باید برای همیشه بمانند—تصمیم‌ها، محدودیت‌ها، قراردادها و مقادیر پیکربندی—بیرون می‌کشد و به **حافظهٔ پروژه** می‌افزاید؛ حافظه‌ای دسته‌بندی‌شده که در همهٔ نشست‌های بعدی همراهت می‌آید. حافظه از کاری که همین حالا انجام می‌دهی ساخته می‌شود.
+
+عامل می‌تواند خاطره‌ها را صریحاً هم ثبت کند، هرچند بیشترشان به‌طور خودکار ذخیره می‌شوند:
+
+- **`ctx_memory`**: دانسته‌های ماندگار میان نشست‌ها را مستقیماً بنویس یا حذف کن؛ دسته‌بندی‌ها محدود و مشخص‌اند (`PROJECT_RULES`, `ARCHITECTURE`, `CONSTRAINTS`, `CONFIG_VALUES`, `NAMING`).
+
+```
+ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for orders.")
+```
+
+> **آگاهی از زمان** *(به‌طور پیش‌فرض روشن)* حس زمان را به عامل می‌دهد: فاصله‌هایی مانند `+2h 15m` میان پیام‌ها و محفظه‌های تاریخ‌دار کمک می‌کنند عامل بفهمد یک رویداد چه‌قدر پیش رخ داده است. برای خاموش‌کردن آن، `temporal_awareness: false` بگذار.
+
+---
+
+## 🌙 تثبیت حافظه
+
+*کاری که خواب برای حافظه می‌کند.* عامل **dreamer** اختیاری شب‌ها اجرا می‌شود تا کیفیت حافظه را بالا نگه دارد و برای هر کار نشست فرزندِ موقتی می‌سازد:
+
+- **نقشه‌برداری از خاطره‌ها**: هر خاطره را به فایل‌های پروژه‌ای که پشتیبان آن‌اند پیوند می‌دهد (یا مستقل از فایل علامت می‌زند) تا عامل بررسی بداند چه چیزی را دوباره بسنجد. این کار معمولاً فقط یک بار برای پرکردن داده‌های پیشین انجام می‌شود.
+- **بررسی**: خاطره‌ها را به‌تدریج با کدبیس فعلی (مسیرها، تنظیمات و الگوها) می‌سنجد و واقعیت‌های منسوخ را اصلاح یا حذف می‌کند.
+- **بررسی گسترده**: همهٔ خاطره‌های نگاشت‌شده به فایل را، بدون توجه به دروازهٔ تغییرات، دوباره با کد می‌سنجد تا تغییرات تدریجی‌ای را هم بیابد که بررسی مرحله‌ای از دست می‌دهد.
+- **سامان‌دهی**: کل مخزن خاطره‌ها را می‌کاود تا موارد تکراری را ادغام کند، عبارت‌ها را دقیق‌تر کند و موارد کم‌ارزش یا زائد را بایگانی کند.
+- **دسته‌بندی**: اهمیت، دامنه و امکان اشتراک‌گذاری امن هر خاطره را امتیازدهی می‌کند، بی‌آنکه کش زندهٔ پرامپت را مختل کند.
+- **بازنگری**: از موقعیت‌هایی که مجبور شدی چیزی را اصلاح یا دوباره توضیح دهی درس می‌گیرد و نکتهٔ ماندگار را ثبت می‌کند.
+- **به‌روزرسانی مستندات**: فایل‌های `ARCHITECTURE.md` و `STRUCTURE.md` را بر پایهٔ تغییرات کدبیس به‌روز نگه می‌دارد.
+- **خاطره‌های کاربر**: مشاهده‌های تکرارشونده دربارهٔ شیوهٔ کارت (سبک ارتباط، تمرکز هنگام بازبینی و الگوهای کاری) را در `` ثبت می‌کند تا در هر نشست همراهت باشند.
+- **ارتقای راهنماها**: پرسش‌های تکراری و همیشگی‌ای را که عامل تاریخ‌نگار دیده به راهنماهای ماندگار تبدیل می‌کند.
+- **نوسازی راهنماها**: موضوع راهنماهای منسوخ را با کد فعلی دوباره بررسی و پاسخ‌هایشان را تازه می‌کند.
+- **یادداشت‌های هوشمند**: یادداشت‌های معوقی را که شرط `surface_condition` آن‌ها برقرار شده ارزیابی می‌کند و موارد آماده را نمایش می‌دهد.
+
+از آنجا که عامل رؤیاپرداز هنگام بی‌کاری اجرا می‌شود، مدل‌های محلی—حتی مدل‌های کند—برای آن مناسب‌اند؛ کسی منتظر نمی‌ماند. هر زمان خواستی با `/ctx-dream` اجرایش کن.
+
+---
+
+## 🔎 بازیابی
+
+*خاطرهٔ درست، در زمان درست.* در هر نوبت، خاطره‌های فعال پروژه و تاریخچهٔ فشرده‌شدهٔ نشست، خودکار و با حفظ پایداری کش به پرامپت افزوده می‌شوند. عامل در صورت نیاز می‌تواند سراغ این ابزارها برود:
+
+- **`ctx_search`**: با یک پرس‌وجو در **خاطره‌های** پروژه، تاریخچهٔ خام **گفت‌وگوها**، **commitهای git** فهرست‌شده، **یادداشت‌های کنارگذاشته‌شده** و **راهنماهای ارتقایافته** جست‌وجو می‌کند. از embedding معنایی و در صورت نیاز جست‌وجوی تمام‌متن استفاده می‌شود.
+
+ ```
+ ctx_search(query="why did we pick event sourcing for orders")
+ ```
+
+- **`ctx_expand`**: وقتی عامل به جزئیات دقیق نیاز دارد، یک بازه از تاریخچهٔ فشرده را به رونوشت اصلی `U:`/`A:` برمی‌گرداند.
+- **`ctx_note`**: دفترچه‌ای برای نیت‌های معوق. یادداشت‌ها در زمان‌های طبیعی دوباره ظاهر می‌شوند (پس از commitها، اجرای عامل تاریخ‌نگار یا پایان کارهای فهرست‌شده). **یادداشت‌های هوشمند** شرطی باز دارند که عامل رؤیاپرداز پیگیر آن است.
+
+بازیابی هم **میان نشست‌ها** کار می‌کند (نشست تازه همه‌چیز را به ارث می‌برد) و هم **میان محیط‌های اجرا** (خاطره‌ای را در OpenCode بنویس و در Pi یا OMP بازیابی کن).
+
+> **راهنمای جست‌وجوی خودکار** *(به‌طور پیش‌فرض روشن)* در هر نوبت، `ctx_search` را در پس‌زمینه اجرا می‌کند و اگر مورد مرتبطی باشد با اشاره‌ای مبهم آن را به یاد عامل می‌آورد؛ مثل وقتی که یادداشتی را که نوشته‌ای کم‌وبیش به خاطر می‌آوری. فقط تکه‌های فشرده افزوده می‌شوند، نه محتوای کامل. برای خاموش‌کردن آن `memory.auto_search.enabled: false` بگذار. **فهرست‌سازی commitهای git** *(نیازمند فعال‌سازی صریح؛ به‌طور پیش‌فرض خاموش)* تاریخچهٔ پروژه را به منبعی معنایی و اضافه برای `ctx_search` تبدیل می‌کند؛ با `memory.git_commit_indexing.enabled: true` روشنش کن.
+
+### ابزارهای عامل در یک نگاه
+
+| ابزار | بخش | کارکرد |
+|------|-------|-------------|
+| `ctx_reduce` | زمینه | محتوای قدیمیِ برچسب‌خورده را برای حذف در صف می‌گذارد و کش را در نظر می‌گیرد |
+| `ctx_memory` | ثبت دانش | خاطره‌های ماندگار میان نشست‌ها را می‌نویسد یا حذف می‌کند |
+| `ctx_search` | بازیابی | در خاطره‌ها، تاریخچهٔ گفت‌وگو، commitهای git، یادداشت‌ها و راهنماها جست‌وجو می‌کند |
+| `ctx_expand` | بازیابی | یک بازه از تاریخچه را به رونوشت اصلی برمی‌گرداند |
+| `ctx_note` | بازیابی | نیت‌های معوق و یادداشت‌های هوشمندی که عامل رؤیاپرداز ارزیابی می‌کند |
+
+---
+
+## فرمان‌ها
+
+| فرمان | توضیح |
+|---------|-------------|
+| `/ctx-status` | نمای عیب‌یابی: برچسب‌ها، حذف‌های در صف، زمان‌ماندگاری کش، وضعیت یادآوری، پیشرفت عامل تاریخ‌نگار، پوشش محفظه‌ها و بودجهٔ تاریخچه |
+| `/ctx-flush` | همهٔ عملیات در صف را بی‌درنگ اجرا می‌کند و از زمان‌ماندگاری کش عبور می‌کند |
+| `/ctx-recomp` | محفظه‌ها را از تاریخچهٔ خام دوباره می‌سازد (بازهٔ `start-end` می‌پذیرد). اگر وضعیت ذخیره‌شده نادرست به‌نظر می‌رسد از آن استفاده کن |
+| `/ctx-wrapup [messages_to_keep]` | تاریخچهٔ زندهٔ قدیمی را فشرده می‌کند و N پیام تازه را خام نگه می‌دارد؛ فشرده‌سازیِ در صف با پیام بعدی مدل نهایی می‌شود |
+| `/ctx-dream` | نگهداشت عامل رؤیاپرداز را به‌درخواست اجرا می‌کند: بازبینی حافظه، مستندات، یادداشت‌های هوشمند و نمایهٔ کاربر |
+| `/ctx-embed` | وضعیت embedding را نشان می‌دهد یا embedding محفظه‌های تاریخچه را آغاز/متوقف می‌کند (`start` \| `pause`) |
+
+---
+
+## برنامهٔ دسکتاپ
+
+یک برنامهٔ دسکتاپ مکمل برای مرور و مدیریت وضعیت Magic Context بیرون از محیط خط فرمان.
+
+
+
+- **مرورگر خاطره‌ها**: خاطره‌های پروژه را بر پایهٔ دسته و پروژه جست‌وجو، فیلتر و ویرایش کن.
+- **تاریخچهٔ نشست**: محفظه‌ها و یادداشت‌های هر نشست را با پیمایش زمانی مرور کن.
+- **عیب‌یابی کش**: خط زمانی زندهٔ برخورد/عدم‌برخورد کش و تشخیص علت بی‌اعتبارشدن آن.
+- **مدیریت عامل رؤیاپرداز**: تاریخچهٔ اجراهای عامل را ببین، اجرا را آغاز کن و نتیجهٔ کارها را بررسی کن.
+- **ویرایشگر تنظیمات**: همهٔ تنظیمات را با فرم ویرایش کن، از جمله زنجیره‌های جایگزین مدل.
+- **نمایشگر گزارش‌ها**: گزارش‌ها را هم‌زمان با ثبت‌شدن ببین و در آن‌ها جست‌وجو کن.
+
+این برنامه مستقیماً پایگاه دادهٔ SQLite مربوط به Magic Context را می‌خواند؛ به سرور یا API اضافی نیاز ندارد و به‌روزرسانی خودکار در آن تعبیه شده است.
+
+---
+
+## پیکربندی
+
+تنظیمات در `magic-context.jsonc` قرار دارند. بیشترشان پیش‌فرض‌های مناسبی دارند، اما مدل عامل تاریخ‌نگارِ محیط اجرایی فعال (`historian.opencode.model`، `historian.pi.model` یا `historian.omp.model`) برای فشرده‌سازی تاریخچه ضروری است. تنظیمات پروژه روی تنظیمات سراسری کاربر اعمال می‌شوند. برای مرجع کامل—از تنظیم زمان‌ماندگاری کش و آستانه‌های اجرا برای هر مدل تا انتخاب مدل‌های تاریخ‌نگار و رؤیاپرداز، ارائه‌دهندگان embedding، تنظیمات حافظه و پیش‌تنظیم‌های سطح پرامپت (`full`/`light`)—به **[CONFIGURATION.md](../../CONFIGURATION.md)** یا **[مرجع پیکربندی در docs.cortexkit.io](https://docs.cortexkit.io/magic-context/reference/configuration/)** مراجعه کن.
+
+> **نکته دربارهٔ تنظیمات هر مدل:** `prompt_surface.models` همیشه مسیر بلوک راهنمای تزریق‌شده را تعیین می‌کند. OpenCode 1.x، Pi و OMP توضیحات ابزار را یک‌بار در هر فرایند ثبت می‌کنند (بر پایهٔ `prompt_surface.default`). OpenCode 2 پنج توضیح `ctx_*` را در هر درخواست و بر پایهٔ مدل پیش‌نویس بازنویسی می‌کند.
+
+**مسیرهای پیکربندی** (یک مسیر مشترک CortexKit؛ تنظیم پروژه بر تنظیم کاربر اولویت دارد):
+1. `/.cortexkit/magic-context.jsonc`
+2. `~/.config/cortexkit/magic-context.jsonc`
+
+از نسخهٔ قدیمی‌تر ارتقا می‌دهی؟ تنظیمات فعلی در نخستین اجرا خودکار به این مسیر منتقل می‌شوند و در محل قبلی نشانهٔ `.MOVED_READPLEASE` باقی می‌ماند.
+
+### پروفایل مدل برای مخزن‌های کاری و شخصی
+
+اگر برای مخزن‌های شخصی و کاری از مجموعه‌مدل‌های جداگانه برای عامل‌های پس‌زمینه استفاده می‌کنی، پروفایل‌ها را در تنظیمات کاربر تعریف کن و در هر مخزن کاری نام پروفایل را انتخاب کن:
+
+```jsonc
+// ~/.config/cortexkit/magic-context.jsonc
+{
+ "profile": "personal",
+ "profiles": {
+ "personal": { "historian": { "opencode": { "model": "anthropic/claude-sonnet-4-6" } } },
+ "work": { "historian": { "opencode": { "model": "openai/gpt-5.2-codex" } } }
+ }
+}
+
+// /.cortexkit/magic-context.jsonc
+{ "profile": "work" }
+```
+
+این همان الگوی جداسازی مخزن‌های کاری از شخصی است که kagbodji درخواست کرده بود. پروفایل‌ها فقط انتخاب مدل عامل‌های پس‌زمینه را جایگزین می‌کنند و تنظیمات پایه‌ای را که در آن‌ها نیامده حفظ می‌کنند؛ تعریفشان فقط در تنظیمات کاربر ممکن است. پروژه می‌تواند یک پروفایل شناخته‌شدهٔ کاربر را انتخاب کند، اما نمی‌تواند محتوای آن را تعیین کند. برای نمونهٔ کامل OpenCode/Pi/OMP، رفتار جایگزین و مرز اعتماد، [CONFIGURATION.md](../../CONFIGURATION.md#per-repository-model-profiles) را ببین.
+
+---
+
+## ذخیره‌سازی
+
+همهٔ داده‌های ماندگار در پایگاه دادهٔ SQLite محلی و در مخزن مشترک CortexKit نگه‌داری می‌شوند (`~/.local/share/cortexkit/magic-context/context.db`؛ در Windows مسیر هم‌ارز XDG به‌کار می‌رود؛ پایگاه‌های دادهٔ قدیمی داخل پوشهٔ OpenCode در نخستین راه‌اندازی مهاجرت می‌کنند). اگر میزبان `XDG_DATA_HOME` را جدا می‌کند، `MAGIC_CONTEXT_STORAGE_DIR` را روی مسیر مطلق و کامل پوشهٔ ذخیره‌سازی Magic Context بگذار؛ این مقدار صریح بر مسیر برگرفته از XDG اولویت دارد. همهٔ فرایندهایی که از این مخزن مشترک استفاده می‌کنند باید همین مقدار صریح را دریافت کنند. میزبان‌ها متغیر را وقتی صریحاً تنظیم شده باشد منتقل می‌کنند، اما Magic Context آن را از مسیر پیش‌فرض خودش تولید نمی‌کند. این جایگزین فقط پایگاه دادهٔ سمت محیط اجرا را جابه‌جا می‌کند؛ وضعیت daemonِ `subc` برای هر کاربر در محل مشترک خودش می‌ماند. فرایندهایی با نسخه‌های متفاوت، تا وقتی همه به‌روز نشوند، مهاجرت را در پوشهٔ مشترک مسدود می‌کنند. اگر پایگاه داده باز نشود، Magic Context خود را غیرفعال می‌کند و به تو اطلاع می‌دهد. خاطره‌ها به **شناسهٔ پایدار پروژه** که از مخزن به دست می‌آید متصل‌اند؛ بنابراین با پروژه میان worktreeها، cloneها و forkها جابه‌جا می‌شوند و به مسیر یک پوشه وابسته نیستند.
+
+Magic Context در چند مسیر دیگر هم داده می‌نویسد:
+
+| مسیر | محتوا | ماندگاری |
+|---|---|---|
+| `~/.local/share/cortexkit/magic-context/context.db` | پایگاه دادهٔ SQLite: برچسب‌ها، محفظه‌ها، خاطره‌ها و همهٔ داده‌های ماندگار (مسیر هم‌ارز XDG در Windows) | **باید ماندگار بماند.** حذف آن به‌معنای ازدست‌رفتن خاطره‌ها و تاریخچه است. |
+| `~/.local/share/cortexkit/magic-context/models/` | نهانگاه مدل embedding محلی (حدود ۹۰ مگابایت، `Xenova/all-MiniLM-L6-v2` با قالب ONNX) که در نخستین استفاده، اگر embedding محلی روشن باشد، دانلود می‌شود | بهتر است ماندگار بماند وگرنه در هر اجرا دوباره دانلود می‌شود. اگر `embedding.provider` روی `"off"` باشد یا backend از نوع `openai_compatible`/`ollama` تنظیم شده باشد استفاده نمی‌شود. خاموش‌کردن `memory.enabled` هم مانعش نیست، چون تاریخچهٔ نشست همچنان embedding می‌شود. |
+| `$MAGIC_CONTEXT_LOG_PATH` (پیش‌فرض: `${TMPDIR}/opencode/magic-context/magic-context.log`؛ برای Pi از `pi/` استفاده می‌شود) | گزارش عیب‌یابی. با `MAGIC_CONTEXT_LOG_PATH` مسیر دیگری تعیین کن (مثلاً مسیری ماندگار در یک container). | موقت؛ نگه‌داشتنش ضروری نیست. |
+
+**محیط‌های محدود یا موقت (Docker، CI و containerهای دورریختنی):** پوشهٔ `~/.local/share/cortexkit/magic-context/` را روی volume ماندگار mount کن تا پایگاه داده و نهانگاه مدل میان اجراها باقی بمانند. اگر فقط نهانگاه مدل موقت باشد، مدل دوباره دانلود می‌شود؛ اما اگر پایگاه داده موقت باشد، خاطره و تاریخچه انباشته نمی‌شوند. برای حذف کامل دانلود مدلِ حدود ۹۰ مگابایتی، `embedding.provider: "off"` بگذار یا `embedding` را به backend راه‌دور `openai_compatible`/`ollama` وصل کن.
+
+---
+
+## تاریخچهٔ ستاره‌ها
+
+
+
+
+
+
+
+
+
+---
+
+## توسعه
+
+**پیش‌نیاز:** [Bun](https://bun.sh) نسخهٔ 1.4.0 یا بالاتر
+
+تفاوت‌های Bun 1.3.x در ارزیابی ماژول‌ها و شکل خطاهای resolver ممکن است تغییرات بی‌ارتباط مشارکت‌کنندگان را به خطاهای پرسر‌وصدا در آزمون‌های موازی و ساخت تبدیل کند (مسئله‌های [#445](https://github.com/cortexkit/magic-context/issues/445) و [#446](https://github.com/cortexkit/magic-context/issues/446)). دروازه‌های مخزن پیش از اجرا نسخه را بررسی می‌کنند تا نسخه‌های پشتیبانی‌نشده به‌جای خطاهای نامربوط، پیام نسخهٔ لازم را نشان دهند.
+
+```sh
+bun install # Install dependencies
+bun run build # Build the plugin
+bun run typecheck # Type-check without emitting
+bun test # Run tests
+bun run lint # Lint (Biome)
+bun run format # Format (Biome)
+```
+
+اجرای Dream به سرور فعال OpenCode نیاز دارد (عامل رؤیاپرداز نشست‌های فرزند موقت می‌سازد). برای نگهداشت درخواستی، داخل OpenCode از `/ctx-dream` استفاده کن.
+
+### فهرست آزمون‌های جهش
+
+قبول‌شدن یک آزمون ایمنی به‌تنهایی چیز زیادی را ثابت نمی‌کند، مگر اینکه دیده باشیم هنگام خرابی هم شکست می‌خورد. [`mutations.toml`](../../mutations.toml) فهرست ثبت‌شدهٔ این آزمون‌هاست: هر ردیف عمداً یکی از محافظ‌های کد تولیدی را از کار می‌اندازد و آزمونی را نام می‌برد که باید در نتیجه شکست بخورد؛ این‌طور هیچ محافظی بی‌سروصدا بی‌اثر نمی‌شود. هر ردیف باید جلوی خرابی خاموش و پرهزینه‌ای را بگیرد: بی‌اعتبارشدن کش پرامپت، رد درخواستی که باید به‌شکل fail-closed عمل کند، نقض قرارداد ارتباطی، ناایمنی هنگام crash، ازدست‌رفتن داده یا مجوز نادرست فایل. هر محافظی که باید دقیقاً یک‌بار اجرا شود (مثل lease یا پاک‌سازی compare-and-set) دست‌کم یک ردیف دارد که مسیر واقعی تولید را می‌پیماید. برای سبک و ظاهر ردیفی تعریف نمی‌شود.
+
+اجرای پین‌شدهٔ [`ck-mutate`](https://github.com/cortexkit/commons/tree/7d08e73722fa3e79bbcc2607753978ab768f1c6b/crates/cortexkit-mutate) فهرست را از درخت کاری پاک اجرا می‌کند: اول بررسی می‌کند آزمون نام‌برده موفق است، سپس خرابی را اعمال می‌کند و انتظار دارد آزمون شکست بخورد؛ در پایان فایل منبع را بایت‌به‌بایت برمی‌گرداند.
+
+```sh
+cargo install --locked --git https://github.com/cortexkit/commons --rev 7d08e73722fa3e79bbcc2607753978ab768f1c6b cortexkit-mutate
+bun install --frozen-lockfile
+ck-mutate check # anchors match exactly once; cargo test names exist
+ck-mutate run --all # every row (slow: the Rust rows rebuild mc-module)
+ck-mutate run --diff origin/master # only the rows a change touches
+ck-mutate run --only ts-schema-fence-refuses-newer-database
+```
+
+هر ردیف باید نتیجهٔ CAUGHT بدهد. [`mutations.yml`](../../.github/workflows/mutations.yml) ردیف‌هایی را که pull request (یا push به `train/**`) لمس می‌کند دوباره اجرا می‌کند؛ با هر push به master کل فهرست را اجرا می‌کند و هر شب نیز کل فهرست را با `--broad` می‌سنجد. هنگام اجرای این فرایند هیچ فایلی را با `git checkout` برنگردان: این کار جهش را حذف می‌کند و باعث می‌شود جهش به‌اشتباه زنده‌مانده گزارش شود.
+
+برای افزودن یک ردیف:
+
+1. خط تولیدی‌ای را پیدا کن که خودِ محافظ است و مقدار `old` را از فایل بردار، نه از حافظه. `new` را کوچک‌ترین تغییری انتخاب کن که محافظت را حذف کند (`if (false)`، `return true` یا حذف یک شرط)، نه تغییری که کامپایل را خراب کند.
+2. آزمونی را پیدا کن که باید این جهش را بگیرد. تغییر را دستی اعمال کن، فایل آزمون را اجرا کن و مطمئن شو آزمون به‌دلیل همان محافظ ازکارافتاده شکست می‌خورد؛ بعد فایل را برگردان. اگر هیچ آزمونی شکست نخورد، این یک یافته است: اول در commit جداگانه آزمون مفقود را اضافه کن.
+3. ردیف را اضافه کن. آزمون‌های Bun از نوع `command` هستند: یک ردیف موجود را کپی کن و `expect_red` را روی regex لنگرشدهٔ `-t` برای نام کامل آزمون بگذار (نام‌های `describe` و آزمون را با فاصله به هم وصل کن، نویسه‌های ویژهٔ regex را escape کن و هر فاصله را `\s` بنویس). آزمون‌های Rust در mc-module ردیف‌های `command` با اجرای `cargo test --lib -- --exact` هستند؛ هدف‌های کوچک Rust ردیف‌های `cargo` با `only = true` هستند. هرجا آزمون ممکن است به دلیلی نامرتبط هم شکست بخورد، `expect_message` (زیررشته یا `/regex/`) را اضافه کن.
+4. `ck-mutate check` و سپس `ck-mutate run --only ` را اجرا کن. ردیف را فقط وقتی commit کن که نتیجه CAUGHT باشد.
+
+اگر آزمونی دیگر جهش را نگیرد، باید آن را به‌عنوان باگ اصلاح کرد؛ ردیف را حذف نکن.
+
+---
+
+### نشانگر بی‌اعتبارشدن کش
+
+`packages/plugin/scripts/cache-bust-sentinel.ts` درخواست‌های اخیر OpenCode و ارائه‌دهنده‌های Pi/OMP را بررسی می‌کند تا موارد بی‌اعتبارشدن کش را پیدا کند که با قراردادهای fold، refresh، reduction، flush، force-band یا provider/system-prompt در Magic Context توضیح داده نمی‌شوند. هر درخواست ارائه‌دهنده را به نزدیک‌ترین رکورد گذر MC، از ۳۰ ثانیه پیش تا ۵ ثانیه پس از درخواست، وصل می‌کند: داده‌های `transform_decisions`/`scheduler_history` در `context.db` و ردّ `mc_pass_trace`/آینهٔ تصمیم در حالت Rust در `store.db`. اگر رکورد گذر متناظر پیدا نشود، `no_mc_pass_row` گزارش می‌شود. پایگاه دادهٔ MC، پایگاه دادهٔ OpenCode، dumpهای افزونهٔ احراز هویت، فایل‌های JSONLِ Pi/OMP و artifactهای `.pi/pi-llm-debugging`/آرایه‌های سرو‌شده را فقط می‌خواند. تنها چیزی که می‌نویسد فایل وضعیتِ آخرین‌مقدار/جلوگیری از تکرار در `~/.local/share/cortexkit/magic-context/cache-bust-sentinel-state.json` (یا مسیر تعیین‌شده با `MAGIC_CONTEXT_STORAGE_DIR`) است.
+
+برای یک اجرای آزمایشی از ریشهٔ مخزن استفاده کن؛ هر پنجرهٔ تازه و توضیح‌داده‌نشدهٔ بی‌اعتبارشدن کش در یک خط JSON چاپ می‌شود:
+
+```sh
+bun packages/plugin/scripts/cache-bust-sentinel.ts --once
+```
+
+برای اجرای یک‌دقیقه‌ای داخلی، `--once` را حذف کن؛ یا آن را هر ۱ تا ۵ دقیقه با cron/launchd اجرا کن. الگوی `packages/plugin/scripts/launchd/com.cortexkit.magic-context.cache-bust-sentinel.plist` هر پنج دقیقه اجرا می‌شود، `--send` را روشن می‌کند، `RunAtLoad=false` دارد و خودکار نصب نمی‌شود. پیش از بارگذاری، جای‌نگهدارهای `__BUN_PATH__`، `__REPO_ROOT__` و `__LOG_DIR__` را عوض کن. نمونهٔ cron:
+
+```cron
+*/5 * * * * cd /path/to/magic-context && /path/to/bun packages/plugin/scripts/cache-bust-sentinel.ts --once --send >> /path/to/cache-bust-sentinel.jsonl 2>> /path/to/cache-bust-sentinel.log
+```
+
+`--send` خروجی آزمایشیِ خط‌به‌خط JSON را به عملیات `agent.deliver` در ماژول `prefrontal-core` تبدیل می‌کند. به‌طور پیش‌فرض از نام نمایشی `mc-cache-bust-sentinel` یک پیام همتای با اولویت بالا در registry به `agent_b613e5cf2ee55b8c` می‌فرستد؛ نشست فرستنده نیز `health-sentinel-mc` و محیط اجرایش `magic-context` ثبت می‌شود. برای انتخاب گیرنده یا نام نمایشی دیگری از `--wake-agent-id` یا `--wake-from-agent` استفاده کن. پاسخ‌های پذیرفته‌شده و در صف، موفق شمرده می‌شوند؛ سفارش تکراریِ ثبت‌شده با همان شناسهٔ تحویل تکراری شمرده می‌شود. رد فرستنده بدون تلاش دوباره برای همان شناسه ثبت می‌شود و پاسخ نامعتبر یا تعارض idempotency اجرا را ناموفق می‌کند. `--connection-file`، `--wake-module-id`، `--wake-agent-id`، `--wake-from-agent`، `--state-file`، `--db` یا `--rust-store` را فقط وقتی به کار ببر که مسیر runtime مربوطه پیش‌فرض نیست.
+
+### نشانگر تأخیر تبدیل
+
+`packages/plugin/scripts/transform-latency-sentinel.ts` گزارش‌های Magic Context در OpenCode و Pi و گزارش تاریخ‌دار ماژول `ck-mc` را فقط می‌خواند. هر بار اجرا حداکثر ۴ مگابایت **بایت تازه برای هر فایل** می‌خواند؛ watermarkهای inode/اندازه چرخش فایل را تشخیص می‌دهند و خط‌های ناقص انتهایی را دوباره می‌خوانند. تنها نوشتهٔ ماندگارش `transform-latency-sentinel-state.json` در پوشهٔ ذخیره‌سازی Magic Context است. هشدارهای هر نشست این موارد را پوشش می‌دهند: p90 بیش از ۵ ثانیه در ده گذر طی ده دقیقه، هر گذر بیش از ۱۲ ثانیه، پایان مهلت انتقال/ماژول/همگام‌سازی وضعیت، گذارهای park در Rust، ردها و افزایش پیوستهٔ زمان ماژول در دست‌کم بیست گذر. هشدار هم‌نوع دوباره فقط با افزایش شدت ۵۰درصدی یا پس از شش ساعت ارسال می‌شود. هر هشدار شناسهٔ نشست، نام فهرست همتاها (اگر موجود نباشد، شناسهٔ پروژه در `session_projects`)، p50/p90/بیشینهٔ گذر، میانهٔ زمان ماژول و افزونه و میانگین بار سیستم را دارد. `loadSampledAt` زمان نمونه‌برداری بار را ثبت می‌کند؛ بازپخش تاریخی نمی‌تواند بار تاریخی دستگاه را بازسازی کند.
+
+اجرای آزمایشی بدون ارسال: `bun packages/plugin/scripts/transform-latency-sentinel.ts --once`. برای بررسی گذشته از `--replay --since 2026-09-28T17:00:00Z --until 2026-09-28T18:15:00Z` استفاده کن؛ بازپخش داده را در قطعه‌های ۴ مگابایتی می‌خواند، بی‌آنکه watermark بنویسد یا هشداری بفرستد. `--send` در هر اجرا با `agent.deliver` یک پیام همتای با اولویت بالا می‌فرستد. الگوی launchd پنج‌دقیقه‌ای در `packages/plugin/scripts/launchd/com.cortexkit.magic-context.transform-latency-sentinel.plist` از `--once --send` و `RunAtLoad=false` استفاده می‌کند؛ مانند نشانگرهای دیگر، خودکار نصب نمی‌شود. پیش از ثبت به‌عنوان LaunchAgent، `__BUN_PATH__`، `__REPO_ROOT__` و `__LOG_DIR__` را با مسیر فایل اجرایی bun، ریشهٔ مخزن و پوشهٔ گزارش‌ها جایگزین کن. برای مسیرهای غیراستاندارد از `--opencode-log`، `--pi-log`، `--module-log`، `--db`، `--peer-db`، `--state-file` و `--connection-file` استفاده کن.
+
+### نشانگر شکست عامل رؤیاپرداز و تاریخ‌نگار
+
+`packages/plugin/scripts/subagent-failure-sentinel.ts` ردیف‌های کامل‌شدهٔ `subagent_invocations` را از `context.db` با اتصال فقط‌خواندنی SQLite و مهلت انتظار قفل سه‌ثانیه‌ای می‌خواند. وضعیت‌های `failed` و `timed_out` را شکست می‌شمارد؛ `empty` و `aborted` جداگانه شمرده می‌شوند. این ابزار طی هفت روز یک دستهٔ خطای تازه (عامل فرزند، کار، خطای نرمال‌شده)، کاری با دست‌کم هشت اجرا و سهم شکست حداقل ۲۵٪ در ۲۴ ساعت، یا دسته‌ای را گزارش می‌کند که شمارش آن نسبت به ۲۴ ساعت پیش دو برابر شده باشد. شناسه‌ها، عددها، مدت‌ها و مسیرهای متغیر خطاها به دسته‌های باثبات تبدیل می‌شوند. هر اجرای پنج‌دقیقه‌ای حداکثر ۵۰۱ ردیف تازه و ۵٬۰۰۱ ردیف تاریخچهٔ اخیر را می‌خواند (شامل ردیف‌های مرزی)؛ اگر تاریخچه ناقص باشد، قواعدی که بازهٔ کاملشان قابل سنجش نیست اجرا نمی‌شوند. تنها نوشتهٔ محلی فایل watermark/جلوگیری از تکرار `subagent-failure-sentinel-state.json` در پوشهٔ ذخیره‌سازی Magic Context است. ادامهٔ watermark بر پایهٔ `(ended_at, id)` انجام می‌شود؛ ارسال هشدار برای شش ساعت متوقف می‌ماند، مگر اینکه شمار دسته ۵۰٪ رشد کند. آغاز و خلاصهٔ اجرا، از جمله تعداد ردیف‌های بررسی‌شده و محدودبودن اسکن، ثبت می‌شود. در هر اجرا حداکثر یک پیام بیدارباش می‌فرستد که قاعده، کار، دسته، شمار دسته، سهم شکست، نمونهٔ خطا، تازه‌ترین شناسهٔ نشست و تعداد وضعیت‌های empty/aborted را فهرست می‌کند.
+
+اجرای آزمایشی با `bun packages/plugin/scripts/subagent-failure-sentinel.ts --once` انجام می‌شود؛ برای انتخاب پایگاه دادهٔ fixture و فایل وضعیت از `--db` و `--state-file` استفاده کن. بدون `--once` هر دقیقه تکرار می‌شود. الگوی launchd در `packages/plugin/scripts/launchd/com.cortexkit.magic-context.subagent-failure-sentinel.plist` هر پنج دقیقه با `--once --send` اجرا می‌شود، `RunAtLoad=false` دارد و گزارش‌های JSONL/stdout و stderr را جداگانه ذخیره می‌کند. `--send` همان پیام همتای `agent.deliver` با اولویت بالای `prefrontal-core` را، مانند نشانگر بی‌اعتبارشدن کش، به عامل اصلی Magic Context می‌فرستد. برای نصب و فعال‌سازی در macOS، (این کار خودکار انجام نمی‌شود) فرمان‌های زیر را **از ریشهٔ مخزن** اجرا کن:
+
+```sh
+mkdir -p "$HOME/Library/LaunchAgents" "$HOME/Library/Logs/cortexkit"
+sed -e "s|__BUN_PATH__|$(command -v bun)|g" \
+ -e "s|__REPO_ROOT__|$(pwd -P)|g" \
+ -e "s|__LOG_DIR__|$HOME/Library/Logs/cortexkit|g" \
+ packages/plugin/scripts/launchd/com.cortexkit.magic-context.subagent-failure-sentinel.plist \
+ > "$HOME/Library/LaunchAgents/com.cortexkit.magic-context.subagent-failure-sentinel.plist"
+launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.cortexkit.magic-context.subagent-failure-sentinel.plist"
+```
+
+---
+## مشارکت
+
+گزارش باگ و pull request پذیرفته می‌شود. پیش از شروع، [CONTRIBUTING.md](../../CONTRIBUTING.md) را دربارهٔ قواعد مسئله‌های تأییدشده و پوشش محیط‌های اجرا بخوان.
+
+---
+
+## مجوز
+
+[MIT](../../LICENSE)
From 9de9224d160bf3ba3f1de91c7992d845e6b467a3 Mon Sep 17 00:00:00 2001
From: danialshirali16
Date: Thu, 22 Oct 2026 13:03:28 +0330
Subject: [PATCH 5/5] chore: re-trigger the review-findings gate
All reviewer-bot threads are now resolved, but GitHub sends no event when
a review thread is resolved, so the gate that reads them did not re-run
on its own. This empty commit fires the synchronize event that does.
+ 
+ 
+ 
+ 
+ 
+