सत्र प्रबंधन एवं संपीड़न (गहन विवेचन)¶

यह दस्तावेज़ बताता है कि OpenClaw सत्रों को एंड-टू-एंड कैसे प्रबंधित करता है:

• सत्र रूटिंग (इनबाउंड संदेश कैसे sessionKey से मैप होते हैं)
• सत्र स्टोर (sessions.json) और यह क्या ट्रैक करता है
• ट्रांसक्रिप्ट स्थायित्व (*.jsonl) और इसकी संरचना
• ट्रांसक्रिप्ट स्वच्छता (रन से पहले प्रदाता-विशिष्ट सुधार)
• कॉन्टेक्स्ट सीमाएँ (कॉन्टेक्स्ट विंडो बनाम ट्रैक किए गए टोकन)
• संपीड़न (मैनुअल + स्वचालित-संपीड़न) और प्री-कम्पैक्शन कार्य को कहाँ हुक करें
• जब daily + idle दोनों कॉन्फ़िगर हों, तो जो पहले expire होता है वही लागू होता है।

यदि आप पहले उच्च-स्तरीय अवलोकन चाहते हैं, तो यहाँ से शुरू करें:

• /concepts/session
• /concepts/compaction
• /concepts/session-pruning
• /reference/transcript-hygiene

---

सत्य का स्रोत: Gateway¶

OpenClaw को एकल Gateway प्रक्रिया के चारों ओर डिज़ाइन किया गया है जो सत्र स्थिति का स्वामित्व रखती है।

• UI (macOS ऐप, वेब Control UI, TUI) को सत्र सूचियों और टोकन गणनाओं के लिए Gateway से क्वेरी करनी चाहिए।
• रिमोट मोड में, सत्र फ़ाइलें रिमोट होस्ट पर होती हैं; “अपने लोकल Mac फ़ाइलें जाँचना” Gateway द्वारा उपयोग किए जा रहे डेटा को प्रतिबिंबित नहीं करेगा।

---

दो स्थायित्व परतें¶

OpenClaw सत्रों को दो परतों में स्थायी करता है:

1. सत्र स्टोर (sessions.json) - कुंजी/मान मानचित्र: sessionKey -> SessionEntry - छोटा, परिवर्तनशील, संपादन (या प्रविष्टियाँ हटाने) के लिए सुरक्षित - सत्र मेटाडेटा ट्रैक करता है (वर्तमान सत्र आईडी, अंतिम गतिविधि, टॉगल्स, टोकन काउंटर, आदि)

2. ट्रांसक्रिप्ट (<sessionId>.jsonl) - ट्री संरचना के साथ केवल-परिशिष्ट ट्रांसक्रिप्ट (प्रविष्टियों में id + parentId होते हैं) - वास्तविक बातचीत + टूल कॉल्स + संपीड़न सारांश संग्रहीत करता है - भविष्य के टर्न के लिए मॉडल कॉन्टेक्स्ट पुनर्निर्माण में उपयोग होता है

---

ऑन-डिस्क स्थान¶

प्रति एजेंट, Gateway होस्ट पर:

• स्टोर: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• ट्रांसक्रिप्ट्स: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
• Telegram टॉपिक सत्र: .../<sessionId>-topic-<threadId>.jsonl

OpenClaw इन्हें src/config/sessions.ts के माध्यम से रिज़ॉल्व करता है।

---

सत्र कुंजियाँ (sessionKey)¶

एक sessionKey यह पहचानता है कि आप किस वार्तालाप बकेट में हैं (रूटिंग + पृथक्करण)।

सामान्य पैटर्न:

• मुख्य/डायरेक्ट चैट (प्रति एजेंट): agent:<agentId>:<mainKey> (डिफ़ॉल्ट main)
• समूह: agent:<agentId>:<channel>:group:<id>
• रूम/चैनल (Discord/Slack): agent:<agentId>:<channel>:channel:<id> या ...:room:<id>
• क्रॉन: cron:<job.id>
• वेबहुक: hook:<uuid> (जब तक ओवरराइड न किया जाए)

