মূল কনটেন্টে যান
এআই টিউটোরিয়াল

fast-jev-compaction দিয়ে Claude Code-এর সঠিক কনটেক্সট সংরক্ষণ করুন

fast-jev-compaction কীভাবে npm লাইব্রেরি বা Claude Code প্লাগইন হিসেবে ইনস্টল ও ব্যবহার করবেন তা জানুন। এই টিউটোরিয়ালে এর Jev-ভিত্তিক সিদ্ধান্ত, কনফিগারেশন বিকল্প, কাস্টম ট্রান্সপোর্ট সমর্থন, ব্যর্থতার আচরণ এবং গুরুত্বপূর্ণ লেখা হুবহু সংরক্ষণ করে দীর্ঘ ট্রান্সক্রিপ্ট নিরাপদে সংক্ষিপ্ত করার কৌশল ব্যাখ্যা করা হয়েছে।

পড়তে প্রায় 24 মিনিট লাগবে
fast-jev-compaction দিয়ে Claude Code-এর সঠিক কনটেক্সট সংরক্ষণ করুন

fast-jev-compaction কী করে

fast-jev-compaction হলো একটি npm লাইব্রেরি এবং Claude Code প্লাগইন, যা দীর্ঘ এজেন্ট ট্রান্সক্রিপ্টকে সারাংশে পুনর্লিখন না করে ছোট করে। এর পরিবর্তে, এটি Jev মডেলকে পুরোনো টুল কল এবং টুল ফলাফল স্কোর করতে বলে, তারপর কনফিগারযোগ্য থ্রেশহোল্ড অনুযায়ী সেগুলো রেখে দেয়, সংক্ষিপ্ত করে বা সরিয়ে দেয়।

ব্যবহারকারী ও অ্যাসিস্ট্যান্টের লেখা হুবহু এবং মূল ক্রমে থাকে। শুধু টুল কল এবং তাদের সংশ্লিষ্ট ফলাফল সরানোর জন্য বিবেচিত হয়। এর ফলে প্রচলিত সারাংশ তৈরির মাধ্যমে নির্দিষ্ট সীমাবদ্ধতা, ফাইল পাথ, কমান্ড এবং ত্রুটি বার্তা হারিয়ে যাওয়ার ঝুঁকি এড়ানো যায়।

রিপোজিটরিতে src/-এর অধীনে পুনর্ব্যবহারযোগ্য প্যাকেজ এবং hooks/ ও .claude-plugin/-এর অধীনে Claude Code ফাংশন-হুক প্লাগইন—দুটিই রয়েছে।

কমপ্যাকশন কীভাবে কাজ করে

  1. প্রতিটি tool_use-কে tool_use_id-এর মাধ্যমে তার tool_result-এর সঙ্গে জোড়া হয়।

  2. প্রথম মেসেজের কল এবং সর্বশেষ preserveRecentMessages সংখ্যক মেসেজ পিন করা থাকে, তাই সেগুলো পরিবর্তন করা হয় না।

  3. পুরো কথোপকথনটি পুরোনো থেকে নতুন ক্রমে Jev-এর কাছে পাঠানো হয়। এই সিদ্ধান্ত-অবস্থায় টুল-ফলাফলের বিষয়বস্তু ছোট নোট দিয়ে প্রতিস্থাপিত হয়, যেমন ok, 4213 chars (omitted); তবে টুল ইনপুট এবং লেখা উপলভ্য থাকে।

  4. প্রতিটি নন-পিনড কলের জন্য Jev দুটি প্রশ্নের উত্তর দেয়: কলটি সম্পর্কে জানা এখনও গুরুত্বপূর্ণ কি না, এবং সম্পূর্ণ ফলাফলটি হুবহু উপলভ্য রাখা জরুরি কি না।

  5. ফেরত আসা সম্ভাবনাগুলো keepThreshold-এর সঙ্গে তুলনা করা হয়।

  6. কোনো অনাথ ফলাফল রেখে না দিয়ে ট্রান্সক্রিপ্ট পুনর্গঠন করা হয়।

