AI এজেন্টের সেশনের মধ্যে স্মৃতি: অগ্রগতির ফাইল, সিদ্ধান্তের লগ, git ও init-স্ক্রিপ্ট

এজেন্ট কিছু মনে রাখে না কেন

মডেল প্রতিটি চালনার মাঝে কোনো অবস্থা ধরে রাখে না। আপনার কাজ সম্পর্কে এজেন্ট যা «জানে», তা বর্তমান সেশনের কনটেক্সট উইন্ডোতে থাকে: পড়া ফাইল, কমান্ডের আউটপুট, আপনার সঙ্গে কথোপকথন। সেশন বন্ধ হলো বা কনটেক্সট ভরে গেল, নতুন সেশন শূন্য থেকে শুরু করে এবং দেখে শুধু ডিস্কে লেখা জিনিস।

একটি কার্যকর মডেল: একজন প্রতিভাবান ইঞ্জিনিয়ার, যে প্রতি সকালে কাজে আসে কিন্তু স্মৃতি সম্পূর্ণ মুছে গেছে। সে দ্রুত কোড বুঝে ফেলবে, কিন্তু মনে করতে পারবে না গতকাল কোন স্থাপত্য বাছা হয়েছিল, কেন বাকিগুলো বাতিল হয়েছিল, আর টেস্ট কোন অবস্থায় আছে। লিখিত নোট না থাকলে সে পনেরো-বিশ মিনিট অনুসন্ধানে কাটাবে এবং বেশ সম্ভাবনায় এমন কিছু আবার বানাবে যা আপনি ইচ্ছে করেই বাতিল করেছিলেন।

তাই AI এজেন্টের স্মৃতি মডেলের বৈশিষ্ট্য নয়, হারনেসের একটি অংশ: ফাইল ও নিয়মের একটি সেট, যা আপনি নিজে ডিজাইন করেন। ভালো খবর, এজন্য ভেক্টর ডেটাবেস বা বিশেষ সেবা লাগে না। কয়েকটি Markdown ফাইল, git এবং শৃঙ্খলা যথেষ্ট।

বড় কনটেক্সট উইন্ডো কেন সমস্যা মেটায় না

মনে হতে পারে একটু বড় উইন্ডোর মডেল আসা পর্যন্ত অপেক্ষা করলেই হবে। কিন্তু জটিল কাজ যেকোনো উইন্ডো ভরে ফেলে: এজেন্ট কোডবেস পড়ে, সিদ্ধান্তের ইতিহাস জমে, টেস্টের বাকবাকে আউটপুট আসে, এবং পুরো কথোপকথন ধরে রাখা হয়। চাহিদা উইন্ডোর সঙ্গে সঙ্গে বাড়ে। এটি আকারের প্রশ্ন নয়, স্থাপত্যের সমস্যা।

আরেকটি প্রভাবও আছে। উইন্ডোর সীমার কাছাকাছি অনেক মডেল তাড়াহুড়ো শুরু করে: যাচাই এড়িয়ে যায়, জটিল সমাধানের বদলে সহজটি বেছে নেয়। Anthropic তার মডেলগুলোর জন্য এই পর্যবেক্ষণ বর্ণনা করেছে, তবে প্রভাবের মাত্রা মডেলভেদে আলাদা। সীমার কাছে দীর্ঘ সেশন শুধু তথ্য হারানোর ঝুঁকি নয়, কাজের মানও কমানোর ঝুঁকি।

কমপ্যাকশন: কী টিকে থাকে, কী হারায়

কমপ্যাকশন হলো শুরুর কথোপকথন একটি সারসংক্ষেপে সংকুচিত করা, যাতে একই সেশনে জায়গা খালি হয়। Claude Code-এ এটি করে /compact কমান্ড, এবং উইন্ডো সীমার কাছে গেলে তা নিজে থেকেও ঘটে। /clear উল্টো: ইতিহাস মুছে নতুন করে শুরু করে।

