DEV Community

Ray
Ray

Posted on

How I Stopped Re-Explaining Everything to Claude Code Every Single Session

#ai #devtools #productivity #claudecode

How I Stopped Re-Explaining Everything to Claude Code Every Single Session

Every time I started a new Claude Code session, I spent the first 5-10 minutes doing the same thing:

  • "Here's what we're building..."
  • "You prefer direct communication, no filler..."
  • "We're using this stack, this naming convention..."
  • "Last time we got stuck on X, we decided to do Y..."

It was like onboarding a new employee every morning. Except the employee was brilliant, I just had no way to give them a briefcase full of institutional knowledge before they sat down.

After months of frustration, I built a system that fixed this. Here's how it works.

The Problem: Every Session Starts from Zero

Claude Code (and most AI coding agents) don't retain memory between sessions. Each conversation is a clean slate. That's fine for a one-off question, but if you're building something real — a product, a tool, a side project — you end up re-establishing context over and over.

The problem compounds. You forget what you told it last time. It makes decisions inconsistent with what you'd established before. You're rebuilding momentum from scratch every single day.

There had to be a better way.

The Solution: A Workspace Memory System

The core insight: Claude Code reads files at the start of every session. If you put the right information in the right files, it starts every session already knowing who you are, how you work, and where things left off.

I built a 4-file system around this:

1. AGENTS.md — Workspace Instructions

This is the entry point. It tells Claude Code what to read, when, and in what order. Think of it as the "boot sequence" for your agent.

# AGENTS.md

## Every Session
Before doing anything else:
1. Read `SOUL.md` — this is who you are
2. Read `USER.md` — this is who you're helping  
3. Read `memory/YYYY-MM-DD.md` (today + yesterday) — MANDATORY
4. If in MAIN SESSION: Also read `MEMORY.md`
Enter fullscreen mode Exit fullscreen mode

Simple, but powerful. Every session starts with a full context reload.

2. SOUL.md — Agent Personality

This was the unexpected one. Once I gave Claude Code a consistent personality profile — communication style, values, decision-making rules — the responses got dramatically more consistent.

# SOUL.md

## Core
- **Blunt and direct.** No fluff, no filler. Just answer.
- **Always honest.** No sugarcoating. If something's wrong, say it.
- **Never assume.** If unsure, ask. Being wrong is worse than asking.
- **Verify everything.** If you changed it, prove it works.
Enter fullscreen mode Exit fullscreen mode

This isn't just flavor. It shapes how it handles ambiguity, how it communicates tradeoffs, whether it asks before acting externally. The personality is the operating system for judgment.

3. USER.md — About You

Your name, timezone, preferences, rules. The things you'd tell a new teammate on day one.

# USER.md

- **Name:** Ray
- **Timezone:** US Eastern (ET)
- **Rules:** Direct communication. No summaries of summaries.
Enter fullscreen mode Exit fullscreen mode

4. The Memory System — Where It Gets Powerful

This is the real unlock. Daily notes + long-term memory:

memory/
  2026-03-25.md  ← yesterday's session log
  2026-03-26.md  ← today's notes
MEMORY.md        ← curated long-term context
Enter fullscreen mode Exit fullscreen mode

At the end of each session (or whenever something important happens), you log it. The agent reads today's and yesterday's notes at the start of every session. MEMORY.md holds the things that matter long-term: decisions made, lessons learned, preferences discovered.

The effect compounds. Session 50 is dramatically more efficient than session 1 because there's 50 sessions of accumulated context. The agent knows your codebase, your preferences, your in-progress decisions — because it wrote them down.

What a Real Production Setup Looks Like

After running this in production for several months on multiple projects, I've added:

5 skills — reusable SKILL.md files that give Claude Code specialized behavior for specific task types:

  • coding-agent — delegate to sub-agents for parallel work
  • model-router — auto-switch models by complexity (this alone cut token costs 40-60%)
  • collaborative-research — two-agent research workflow
  • market-research — browser automation + AI sentiment
  • healthcheck — security auditing

The model router deserves special mention. Not every task needs your most expensive model. A well-designed routing system can cut costs dramatically without sacrificing quality on complex tasks.

The Setup Guide

Setting this up from scratch takes about 2-3 hours if you're figuring it out yourself. There are some non-obvious things:

  • The exact structure for AGENTS.md that Claude Code respects
  • How to write SOUL.md so it actually shapes behavior (not just decorative)
  • The memory file naming convention that works with date-parsing
  • How skills are loaded and when to use them

I packaged our full production setup — the exact files we run — into a starter kit. Everything above, plus the guides, plus the 5 skills, plus a token optimization guide that walks through the model router setup.

It's on Gumroad: Claude Code Starter Kit — Persistent AI Agent Setup ($29, one-time)

Or you can build it yourself from what I described above. Either way, stop re-explaining yourself every morning.

TL;DR

  1. AGENTS.md — boot sequence, tells the agent what to read
  2. SOUL.md — personality that shapes judgment and consistency
  3. USER.md — who you are
  4. Daily notes + MEMORY.md — accumulated context that compounds over time

Four files. Changes the entire experience of building with Claude Code.

Building in public with OpenClaw. Follow for more AI agent patterns.

Top comments (0)