সিদ্ধান্তের ফলাফল

  • ফলাফলের স্কোর থ্রেশহোল্ডে পৌঁছালে কল এবং সম্পূর্ণ ফলাফল—দুটিই রাখা হয়।

  • শুধু কলের স্কোর থ্রেশহোল্ডে পৌঁছালে কলটি রাখা হয় এবং ফলাফলটি প্রথম truncateHeadChars অক্ষর পর্যন্ত সংক্ষিপ্ত করে তার পরে একটি নোট যোগ করা হয়।

  • কোনো স্কোরই থ্রেশহোল্ডে না পৌঁছালে কল এবং তার ফলাফল একসঙ্গে সরিয়ে দেওয়া হয়।

যেসব মেসেজ খালি হয়ে যায়, সেগুলো সরিয়ে দেওয়া হয়। যেসব মেসেজে পরিবর্তনের প্রয়োজন নেই, সেগুলো একই অবজেক্ট হিসেবে ফেরত দেওয়া হয়।

বড় ইতিহাসকে Jev রিকোয়েস্টে ফিট করানো

সিদ্ধান্ত-অবস্থার আনুমানিক টোকেনের ডিফল্ট সীমা হলো 25000। মূল অবস্থা অতিরিক্ত বড় হলে, লাইব্রেরি Jev-কে দেখানো উপস্থাপনাটি ধাপে ধাপে সংক্ষিপ্ত করে। এটি টুল ইনপুট ছাঁটে, হেড ও টেইল ব্যবহার করে দীর্ঘ লেখা সংক্ষিপ্ত করে, পুরোনো মেসেজগুলো একত্র করে, পুরোনো কলগুলোকে এক লাইনের রেকর্ডে নামিয়ে আনে, পুরোনো কল-বিহীন মেসেজ বাদ দেয় এবং পুরোনো শুধু-কল মেসেজের ধারাগুলো একত্র করে।

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

প্রশ্নগুলোও ব্যাচে ভাগ করা হয়, যাতে প্রতিটি স্টেট-প্লাস-প্রশ্ন রিকোয়েস্ট maxRequestTokens-এর নিচে থাকে; এর ডিফল্ট মান 30000। রিকোয়েস্টগুলো সমান্তরালে চলে এবং তাদের সিদ্ধান্তগুলো একত্র করা হয়।

npm লাইব্রেরি ইনস্টল করুন

প্যাকেজটি ইনস্টল করুন এবং পরিবেশের মাধ্যমে একটি TypeSafe API কী দিন:

npm install fast-jev-compaction
export TYPESAFE_API_KEY=...

API কী কমিট করবেন না বা সরাসরি কোনো সোর্স ফাইলে রাখবেন না।

ডিফল্ট ক্লায়েন্ট process.env.TYPESAFE_API_KEY পড়ে। API কল করার সময় আপনি apiKey অপশনও দিতে পারেন।

একটি ট্রান্সক্রিপ্ট কমপ্যাক্ট করুন

compactMessages ইমপোর্ট করুন, একটি ট্রান্সক্রিপ্ট প্রস্তুত করুন এবং ডিফল্ট থেকে ভিন্ন যেকোনো অপশন পাস করুন:

import {
  compactMessages,
  reductionRatio,
  type Message,
} from 'fast-jev-compaction';

const transcript: Message[] = [
  {
    role: 'user',
    text: 'Fix the failing test. Never edit src/generated.',
    toolUses: [],
  },
  {
    role: 'assistant',
    text: '',
    toolUses: [
      {
        tool_use_id: 'toolu_1',
        tool: 'Read',
        input: { file_path: 'src/a.ts' },
      },
    ],
  },
  {
    role: 'user',
    text: '',
    toolUses: [],
    toolResults: [
      { tool_use_id: 'toolu_1', text: '…file contents…' },
    ],
  },
];

const result = await compactMessages(transcript, {
  preserveRecentMessages: 4,
});

console.log(result.messages);
console.log(result.decisions);
console.log(result.stats);

এক্সপোর্ট করা Message টাইপটি Claude Code-এর SessionMessage-এর একটি উপসেট, তাই Claude Code সেশন ট্রান্সক্রিপ্ট সরাসরি প্যাকেজে পাস করা যায়।

কমপ্যাকশন সার্থক হয়েছে কি না দেখুন

প্যাকেজটি reductionRatio এক্সপোর্ট করে, যা কোনো অ্যাপ্লিকেশনকে কমপ্যাক্ট করা ইতিহাস ব্যবহার করবে কি না তা নির্ধারণে সহায়তা করতে পারে:

const result = await compactMessages(transcript);

if (reductionRatio(result) < 0.25) {
  // Keep the original transcript or use another fallback.
} else {
  // Continue with result.messages.
}

