‏cap'n hook؛ حافظهٔ ماندگار برای ایجنت‌های کدنویس

مشکلی که این پروژه سراغش رفته آشناست: ایجنت‌های کدنویس بین جلسه‌ها همه‌چی رو فراموش می‌کنن. مسیر رسیدن از «وبهوک‌های پرداخت کجا هندل می‌شن؟» به فایل و پوشهٔ دقیقش، هم وقت می‌بره هم توکن، و آخر جلسه بخار می‌شه. فردا همون کشف باید از صفر تکرار بشه.

کل یکپارچه‌سازی capn init ـه که یه هوک SessionStart برای Claude Code و Codex نصب می‌کنه. اون هوک هر جلسه فقط یه یادداشت کوتاه به ایجنت نشون می‌ده: قبل از جست‌وجو تو کدبیس از capn بپرس، و بعد از هر کشف سخت ثبتش کن. نویسنده تأکید می‌کنه هیچ لایهٔ میانی یا رفتار اجباری‌ای در کار نیست؛ مدل خودش تصمیم می‌گیره.

حلقه سه حرکت داره. اول پرسیدن: capn ask اگه جواب داشته باشه خروجی JSONL با فایل‌های دقیق برمی‌گردونه و کل جست‌وجو رد می‌شه؛ اگه نداشته باشه با کد ۱ خارج می‌شه و ایجنت می‌ره بگرده. حرکت دوم ثبت چیزیه که گرون تموم شده:

capn chart "where are payment webhooks handled?" \
  --files src/api/webhooks.ts,src/billing/handlers/stripe.ts \
  --details "Router starts near line 40; Stripe handler owns signature checks."

حرکت سوم مهم‌ترینشه: هر فایل پشتیبان موقع ثبت با sha256 اثرانگشت می‌گیره و اگه عوض بشه یا از بین بره، اون ورودی قبل از اینکه دوباره جواب بده حذف می‌شه. ورودی‌ها هیچ‌وقت ویرایش نمی‌شن؛ یا هنوز درستن یا بی‌ارزشن. اسم دستورها هم به همین خاطر chart و unchart ـه نه add و update — کدبیس مثل خط ساحلیه که وقتی جابه‌جا شد، نقشهٔ قدیمی دور انداخته می‌شه.

ادعای عددی پروژه هم مشخصه: تو یه ارزیابی روی ۶۰ سؤال واقعی توسعه‌دهنده‌ها و ۵ کدبیس محصولی — Dub، Polar، PostHog، Twenty و Documenso — ایجنتی که از capn یادآوری کرده ۷۷٪ توکن کمتر از ایجنتی مصرف کرده که سرد جست‌وجو می‌کرده، و جواب‌ها تو هر دو حالت درست بودن. به گفتهٔ نویسنده هزینهٔ یه ثبت با حدود ۱٫۶ بار یادآوری جبران می‌شه.

ذخیره‌سازی عمداً ساده و محلیه: هر سؤال یه فایل مارک‌داون تو .capn/entries/ که آدم هم می‌تونه بازش کنه و بخونه، به‌علاوهٔ یه ایندکس معکوس. بازیابی روی QMD انجام می‌شه؛ به‌صورت پیش‌فرض جست‌وجوی معنایی که اولین بار حدود ۳۰۰ مگابایت مدل دانلود می‌کنه، یا حالت کلیدواژه‌ای BM25 که هیچی دانلود نمی‌کنه و کاملاً قطعیه. کل پوشهٔ .capn/ هم gitignore می‌شه.

نکات کلیدی:

• حافظهٔ اپیزودیک محلی برای ایجنت‌های کدنویس، با مجوز MIT
• یکپارچه‌سازی فقط یه هوک SessionStart ـه، بدون رفتار اجباری
• تازگی جواب با هش فایل تصمیم‌گیری می‌شه، نه با قضاوت مدل
• ورودی کهنه خودش پاک می‌شه؛ بدترین حالت اینه که ایجنت دوباره بگرده
• ادعای ۷۷٪ صرفه‌جویی توکن روی ۶۰ سؤال و ۵ کدبیس واقعی