কমপ্যাকশনের সমস্যা: সারসংক্ষেপ সাধারণত «কী»-কে রাখে আর «কেন»-কে হারায়। তৈরি কোড ফাইলেই থাকে, কিন্তু যুক্তি, যেমন কেন বিকল্প খ নেওয়া হলো, কেন লাইব্রেরি নেওয়া হলো না, কেন অপটিমাইজেশন ইচ্ছে করে বাদ গেল, তা কয়েকটি শব্দে সংকুচিত হয় বা মুছে যায়। পরের ধাপে এজেন্ট একটি সচেতন সিদ্ধান্ত «উন্নত» করে ফেলে, কারণ কারণগুলো আর তার চোখের সামনে নেই।

জটিল মেট্রিক ছাড়া একটি ব্যবহারিক নিয়ম: কাজ যখন উইন্ডোর প্রায় ৬০% নিয়েছে, তখন কোড লেখা থামিয়ে হস্তান্তরের প্রস্তুতি নিন। আর প্রসঙ্গ ৪০%-এ থাকে এবং কাজের শেষ হাতের কাছে, তবে কমপ্যাকশনই যথেষ্ট।

AI এজেন্টের স্মৃতির চারটি আর্টিফ্যাক্ট

মডেলের স্মৃতির ওপর ভরসা না করে একটি বোর্ড-লগ রাখুন। এতে চারটি অংশ আছে, এবং প্রতিটির ভূমিকা আলাদা।

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

## বাধা
- কাজাখ ভাষার morphology-র তথ্য নেই — সিদ্ধান্তের অপেক্ষা

## পরের ধাপ
GET /search-এ পেজিনেশন যোগ করা, মানদণ্ড: দ্বিতীয় পাতার টেস্ট

চারটি ফিল্ডে লক্ষ করুন, যা হস্তান্তরের জন্য যথেষ্ট: কমিটের হ্যাশ, পাস-করা টেস্টের অংশ, বাধাসমূহ এবং পরের ধাপ। নতুন সেশন যদি এই ফাইল দিয়ে কাজটি নিঃসন্দেহে চালিয়ে যেতে না পারে, তবে টেমপ্লেটে একটি ফিল্ড কম আছে।

DECISIONS.md: সিদ্ধান্তের লগ

এখানে থাকে সেই «কেন», যা কমপ্যাকশনে হারায়। একটি এন্ট্রির ফরম্যাট: সিদ্ধান্ত, কারণ, কী বাতিল হলো এবং কেন, সীমাবদ্ধতা।

## 2026-03-14 — ব্যবহারকারীর সেটিংসের ক্যাশ Redis-এ
- সিদ্ধান্ত: Redis, TTL 5 মিনিট, লেখার সময় সক্রিয় বাতিলকরণ।
- কারণ: প্রতিটি অনুরোধে পড়া হয়, ডেটার আকার ছোট।
- বাতিল: PostgreSQL-এর materialized view — পরিবর্তন খুব ঘন ঘন, রক্ষণাবেক্ষণ লাভজনক নয়।
- সীমাবদ্ধতা: পেমেন্টের সেটিংস ক্যাশ করা হবে না।

সবচেয়ে মূল্যবান লাইন এখানে — «বাতিল»। এটি পরের সেশনকে সিদ্ধান্তটি «অপটিমাইজ» করে সেই বিকল্পে ফিরিয়ে নিতে বাধা দেয়, যেটি আগে বিবেচনা করে বাদ দেওয়া হয়েছে। সিদ্ধান্তের লগ শুধু বাড়ে: পুরনো এন্ট্রি মুছে ফেলা হয় না, নতুন এন্ট্রি দিয়ে «প্রতিস্থাপিত» বলে চিহ্নিত করা হয়।

Git-ইতিহাস চেকপয়েন্ট হিসেবে

কমিট কাজের সঙ্গে আগে থেকেই আসা সংস্করণ-করা অবস্থার স্ন্যাপশট। এজেন্ট git log ও git diff পড়ে বুঝতে পারে কী বদলেছে। ইতিহাস স্মৃতির মতো কাজ করার জন্য কমিটের বার্তা লেখা উচিত পরিবর্তনের উদ্দেশ্য, 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-স্ক্রিপ্ট: সেশনের শুরু দ্রুত করা

