Simple Context Memory — No More Session Amnesia in Claude Code

The Problem

Not "a little forgetful" — total blank slate

Every time you start a Claude Code session, Claude wakes up with complete amnesia. The project you've been building for three weeks, the decision you made Thursday about why you're not using Redis, the half-finished design sitting in your last conversation — gone.

The reflex solution is to save everything. Dump the whole context into memory files. But that's just moving noise. Claude can't tell which of the forty remembered facts is the one that matters right now, and you end up re-litigating decisions you already settled.

🧠

Decisions re-litigated

Claude proposes Redis again. You explain why you rejected it — again. The reasoning that took an hour to arrive at the first time costs another hour to reconstruct.

🪤

Compaction is lossy

When the context window fills, Claude Code compacts automatically — and compaction summarizes rather than preserves. The fine-grained why behind decisions is gone.

🌊

Context overload

Dumping everything into memory files moves noise, not signal. Claude can't distinguish load-bearing decisions from incidental observations when they're all the same weight.

🔄

The wrong roads, again

Without a record of what was rejected and why, every session is free to rediscover dead ends. The same wrong paths get explored with fresh confidence each time.

The Solution

A surgical handoff system. Three commands.

When a surgeon hands off to another, they don't read the full patient chart — they write a one-page note: what changed on this shift, what decisions were made and why, what's still open. That's it. Everything else is reconstruction the incoming surgeon can do. These commands implement that system for Claude Code.

Time horizon 01 — Session to session

/closing

Write the handoff note before you leave

Captures what was built, why it was done this way (including the reasoning that prevents re-litigation), what was considered and rejected, and what's explicitly open. Saves an archaeology document to docs/sessions/ with a timestamp filename.

Run before closing Claude Code — or before the context window fills up. Don't wait until the end.

Time horizon 02 — Note to context

/opening

Read the handoff note when you arrive

Reads session archaeology documents and gives you a structured brief: what the project currently is, what decisions are settled, what's pending, and what threads were live when you left off. For large loads, delegates to a subagent so raw history never enters your context.

Run at the start of every session. First thing, before any other commands.

Time horizon 03 — History to current state

/report

Synthesize across all sessions

Reads every session document and produces a single project state report: every still-open deferral cross-referenced against later sessions, every Do Not constraint accumulated across all Roads Not Taken, every standing assumption nobody has confirmed or overturned, and every fragile area still flagged as needing scrutiny. Incremental by default — only processes new sessions on each run.

Run when sessions start accumulating. At 20+ sessions, the report plus 2–3 recent files equals loading everything — at a fraction of the token cost.

/closing — in depth

The archaeology document

The code shows you what was built. Only this document shows you why the obvious alternative wasn't chosen — and where to be careful even when nothing looks obviously wrong. Nine sections. Each one signals to Claude what's load-bearing so it doesn't have to infer.

● docs/sessions/2026-05-19-1531-drop-idempotency-table.md

## Summary

Removed the local idempotency table and switched to Stripe's native idempotency key support. The table was duplicating protection Stripe already provides for free. Next session: decide whether to log the Stripe idempotency keys for audit purposes.

## What We Did

Removed IdempotencyKey model entirely · Switched to Stripe's built-in Idempotency-Key header · Updated payment_processor.rb · Removed migration (rolled back before drop)

## Roads Not Taken

Redis-backed idempotency store — adds an infrastructure dependency for a problem Stripe already solves. Do not introduce a local idempotency store of any kind — Stripe's native support covers all current payment paths.

## Key Discoveries

Does Stripe's idempotency window cover our retry policy?

→ Yes. Stripe's window is 24 hours; our retry policy retries within 6 hours. Safe.

## Assumptions Made

Assumed stripe_event_id is unique per logical charge attempt across retries — never explicitly verified against Stripe's retry docs, just inferred from observed staging behavior. If Stripe ever reuses an event ID across two distinct charge attempts, this strategy would silently swallow a legitimate second charge.

## Where the Agent Struggled

Confirming the 24-hour window took three searches through Stripe's docs before finding the number stated explicitly. Treat the number as solid — but the difficulty finding it is worth knowing if this ever needs re-verifying.

## Open Questions & Next Steps

Do we want to log the Idempotency-Key values we send to Stripe for audit purposes, or is Stripe's dashboard sufficient? Deferred — not a blocker for the current release.

Summary

2–3 sentences. Orient in ten seconds without reading anything else.

What We Did

File paths, function names, design choices. Specific — not vague.

Why We Did It

The reasoning. So future sessions don't re-litigate it.

Roads Not Taken

What was rejected. Each entry ends with a bold Do not [X] because [Y] constraint.

Key Discoveries

Questions answered. Root causes traced. Formatted as question → answer pairs.

Assumptions Made

Implicit choices filled in without ever being decided. Nobody flagged it — so a future reader can't audit it unless it's written down here.

Where the Agent Struggled

A confidence signal, not a content claim. Which parts took multiple attempts or landed with lower confidence — so you know where to look twice.

Open Questions

Deferred items, half-decisions, action items. What the next session picks up.

Files Changed

What changed and where, plus any constraint before a future session touches that file.

/opening — in depth

/opening modes

Pass an argument to control how far back to look. For 3+ session files, /opening delegates to a subagent — the raw archaeology never enters your context window.

Command	What it loads
/opening	Last session (default)
/opening 2	Last 2 sessions
/opening today	All sessions from today
/opening last-week	Sessions from the past 7 days
/opening all	Every session — full arc
/opening summary	Every session as a narrative — "how did we get here?"
/opening search <question>	Searches history to answer a specific question — always delegates to subagent
/opening file <path>	Loads a specific session file directly