ফলাফলের পরিসংখ্যানে কমপ্যাকশনের আগে ও পরে মেসেজ এবং অক্ষরের সংখ্যা, কারণ অনুযায়ী গোষ্ঠীবদ্ধ সিদ্ধান্তের সংখ্যা, আনুমানিক স্টেটের আকার, ব্যবহৃত ফিটিং ধাপ এবং Jev রিকোয়েস্টের সংখ্যা অন্তর্ভুক্ত থাকে।

কমপ্যাকশনের আচরণ কনফিগার করুন

প্রধান অপশনগুলো হলো:

  • apiKey: TypeSafe API কী। ডিফল্ট হিসেবে TYPESAFE_API_KEY ব্যবহৃত হয়।

  • model: Jev মডেলের নাম। ডিফল্ট হলো jev-latest।

  • baseUrl: System One এন্ডপয়েন্ট। ডিফল্ট হলো https://api.typesafe.ai/v1/systemone।

  • fetch: ইনজেক্ট করা যায় এমন fetch ইমপ্লিমেন্টেশন, বিশেষ করে পরীক্ষার ক্ষেত্রে উপযোগী।

  • goal: চলমান কাজের বিবরণ, যা স্টেটে অন্তর্ভুক্ত হয়। ডিফল্ট হিসেবে শেষ তিনটি ব্যবহারকারী প্রম্পট ব্যবহৃত হয়।

  • keepThreshold: কোনো কল বা সম্পূর্ণ ফলাফল সংরক্ষণের জন্য প্রয়োজনীয় ন্যূনতম সম্ভাবনা। ডিফল্ট হলো 0.5।

  • preserveRecentMessages: সর্বশেষ যতগুলো মেসেজ পরিবর্তন করা যাবে না। ডিফল্ট হলো 6; প্রথম মেসেজটিও সবসময় সংরক্ষিত থাকে।

  • maxStateTokens: সিদ্ধান্ত-স্টেটের আনুমানিক টোকেন সীমা। ডিফল্ট হলো 25000।

  • maxRequestTokens: একটি অনুরোধে স্টেট ও প্রশ্নের সম্মিলিত আনুমানিক টোকেন সীমা। ডিফল্ট হলো 30000।

  • truncateHeadChars: কোনো ফলাফল সংক্ষিপ্ত করার সময় শুরু থেকে রাখা অক্ষরের সংখ্যা। ডিফল্ট হলো 300।

const result = await compactMessages(transcript, {
  goal: 'Fix the test without editing generated files',
  keepThreshold: 0.6,
  preserveRecentMessages: 8,
  truncateHeadChars: 500,
});

উচ্চতর keepThreshold মানে সংরক্ষণের জন্য আরও শক্তিশালী সম্ভাবনা প্রয়োজন, ফলে আরও বেশি টুল কার্যকলাপ সরিয়ে ফেলা হতে পারে। কোনো সম্ভাবনা মুছে ফেলা নিরাপদ হওয়ার প্রমাণ নয়; তাই প্রতিনিধিত্বশীল ট্রান্সক্রিপ্টের বিপরীতে থ্রেশহোল্ড পরিবর্তন মূল্যায়ন করুন।

কাস্টম Jev ট্রান্সপোর্ট ব্যবহার করুন

অন্তর্নির্মিত TypeSafe ক্লায়েন্ট আপনার পরিবেশের উপযোগী না হলে, এক্সপোর্ট করা JevAsker ইন্টারফেস ইমপ্লিমেন্ট করুন। এতে একটি ask(state, questions) মেথড থাকা আবশ্যক। এরপর compactMessages-এর পরিবর্তে compact(messages, asker, options) কল করুন।

HTTP অনুরোধের বডি তৈরি করার জন্য প্যাকেজটি buildJevRequest এবং রেসপন্স যাচাইয়ের জন্য parseJevResponse-ও এক্সপোর্ট করে। আরও বিশেষায়িত ইন্টিগ্রেশনের জন্য নিম্নস্তরের বিল্ডিং ব্লকগুলোও পাওয়া যায়:

  • collectToolCalls কলগুলোকে তাদের ফলাফলের সঙ্গে জোড়া দেয়।

  • fitState কনফিগার করা আকারসীমার মধ্যে একটি স্টেট প্রস্তুত করে।

  • batchCalls প্রশ্নগুলোকে একাধিক অনুরোধে ভাগ করে।

  • decideCall স্কোরকে সংরক্ষণ, সংক্ষিপ্তকরণ বা অপসারণের সিদ্ধান্তে রূপান্তর করে।

  • applyDecisions মেসেজের ইতিহাস পুনর্গঠন করে।

