claude-session-memory

Persistent memory and context loading for Claude Code sessions. Never re-explain context from a prior session again.

Update (July 2026): Claude Code now ships part of this natively. As of v2.1.59 (February 2026), Claude Code has built-in auto-memory: a per-project memory directory, a MEMORY.md index loaded every session, topic files read on demand, and automatic persistence as Claude works. That covers this repo's storage substrate — the memory-file format and index pattern below — and if all you want is "Claude remembers my preferences", the native feature does it out of the box.

What native auto-memory does not cover is the layer this skill is really about:

• Session-start reconnaissance. Native memory recalls what Claude learned; it has no idea what other people did overnight. Phase 1 scans git activity, open PR review status, sprint-board comments, and deploys by others — then briefs you.
• Staleness reconciliation. Comparing the knowledge base against git/GitHub reality and fixing drift silently.
• The knowledge graph. Annotated [[wikilinks]] between notes make retrieval deterministic traversal, not search. Native memory files don't link.
• Tool-agnostic, long-term memory. Native auto-memory is per-repository, machine-local, and Claude Code's alone. A plain-markdown knowledge base (e.g. an Obsidian vault) is readable by every agent you run and outlives any one tool.
• Editorial policy. A decision tree for where each fact goes, consolidate-don't-append, absolute dates, mandatory annotated connections. Native auto-memory lets the model free-write; this skill enforces a schema.

Practical upshot: let native auto-memory own raw preference capture, and use this skill for the reconnaissance, graph, and policy layer above it. Full substrate-vs-layer comparison in My Harness Was Invisible. So I Built It an Observatory.

The Problem

Claude Code sessions are stateless. Every conversation starts from zero. You waste the first 5 minutes re-explaining what you were working on, what you decided, and what's next. Decisions made yesterday are forgotten today.

The Solution

A Claude Code skill that governs the full lifecycle of session context:

1. Session Start — Automatically scans git activity, loads knowledge base notes, detects stale state, and briefs you on where you left off.
2. Mid-Session Persistence — After every significant action (decision made, PR created, preference expressed), context is persisted immediately. No batching, no waiting for session end.
3. End-of-Session Extraction — Before the conversation ends, decisions, preferences, state changes, and open threads are extracted and written to durable storage.

How It Works

The skill uses a file-based memory system with frontmatter-tagged markdown files. Each memory has a type (user, feedback, project, reference), timestamps, and context links. A MEMORY.md index file acts as the entry point — it's loaded every session so the agent can decide what else to read. (Since v2.1.59 this index-plus-topic-files pattern is what Claude Code's native auto-memory implements too — see the update note above for how the two fit together.)

Auto-extraction patterns

The skill watches for these patterns and persists without being asked:

Pattern	Action
"I prefer...", "I don't like...", "don't do X"	Save as feedback memory
"We decided...", "Let's go with..."	Save to knowledge base
Corrections to agent behaviour	Save as feedback memory immediately
PR created/merged/closed	Update project state

Staleness detection

At session start, the skill compares what git/GitHub shows vs what the knowledge base says. If a PR is marked "in review" but has been merged, it fixes it silently and tells you what changed.

Installation

1. Create the skills directory if it doesn't exist:

   mkdir -p ~/.claude/skills/session-memory

2. Copy the skill file:

   cp SKILL.md ~/.claude/skills/session-memory/SKILL.md

3. Reference it in your ~/.claude/CLAUDE.md:

   # session-memory
   - **session-memory** (`~/.claude/skills/session-memory/SKILL.md`)
   - Run at session start. Governs full context lifecycle: load, maintain, persist.

Configuration

The skill is designed to be customised. You'll want to:

• Set your repo paths in the session-start scan
• Configure your knowledge base location (Obsidian vault, plain markdown folder, etc.)
• Add your project management tool queries (Jira, Linear, GitHub Issues)
• Adjust the persistence decision tree for your workflow

Design Principles

• Never ask "should I save this?" — if it matches the patterns, just save it.
• Never rely on the user to trigger persistence — it's the agent's job.
• Dates are absolute — never write "yesterday" in persistent storage.
• The user should never have to re-explain context from a prior session.
• Every memory must have timestamps and context links.
• Connection annotations explain relationships — don't just link, explain HOW it's related.

Memory File Format

---
name: short-kebab-case-slug
description: one-line summary used to decide relevance in future sessions
metadata:
  type: user|feedback|project|reference
---

Content here. Link related memories with [[their-name]].

Blog Posts

I wrote about the design and motivation behind this system:

• I Built a Memory Layer for My AI Agent (May 2026) — the original design
• My Harness Was Invisible. So I Built It an Observatory. (July 2026) — the substrate-vs-layer audit, a UI over the whole harness, and skill evals

License

MIT