Sessions and transcripts

เย็นวันศุกร์คุณเปิด session ในโฟลเดอร์ shop-api คุยกับ Claude เรื่องการแก้ validation ของ `POST /orders` ไปได้ครึ่งทาง แล้วปิด terminal กลับบ้าน เช้าวันจันทร์คุณเปิด terminal ที่โฟลเดอร์เดิมและเริ่ม Claude Code อีกครั้ง บทสนทนาเดิมกลับมาพร้อมบริบทที่คุยค้างไว้ ทั้งที่คุณไม่ได้บันทึกอะไรไว้เอง และเครื่องก็ไม่ได้เปิดค้างตลอด weekend คำถามคือบทสนทนานั้นถูกเก็บไว้ที่ใด และทำไมมันกลับมาได้ ถ้า harness อ่านมันกลับมาได้ มันก็ต้องมีที่เก็บที่อ่านซ้ำได้ — ไม่ใช่ความจำในตัวโมเดล เพราะบทที่แล้วเพิ่งอธิบายว่าทุก session เริ่มจาก context ที่ประกอบใหม่ และไม่มีอะไรถูกเก็บไว้ในตัวโมเดลข้าม session อีกด้านของคำถามเดียวกัน: ระหว่าง debug คุณแปะ connection string ที่มีรหัสผ่านของ staging ลงใน session แล้วบอกตัวเองว่า "เดี๋ยวพอแก้เสร็จก็หายไปเอง" — แต่ถ้าบทสนทนาถูกเก็บไว้จริง ข้อความนั้นก็ยังอยู่ที่ใดที่หนึ่งหลังการแก้เสร็จ ทั้งสองอาการชี้ไปที่กลไกเดียวกัน: session ถูกบันทึกเป็น transcript และ transcript คือไฟล์บนเครื่องของคุณ บทนี้จะอธิบายกลไกนั้นก่อน แล้วจึงไปดูว่ามันถูกเรียกอะไรและอยู่ที่ใด

เริ่มจากแยกสองคำที่มักถูกใช้ปนกัน **session** คือบทสนทนาหนึ่งบทที่ผูกกับ project directory หนึ่งโฟลเดอร์ มันคือหน่วยที่คุณกลับเข้าไปได้ ตั้งชื่อได้ แยกสาขาได้ และเป็นหน่วยที่ harness เก็บสถานะอื่น ๆ ของการทำงานไว้ด้วย **transcript** คือไฟล์ที่ harness เขียนบทสนทนานั้นลงไประหว่างที่คุณทำงาน เก็บเป็นข้อความรูปแบบ JSONL — หนึ่งบรรทัดต่อหนึ่งเหตุการณ์: คำสั่งของคุณ คำตอบของ Claude การเรียกเครื่องมือ ผลลัพธ์ของเครื่องมือ และข้อมูลประกอบของแต่ละเหตุการณ์ ทำไมต้องเป็นไฟล์บนดิสก์ของคุณ เพราะ persistence เป็นงานของ harness ไม่ใช่ของโมเดล โมเดลผลิตข้อความเท่านั้น ถ้าอยากให้บทสนทนากลับมาอ่านได้อีก harness ก็ต้องเขียนมันลงที่ที่อ่านซ้ำได้ และการเขียนลงดิสก์คือกลไกที่ตรงไปตรงมาที่สุด: ปิดโปรแกรมไม่ลบไฟล์ เปิดใหม่แล้วอ่านต่อได้ ผลที่ตามมาสำคัญกว่าชื่อเรียก: เพราะ transcript เป็นไฟล์ มันจึงตรวจสอบได้ ย้ายได้ ลบได้ และมีอายุจำกัด และเพราะทุกอย่างที่คุณพิมพ์กลายเป็นบรรทัดในไฟล์นั้น คำถามว่า "แปะอะไรลงใน session ได้" จึงเป็นคำถามเรื่องข้อมูลที่ตกค้างบนเครื่อง ไม่ใช่คำถามเรื่องความจำของโมเดล

