چطور CodeAlmanac از عامل‌های AI برای حفظ حافظهٔ کدبیس استفاده می‌کند؟

تصور کنید یک برنامه نویس ارشد تیم شما استعفا دهد و تمام «چراها» و ترفندهای پنهان پروژه با او برود. CodeAlmanac این کابوس را به پایان می‌رساند و حافظه سازمانی شما را از ذهن افراد به دلِ مخزن کد منتقل می‌کند. در حالی که یک کدبیس (Codebase) حاوی توابع لازم برای اجراست، تصمیمات حیاتی و نکات پنهانی که به آن‌ها «Gotchas» می‌گویند، معمولاً فقط در ذهن توسعه‌دهندگان ارشد باقی می‌مانند.

طبق اعلام تیم توسعه، این ابزار در ۲۱ ژوئیه ۲۰۲۶ منتشر شد تا تنش میان کد و مستندات را حل کند و نگهداری از پایگاه دانش پروژه را به همان عامل‌های هوش مصنوعی بسپارد که در حال نوشتن کد هستند. اکثر مستندات فنی به‌محض نوشته شدن می‌میرند، چون توسعه‌دهندگان وقتی برای به‌روزرسانی آن‌ها ندارند. اما هوش مصنوعی زاینده (Generative AI) — شبیه دستیاری که هر ثانیه تمام تغییرات و گفتگوها را در زمان واقعی می‌بیند و یادداشت می‌کند — می‌تواند این خلأ را پر کند. با تبدیل ویکی به یک شهروند درجه‌یک در مخزن گیت (Git)، CodeAlmanac تضمین می‌کند که دلیلِ پشت هر تغییر (The Why)، هم‌گام با خودِ منطق کد تکامل یابد.

برای درک بهتر، سناریویی را تصور کنید که در آن یک عامل هوش مصنوعی متوجه یک باگ تکراری در زمان انتظار (Timeout) سیستم پرداخت می‌شود. در اینجا، عامل به جای اینکه فقط یک خط کد را اصلاح کند، صفحه ویکی مربوطه را به‌روز می‌کند تا توضیح دهد چرا آن مقدار خاص از Timeout برای یک درگاه پرداخت قدیمی (Legacy Payment Gateway) ضروری است. این رویکرد، هوش مصنوعی را از یک ابزار ساده برای تکمیل خودکار کد (Autocomplete)، به متولی حافظه سازمانی تبدیل می‌کند.

سازوکارهای اصلی و گردش کار

CodeAlmanac یک سیستم محلی (Local-first) است که برای اجرا به پایتون ۳.۱۲ یا بالاتر نیاز دارد. این ابزار به‌طور مستقیم با Codex و Claude Code ادغام شده و از جلسات OAuth موجود در این سرویس‌ها برای اجرای وظایف استفاده می‌کند. این ادغام با قابلیت‌های ویرایشی مدل‌های زبانی همسو است، چرا که Claude Code پیش از این توانایی ویرایش مستقیم فایل‌ها را به محیط ترمینال آورده بود. ابزار مذکور از طریق مجموعه‌ای از «عامل‌های چرخه حیات» (Lifecycle Agents) شامل Build، Ingest و Garden مدیریت می‌شود که توسط Yoke SDK کنترل می‌گردند. این عامل‌ها به صورت یک مجموعه (Collection) در مسیر src/codealmanac/agents/ بسته‌بندی شده‌اند. هر عامل توسط یک فایل agent.yaml (برای تعریف ابزارها و مجوزها) و یک فایل instructions.md (برای دستورالعمل‌های دائمی و پایدار) تعریف می‌شود.

بر اساس مستندات فنی، عامل‌های چرخه حیات به عنوان عامل‌های کدنویسی محلی مورد اعتماد شناخته می‌شوند. آن‌ها با همان مجوزهای گسترده و غیرتعاملی سیستم فایل اجرا می‌شوند که CodeAlmanac در گذشته ارائه می‌داد. بنابراین، مرز پوشه almanac/ در واقع یک دستورالعمل و سیاست مربوط به Commit است، نه یک محیط ایزوله (Sandbox) در سطح سیستم‌عامل.

