Session Memory

Some Claude Code bundles include a disk-backed “session memory” feature: a structured notes file that the runtime can update during a session and re-inject later.

This is reverse engineered from a shipped bundle. Treat the details as “observed behavior,” not a stable public contract.

What You’ll Learn

• What gets saved, and why it’s more useful than a raw transcript.
• How the system writes memory in a format you can inspect and edit.
• How saved memory is re-injected without “taking over” the next session.

How It Works

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

The key property is cadence: it updates often enough to stay useful, but not so often that it becomes noise.

Storage location (conceptual):

[claude-code data dir]/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

Session Memory writes a structured notes file. The shape matters, because it makes the memory scan-friendly and stable under edits.

The sections are roughly:

• session title
• current state + next steps
• task spec and decisions
• important files/functions
• workflow (commands and order)
• errors and fixes
• learnings
• key results
• worklog

Under the hood, the note-taking step is intentionally constrained (paraphrased):

• update the notes file and stop
• keep the exact headers/structure
• only change the content under each section
• keep it detailed (paths, functions, error messages)
• always refresh “Current State”

Back Into the Context Window

When enabled, saved memory can be loaded at the start of a new session. The runtime wraps it in a caution header so the model does not blindly assume it’s relevant.

The injection is wrapped in a “be careful” header so the model does not blindly assume the memories are relevant. It’s closer to:

• “these are from past sessions”
• “they may be unrelated or outdated”
• “use them only if the user’s current messages match”

Customization

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

• Custom template: [claude-code data dir]/session-memory/config/template.md
• Custom extraction prompt: [claude-code data dir]/session-memory/config/prompt.md

What This Means

This is the operational point of view: memory is reliability engineering for long-lived work.

Instead of relying on “whatever the model remembers,” the system maintains a user-auditable state file that can survive:

• session boundaries
• compaction/summarization events
• long gaps between runs

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

Practical Risks (And How To Design Around Them)

• Staleness: memory can drift. Add “last updated” markers and a “known current state” section that is refreshed every run.
• Overreach: don’t let memory override live instructions. Always treat it as optional context, never as authority.
• Privacy: disk-backed notes are data. Give users an obvious delete path and allow disabling extraction.

Related

• /context-window-ops/
• /hooks-and-skills/
• /swarm-mailbox-protocol/