AI एजेंट की याददाश्त सत्रों के बीच: प्रगति-फ़ाइल, निर्णय-लॉग, git और init-स्क्रिप्ट

एजेंट कुछ क्यों नहीं याद रखता

मॉडल हर चलने के बीच कोई अवस्था नहीं रखता। एजेंट आपके कार्य के बारे में जो कुछ «जानता» है, वह वर्तमान सत्र के संदर्भ-विंडो में होता है: पढ़ी गई फ़ाइलें, कमांड का आउटपुट, आपके साथ का संवाद। सत्र बंद हो गया या संदर्भ भर गया, तो नया सत्र शून्य से शुरू होता है और केवल वही देखता है, जो डिस्क पर लिखा है।

एक उपयोगी मॉडल: एक प्रतिभाशाली इंजीनियर, जो हर सुबह दफ़्तर पूरी तरह मिटी हुई याददाश्त के साथ आता है। वह कोड जल्दी समझ लेता है, पर उसे याद नहीं रहता कि कल किस आर्किटेक्चर को चुना गया, क्यों बाकी ठुकराए गए और टेस्ट किस स्थिति में हैं। बिना नोट्स के वह पंद्रह-बीस मिनट खोज में लगाएगा और बड़ी संभावना है कि आपके सोच-समझकर ठुकराए गए विकल्प को फिर से बना देगा।

इसलिए AI एजेंट की याददाश्त मॉडल का गुण नहीं, हार्नेस का हिस्सा है: फ़ाइलों और नियमों का वह समूह, जिसे आप खुद डिज़ाइन करते हैं। अच्छी बात यह है कि इसके लिए वेक्टर डेटाबेस या विशेष सेवाओं की ज़रूरत नहीं। कुछ Markdown फ़ाइलें, git और अनुशासन काफ़ी हैं।

बड़ी संदर्भ-विंडो समस्या क्यों हल नहीं करती

लगता है कि किसी बड़ी विंडो वाले मॉडल का इंतज़ार कर लें। पर जटिल कार्य कोई भी विंडो भर देता है: एजेंट कोडबेस पढ़ता है, निर्णयों का इतिहास जमा होता है, टेस्ट का लंबा आउटपुट आता है, और पूरा संवाद बना रहता है। ज़रूरतें विंडो के साथ बढ़ती हैं। यह आकार की नहीं, आर्किटेक्चर की समस्या है।

एक और असर भी है। विंडो की सीमा के करीब कई मॉडल जल्दबाज़ी करने लगते हैं: जाँच छोड़ देते हैं, सही हल की जगह सरल हल चुनते हैं। Anthropic ने अपने मॉडलों के लिए यह अवलोकन दर्ज किया है, और प्रभाव मॉडल-दर-मॉडल अलग होता है। सीमा पर चलता लंबा सत्र केवल जानकारी खोने का नहीं, काम की गुणवत्ता बिगड़ने का भी जोखिम है।

संक्षेपण: क्या बचता है और क्या खोता है

संक्षेपण (compaction) का अर्थ है बातचीत के शुरुआती हिस्से को छोटे सार में बदलना, ताकि उसी सत्र में जगह बने। Claude Code में यह काम /compact कमांड करती है, और सीमा के करीब पहुँचने पर यह अपने-आप भी होता है। इसके उलट /clear इतिहास मिटाकर बातचीत नए सिरे से शुरू करती है।

संक्षेपण की समस्या यह है कि सार आमतौर पर «क्या» बचाता है और «क्यों» खो देता है। तैयार कोड फ़ाइलों में रहता है, पर तर्क, जैसे विकल्प Б क्यों चुना, कोई लाइब्रेरी क्यों नहीं ली, किस ऑप्टिमाइज़ेशन को जानबूझकर छोड़ा, ये दो शब्दों में सिमट जाते हैं या गायब हो जाते हैं। एजेंट का अगला कदम सोच-समझकर लिए गए फ़ैसले को «सुधार» देता है, क्योंकि उसे उसके कारण नहीं दिखते।

बिना जटिल मेट्रिक्स का व्यावहारिक नियम: जब कार्य लगभग 60% विंडो ले ले, तो कोड लिखना रोककर हैंडओवर की तैयारी करें। अगर संदर्भ 40% भरा है और कार्य का अंत पास है, तो संक्षेपण काफ़ी है।