سه عامل کلیدی در این سیستم فعال‌اند:

• Ingest (جذب): این عامل مواد خام را می‌گیرد و آن‌ها را در ویکی ادغام می‌کند. ورودی‌های پشتیبانی شده شامل فایل‌های محلی، دایرکتوری‌ها، تغییرات گیت (Git diffs)، محدوده‌های کامیت (Commit ranges)، PRها یا Issueهای گیت‌هاب، URLها و حتی متن گفتگوهای محلی با عامل‌ها است. برای مثال، کاربر می‌تواند دستور codealmanac ingest README.md --using codex یا codealmanac ingest github:pr:123 --using claude را اجرا کند.
• Garden (باغبانی): یک عامل نگهداری است که گراف موجود ویکی را بهبود می‌بخشد. هدف این عامل، شناسایی صفحات منقضی شده (Stale)، لینک‌ها، موضوعات، سرنخ‌های ضعیف، صفحات تکراری و ادعاهای بدون پشتیبانی است. اگر متریال جدید هیچ دانش پایداری اضافه نکند، عامل عملیات را متوقف کرده (no-op) و ویکی را بدون تغییر رها می‌کند.
• Sync (همگام‌سازی): یک فرآیند پس‌زمینه است که ذخیره‌گاه‌های متن (Transcript stores) Codex و Claude را برای یافتن گفتگوهای فعال از آخرین همگام‌سازی موفق اسکن می‌کند. گفتگوهایی که با مخازن ثبت شده مرتبط هستند، به عنوان کارهای عادی Ingest در صف قرار می‌گیرند. Sync ممکن است تصمیم بگیرد که یک گفتگو حاوی هیچ دانش پایداری نیست و تغیری در ویکی ایجاد نکند.

معماری فنی و اجرا

تمام عملیات روی macOS از طریق سه Job خاص در launchd اجرا می‌شود که در پس‌زمینه فعالیت می‌کنند. این زمان‌بندی‌ها به صورت محلی اجرا شده و از طریق دستور codealmanac automation status قابل بررسی هستند:

• Sync: هر ۵ ساعت یک‌بار اجرا می‌شود تا گفتگوهای اخیر Codex و Claude را اسکن کرده و دانش مفید را برای ویکی‌های ثبت‌شده مربوطه در صف قرار دهد.
• Garden: هر ۲۴ ساعت یک‌بار اجرا می‌شود تا هر ویکی ثبت‌شده را برای یافتن دانش منقضی شده، تکراری یا ارتباطات ضعیف بازبینی کند.
• Update: هر ۲۴ ساعت یک‌بار برای بررسی و نصب به‌روزرسانی‌های CLI در صورت ایمن بودن اجرا می‌شود. این عملیات زمانی که کارهای چرخه حیات (Lifecycle) در حال اجرا باشند، نادیده گرفته می‌شود.

سیستم یک پوشه به نام almanac/ در ریشه مخزن ایجاد می‌کند. یک مخزن تنها زمانی به عنوان ویکی برای تشخیص خودکار شناخته می‌شود که هر دو فایل almanac/topics.yaml و almanac/README.md در آن موجود باشد.

ساختار ویکی و جزئیات

صفحات Markdown مستقیماً زیر پوشه almanac/ در پوشه‌های معنادار قرار می‌گیرند. ساختار دایرکتوری پیش‌فرض شامل موارد زیر است:

• almanac/README.md: به عنوان صفحه فرود (Landing page) برای مسیر اصلی عمل می‌کند.
• almanac/topics.yaml: صفحات را در پوشه‌های مختلف سازمان‌دهی می‌کند.
• almanac/architecture/: حاوی مستندات طراحی سطح بالا است (مانند indexer.md).
• almanac/decisions/: ثبت می‌کند که چرا چیزها به روش خاصی ساخته شده‌اند (مانند local-first.md).
• almanac/guides/: مستندات کاربردی و راهنماهای عملی (مانند setup.md).