এজেন্ট যাতে ছবিটি হাতে জোড়া না দেয়, তাকে এমন একটি স্ক্রিপ্ট দিন যা পরিবেশ যাচাই করে এবং অবস্থা ছাপায়। স্ক্রিপ্টটি ইডেমপোটেন্ট হওয়া উচিত: যতবার খুশি চালানো যায়, এবং শেষে একটি স্পষ্ট প্রস্তুতির বার্তা দেয়।

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

echo "== ১. পরিবেশ =="
command -v uv >/dev/null || { echo "FAIL: uv ইনস্টল নেই"; exit 1; }
uv sync --frozen

echo "== ২. রিপোজিটরি =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: কার্যকরী ডিরেক্টরি অপরিষ্কার"
else
  echo "OK: পরিষ্কার"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== ৩. যাচাই =="
make check

echo "== ৪. অবস্থা =="
cat PROGRESS.md

echo "কাজের জন্য প্রস্তুত"

তখন আসার প্রোটোকলে একটি লাইনই যথেষ্ট: «scripts/init.sh চালাও»। Claude Code-এ এমন চালনা SessionStart ইভেন্টের হুক দিয়ে স্বয়ংক্রিয় করা যায়, কিন্তু হুক ছাড়াও এজেন্ট ফাইলের নির্দেশে স্ক্রিপ্টটি চালাবে।

স্মৃতিতে কী রাখবেন, কী রাখবেন না

প্রধান ভুল: স্মৃতিকে আবর্জনার স্তূপে পরিণত করা। এজেন্ট শুরুতে যে প্রতিটি লাইন পড়ে, তা কনটেক্সটে জায়গা নেয়, এবং অপ্রয়োজনীয় লাইন গুরুত্বপূর্ণটিকে ঢেকে দেয়।

জীবনকাল অনুযায়ী আলাদা করুন। প্রকল্পের নিয়ম খুব কমই বদলায় এবং সব কাজে প্রযোজ্য — সেগুলোর জায়গা নির্দেশনা-ফাইলে। অবস্থা প্রতি সেশনে বদলায় — তার জায়গা অগ্রগতির ফাইলে। দুটো মিশে গেলে নির্দেশনা-ফাইল পুরনো নোটে ফুলে উঠবে।

প্রথম সেশন: আরম্ভকে আলাদা পর্ব হিসেবে দেখা

প্রথম সেশন যদি বিশৃঙ্খলায় যায়, তবে সেশনের মধ্যের স্মৃতি কাজে আসে না। সাধারণ চিত্র: একটি খালি রিপোজিটরিতে আপনি লিখলেন «অনুসন্ধান যোগ করো», আধঘণ্টা পরে দেখা গেল টেস্ট ফ্রেমওয়ার্ক ভুলভাবে সেট আছে এবং মাইগ্রেশনের ফরম্যাট ভুল। অনুসন্ধান এসেছে, কিন্তু ভিত্তি বাঁকা।

কারণ, বাস্তবায়ন আর আরম্ভ আলাদা জিনিস অপটিমাইজ করে: প্রথমটি এই সেশনে কতগুলো ফিচার তৈরি হলো, দ্বিতীয়টি পরের সবগুলো সেশনের গতি ও নির্ভরযোগ্যতা। এজেন্ট দৃশ্যমান ফলের দিকে ঝোঁকে, অর্থাৎ কোডের দিকে। তাই আরম্ভকে আলাদা সেশনে রাখুন, যার চারটি শর্তসহ গ্রহণযোগ্যতার মানদণ্ড আছে।

• চালু হওয়া: পরিষ্কার ক্লোন থেকে make setup ও make dev কাজ করে।
• যাচাই করা যায়: make test আছে এবং অন্তত একটি সত্যিকারের পাস-করা টেস্ট আছে।
• অগ্রগতি দেখা যায়: অবস্থা-ফাইল আছে এবং পড়া যায়।
• কাজ ধরা যায়: গ্রহণযোগ্যতার মানদণ্ডসহ কাজের তালিকা আছে।

