Session Vs. Memory in claude CLI /memory: Finally Context That Survives!

There are TWO features in the new /memory capability in claude CLI:
-session
-memory

I discovered this after inspecting /context after JUST starting a new claude session and running my new fav command at startup /primer (more on this amazing command in another article) and seeing I had already taken up about 12 bubbles!!! WAY too much for the start of a session.

There are 3 primary files that make up the /memory file system in my workflow:

1. project-context.md - The "what's the current state" file
2. architecture-decisions.md - The "why we chose X over Y" file
3. known-gotchas.md - The "problems and solutions" file

When I had allowed 2 of these files to grow to over 1200 lines each THAT was what was burning up my early conversation context!! So I trimmed ALL 3 down to less then 500 lines and BAM when I run a new claude and a /primer I see this!

So the big message there is keep these 3 files trim and under 500 lines each!

Now let's move on to this slightly more interesting session. How does session work and how are it's benefits useful to us?

Session files (in .claude/memory/sessions/[date]-[topic].md) are different from those three core files.

Session files are:

• Task-specific - Created AFTER completing a major task
• Deep dives - More detailed than the core files (can be longer, like 500-800 lines)
• Selectively read - Only read when RELEVANT to current work
• Historical record - "What did we learn when we built X?"

The key difference:

Core 3 files (project-context, architecture-decisions, known-gotchas):

• Read at EVERY session startup
• MUST be short (<500 lines, ideally <300)
• Broad overview, not deep details

Session files:

• Read ONLY when continuing related work
• CAN be longer (500-800 lines)
• Deep details about specific implementations

Example:
Session 1 (Monday): Build Fitbit integration

• Claude reads the core 3 files (startup)
• Implements feature
• Creates sessions/2025-11-04-fitbit-integration.md with all the details

Session 2 (Tuesday): Build WHOOP integration

• Claude reads the core 3 files (startup)
• Claude ALSO reads sessions/2025-11-04-fitbit-integration.md (because it's relevant)
• Reuses patterns from Fitbit

Session 3 (Wednesday): Fix unrelated bug

• Claude reads the core 3 files (startup)
• Does NOT read Fitbit session file (not relevant)

So let's see what this would look like in a real world example when I give claude a prompt to look into something we just fixed.

You can see claude initally goes to git BUT then it looks at session and finds the latest and FULL picture! I feel like session WAS the missing link. I have seen full bug fixes based on JUST session and the existing skills! So rewarding NOT having to tell claude what we did recently!