Add user warning/caveat: only update Claude Code when you do NOT depend on old/existing sessions to resume!

[oberstet]

confirmed this trap by letting Claude self-analyze my situation:

● Here's what I found:                                                                                                         
                                                                                                
  Your sessions-index.json for this project has 0 entries — that's why --resume shows nothing. Other projects (like campfireos,
   typedefint) have proper entries and would work fine.                                                                        
                                                                                                                               
  You have 5 conversation files in this project:                                                                               
  File: b73e6987...                                                                                                            
  Size: 22 MB
  Content: 5,360 messages (real conversation about Docker builds, wheels, SLSA, etc.)
  Date Range: Dec 2025 – Jan 28, 2026
  ────────────────────────────────────────
  File: 4a1d5bd4...
  Size: 387 KB
  Content: Only file-history-snapshots (no conversation)
  Date Range: —
  ────────────────────────────────────────
  File: a5959ef5...
  Size: 259 KB
  Content: Only file-history-snapshots (no conversation)
  Date Range: —
  ────────────────────────────────────────
  File: 1a4733f7...
  Size: 59 KB
  Content: Only file-history-snapshots (no conversation)
  Date Range: —
  ────────────────────────────────────────
  File: adce2fca...
  Size: 80 KB
  Content: This conversation (current)
  Date Range: Feb 13, 2026
  Your hypothesis is correct — these conversations were created by an older version of Claude Code that didn't write to
  sessions-index.json, so --resume can't find them. The 3 snapshot-only files may have been from sessions where you exited
  quickly, and the old format only saved file snapshots.

  The big b73e6987 conversation (Docker/SLSA/wheels work) is the one you're probably looking for. Would you like me to manually
   add it to sessions-index.json so --resume can find it? I can reconstruct the index entry from the file metadata. Though
  note: a 22 MB / 5,360-message conversation may be too large for Claude Code to actually load back into context effectively.

✻ Churned for 1m 18s

❯ oh, I see! thanks for digging. this is an important caveat I need to ingest: "only update Claude Code when you do not        
  depend on old/existing sessions to resume - because the version update might change session storage/persistency format      
  or indexes!"                                                                                                                 
                                                                                                                               
● Yes, that's a solid takeaway. And to be precise about what happened here: it's not that the conversation data was lost — the 
  22 MB JSONL file is still fully intact. It's just that the index (sessions-index.json) wasn't backfilled when the newer      
  Claude Code version introduced it, so --resume doesn't know about the old sessions.                                        
                                                                                                                               
  A few practical notes:
                                                                                                                               
  - The data is still there — if a future Claude Code update re-indexes old sessions, they'd reappear                        
  - You could back up ~/.claude/projects/ before upgrading, just in case
  - That massive session (5,360 messages, 22 MB) had already been context-compressed 7 times — it was pushing the limits
  regardless

  Let me save this insight to memory so we remember it going forward.

● Wrote 1 memory (ctrl+o to expand)   
                                              
● Saved. Is there anything from that old session you'd like to pick back up, or are you starting fresh?

[oberstet]

also document / note the different memories:

• Conversation = ephemeral, tied to one session, can be resumed but eventually hits context limits
• Memory files = persistent, always loaded, shared across all sessions in this project

❯ oh, I see! thanks for digging. this is an important caveat I need to ingest: "only update Claude Code when you do not        
  depend on old/existing sessions to resume - because the version update might change session storage/persistency format      
  or indexes!"                                                                                                                 
                                                                                                                               
● Yes, that's a solid takeaway. And to be precise about what happened here: it's not that the conversation data was lost — the 
  22 MB JSONL file is still fully intact. It's just that the index (sessions-index.json) wasn't backfilled when the newer      
  Claude Code version introduced it, so --resume doesn't know about the old sessions.                                        
                                                                                                                               
  A few practical notes:
                                                                                                                               
  - The data is still there — if a future Claude Code update re-indexes old sessions, they'd reappear                        
  - You could back up ~/.claude/projects/ before upgrading, just in case
  - That massive session (5,360 messages, 22 MB) had already been context-compressed 7 times — it was pushing the limits
  regardless

  Let me save this insight to memory so we remember it going forward.

● Wrote 1 memory (ctrl+o to expand)   
                                              
● Saved. Is there anything from that old session you'd like to pick back up, or are you starting fresh?
                                                                                                                               
❯ let's start fresh! before jumping in, where will you store the conversation/context? just trying to learn and improve my     
   workflows.                                                                                                                  
                                                                                                                               
● Great question. Here's how it works for this session:                                                                        
                                                                                                                               
  Conversation data — stored in:                                                                                               
  ~/.claude/projects/-home-oberstet-work-typedefint-customer-galt-aero/adce2fca-bb86-4f0c-ac62-983ace1bf914.jsonl              
  That's the JSONL file for this session (it already exists — we've been talking). It grows with every message exchange. As    
  long as the session index gets written properly (which current Claude Code does), --resume will find it next time.           
                                                                                                                               
  Persistent memory — stored in:                                                                                               
  ~/.claude/projects/-home-oberstet-work-typedefint-customer-galt-aero/memory/MEMORY.md                                        
  This is loaded into my system prompt at the start of every session in this project directory. It survives across sessions —
  so key lessons, project context, and patterns I write there carry forward even when starting fresh. I can also create
  additional topic files in that memory/ folder and link to them from MEMORY.md.

  Key distinction:
  - Conversation = ephemeral, tied to one session, can be resumed but eventually hits context limits
  - Memory files = persistent, always loaded, shared across all sessions in this project

  So if there's anything important you want me to always remember in this project, the memory files are the right place. The
  conversation itself is just the back-and-forth for one work session.

  Want to dive into work now?

[oberstet]

need to ask explicitly to update:

● Great, main is synced and up to date on asgard1. Clean merge with all 161 lines landed.                                      
   
❯ very good! since I want to move to sth else for now, but continue soon again, please update your persistent memory for       
  the topic/project we have just worked on as you see fit. I mean this:   Persistent memory — stored in:                      
                                                                                                                               
    ~/.claude/projects/-home-oberstet-work-typedefint-customer-galt-aero/memory/MEMORY.md                                      
                                                                                                                               
                                                                                                                             
                                                                                                                             
● Recalled 1 memory, wrote 1 memory (ctrl+o to expand)                                                                         

● Updated. Key additions:                                                                                                      
   
  - Git hooks policy — so I don't hit the co-author trailer rejection again                                                    
  - Crossbar PID 1 behavior — the core insight behind the wrapped entrypoint approach                                        
  - Project layout — justfile location, bare repo path, multi-stage git workflow                                               
  - Recent work summary — what was done, what was merged, what commit, what was tested                                         
                                                                                                                               
  Should be easy to pick up where we left off next time.

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
❯  
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  ⏵⏵ accept edits on (shift+tab to cycle) · ctrl+t to hide tasks        ✗ Auto-update failed · Try claude doctor or npm i -g 
                                                                        @anthropic-ai/claude-code