از آنجا که ویکی از فرمت ساده مارک‌داون است، هر تغییر از طریق Git diffهای استاندارد بازبینی می‌شود؛ این بدان معنای است که انسان‌ها قدرت وتوی نهایی را بر مستندات تولید شده توسط هوش مصنوعی دارند.

تعامل و مدیریت

برای کسانی که به دنبال یک نمای بصری هستند، ابزار شامل یک نمایشگر وب محلی فقط-خواندنی است که با دستور codealmanac serve اجرا می‌شود. این نمایشگر صفحات، جست‌وجو، موضوعات، لینک‌های بازگشتی (Backlinks) و پیمایش مراجع فایل را رندر می‌کند. به طور پیش‌فرض، نمایشگر می‌تواند بین ویکی‌های محلی ثبت شده جابه‌جا شود، اما کاربران می‌توانند آن را با دستور codealmanac serve --wiki <name> به یک ویکی خاص محدود کنند. برای استفاده‌های بدون رابط گرافیکی یا اسکریپتی، گزینه codealmanac serve --no-open در دسترس است.

توسعه‌دهندگان همچنین می‌توانند از طریق CLI و دستورات زیر تعامل داشته باشند:

• codealmanac search "checkout timeout" برای یافتن جریان‌های خاص سیستم.
• codealmanac search --mentions src/checkout/ برای یافتن صفحاتی که به فایل‌های خاصی اشاره می‌کنند.
• codealmanac show checkout-flow برای خواندن یک صفحه در ترمینال.
• codealmanac topics و codealmanac health برای بررسی وضعیت ویکی.
• codealmanac validate برای بررسی یکپارچگی (Integrity) ویکی.

اجراهای چرخه حیات در مسیر ~/.codealmanac/ ثبت می‌شوند. کاربران می‌توانند این موارد را از طریق مجموعه دستورات jobs کنترل کنند:

• codealmanac jobs: لیست اجراهای اخیر را با ID، نوع، وضعیت و زمان صرف شده نمایش می‌دهد.
• codealmanac jobs show <run-id>: خلاصه‌ای از Job، تغییرات صفحات، برچسب‌های زمانی و جزئیات خطا را ارائه می‌دهد.
• codealmanac jobs logs <run-id>: یک snapshot از تاریخچه رویدادها، شامل پیشرفت، فعالیت ابزارها و خطاها را چاپ می‌کند.
• codealmanac jobs attach <run-id>: رویدادهای جدید را به صورت زنده دنبال می‌کند تا زمانی که Job تمام شود، شکست بخورد یا لغو شود.
• codealmanac jobs cancel <run-id>: یک Job در حال اجرا و عامل آن را متوقف می‌کند یا از شروع یک Job در صف جلوگیری می‌کند.

افزودن پرچم --json به این دستورات اجازه می‌دهد تا خروجی آن‌ها توسط اسکریپت‌ها مصرف شود.

مدل اعتماد و امنیت

به دلیل اینکه عامل‌های چرخه حیات برای خواندن کدبیس و نوشتن در ویکی به مجوزهای گسترده سیستم فایل نیاز دارند، مدل اعتماد در اینجا صریح است. مرز پوشه almanac/ یک سیاست آموزشی و سیاستی برای کامیت است، نه یک Sandbox در سطح OS. کاربران تشویق می‌شوند دستورات چرخه حیات را تنها در مخازنی اجرا کنند که این مدل اعتماد را می‌پذیرند.

کاربران می‌توانند تمامی کامیت‌های خودکار را بازبینی کنند یا ویژگی auto_commit را در فایل config.toml غیرفعال کنند تا نظارت انسانی تضمین شود. این کار از طریق codealmanac config set auto_commit false امکان‌پذیر است. لازم به ذکر است که CodeAlmanac فایل‌ها را stage نمی‌کند، diffها را تقسیم نمی‌کند و به صورت داخلی کامیت نمی‌کند؛ auto_commit صرفاً به عامل اجازه می‌دهد از دستورات معمولی Git استفاده کند.