कैनोनिकल नियम /concepts/session पर दस्तावेज़ित हैं।

---

सत्र आईडी (sessionId)¶

प्रत्येक sessionKey एक वर्तमान sessionId की ओर संकेत करता है (वह ट्रांसक्रिप्ट फ़ाइल जो बातचीत को जारी रखती है)।

व्यावहारिक नियम:

• रीसेट (/new, /reset) उस sessionKey के लिए एक नया sessionId बनाता है।
• दैनिक रीसेट (डिफ़ॉल्ट Gateway होस्ट के स्थानीय समयानुसार सुबह 4:00 बजे) रीसेट सीमा के बाद आने वाले अगले संदेश पर एक नया sessionId बनाता है।
• Compaction persistent है (session pruning के विपरीत)। देखें /concepts/session-pruning।

कार्यान्वयन विवरण: निर्णय src/auto-reply/reply/session.ts में initSessionState() में होता है।

---

सत्र स्टोर स्कीमा (sessions.json)¶

स्टोर का मान प्रकार src/config/sessions.ts में SessionEntry है।

मुख्य फ़ील्ड्स (पूर्ण सूची नहीं):

• sessionId: वर्तमान ट्रांसक्रिप्ट आईडी (फ़ाइलनाम इससे व्युत्पन्न होता है जब तक sessionFile सेट न हो)
• updatedAt: अंतिम गतिविधि टाइमस्टैम्प
• sessionFile: वैकल्पिक स्पष्ट ट्रांसक्रिप्ट पथ ओवरराइड
• chatType: direct | group | room (UI और सेंड नीति में सहायक)
• provider, subject, room, space, displayName: समूह/चैनल लेबलिंग के लिए मेटाडेटा
• टॉगल्स:
• thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
• sendPolicy (प्रति-सत्र ओवरराइड)
• मॉडल चयन:
• providerOverride, modelOverride, authProfileOverride
• टोकन काउंटर (सर्वोत्तम-प्रयास / प्रदाता-निर्भर):
• inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: इस सत्र कुंजी के लिए स्वचालित-संपीड़न कितनी बार पूरा हुआ
• memoryFlushAt: अंतिम प्री-कम्पैक्शन मेमोरी फ्लश का टाइमस्टैम्प
• memoryFlushCompactionCount: अंतिम फ्लश के समय का संपीड़न काउंट

स्टोर संपादन के लिए सुरक्षित है, लेकिन Gateway प्राधिकृत है: सत्र चलने पर यह प्रविष्टियों को पुनर्लेखित या पुनर्जलित कर सकता है।

---

ट्रांसक्रिप्ट संरचना (*.jsonl)¶

ट्रांसक्रिप्ट्स @mariozechner/pi-coding-agent के SessionManager द्वारा प्रबंधित होते हैं।

फ़ाइल JSONL है:

• पहली पंक्ति: सत्र हेडर (type: "session", जिसमें id, cwd, timestamp, वैकल्पिक parentSession शामिल हैं)
• फिर: id + parentId (ट्री) के साथ सत्र प्रविष्टियाँ

उल्लेखनीय प्रविष्टि प्रकार:

• message: user/assistant/toolResult संदेश
• custom_message: एक्सटेंशन-इंजेक्टेड संदेश जो मॉडल कॉन्टेक्स्ट में प्रवेश करते हैं (UI से छिपाए जा सकते हैं)
• custom: एक्सटेंशन स्टेट जो मॉडल कॉन्टेक्स्ट में प्रवेश नहीं करता
• compaction: firstKeptEntryId और tokensBefore के साथ स्थायी संपीड़न सारांश
• branch_summary: ट्री शाखा नेविगेशन के समय स्थायी सारांश

OpenClaw जानबूझकर ट्रांसक्रिप्ट्स को “फिक्स अप” नहीं करता; Gateway इन्हें पढ़ने/लिखने के लिए SessionManager का उपयोग करता है।

