Session Memory

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

unreleasedmemorycontext

(un)official. reverse-engineered from latest claude code (v2.0.72). not public yet. grab the npm tarball, string search, and verify yourself with opus :)

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. Don’t worry about the complexity — it’s all automatic:

# 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.

Under the hood, Claude receives these instructions to fill in the template:

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}}

Back Into the Context Window

Past memories load silently when you start a new session. Claude just picks up where you left off.

Here’s what gets injected behind the scenes:

<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>

Customization

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

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

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.

tldr: this is the start of infinite context.

the hack: read markdown, write markdown.

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

← Back to all posts