Claude Code প্লাগইন ইনস্টল করুন

প্লাগইনটির জন্য Claude Code 2.1.274 বা পরবর্তী সংস্করণ প্রয়োজন। ফাংশন হুক একটি প্রাথমিক অ্যাক্সেস বৈশিষ্ট্য, তাই Claude Code যেখানে চলে সেখানে এটি সক্রিয় করুন। উদাহরণস্বরূপ, ~/.claude/settings.json-এ পরিবেশ সেটিংস যোগ করুন:

{
  "env": {
    "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1",
    "TYPESAFE_API_KEY": "<your key>"
  }
}

রিপোজিটরিটিকে প্লাগইন মার্কেটপ্লেস হিসেবে যোগ করে প্লাগইনটি ইনস্টল করুন:

claude plugin marketplace add tamaratran/fast-jev-compaction
claude plugin install fast-jev-compaction@fast-jev-compaction

ইনস্টলার থ্রেশহোল্ড এবং truncateHeadChars-এর মতো বিকল্পের জন্য প্রম্পট দেখায়। পরিবেশের TYPESAFE_API_KEY ব্যবহার করতে API-কী বিকল্পটি ডিফল্ট অবস্থায় রাখুন।

Claude Code পুনরায় চালু করুন অথবা চালান:

/reload-plugins

সক্রিয় হওয়ার পর /compact এবং স্বয়ংক্রিয় কমপ্যাকশন উভয়ই Jev হুকের মাধ্যমে সম্পন্ন হয়। সফল প্রতিস্থাপনের ক্ষেত্রে fast-jev-compaction: kept N/M messages, no summary (...)-এর মতো একটি টোস্ট দেখা যায়। Jev ব্যর্থ হলে বা হ্রাস অপর্যাপ্ত হলে, হুকটি Claude Code-এর অন্তর্নির্মিত সারাংশে ফিরে যায়।

চেকআউট থেকে সরাসরি প্লাগইন চালান

প্রকাশ বা ইনস্টল না করেই আপনি রিপোজিটরিটি পরীক্ষা করতে পারেন:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .

রিপোজিটরির রুট থেকে এই কমান্ডটি চালান।

উন্নত ব্যবহারের পরামর্শ

সক্রিয় কাজ সুরক্ষিত রাখুন

সাম্প্রতিক টুল আউটপুট পুনরায় ব্যবহারের সম্ভাবনা থাকলে preserveRecentMessages বাড়ান। এই মেসেজগুলোর কলগুলো পিন করা থাকে এবং সরানো বা সংক্ষিপ্ত করা যায় না।

সুনির্দিষ্ট লক্ষ্য দিন

ডিফল্ট লক্ষ্যটি শেষ তিনটি ব্যবহারকারী প্রম্পট থেকে তৈরি হয়। দীর্ঘ বা পরিবর্তনশীল সেশনের ক্ষেত্রে স্পষ্টভাবে goal সেট করলে Jev চলমান কাজের আরও পরিষ্কার বিবরণ পেতে পারে।

ফলব্যাক নীতি নির্ধারণে পরিসংখ্যান ব্যবহার করুন

প্রতিটি কমপ্যাক্ট করা ফলাফল স্বয়ংক্রিয়ভাবে গ্রহণ না করে result.stats এবং reductionRatio(result) পরীক্ষা করুন। সংক্ষিপ্ত সেশনে মূল ট্রান্সক্রিপ্ট প্রতিস্থাপনকে যুক্তিযুক্ত করার মতো পর্যাপ্ত হ্রাস নাও হতে পারে।

ত্রুটির জন্য প্রস্তুত থাকুন

Jev ব্যর্থ হলে, বিকৃত ডেটা ফেরত দিলে, প্রয়োজনীয় কোনো কী বাদ দিলে, অথবা স্টেট সীমার মধ্যে ফিট করা যায় না এমন ইতিহাস পেলে কমপ্যাকশন ব্যর্থ হয়। লাইব্রেরি কলগুলো ত্রুটি-পরিচালনার মধ্যে রাখুন এবং প্রয়োজনে মূল ট্রান্সক্রিপ্ট সংরক্ষণ করুন বা অন্য কমপ্যাকশন কৌশল ব্যবহার করুন। Claude Code হুক ইতিমধ্যেই এর অন্তর্নির্মিত সারাংশে ফিরে যায়।

