Claude Code Memory: Store the WHY So Claude Starts Every Session Briefed

Published June 2026 · 6 min read

Here is the situation every developer hits within a week of using Claude Code seriously. You spend a session explaining your project: why the auth layer is the way it is, which environment variables need to be set manually and why, what the team agreed about database migrations, why you're pinned to a specific library version. Claude is excellent. You get real work done.

Next session: blank. You're re-explaining it all from scratch.

This isn't a bug in Claude — it's a deliberate privacy and cost boundary. But it does mean that as a developer, you carry context that Claude can't. The question is where that context lives between sessions.

What context goes stale, and what doesn't

Your codebase is in your repo. Claude Code can read it. So "what does this function do" is not the problem — that's always recoverable from source. The problem is the interpretive layer: the reasoning that doesn't survive in code, comments, or commit messages.

Things that fall through the cracks:

• Architecture decisions — "We chose this pattern because X, not because Y which would seem obvious." The decision is in the code, the reasoning isn't.
• Environment gotchas — "The staging environment needs this flag set manually, and if you don't, it silently falls back to development behaviour." Nowhere in the repo.
• Ongoing TODOs and open questions — "We need to revisit the pagination approach after the indexing work lands. Currently punting." Not filed as an issue, lives in your head.
• Team conventions — "We don't use default exports in this project, even though the framework recommends them. Dan started this and now it's the norm." New contributor won't know.
• Debugging notes — "This intermittent failure has been traced to a race condition in the event emitter. We haven't fixed it yet but here's how to reproduce it reliably."
• Dependency reasons — "We're pinned to v2.3.1 of this library because v2.4 broke our custom resolver. Do not upgrade until upstream fixes their issue #4421."

None of this lives anywhere that Claude can read. So you re-explain it, every session.

The Stash approach: store the interpretive layer once

Stash is a hosted MCP server Claude connects to. You write records to it in any session, and Claude can query them in any future session. The idea is simple: the first time you explain something to Claude that you'd otherwise explain again, you also tell it to save it to Stash.

Typical collections a developer maintains:

• arch-decisions — Architecture decisions with the reasoning, not just the outcome
• env-notes — Environment-specific behaviour, manual steps, and known quirks
• open-questions — Active unknowns the team is tracking
• conventions — Code style, naming, and pattern decisions that aren't enforced by linting
• debug-log — Known bugs under investigation, reproduction steps, working theories

What this looks like in practice

Here is a realistic session start. The developer picks up work on a payment integration:

Developer: context("payments")

Claude: Found 4 records in payments collection:

  arch-decisions/stripe-webhooks: We handle Stripe webhooks via a dedicated
  /webhooks endpoint rather than inline in the order flow. Reason: the order
  flow is synchronous and Stripe recommends async webhook handling to avoid
  timeouts. Idempotency key is the Stripe event ID — implemented 2026-04-12
  after an incident where duplicate charges were processed.

  env-notes/stripe-keys: STRIPE_WEBHOOK_SECRET must be set manually in each
  environment. It is NOT in .env.example because the value changes per
  endpoint URL. Staging uses a different Stripe account entirely.

  open-questions/refund-flow: We haven't handled partial refunds in the
  current flow. The Stripe API supports it; we just haven't built the UI.
  Punting until after the billing milestone.

  debug-log/webhook-timeout: Intermittent 504s on the webhook endpoint under
  load. Root cause not confirmed — suspect the order lock acquisition. Not
  reproducing in staging reliably.

The developer is up to speed in one call. Claude knows what they're working with before the first substantive message. No re-briefing, no "as I mentioned last time."

Later in the session, the developer learns something new:

Developer: Good to know. Add to debug-log: confirmed the webhook timeout is
caused by the order lock. The lock times out at 5s and the payment processor
can take up to 8s under peak load. Fix is to raise the timeout to 15s or
move the lock acquisition to after the Stripe call.

Claude: Saved to debug-log/webhook-timeout.

Next session, that knowledge is there. It compounds.

What not to store

A few things that don't belong in Stash:

• Secrets and credentials. Never. Not API keys, not tokens, not passwords. Use your secrets manager for that. Stash is not a secrets store.
• Large diffs or full file contents. Claude can read your repo. Don't paste source code into Stash — store the reasoning about the source code.
• Things that change every commit. Stash is for durable context. If something changes every day, it's not worth the maintenance overhead.
• Things that are already well-documented. If it's in the README or a proper ADR (Architecture Decision Record), link to it rather than duplicating it.

The target is the reasoning that a new team member would need to extract from a two-hour conversation with a senior developer. That is exactly the context that vanishes between Claude sessions.

The token math is worth understanding

When you call context("payments"), Stash does a full-text search across your records and returns the relevant ones. A typical developer collection has 20–40 records; a context call might return 4–6. That's roughly 400–800 tokens — a fraction of what you'd spend re-briefing Claude from scratch. And the quality of context is higher because it's structured and curated, not the noise of pasting a conversation history.

Getting started in one session

Add the connector (paste the URL below into Claude's MCP settings). Then in your next working session:

1. Create a collection called arch-decisions.
2. Add the three most important architecture decisions in your current project — the ones you'd spend most time re-explaining to a new developer.
3. At the end of the session, add anything you explained to Claude that felt like it would need to be explained again.

Within a week you'll have a working knowledge layer. Within a month, Claude will start sessions knowing your project well enough that you stop explaining the backstory entirely.

Pricing

Free tier covers most individual developers. Pro (£8/month) raises limits for larger codebases or team use. Pricing may change; cancel anytime.