चार कलाकृतियाँ, जिनसे एजेंट की याददाश्त बनती है

मॉडल की याददाश्त पर भरोसा करने के बजाय एक बोर्ड-लॉग रखें। इसके चार हिस्से हैं, और हर एक की अपनी भूमिका है।

1. PROGRESS.md — अभी हम कहाँ हैं।
2. DECISIONS.md — ऐसा क्यों किया, दूसरा क्यों नहीं।
3. Git-कमिट — अवस्था के मुफ़्त चेकपॉइंट।
4. AGENTS.md में शिफ़्ट-प्रोटोकॉल — आने और जाने पर क्या करना है।

PROGRESS.md: प्रगति-फ़ाइल

इसका एक ही सवाल है: प्रोजेक्ट अभी किस स्थिति में है। एजेंट सत्र की शुरुआत में इसे पहले पढ़ता है और जाने से पहले सबसे आखिर में अपडेट करता है। फ़ाइल छोटी रहती है, उसे बार-बार नए सिरे से लिखा जाता है, इतिहास बस git में रहता है।

# PROGRESS.md

## अभी का लक्ष्य
उत्पाद कैटलॉग में खोज (फ़ीचर search-01)

## स्थिति
- HEAD: 4f2a9c1
- make check: हरा, 142/142 टेस्ट
- हो चुका: PostgreSQL में इंडेक्स (tsvector), GET /search हैंडलर
- जाँचा गया: यूनिट-टेस्ट + 3 अनुरोधों पर हाथ से curl

## अवरोध
- कज़ाख भाषा के लिए मॉर्फ़ोलॉजी का डेटा नहीं है — निर्णय की प्रतीक्षा

## अगला कदम
GET /search में पेजिनेशन जोड़ना, मानदंड: दूसरे पन्ने पर टेस्ट

इन चार फ़ील्ड पर ध्यान दें, जो हैंडओवर के लिए काफ़ी हैं: कमिट का हैश, पास होने वाले टेस्टों का अनुपात, अवरोध और अगला कदम। अगर नया सत्र इस फ़ाइल से काम को एक अर्थ में आगे नहीं बढ़ा सकता, तो टेम्पलेट में कोई फ़ील्ड कम है।

DECISIONS.md: निर्णयों का लॉग

इसमें वही «क्यों» रहता है, जो संक्षेपण में खो जाता है। प्रविष्टि का प्रारूप: निर्णय, कारण, क्या ठुकराया और क्यों, सीमाएँ।

## 2026-03-14 — उपयोगकर्ता सेटिंग्स का कैश Redis में
- निर्णय: Redis, TTL 5 मिनट, लिखने पर सक्रिय अमान्यकरण।
- कारण: हर अनुरोध पर पढ़ा जाता है, डेटा बहुत छोटा है।
- ठुकराया: PostgreSQL में materialized view — बदलाव बहुत बार होते हैं,
  उसका रख-रखाव लाभकारी नहीं।
- सीमा: भुगतान की सेटिंग्स कैश न करें।

इसकी सबसे कीमती पंक्ति «ठुकराया» है। वही अगले सत्र को उस विकल्प की ओर «ऑप्टिमाइज़» करने से रोकती है, जिस पर पहले विचार करके छोड़ दिया गया था। निर्णय-लॉग, प्रगति-फ़ाइल के विपरीत, केवल बढ़ता है: पुरानी प्रविष्टियाँ मिटाई नहीं जातीं, बल्कि नई से बदली हुई चिह्नित की जाती हैं।

git-इतिहास को चेकपॉइंट के रूप में

कमिट काम के भीतर पहले से बने, संस्करणबद्ध अवस्था-चित्र हैं। एजेंट git log और git diff पढ़कर देख सकता है कि क्या बदला गया। इतिहास याददाश्त का काम करे, इसके लिए कमिट-संदेश को मंशा समझानी चाहिए, डिफ़ दोबारा नहीं बताना चाहिए।

# बुरा
git commit -m "update search.py"

# अच्छा
git commit -m "search: LIKE की जगह tsvector इंडेक्स

LIKE '%q%' इंडेक्स का उपयोग नहीं करता, 200k उत्पादों पर अनुरोध 1.8 सेकंड।
पेजिनेशन अभी नहीं है, देखें PROGRESS.md."

