Stop re-explaining your project to Claude Code every session

#ai #claude #productivity #opensource

You open a new Claude Code session and spend the first ten minutes re-explaining your project. What you're building. Why you chose Postgres over Mongo. That you hate verbose output and want diffs, not essays. That the auth rewrite is a compliance deadline, not tech debt.

Then the session ends and all of it evaporates. Next session, you do it again.

The model isn't the problem — context is. Claude Code starts every conversation as a blank slate. The fix isn't a bigger model or a vector database. It's a small, structured set of plain markdown files that load automatically at session start.

The structure

~/.claude/
  CLAUDE.md                    # custom instructions, loaded every session
  projects/<project>/
    CLAUDE.md                  # project-specific instructions
    memory/
      MEMORY.md                # index — always loaded, kept under 200 lines
      user_profile.md          # who you are, your skills, preferences
      feedback_style.md        # how you want Claude to behave
      project_overview.md      # what you're building, architecture decisions
      reference_links.md       # external resources, API docs, dashboards

No dependencies, no daemon, no cloud. Just files Claude reads on startup.

Four memory types, and one rule that matters most

Type	What to store	Example
`user`	Your role, skills, preferences	"Senior backend dev, prefers Go, hates verbose output"
`feedback`	Corrections you've given Claude	"Don't mock the database in tests — use the real DB"
`project`	Ongoing context, deadlines, decisions	"Auth rewrite is compliance-driven, not tech debt"
`reference`	Pointers to external resources	"Bug tracker is Linear project INGEST"

The single highest-value type is feedback. Every time you correct Claude — "stop doing X," "always do Y" — that correction should become a memory file. That's the difference between an assistant that repeats the same mistake every session and one that learns once and never repeats it.

The index rule (the part people get wrong)

MEMORY.md is the one file loaded into every conversation. So it has exactly one job: be a lean index of pointers, not a content dump.

Keep it under 200 lines. Past that it gets truncated and you silently lose the tail. What goes in the index:

One-line links to topic files, each with a short description
Critical facts that apply to literally every session

What does not go in the index — or anywhere in memory:

Code conventions — Claude reads your code directly
File paths and structure — that's what glob/grep are for
Git history — git log is authoritative
Bug fixes — the fix already lives in the code

If it's derivable from the repo, don't store it. Memory is for the things the code can't tell Claude: who you are, what you've decided and why, and how you want to be worked with.

How it actually plays out

After the one-time setup, you don't manage memory by hand. You say "remember that I prefer X" mid-conversation and Claude writes the file. You correct it once and the correction persists. Review the set monthly — delete what's stale, tighten the index. A lean memory system beats a bloated one every time.

The payoff is mundane and enormous: every session starts with Claude already knowing your project, your standards, and your last six months of decisions. The first ten minutes go away.

Try it

It's free and open source — templates plus a one-command setup:

git clone https://github.com/LuciferForge/claude-code-memory.git
cd claude-code-memory
python3 setup.py

Repo (templates + the index rules in full): https://github.com/LuciferForge/claude-code-memory?utm_source=devto&utm_medium=article&utm_campaign=claude-code-memory-2026-06-01

If you've built your own memory setup for Claude Code, I want to hear how you structure the index — that's the part everyone solves differently.

DEV Community