تصور کنید برنامه‌نویسی هستید که برای یادآوری هدرهای یک وب‌هوک پرداخت یا نقاط انتهایی مربوط به بازپرداخت‌های جزئی (Partial Refund)، باید هر بار دستورات cURL را به صورت دستی در ChatGPT کپی کند؛ این فرآیند خسته‌کننده و دستی اکنون به تاریخ پیوست. در ۶ اکتبر ۲۰۲۶، شرکت Cognee رابط رسمی اتصال به داده‌های Postman را منتشر کرد تا مجموعه‌های ایستا (Static) را به یک لایه حافظه پویا، پایدار و قابل پرس‌وجو برای عامل‌های هوش مصنوعی (AI Agents) تبدیل کند.
بسیاری از تیم‌های نرم‌افزاری صدها میکروسرویس و APIهای شخص ثالث را مدیریت می‌کنند و در این میان، Postman برای آن‌ها حکم مستندات زنده را دارد که مسیرهای Endpoint، الزامات احراز هویت، بدنه درخواست‌ها (Request Bodies) و پارامترهای پرس‌وجو را در خود جای داده است. اما مدل‌های زبانی بزرگ (LLM) — مثل کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن جواب می‌دهد — معمولاً دسترسی مستقیم به این دانش سازمانی ندارند. این موضوع باعث ایجاد شکافی میان وضعیت واقعی API و درک هوش مصنوعی می‌شود. این رابط که در جریان رویداد Mergetober ۲۰۲۶ ساخته شده، با تبدیل نقاط انتهایی به موجودیت‌های ساختاریافته به جای متن‌های خام، این فاصله را پر می‌کند.
به نقل از گزارش dev.to، این سیستم از ابزار dlt (data load tool) برای انتقال داده‌ها در یک خط لوله (Pipeline) سه مرحله‌ای استفاده می‌کند:
cognee.add(data): مستندات یا رکوردهای ساختاریافته را در سیستم مرحله‌بندی (Stage) می‌کند.cognee.cognify(): محتوا را با یک LLM تحلیل می‌کند تا موجودیت‌های دامنه و روابط بین آن‌ها را استخراج کرده و یک گراف دانش (Knowledge Graph) پایدار بسازد.cognee.search(query): برای بازیابی دقیق حافظه متنی، در گراف متصل و شاخص‌های برداری (Vector Indexes) جست‌وجو می‌کند.
یکی از بزرگ‌ترین چالش‌های فنی، حل مسئله سلسله‌مراتب JSON است. مجموعه‌های Postman در واقع درخت‌هایی با تودرتویی عمیق هستند؛ جایی که مجموعه‌ها شامل پوشه‌ها، پوشه‌ها شامل زیرپوشه‌ها و آیتم‌ها شامل درخواست‌ها و پاسخ‌ها هستند. برای اینکه هوش مصنوعی صرفاً سینتکس JSON را تکرار نکند، Cognee از یک رندرکننده مارک‌داون اختصاصی (renderer.py) استفاده می‌کند. این ابزار درخت داده‌ها را تا ۵۰ سطح عمق بررسی می‌کند تا مستنداتی مجزا با ویژگی‌های زیر ایجاد کند:
- مسیرهای ناوبری (Breadcrumbs): نمایش صریح مسیر ناوبری پوشه‌ها (مثلاً: Orders > Fulfillment > Ship Package).
- متد و مسیر HTTP: ساختارهای واضح در قالب سرتیترها مانند
[POST] /v1/orders/{id}/fulfill. - جداول پارامتر: جداول فرمت‌شده مارک‌داون برای هدرها، پارامترهای مسیر (Path Parameters) و پارامترهای پرس‌وجو (Query Parameters).
- طرح‌های Payload: تعاریف JSON، GraphQL و form-data با هایلایت سینتکس.
- پاسخ‌های نمونه: ثبت کدهای وضعیت (مانند ۲۰۰، ۴۰۰، ۴۰۴) و نمونه‌های بدنه JSON.
در این ساختار، هر درخواست به یک گره مستقل در گراف Cognee تبدیل می‌شود که با یک شناسه ترکیبی قطعی (Deterministic Composite ID) با فرمت f"{collection_uid}:{item_id}" برچسب می‌خورد.
بر اساس مستندات فنی این پروژه، برای جلوگیری از برخورد با محدودیت‌های نرخ درخواست (Rate Limit) در REST API مربوط به Postman، سیستم از همگام‌سازی افزایشی با بازدهی بالا استفاده می‌کند. این سیستم متادیتای updatedAt را با استفاده از dlt.current.resource_state() ردیابی می‌کند. اگر برچسب زمانی یک مجموعه تغییر نکرده باشد، رابط اتصال به‌طور کامل از فراخوانی API جزئیات صرف‌نظر می‌کند — که منجر به مصرف صفر درخواست API می‌شود — و ردیف‌های مستندات را مستقیماً از حافظه موقت (State Cache) بازمی‌گرداند.
برای حفظ بهداشت داده‌ها، رابط اتصال از معناشناسی «حذف در صورت پاک‌شدن» (forget-on-delete) از طریق متد full-snapshot استفاده می‌کند. با تعریف write_disposition="replace" در @dlt.resource و برچسب‌گذاری DOCUMENT_SOURCE_ATTR = "postman"، اسنپ‌شات فعال تنها شامل مجموعه‌هایی است که در حال حاضر قابل مشاهده هستند. هر مجموعه‌ای که در Postman حذف یا غیرقابل اشتراک شود، از مرحله Stage خارج شده و باعث می‌شود سیستم داخلی orphan_cleanup در Cognee، گره‌ها و روابط قدیمی را از گراف دانش پاک کند.
استانداردهای مهندسی تولید (Production Engineering) در این پیاده‌سازی به شدت رعایت شده است:
- کلاینت HTTP مقاوم: ماژول
client.pyدارای قابلیت Exponential Backoff خودکار همراه با Jitter است و هدرهایRetry-Afterرا در هنگام خطاهای ۴۲۹ (Rate Limit) به صورت بومی تحلیل می‌کند. همچنین خطاهای Gateway مانند HTML 502/500 را مدیریت می‌کند. - هشینگ قطعی: سیستم برای آیتم‌هایی که فاقد شناسه صریح هستند، از کلیدهای جایگزین UUIDv5 مطابق استاندارد RFC 4122 استفاده می‌کند.
- جلوگیری از نوسان داده (Churn Prevention): برچسب‌های زمانی متغیر مانند
createdAtوupdatedAtاز بدنه مستندات حذف شده‌اند تا از تغییرات بی‌مورد درcontent_hashدر Cognee جلوگیری شود. - رعایت تایپوگرافی: یک قانون «ناپایدار نبودن Emdash» (Zero Emdash Invariant) برای پاک‌سازی خودکار متن مطابق با دستورالعمل‌های مخزن کد اعمال شده است.
- اعتبارسنجی: یک مجموعه تست آفلاین (
test_postman.py) شامل ۱۸۰ تست واحد در ۴ سطح مختلف وجود دارد که در تنها ۰.۶۲ ثانیه اجرا می‌شود.
این تغییر، مستندات API را از یک دفترچه راهنمای غیرفعال به بخشی فعال از پشته (Stack) هوش مصنوعی تبدیل می‌کند. حالا توسعه‌دهندگان می‌توانند بازرسان خودکار API یا دستیارهای کدنویسی هوشمندی بسازند که وابستگی‌های سرویس را واقعاً درک می‌کنند.
برای توسعه‌دهنده، این یعنی «حافظه سازمانی» یک API دیگر در یک فضای کاری محبوس نیست، بلکه ابزاری برای هر گردش‌کار عامل‌محور (Agentic) است. این رویکرد در تضاد با متدهای سنتی است و می‌تواند چالش‌های بازسازی سیستم‌های میراثی را از طریق اتوماسیون هوشمند حل کند. معیار موفقیت مستندات از «خوانایی برای انسان» به «قابلیت ایندکس برای عامل‌ها» تغییر کرده است.
برای توسعه‌دهنده، این یعنی «حافظه سازمانی» یک API دیگر در یک فضای کاری محبوس نیست، بلکه ابزاری برای هر گردش‌کار عامل‌محور (Agentic) است. این قابلیت اتصال به داده‌های خارجی، مشابه توسعه‌های اخیر متا در عامل Muse برای مدیریت عملیات کسب‌وکارهاست که بر پایه اتصال به منابع داده‌ای متنوع بنا شده است. معیار موفقیت مستندات از «خوانایی برای انسان» به «قابلیت ایندکس برای عامل‌ها» تغییر کرده است.
گام بعدی شما
- اگر از Postman برای مدیریت APIها استفاده می‌کنید، کلید
POSTMAN_API_KEYخود را آماده کنید. - مخزن جامعه Cognee را در مسیر
packages/connector/postman/بررسی کرده وpostman_sourceرا اجرا کنید. - سعی کنید یک عامل ساده بسازید که بتواند بر اساس گراف دانش، تداخلات بین Endpoints مختلف را شناسایی کند.
اما این تنها بخشی از معماری حافظه است؛ برای درک نحوه مدیریت داده‌های غیرساختاریافته در گراف‌های دانش، تحلیل ما درباره پروتکل MCP را بخوانید.
گفتگو