The summary mode is what you want after a long break — it tells the story of how the project arrived at its current shape. The search mode finds specific decisions: /opening search why did we drop the webhook approach

/report — in depth

Accumulated state across all sessions

One session document answers "what happened last time?" Thirty session documents answer a harder question: what is the accumulated state of all deferred work, locked constraints, standing assumptions, and fragile areas across the entire project history? The report collapses that into a single load — four sections, not two.

/report

Incremental — reads last_session cursor from the report frontmatter and only processes new sessions. At 20+ sessions you're not re-paying the synthesis cost on history already captured.

/report full

Ignores the cursor and rebuilds from every session document. Use after a /closing that may have resolved items the report currently shows as open.

Compaction Protection

Three hooks. One layered defence.

Claude Code compacts automatically when the context window fills — and compaction is lossy. Don't wait until the end of a session to run /closing. These hooks automate the safety net.

Hook 01

context-watch.py

UserPromptSubmit

Monitors context usage on every prompt. Warns at 60% and 75% — early notice to run /closing manually before compaction happens. Parses the session JSONL backwards for the last usage block.

Hook 02 — Safety Net

pre-compact.py

PreCompact

Acts automatically if you don't. Instructs Claude to write a session document immediately before compaction runs — so even if you miss the 60% warning, the archaeology is preserved.

Hook 03

post-compact.py

PostCompact

After compaction, names the session file that was written and prompts you to run /opening to reorient. If no file was written, tells you to run /closing immediately to capture what remains.

Inside /closing

SBAR-C — a nursing handoff framework

Before writing any section, /closing has Claude reason through the session using SBAR-C as a completeness check. This reasoning doesn't produce extra sections — it surfaces content for the sections that already exist, and catches contingencies before they get buried.

Situation

What is the current state of the project? What changed this session?

Background

What led to the key decisions? What context is needed to understand why things are the way they are?

Assessment

What was figured out that wasn't known before? What questions were answered?

Recommendation

What needs to happen next? What is the clearest path forward for the next session?

Contingency

What assumptions were made that, if they change, would reopen a closed decision — and which assumptions were never a decision at all, just a gap quietly filled in?

Contingency is the key addition to standard SBAR, and it splits two ways. A contingency tied to a decision lands as a conditional in the Do Not line: Do not X because Y — unless Z, in which case reconsider. That way the guard rail carries its own expiry condition. A contingency not tied to any decision — an assumption nobody consciously made, or a part of the work that was harder to get right than it looks — lands in Assumptions Made or Where the Agent Struggled instead. A future session doesn't blindly respect an outdated constraint, and it doesn't mistake something fragile for something solid either.

Why It Works

Three commands, three different jobs

Structured format does the compression before the document enters context

Contrast dumping raw chat history: Claude sees a wall of text with no signal about what matters. The archaeology format extracts the signal before Claude reads it. Each section signals what's load-bearing — Summary orients in ten seconds, Roads Not Taken surface the guard rails, Key Discoveries prevent re-discovery of hard-won knowledge, and Assumptions Made / Where the Agent Struggled flag reliability, not just content — where to look twice even when nothing looks obviously wrong.

Subagents keep your context window clean

For large loads (3+ session files), /opening delegates to a subagent. The subagent reads all the documents and returns a finished synthesis — the raw archaeology never enters your context window. For /opening search, the subagent always runs regardless of file count, because question-answering across a history of decisions is exactly the kind of synthesis a subagent handles well.

The report solves the 30-session problem

At scale, the question shifts from "what happened last time?" to "what is the accumulated state of all deferred work, locked constraints, standing assumptions, and fragile areas across the entire project history?" The last_session cursor in the report frontmatter means you don't re-pay the synthesis cost on history already captured — subsequent runs only process new sessions.

Together they mean no session starts cold

/closing captures the handoff before it's lost. /opening reads the handoff and orients the new session in seconds. /report collapses accumulated sessions into one load when individual files become too many to read. Each command operates at a different time horizon — and together they cover the full lifecycle of a project that outlasts any single context window.

Installation

30 seconds. No config. No restart.

Install globally — these commands are useful in every project, not just one. Claude Code picks up .md files in commands/ directories automatically.

Clone the repo

Gets the commands, hook scripts, and install script onto your machine.

git clone https://github.com/revans/simple-context-memory

Run the install script

Copies commands to ~/.claude/commands/, hooks to ~/.claude/hooks/, and checks whether hooks are wired in settings.json — printing the required JSON if not. Existing files are overwritten without prompting.

bash simple-context-memory/init.sh

That's it

Open any Claude Code session and run /opening to start. The first session will tell you there are no previous sessions yet — run /closing before you end it.

# In any Claude Code session:
/opening        # load context
# ... do your work ...
/closing        # save before you leave

Optional — wire the compaction hooks

The install script handles this if you ran it. If you installed manually, add this to ~/.claude/settings.json to enable the three-layer compaction defence.

{
  "hooks": {
    "UserPromptSubmit": [{ "type": "command",
      "command": "python3 ~/.claude/hooks/context-watch.py" }],
    "PreCompact": [{ "type": "command",
      "command": "python3 ~/.claude/hooks/pre-compact.py" }],
    "PostCompact": [{ "type": "command",
      "command": "python3 ~/.claude/hooks/post-compact.py" }]
  }
}

Output lives with your project

The commands are global (~/.claude/commands/). The output files are local to each project under docs/sessions/ and docs/reports/. Commit both to your repo — the session history and the report are the institutional memory of the project and belong in version control next to the code.

Claude Code starts with total amnesia. Every session.