در رابطه با حریم خصوصی، این ابزار از تله‌متری ناشناس از طریق یک UUID تصادفی در هنگام نصب استفاده می‌کند. این تله‌متری نتایج کنترل شده دستورات و چرخه حیات به همراه کرش‌های مدیریت‌نشده و پاکسازی شده را ارسال می‌کند. این سیستم هرگز کد، مسیرها، آرگومان‌ها، کوئری‌ها، پرامپت‌ها، تراکریت‌ها، IDهای مخزن/اجرا، متغیرهای محلی یا اعتبارنامه‌ها را ارسال نمی‌کند و ردیابی GeoIP نیز غیرفعال است. بدون یک لاگین آینده، پروفایل UUID هیچ نام یا ایمیلی ندارد. کاربران می‌توانند در هنگام نصب با setup --no-telemetry یا با قرار دادن telemetry.enabled روی false یا استفاده از DO_NOT_TRACK=1 در هر زمان، از این مورد خارج شوند.

پیکربندی و وضعیت محلی

پیکربندی کاربر در ~/.codealmanac/config.toml ذخیره می‌شود. مقادیر پیش‌فرض کلیدی عبارتند از:

• auto_commit = true
• [harness] default = "codex"
• [harness] model = "gpt-5.5"
• [automation.sync] enabled = true و every = "5h"
• [automation.garden] enabled = true و every = "24h"
• [automation.update] enabled = true و every = "24h"

کاربران می‌توانند زمان‌بندی‌های اتوماسیون را با دستوراتی مانند codealmanac config set automation.sync.every 5h تغییر دهند. اگر فایل TOML به صورت دستی ویرایش شود، باید دستور codealmanac config apply برای به‌روزرسانی launchd اجرا گردد. پرچم‌های CLI همیشه بر فایل پیکربندی اولویت دارند.

وضعیت محلی مشتق‌شده (Derived Local State) جدا از درخت ویکی کامیت شده در ~/.codealmanac/ ذخیره می‌شود:

• codealmanac.db: مخازن، اجراها، رویدادها، قفل‌های worker و وضعیت Sync را ثبت می‌کند.
• repos/<repo-id>/index.db: شامل ایندکس‌های مشتق‌شده برای هر مخزن است.
• logs/: لاگ‌های مربوط به Jobهای اتوماسیون پس‌زمینه را در ~/.codealmanac/logs/ ذخیره می‌کند.

ادغام با ارائه‌دهندگان و SDK

CodeAlmanac از almanac-yoke به عنوان تنها مرز ارائه‌دهنده (Provider Boundary) استفاده می‌کند. این رویکرد یادآور معماری‌های پیشرفته‌تری است که در پروژه y برای پیوند عامل‌های هوش مصنوعی با رابط‌های کاربری پویا به کار رفته است. Codex از طریق app-server اجرا می‌شود، در حالی که Claude از سطح پیش‌فرض Yoke — که در حال حاضر SDK عامل پایتون است — استفاده می‌کند. جلسات OAuth موجود Codex یا Claude Code مورد استفاده مجدد قرار می‌گیرند. اعتبارنامه‌های API می‌توانند هنگام جاسازی SDK از طریق Yoke ارائه شوند.

عامل‌های Build، Ingest و Garden به عنوان یک مجموعه عامل (Agent Collection) در Yoke بسته‌بندی شده‌اند. هر عامل از قرارداد پوشه بومی Yoke استفاده می‌کند: agent.yaml ابزارها و مجوزها را توصیف می‌کند و instructions.md حاوی دستورالعمل‌های دائمی عامل است. یک اجرای چرخه حیات تنها کانتکست زمان اجرای تایپ‌شده خود را به عنوان پرامپت وظیفه ارسال می‌کند. پوشه‌های اختیاری skills/، subagents/ و workflows/ را می‌توان به یک عامل اضافه کرد، هرچند اجرای بومی Claude یا Codex همچنان تصمیم می‌گیرد چگونه از آن‌ها استفاده کند. کاربران می‌توانند در دسترس بودن Harness را با codealmanac doctor بررسی کرده و با codex login یا claude auth login احراز هویت کنند.

تغییری در تجربه توسعه‌دهنده