हर हरे टेस्ट-रन के बाद छोटे, बार-बार होने वाले कमिट एक रोलबैक-बिंदु भी देते हैं। अगर सत्र गलत दिशा में गया, तो आधे-पके बदलावों को सुलझाने के बजाय आखिरी जाँची गई अवस्था पर लौटना आसान है।

AGENTS.md में शिफ़्ट-प्रोटोकॉल

अवस्था-फ़ाइलें तभी काम की हैं, जब एजेंट उनके बारे में जानता हो। इसलिए निर्देश-फ़ाइल (AGENTS.md या CLAUDE.md) में छोटा प्रोटोकॉल लिखा जाता है: आने और जाने पर क्या करना है।

## शिफ़्ट पर आना
1. PROGRESS.md और DECISIONS.md पढ़ें।
2. .agent/feature_list.json में सक्रिय कार्य खोजें।
3. make check चलाएँ — पक्का करें कि रिपॉज़िटरी सुसंगत है।
4. «अगले कदम» से आगे बढ़ें, तय किए गए फ़ैसलों को दोबारा न खोलें।

## शिफ़्ट से जाना
1. make check चलाएँ, हरी अवस्था कमिट करें।
2. PROGRESS.md अपडेट करें: HEAD, टेस्ट, अवरोध, अगला कदम।
3. DECISIONS.md में नए निर्णय जोड़ें।
4. वर्किंग ट्री में आधा-अधूरा काम न छोड़ें।

प्रोटोकॉल छोटा रखना बेहतर है: यह इनपुट-फ़ाइल में कुछ पंक्तियाँ हैं, अलग से लंबा दस्तावेज़ नहीं।

Init-स्क्रिप्ट: सत्र की शुरुआत कैसे तेज़ करें

ताकि एजेंट तस्वीर हाथ से न जोड़े, उसे एक ऐसी स्क्रिप्ट दें जो वातावरण जाँचे और स्थिति छापे। स्क्रिप्ट idempotent हो, यानी कितनी भी बार चलाई जा सके, और अंत में साफ़ «तैयार» संदेश दे।

#!/usr/bin/env bash
set -euo pipefail

echo "== 1. वातावरण =="
command -v uv >/dev/null || { echo "FAIL: uv इंस्टॉल नहीं है"; exit 1; }
uv sync --frozen

echo "== 2. रिपॉज़िटरी =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: वर्किंग ट्री गंदा है"
else
  echo "OK: साफ़ है"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== 3. जाँच =="
make check

echo "== 4. स्थिति =="
cat PROGRESS.md

echo "काम के लिए तैयार"

तब शुरुआती प्रोटोकॉल में एक पंक्ति काफ़ी है: «scripts/init.sh चलाओ»। Claude Code में यह चलना सत्र-शुरुआत के हुक (इवेंट SessionStart) से स्वचालित किया जा सकता है, पर हुक के बिना भी एजेंट फ़ाइल के निर्देश से स्क्रिप्ट चला लेगा।

एजेंट की याददाश्त में क्या रखें और क्या नहीं

सबसे बड़ी गलती है याददाश्त को कबाड़खाना बना देना। हर पंक्ति, जिसे एजेंट शुरुआत में पढ़ता है, संदर्भ में जगह लेती है, और फ़ालतू बातें ज़रूरी बातों को धुंधला कर देती हैं।

जीवन-काल के अनुसार भी अलग करें। प्रोजेक्ट के नियम कम बदलते हैं और सभी कार्यों पर लागू होते हैं, इसलिए वे इनपुट-निर्देश फ़ाइल में रहें। अवस्था हर सत्र में बदलती है, इसलिए वह प्रगति-फ़ाइल में रहे। दोनों मिल जाएँ तो निर्देश-फ़ाइल पुराने नोट्स से जल्दी फूल जाती है।

पहला सत्र: आरंभ (init) को अलग चरण के रूप में

पहला सत्र अगर अराजकता में चला गया, तो सत्रों के बीच की याददाश्त से कुछ नहीं बदलता। आम तस्वीर: आप साफ़ रिपॉज़िटरी में लिखते हैं «खोज जोड़ो», और आधे घंटे बाद पता चलता है कि टेस्ट फ़्रेमवर्क गलत सेट है और माइग्रेशन का फ़ॉर्मेट भी गलत है। खोज बन गई, पर नींव टेढ़ी है।