অনুরোধের খরচ বুঝুন

প্রতিটি প্রশ্নের ব্যাচের জন্য সম্পূর্ণ ফিট করা স্টেট পুনরাবৃত্তি করা হয়। ফলে স্টেট সীমার কাছাকাছি কোনো ইতিহাসের ক্ষেত্রে ছোট ছোট প্রতিটি প্রশ্নগুচ্ছের জন্য একটি করে বড় অনুরোধের প্রয়োজন হতে পারে। সীমা সমন্বয় করার সময় result.stats-এ অনুরোধের সংখ্যা পর্যালোচনা করুন।

নেটওয়ার্ক অনুরোধ ছাড়াই পরীক্ষা করুন

রিপোজিটরির ইউনিট টেস্টগুলো একটি নকল Jev ইমপ্লিমেন্টেশন ব্যবহার করে এবং কখনো TypeSafe-এ সংযোগ করে না। আপনার অ্যাপ্লিকেশনের পরীক্ষাতেও কাস্টম JevAsker বা ইনজেক্ট করা fetch ইমপ্লিমেন্টেশন একই পদ্ধতি সমর্থন করতে পারে।

ডেভেলপমেন্ট কমান্ড

রিপোজিটরি থেকে কাজ করার সময়, নির্ভরতাগুলো ইনস্টল করে উপলব্ধ যাচাইগুলো চালান:

npm install
npm run typecheck
npm test
npm run build
npm run validate:plugin
TYPESAFE_API_KEY="$(cat ~/.typesafe_key)" npm run demo

ডেমো কমান্ডটি লাইভ নেটওয়ার্ক পরীক্ষা সম্পাদন করে। রিপোজিটরিতে demo/JevDemo-এর অধীনে একটি macOS SwiftUI অ্যানিমেশনও রয়েছে। এটি একটি পূর্বনির্ধারিত ট্রান্সক্রিপ্ট ব্যবহার করে কমপ্যাকশন প্রক্রিয়াকে উপস্থাপন করে এবং API-তে কল করে না:

demo/JevDemo/build.sh

অ্যাপে অ্যানিমেশনটি আবার চালাতে স্পেসবার চাপুন।

গুরুত্বপূর্ণ সীমাবদ্ধতা

  • শুধু টুল কল এবং ফলাফল সরানো বা সংক্ষিপ্ত করা যায়। টেক্সট মেসেজ আউটপুটে অপরিবর্তিত থাকে।

  • টোকেনের সংখ্যা টোকেনাইজারের পরিবর্তে অক্ষরের প্যাটার্ন থেকে তৈরি করা আনুমানিক হিসাব।

  • Jev-এর সম্ভাবনা কোনো ফলাফল মুছে ফেলার জন্য নিরাপদ হওয়ার নিশ্চয়তা দেয় না, যদিও প্রয়োজন হলে অ্যাসিস্ট্যান্ট মুছে ফেলা টুল কলটি আবার চালাতে পারে।

  • প্রতিটি রিকোয়েস্ট ব্যাচে সম্পূর্ণ স্টেট পুনরাবৃত্তি করা হয়, ফলে কনফিগার করা সীমার কাছাকাছি থাকা ইতিহাসের জন্য খরচ বেড়ে যেতে পারে।

উপসংহার

fast-jev-compaction ক্ষতিপূরণহীন কথোপকথন সারাংশের একটি বিকল্প প্রদান করে। এটি ব্যবহারকারী ও অ্যাসিস্ট্যান্টের টেক্সট সংরক্ষণ করার পাশাপাশি পুরোনো টুল কার্যকলাপ বেছে বেছে বাদ দেয়। অ্যাপ্লিকেশন-স্তরের নিয়ন্ত্রণের জন্য npm API, স্বয়ংক্রিয় ইন্টিগ্রেশনের জন্য Claude Code প্লাগইন এবং আপনার ওয়ার্কফ্লো অনুযায়ী কমপ্যাকশন সামঞ্জস্য করতে প্রদত্ত থ্রেশহোল্ড, সংরক্ষণ সেটিংস, পরিসংখ্যান ও ফলব্যাক আচরণ ব্যবহার করুন।