پروژه‌ای که هفته‌ها با دستیار هوش مصنوعی ادامه دارد، نباید فقط به تاریخچه یک چت وابسته باشد. ChatHandoffKit با فایل‌های Markdown، ثبت وضعیت کنترل‌شده و ذخیره‌سازی نسخه‌بندی‌شده کمک می‌کند تصمیم‌ها و قدم بعدی پروژه قابل بازیابی باشند.
مسئله اصلی، فراموشی تصمیم‌های پروژه بود
وقتی روی یک پروژه چند هفته با دستیار هوش مصنوعی کار می‌کنم، در میان پیام‌ها اطلاعات زیادی شکل می‌گیرد: تصمیم‌های معماری، راهکارهای ردشده، خطاهای رفع‌شده، محدودیت‌های پروژه و کارهایی که باید در جلسه بعد ادامه پیدا کنند.
اما وقتی مکالمه طولانی می‌شود و کار را در یک چت جدید ادامه می‌دهیم، همه این جزئیات الزاماً در دسترس نیستند. ممکن است دوباره درباره موضوعی تصمیم بگیریم که قبلاً حل شده، یا دلیل یک انتخاب فنی را از یاد ببریم.
برای من سؤال این بود: چطور می‌توانیم حافظه پروژه را مستقل از خود مکالمه، شفاف و قابل بازبینی نگه داریم؟
راه‌حل اولیه‌ام یک ابزار برنامه‌نویسی نبود؛ مجموعه‌ای از فایل‌های Markdown در یک مخزن خصوصی GitHub بود که وضعیت و تصمیم‌های چند پروژه واقعی را در آن ثبت می‌کردم. بعد از استفاده عملی، همین تجربه به نقطه آغاز ChatHandoffKit تبدیل شد؛ یک ابزار متن‌باز Python برای مدیریت حافظه پروژه.
حافظه ساختاریافته، نه بازیابی خودکار تمام چت‌ها
ChatHandoffKit قرار نیست بدون دسترسی یا تأیید، تاریخچه همه مکالمات ChatGPT را بخواند. در این روش، کاربر یا دستیارِ دارای دسترسی، اطلاعات مهم را استخراج و پیش از ثبت نهایی بررسی می‌کند.
دانش پروژه در فایل‌های ساده Markdown نگهداری می‌شود:
projects/my-project/
├── START_HERE.md
├── PROJECT_CONTEXT.md
├── CURRENT_STATE.md
├── DECISIONS.md
├── PROMPTS.md
├── ERRORS_AND_SOLUTIONS.md
└── SESSION_LOG.mdنقش فایل‌ها از هم جداست. CURRENT_STATE.md وضعیت فعلی و قدم بعدی را نشان می‌دهد؛ DECISIONS.md دلایل تصمیم‌های مهم را نگه می‌دارد؛ SESSION_LOG.md تاریخچه مرحله‌های ثبت‌شده را حفظ می‌کند. فایل‌های دیگر زمینه پروژه، پرامپت‌های قابل استفاده مجدد و خطاهای شناخته‌شده را توضیح می‌دهند.
آخرین وضعیت پروژه با تاریخچه تصمیم‌هایی که ما را به آن وضعیت رسانده‌اند، یک چیز نیست. این تفکیک بخش مهمی از طراحی است.
جریان کار: ساخت، ثبت وضعیت، ادامه
ابزار خط فرمان ChatHandoffKit سه مرحله اساسی دارد:
- Initialize: ساخت فضای دانش و فایل‌های استاندارد.
- Checkpoint: ثبت کنترل‌شده آخرین وضعیت و افزودن سابقه تصمیم‌ها و اقدامات.
- Resume: خواندن مجموعه‌ای محدود از فایل‌ها برای ادامه پروژه در گفت‌وگویی تازه.
برای یک پروژه کاملاً ساختگی مدیریت وظایف، می‌توان از دستورهایی شبیه این استفاده کرد:
chathandoff init --root my-memory --git
chathandoff create task-manager --title "Task Manager" \
--objective "Build a fictional task-management app" --root my-memory
chathandoff checkpoint task-manager --root my-memory \
--state "Initial architecture reviewed" \
--next "Implement the first task API" \
--decision "Use SQLite for the local demo"
chathandoff resume task-manager --root my-memoryاین پروژه دستورهای status و validate و ثبت نسخه در Git را هم دارد. صرف اجرای Checkpoint به معنای انتشار خودکار اطلاعات نیست.
در طراحی فایل وضعیت، تنها بخشی که به‌طور مشخص برای ابزار علامت‌گذاری شده است به‌روزرسانی می‌شود و یادداشت‌های خارج از آن دست‌نخورده می‌مانند. تاریخچه جلسات و تصمیم‌ها نیز جدا نگهداری می‌شوند.
چرا Git و GitHub؟
وقتی مستندات با Git نسخه‌بندی می‌شوند، می‌توان تفاوت هر تغییر، زمان Commit و روند تصمیم‌گیری را بررسی کرد. اگر جهت پروژه تغییر کند، دلیل تصمیم قبلی لزوماً زیر یک خلاصه جدید ناپدید نمی‌شود.
ChatHandoffKit می‌تواند فایل‌های مدیریت‌شده را به‌شکل انتخابی Commit کند و با درخواست صریح کاربر به یک Git Remote ارسال کند. در صورت اختلاف تاریخچه Remote، به‌جای Force Push و بازنویسی کار دیگران، عملیات متوقف می‌شود.
اتصال GitHub در نسخه‌های فعلی از طریق Git معمولی است، نه یک آداپتور اختصاصی GitHub API. کاربر همچنان Remote و احراز هویت خودش را تنظیم می‌کند.
نسخه ۰.۲ و اتصال آزمایشی به Google Drive
در مرحله بعد به این فکر کردم که اگر کاربر نخواهد از Git استفاده کند، چه راهی وجود دارد؟ در نسخه 0.2.0 یک آداپتور اختیاری Google Drive برای فایل‌های Markdown اضافه شد.
این آداپتور از OAuth برنامه دسکتاپ و سطح دسترسی محدود drive.file استفاده می‌کند. امکان ساخت فولدر مربوط به برنامه، بارگذاری فایل‌ها و بازیابی آن‌ها در یک فضای محلی فراهم شده است. انتقال فایل‌ها با فرمان صریح کاربر انجام می‌شود و مقایسه هش SHA-256 کمک می‌کند تغییرات دو طرف پیش از بازنویسی بررسی شوند.
عمداً حذف خودکار فایل‌های Drive، ادغام خودکار تعارض‌ها و همگام‌سازی دائمی GitHub و Drive پیاده‌سازی نشده است.
یک محدودیت را باید روشن بگویم: تست‌های شبیه‌سازی‌شده آداپتور و CI موفق بوده‌اند، اما تا زمان نگارش، چرخه کامل OAuth و انتقال با یک حساب واقعی Google آزمایش پذیرش نشده است. بنابراین اتصال Drive هنوز آزمایشی است و نباید آن را آماده استفاده عملیاتی بدون محدودیت معرفی کرد.
هدف این است که Markdown قالب مشترک و قابل‌انتقال بماند؛ فارغ از اینکه مقصد ذخیره‌سازی Git باشد یا Google Drive.
چه چیزهایی واقعاً بررسی شده‌اند؟
مخزن عمومی حاوی سورس CLI، راهنمای نصب، قالب‌ها، ملاحظات امنیتی، یک پروژه نمونه ساختگی و تست‌های خودکار است. در نسخه ۰.۲، اجرای GitHub Actions در چهار نسخه Python یعنی 3.10 تا 3.13 موفق بوده است.
این نتیجه برای سناریوهای محلی و موارد شبیه‌سازی‌شده Drive که در تست‌ها پوشش داده شده‌اند، پشتوانه فنی ایجاد می‌کند؛ اما اثبات‌کننده آمادگی سازمانی، نبود همه تعارض‌های هم‌زمان یا سازگاری نهایی با حساب واقعی Google نیست.
دو محدودیت دیگر هم مهم‌اند:
- دقت دانش ذخیره‌شده به بازبینی انسانی وابسته است. ابزار نمی‌تواند صحت تمام ادعاهای یک مکالمه را تشخیص دهد یا پیام‌های خارج از دسترس را بازیابی کند.
- حریم خصوصی فقط با خصوصی‌بودن Repository تضمین نمی‌شود. تشخیص اطلاعات محرمانه در ابزار ابتدایی است و باید فایل‌ها پیش از انتشار بررسی شوند. مثال‌های عمومی پروژه با اطلاعات ساختگی تهیه شده‌اند.
همچنین به‌روزرسانی چند فایل در یک Checkpoint هنوز یک تراکنش اتمیک سراسری نیست و در تعارض‌ها ممکن است به بررسی و اصلاح دستی نیاز باشد.
چرا پروژه را متن‌باز کردم؟
هدف ساخت یک موتور حافظه غیرقابل‌بررسی نبود؛ می‌خواستم گردش‌کاری ساده، قابل‌خواندن و قابل‌تغییر بسازم که دیگران بتوانند در پروژه‌های طولانی خود از آن استفاده کنند.
این پروژه برای من نمونه‌ای از تبدیل یک مشکل واقعی به یک ابزار مهندسی است: تعیین مرز امکانات، نگهداری تاریخچه، کنترل تعارض، آزمایش خودکار و مستندسازی شفاف.
در برنامه توسعه، آزمون اتصال واقعی Google Drive، بهبود مدیریت تعارض، کامل‌ترشدن رابط ذخیره‌سازی و تقویت بررسی‌های امنیتی قرار دارند. یکپارچه‌سازی‌هایی مانند MCP نیز فقط ایده‌های آینده‌اند، نه امکانات موجود.