আপনি যদি প্রায়ই নতুন প্রকল্প শুরু করেন, একটি রিপোজিটরি-টেমপ্লেট বানান: Makefile, টেস্ট ফ্রেমওয়ার্ক, AGENTS.md-এর কাঠামো, .agent/ ফোল্ডার, scripts/init.sh, লিন্টার ও CI। তখন আরম্ভ শুধু নির্দিষ্ট প্রকল্পের বৈশিষ্ট্যে সীমাবদ্ধ থাকে।

স্মৃতি কাজ করছে কি না যাচাই

সবচেয়ে সৎ মেট্রিক: নতুন সেশন শুরু থেকে প্রথম অর্থপূর্ণ কোড-বদল পর্যন্ত সময়। আর্টিফ্যাক্ট ছাড়া এটি সাধারণত পনেরো-বিশ মিনিটের অনুসন্ধান; ভালো হস্তান্তরে দুই-তিন মিনিট। একবার আগে ও পরে মাপুন, তাহলে দেখা যাবে শৃঙ্খলা লাভজনক কি না।

দ্বিতীয় উপায় ঠান্ডা-শুরুর পরীক্ষা। নতুন সেশন খুলুন, লিখুন «চালিয়ে যাও» এবং পাঁচটি প্রশ্ন করুন: বর্তমান লক্ষ্য কী, টেস্ট কোন অবস্থায়, মূল বিষয়ে কোন সিদ্ধান্ত নেওয়া হয়েছে এবং কেন, কী বাধা দিচ্ছে, পরের ধাপ কী। এজেন্ট পাঁচটিরই উত্তর যদি ফাইল থেকে দেয়, অনুমান ছাড়া, তবে স্মৃতি ঠিকভাবে গড়া। প্রতিটি অনিশ্চিত উত্তর টেমপ্লেটে একটি না-থাকা ফিল্ড।

সাধারণ ভুল

• অগ্রগতির ফাইল শুধু বাড়ে। এক মাস পরে তাতে শত শত লাইন ইতিহাস। বর্তমান অবস্থা অনুযায়ী আবার লিখুন; ইতিহাস থাকুক git-এ।
• «বাতিল»-এর লাইন নেই। বাতিল বিকল্প ছাড়া সিদ্ধান্তের লগ পুনরায় বিতর্ক থেকে রক্ষা করে না।
• এজেন্ট অবস্থা «আন্দাজে» আপডেট করে। লিখুন কীভাবে যাচাই হয়েছে: কমান্ড ও ফল, «সব কাজ করছে» নয়।
• উইন্ডোর সীমায় হস্তান্তর। কনটেক্সটের কিনারায় এজেন্ট ইতিমধ্যে তাড়াহুড়ো করে; হস্তান্তর আগেভাগে শুরু করুন, প্রায় ৬০%-এ।
• প্রস্থানে অপরিষ্কার কার্যকরী ডিরেক্টরি। কমিট ছাড়া আধা-তৈরি বদল পরের সেশনকে বিভ্রান্ত করে।

সংক্ষেপে

AI এজেন্টের স্মৃতি মডেলের ওপর নয়, তৈরি হয় ফাইলের ওপর: PROGRESS.md বর্তমান অবস্থা ধরে রাখে, DECISIONS.md কারণ ও বাতিল বিকল্প, git-কমিট উদ্দেশ্যসহ চেকপয়েন্ট, আর AGENTS.md-এর প্রোটোকল নিশ্চিত করে এসব পড়া ও আপডেট হয়। Init-স্ক্রিপ্ট শুরুকে এক কমান্ডে নামায়, আর ঠান্ডা-শুরুর পরীক্ষা দেখায় রেকর্ড যথেষ্ট কি না। এজেন্টের বোর্ড-লগ ও bootstrap-চুক্তি কোর্সে একটি বাস্তব উদাহরণে বিস্তারিত দেখানো হয়েছে।