---

कॉन्टेक्स्ट विंडो बनाम ट्रैक किए गए टोकन¶

दो अलग-अलग अवधारणाएँ महत्वपूर्ण हैं:

1. मॉडल कॉन्टेक्स्ट विंडो: प्रति मॉडल कठोर सीमा (मॉडल को दिखाई देने वाले टोकन)
2. सत्र स्टोर काउंटर: sessions.json में लिखे गए रोलिंग आँकड़े (/status और डैशबोर्ड के लिए उपयोग)

यदि आप सीमाएँ ट्यून कर रहे हैं:

• कॉन्टेक्स्ट विंडो मॉडल कैटलॉग से आती है (और कॉन्फ़िग के माध्यम से ओवरराइड की जा सकती है)।
• स्टोर में contextTokens एक रनटाइम अनुमान/रिपोर्टिंग मान है; इसे कठोर गारंटी न मानें।

अधिक जानकारी के लिए /token-use देखें।

---

संपीड़न: यह क्या है¶

संपीड़न पुराने वार्तालाप को ट्रांसक्रिप्ट में एक स्थायी compaction प्रविष्टि में सारांशित करता है और हाल के संदेशों को यथावत रखता है।

संपीड़न के बाद, भविष्य के टर्न देखते हैं:

• संपीड़न सारांश
• firstKeptEntryId के बाद के संदेश

लक्ष्य: auto-compaction होने से पहले, एक silent agentic turn चलाएँ जो durable state को disk पर लिखे (जैसे agent workspace में memory/YYYY-MM-DD.md), ताकि compaction महत्वपूर्ण context को मिटा न सके। Session key गलत है?

---

स्वचालित-संपीड़न कब होता है (Pi रनटाइम)¶

एंबेडेड Pi एजेंट में, स्वचालित-संपीड़न दो स्थितियों में ट्रिगर होता है:

1. ओवरफ़्लो रिकवरी: मॉडल कॉन्टेक्स्ट ओवरफ़्लो त्रुटि लौटाता है → संपीड़न → पुनः प्रयास।
2. थ्रेशहोल्ड मेंटेनेंस: एक सफल टर्न के बाद, जब:

contextTokens > contextWindow - reserveTokens

जहाँ:

• contextWindow मॉडल की कॉन्टेक्स्ट विंडो है
• reserveTokens प्रॉम्प्ट्स + अगले मॉडल आउटपुट के लिए आरक्षित हेडरूम है

ये Pi रनटाइम सेमांटिक्स हैं (OpenClaw इवेंट्स उपभोग करता है, लेकिन संपीड़न कब करना है यह Pi तय करता है)।

---

संपीड़न सेटिंग्स (reserveTokens, keepRecentTokens)¶

Pi की संपीड़न सेटिंग्स Pi सेटिंग्स में रहती हैं:

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

OpenClaw एंबेडेड रन के लिए एक सेफ़्टी फ़्लोर भी लागू करता है:

• यदि compaction.reserveTokens < reserveTokensFloor, OpenClaw इसे बढ़ाता है।
• डिफ़ॉल्ट फ़्लोर 20000 टोकन है।
• फ़्लोर अक्षम करने के लिए agents.defaults.compaction.reserveTokensFloor: 0 सेट करें।
• यदि यह पहले से अधिक है, तो OpenClaw इसे यथावत छोड़ देता है।

क्यों: संपीड़न अपरिहार्य होने से पहले बहु-टर्न “हाउसकीपिंग” (जैसे मेमोरी राइट्स) के लिए पर्याप्त हेडरूम छोड़ना।

कार्यान्वयन: src/agents/pi-settings.ts में ensurePiCompactionReserveTokens() (src/agents/pi-embedded-runner.ts से कॉल किया गया)।

---

उपयोगकर्ता-दृश्य सतहें¶

आप संपीड़न और सत्र स्थिति को यहाँ देख सकते हैं:

