Session Memory

Persistent context across Claude Code sessions — coming to a terminal near you

unreleasedmemorycontext

Claude Code is getting long-term memory.

Session Memory automatically captures key information from your conversations and persists it to disk. Task specifications, file references, workflow patterns, errors encountered — all preserved and restored in future sessions.

If you’ve ever had to re-explain your project to Claude after a long session — that’s about to change.

How It Works

Session Memory runs in the background, periodically extracting important information to a structured markdown file. No commands to run, no manual saving.

Trigger conditions:

Storage location:

~/.claude/session-memory/
├── config/
│   ├── template.md      # Custom template (optional)
│   └── prompt.md        # Custom extraction prompt (optional)
└── [session-id].md      # Your session notes

Files are plain markdown. You can read them, edit them, or delete them.

What Gets Captured

Here’s the template Claude uses to structure what it remembers:

# Session Title
A short, distinctive 5-10 word description

# Current State
What's actively being worked on. Pending tasks. Immediate next steps.

# Task Specification
What the user asked to build. Design decisions. Explanatory context.

# Files and Functions
Important files, what they contain, why they're relevant.

# Workflow
Bash commands usually run and in what order. How to interpret output.

# Errors & Corrections
Errors encountered and how they were fixed. What approaches failed.

# Codebase and System Documentation
Important system components. How they work together.

# Learnings
What worked well. What didn't. What to avoid.

# Key Results
If the user asked for specific output — answers, tables, documents —
the exact result is preserved here.

# Worklog
Step by step, what was attempted and done. Terse summary.

The Current State section is particularly important — it’s what enables Claude to pick up exactly where you left off, even after context has been compacted.

Re-injection

When you start a new session, Claude Code quietly injects past session memories as context. You won’t see this, but Claude will have access to what you worked on before.

Customization

Want different sections? Different extraction logic? Both are customizable.

Each section is capped at ~2,000 tokens to keep memories focused.

Availability

Session Memory is currently feature-gated and in internal testing — not yet available to the public.

What This Means

Context loss has been one of the most common frustrations with Claude Code — long conversations get compressed, details get lost, and you end up re-explaining things you already covered.

Session Memory fixes this — a persistent layer of context that survives session boundaries, context compaction, and time.

The files are yours. They’re on your disk, in plain markdown, editable and deletable. Claude learns from them, but you control them.

This is the start of infinite context.

Under the Hood

For those who want to see exactly what’s happening behind the scenes — here are the actual prompts.

The Extraction Prompt

Notice how Current State gets special emphasis — it’s the continuity anchor that survives context compaction. The prompt also demands specifics (file paths, function names, error messages) over vague summaries.

Based on the user conversation above (EXCLUDING this note-taking instruction
message as well as system prompt, claude.md entries, or any past session
summaries), update the session notes file.

The file {{notesPath}} has already been read for you. Here are its current contents:
<current_notes_content>
{{currentNotes}}
</current_notes_content>

Your ONLY task is to use the Edit tool to update the notes file, then stop.
You can make multiple edits (update every section as needed) - make all
Edit tool calls in parallel in a single message. Do not call any other tools.

CRITICAL RULES FOR EDITING:
- The file must maintain its exact structure with all sections, headers,
  and italic descriptions intact
- NEVER modify, delete, or add section headers (the lines starting with '#')
- NEVER modify or delete the italic _section description_ lines
- ONLY update the actual content that appears BELOW the italic descriptions
- Write DETAILED, INFO-DENSE content - include specifics like file paths,
  function names, error messages
- For "Key results", include the complete, exact output the user requested
- Keep each section under ~2000 tokens/words
- IMPORTANT: Always update "Current State" to reflect the most recent work

Use the Edit tool with file_path: {{notesPath}}

The Re-injection Format

Past memories are injected as previews, with an explicit warning: don’t assume relevance unless the user’s messages indicate otherwise.

<session-memory>
These session summaries are from PAST sessions that might not be related
to the current task and may have outdated info. Do not assume the current
task is related to these summaries, until the user's messages indicate so
or reference similar tasks. Only a preview of each memory is shown - use
the Read tool with the provided path to access full session memory when
a session is relevant.

[Preview of past session memories here]
</session-memory>

Next up: Claude Code is also getting multi-agent swarms. Stay tuned.

← Back to all posts