ในหนึ่ง session สิ่งที่ถูกเขียนลง transcript ไม่ได้มีแค่คำพูด ตัวอย่างจาก shop-api: คุณสั่งให้ Claude แก้ validation ของ `POST /orders` แล้วรัน `pnpm test` ลำดับเหตุการณ์ที่ถูกบันทึกจะหน้าตาคล้ายนี้ prompt ของคุณ → การอ่านไฟล์ของ Claude → การแก้ `src/routes/orders.ts` → คำสั่ง Bash ที่รัน → ผลลัพธ์ของเทสต์ → คำตอบสรุปของ Claude แต่ละบรรทัดเป็น JSON object ที่สมบูรณ์ในตัวเอง สิ่งที่ต้องรู้คือรูปแบบภายในของไฟล์เป็นเรื่องของ Claude Code เองและเปลี่ยนได้ระหว่างรุ่น เอกสารจึงแนะนำให้อ่าน transcript ผ่านช่องทางที่ออกแบบมา เช่นการ export เป็นข้อความที่มนุษย์อ่านได้ แทนการเขียนสคริปต์แกะไฟล์ดิบ แล้วอะไรอ่าน transcript กลับ สามกลไกที่คุณจะเจอบ่อยคือการกลับเข้า session เดิม การย้อนสถานะของ session และการแยกสาขาบทสนทนา ทั้งสามอย่างอ่านจากไฟล์เดียวกัน นี่คือเหตุผลว่าทำไมปิด terminal แล้วกลับมาได้ และทำไมลบไฟล์ทิ้งแล้วประวัติหาย สองค่าที่ควบคุมไฟล์นี้คือที่เก็บ ซึ่งย้ายได้ผ่าน environment variable และอายุ ซึ่ง harness จัดการตามรอบ retention ทั้งคู่เป็นค่าที่ตั้งได้และเปลี่ยนได้ จึงรวมไว้ในตารางด้านล่างพร้อมวันที่ตรวจสอบ

สรุปเชิงกลไก: transcript คือหลักฐานถาวรของ session บนเครื่องนี้ ข้อเท็จจริงนี้บอกว่าไฟล์อยู่ที่ใดและเก็บสิ่งที่พิมพ์ไว้อย่างไร แต่ไม่ได้ยืนยันเรื่องการเข้ารหัสหรือการส่งข้อมูลไปที่อื่น ซึ่งเป็นคนละคำถามและต้องดูเอกสารเจ้าของเรื่องนั้นโดยตรง สิ่งที่คุณใช้ตัดสินใจได้ทันทีคือ: ทุกอย่างที่คุณพิมพ์กลายเป็นบรรทัดในไฟล์ที่อ่านได้ด้วยเครื่องมือทั่วไป และไฟล์นั้นมีอายุตามค่าที่ตั้งไว้

สองแบบจำลองด้านล่างอธิบาย session ว่า "จำได้" เหมือนกัน แต่พึ่งข้อเท็จจริงคนละอย่าง และนำไปสู่การตัดสินใจคนละชุด

• session คือบทสนทนาที่ผูกกับ project directory; transcript คือไฟล์ JSONL ที่ harness เขียนต่อท้ายบนดิสก์ของคุณ
• ปิด terminal ไม่ลบ transcript — การกลับเข้า session เดิม การย้อนสถานะ และการแยกสาขา อ่านกลับจากไฟล์นี้
• ทุกอย่างที่คุณพิมพ์กลายเป็นบรรทัดในไฟล์: ตัดสินใจก่อนแปะ และรู้ว่าไฟล์มีอายุตามค่าที่ตั้งไว้
• ก้าวต่อไป: บทถัดไปคือ Checkpoints and rewind ซึ่งจะพาไปรู้ว่า harness snapshot การแก้ไฟล์แยกจาก git อย่างไร และย้อนกลับได้แค่ไหน