• /status (किसी भी चैट सत्र में)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• वर्बोज़ मोड: 🧹 Auto-compaction complete + संपीड़न काउंट

---

साइलेंट हाउसकीपिंग (NO_REPLY)¶

OpenClaw पृष्ठभूमि कार्यों के लिए “साइलेंट” टर्न का समर्थन करता है, जहाँ उपयोगकर्ता को मध्यवर्ती आउटपुट नहीं दिखना चाहिए।

परंपरा:

• असिस्टेंट अपने आउटपुट की शुरुआत NO_REPLY से करता है ताकि “उपयोगकर्ता को उत्तर न दें” संकेतित हो।
• OpenClaw डिलीवरी लेयर में इसे स्ट्रिप/दबा देता है।

2026.1.10 से, OpenClaw ड्राफ़्ट/टाइपिंग स्ट्रीमिंग को भी दबाता है जब कोई आंशिक चंक NO_REPLY से शुरू होता है, ताकि साइलेंट ऑपरेशन मध्य-टर्न में आंशिक आउटपुट लीक न करें।

---

प्री-कम्पैक्शन “मेमोरी फ्लश” (कार्यान्वित)¶

/concepts/session से शुरू करें और /status में sessionKey की पुष्टि करें।

OpenClaw प्री-थ्रेशहोल्ड फ्लश दृष्टिकोण का उपयोग करता है:

1. सत्र कॉन्टेक्स्ट उपयोग की निगरानी।
2. जब यह एक “सॉफ्ट थ्रेशहोल्ड” (Pi के संपीड़न थ्रेशहोल्ड से नीचे) पार करता है, तो एक साइलेंट “अब मेमोरी लिखें” निर्देश एजेंट को चलाएँ।
3. NO_REPLY का उपयोग करें ताकि उपयोगकर्ता को कुछ भी न दिखे।

कॉन्फ़िग (agents.defaults.compaction.memoryFlush):

• enabled (डिफ़ॉल्ट: true)
• softThresholdTokens (डिफ़ॉल्ट: 4000)
• prompt (फ्लश टर्न के लिए उपयोगकर्ता संदेश)
• systemPrompt (फ्लश टर्न के लिए जोड़ा गया अतिरिक्त सिस्टम प्रॉम्प्ट)

टिप्पणियाँ:

• डिफ़ॉल्ट प्रॉम्प्ट/सिस्टम प्रॉम्प्ट में डिलीवरी दबाने के लिए NO_REPLY संकेत शामिल होता है।
• फ्लश प्रति संपीड़न चक्र एक बार चलता है ( sessions.json में ट्रैक किया गया)।
• फ्लश केवल एंबेडेड Pi सत्रों के लिए चलता है (CLI बैकएंड इसे छोड़ देते हैं)।
• जब सत्र वर्कस्पेस रीड-ओनली हो (workspaceAccess: "ro" या "none"), तो फ्लश छोड़ा जाता है।
• वर्कस्पेस फ़ाइल लेआउट और राइट पैटर्न के लिए Memory देखें।

Pi एक्सटेंशन API में session_before_compact हुक भी एक्सपोज़ करता है, लेकिन OpenClaw की फ्लश लॉजिक आज Gateway पक्ष पर रहती है।

---

समस्या-निवारण चेकलिस्ट¶

• Store बनाम transcript mismatch? openclaw status से Gateway host और store path की पुष्टि करें।
• Compaction spam? जाँच करें:
• Silent turns लीक हो रहे हैं? पुष्टि करें कि reply NO_REPLY (exact token) से शुरू होता है और आप उस build पर हैं जिसमें streaming suppression fix शामिल है।
• मॉडल कॉन्टेक्स्ट विंडो (बहुत छोटी)
• संपीड़न सेटिंग्स (मॉडल विंडो के लिए reserveTokens बहुत अधिक होने पर पहले संपीड़न हो सकता है)
• टूल-रिज़ल्ट ब्लोट: सत्र प्रूनिंग सक्षम/ट्यून करें
• "Hello, C-3PO! 🤖