این ابزار به طور fundamental مشکل «آنبوردینگ» را تغییر می‌دهد. به‌جای گشتن در PDFهای ۲۰۰ صفحه‌ای یا صفحات منقضی شده Confluence، یک توسعه‌دهنده جدید می‌تواند از عامل هوش مصنوعی محلی درباره یک ناوردای (Invariant) خاص بپرسد. عامل فقط بر اساس کد حدس نمی‌زند — بلکه به صفحه ویکی احراز شده‌ای استناد می‌کند که توسط عامل هوش مصنوعی مهندس ارشد قبلی ایجاد شده است.

با اتوماسیون «باغبانی» دانش، CodeAlmanac بار شناختی مستندسازی را حذف می‌کند. این ابزار ویکی را از یک بایگانی ایستا به یک ساختار داده پویا تبدیل می‌کند که هوش مصنوعی می‌تواند از آن برای بهبود دقت کدنویسی خود در وظایف آینده استفاده کند.

نصب و مهاجرت

برای شروع، توسعه‌دهندگان می‌توانند از دستور uv tool install codealmanac@latest و سپس codealmanac setup استفاده کنند. فرآیند نصب تعاملی است، اما می‌توان با codealmanac setup --yes برای پیش‌فرض‌های Codex یا codealmanac setup --yes --runner claude برای Claude آن را تسریع کرد. پرچم --target (مثلاً --target codex) تنها فایل‌های دستورالعمل جهانی عامل را انتخاب می‌کند، نه Runner هوش مصنوعی را.

کاربران همچنین می‌توانند نصب را با پرچم‌های زیر سفارشی کنند:

• --sync-every 5h: تغییر فرکانس اسکن.
• --sync-off: عدم نصب همگام‌سازی خودکار تراکریت.
• --garden-off: عدم نصب پاکسازی خودکار ویکی.
• --no-auto-update: عدم نصب به‌روزرسانی‌های خودکار CLI.

برای حذف تمام مصنوعات محلی متعلق به CodeAlmanac، از codealmanac uninstall --yes استفاده کنید.

برای کسانی که از CLI قدیمی npm مهاجرت می‌کنند، فرآیند شامل حذف تمام پکیج‌های جهانی npm، Hookها و دستورالعمل‌های قدیمی عامل است. مسیر مهاجرت توصیه شده عبارت است از:

1. npm uninstall -g codealmanac (و حذف هرگونه نصب توسط bun، pnpm یا yarn).
2. uv tool install codealmanac@latest
3. codealmanac setup --yes
4. codealmanac doctor برای تأیید در دسترس بودن Harness.

درخت‌های almanac/ محلی در هر مخزن را تغییر ندهید؛ آن‌ها محتوای ویکی کامیت شده هستند و بخشی از نصب CLI نیستند.

اگر کاربر با خطاهای spawn ... ENOENT در Harness کدکس مواجه شد، این معمولاً نشان‌دهنده یک باینری محلی خراب است که اغلب به دلیل نصب ناقص یا تغییر نسخه Node تحت nvm/volta/fnm رخ می‌دهد. این مشکل با نصب مجدد Codex CLI از طریق npm install -g @openai/codex و تأیید با codex --version حل می‌شود. نصب مجدد باعث خروج شما از حساب نمی‌شود، زیرا codex لاگین خود را در ~/.codex نگه می‌دارد. متناوباً، کاربر می‌تواند codealmanac config set harness.default claude Runner خود را تغییر دهد.

گام بعدی شما

• اگر پروژه بزرگی با مستندات قدیمی دارید، ابتدا codealmanac setup را اجرا کرده و با دستور ingest فایل‌های README فعلی را جذب کنید.
• در فایل config.toml مقدار auto_commit را false کنید تا در ابتدای کار، کیفیت نوشته‌های AI را شخصاً تایید کنید.
• از دستور codealmanac serve برای تحلیل بصری روابط پرداخت و معماری سیستم خود استفاده کنید.

اما تاثیر این رویکرد بر کاهش هزینه‌های استنتاج در پروژه‌های عظیم، داستان دیگری است — به تحلیل ما درباره بهینه‌سازی توکن‌ها در مدل‌های استدلالی مراجعه کنید.