कारण यह कि कार्यान्वयन और आरंभ अलग चीज़ों को अनुकूलित करते हैं: पहला इस सत्र में तैयार फ़ीचरों की संख्या को, दूसरा आगे के सभी सत्रों की गति और भरोसेमंदी को। एजेंट दिखने वाले परिणाम की ओर झुकता है, यानी कोड की ओर। इसलिए आरंभ को चार शर्तों वाले स्पष्ट मानदंड के साथ अलग सत्र में रखें।

• चले: साफ़ क्लोन से make setup और make dev काम करें।
• जाँच हो: make test हो और कम से कम एक असली, पास होने वाला टेस्ट हो।
• प्रगति दिखे: अवस्था-फ़ाइल मौजूद हो और पढ़ी जा सके।
• काम उठाया जा सके: स्वीकृति-मानदंड वाली कार्य-सूची हो।

अगर आप अक्सर नए प्रोजेक्ट शुरू करते हैं, तो एक रिपॉज़िटरी-टेम्पलेट रखें: Makefile, टेस्ट-फ़्रेमवर्क, AGENTS.md का ढाँचा, .agent/ फ़ोल्डर, scripts/init.sh, लिंटर और CI। तब आरंभ केवल उस प्रोजेक्ट की विशेषताओं तक सीमित रह जाता है।

जाँचें कि याददाश्त काम कर रही है

सबसे ईमानदार मेट्रिक है: नए सत्र की शुरुआत से पहले कोड-बदलाव तक का समय। बिना कलाकृतियों के यह आमतौर पर पंद्रह-बीस मिनट की खोज होती है, अच्छे हैंडओवर के साथ दो-तीन मिनट। एक बार पहले और बाद में नाप लें, तो दिख जाएगा कि अनुशासन फ़ायदेमंद है या नहीं।

दूसरा तरीका है कोल्ड-स्टार्ट टेस्ट। नया सत्र खोलें, लिखें «जारी रखो», और पाँच सवाल पूछें: अभी का लक्ष्य क्या है, टेस्ट किस स्थिति में हैं, मुख्य विषय पर कौन सा निर्णय लिया गया और क्यों, क्या अवरुद्ध है, अगला कदम क्या है। अगर एजेंट पाँचों के उत्तर फ़ाइलों से देता है, बिना अंदाज़े के, तो याददाश्त सही बनी है। हर अनिश्चित उत्तर टेम्पलेट में एक छूटा हुआ फ़ील्ड है।

आम गलतियाँ

• प्रगति-फ़ाइल केवल बढ़ती है। एक महीने बाद उसमें सैकड़ों पंक्तियों का इतिहास होता है। उसे मौजूदा स्थिति के हिसाब से दोबारा लिखें, इतिहास git में है।
• «ठुकराया» वाली पंक्ति नहीं। निर्णय-लॉग में ठुकराए गए विकल्प न हों, तो वह दोबारा होने वाली बहसों से नहीं बचाता।
• एजेंट अवस्था «अंदाज़े से» अपडेट करता है। लिखें कि जाँच कैसे हुई: कमांड और परिणाम, «सब चल रहा है» नहीं।
• संदर्भ की सीमा पर हैंडओवर। विंडो की सीमा पर एजेंट पहले से जल्दबाज़ी कर रहा होता है; हैंडओवर लगभग 60% पर शुरू करें।
• सत्र के अंत में गंदा वर्किंग ट्री। बिना कमिट के आधे-पके बदलाव अगले सत्र को भ्रमित करते हैं।

संक्षेप में

AI एजेंट की सत्रों के बीच याददाश्त मॉडल पर नहीं, फ़ाइलों पर टिकती है: PROGRESS.md वर्तमान अवस्था रखता है, DECISIONS.md कारण और ठुकराए गए विकल्प, git-कमिट मंशा समझाने वाले चेकपॉइंट, और AGENTS.md का शिफ़्ट-प्रोटोकॉल एजेंट को यह सब पढ़ने और अपडेट करने पर मजबूर करता है। Init-स्क्रिप्ट शुरुआत को एक कमांड तक सीमित करती है, और कोल्ड-स्टार्ट टेस्ट दिखाता है कि प्रविष्टियाँ काफ़ी हैं या नहीं। बोर्ड-लॉग और bootstrap-अनुबंध कोर्स में harness engineering पर व्यवहार में समझाए गए हैं।