✓TOKENS USED1,042,000,000
← Back to posts

Claude Memory vs. GitHub: The Two-Layer System Behind Seamless AI Sessions

April 14, 2026

Most people assume their AI agent picks up right where things left off.

It doesn't. Not by default. Not even close.

Every new session starts with zero knowledge of what you built last week, what project you're in the middle of, or how you like to work. The model knows nothing about you except what's in the current conversation window.

I ran into this hard. Started a session, referenced a pipeline I'd spent 20 hours building, and Claude had no idea what I was talking about. Had to re-explain everything. Again.

So I built a system. Two layers. One tells Claude how to show up. The other tells it what we're building. You need both. They're not the same thing.

Layer 1: Claude Memory (How to Work With Me)

Claude Code has a memory system. It lives in your local project folder as a set of markdown files.

Here's what it actually does: it tells Claude how to show up, not what you're working on.

Think of it like onboarding a new person on your team. Before they touch anything, you'd tell them: how you communicate, what decisions they can make on their own, what drives you crazy, what the non-negotiables are. That's memory.

My memory files cover:

  • Who I am (not my resume, my actual identity and what drives me)
  • How I write (what AI tells to never use, specific phrases, format rules)
  • Behavioral rules (never use em dashes, always share GitHub links for artifacts, follow up on background tasks)
  • Project references (where to find context on each thing I'm working on)

What memory does NOT cover: the actual work. Not the code. Not the artifacts. Not where things stand on a specific project. Not what happened in last week's sessions. That's not what it's built for.

If your computer crashed today and you started fresh, memory would tell Claude exactly how to work with you. But it would have no idea what you've been building. That's the gap.

Layer 2: GitHub (What We're Actually Working On)

This is where the work lives.

Every meaningful project I build with Claude gets backed up to GitHub. Not just the code. The context too.

For my ICP Intelligence pipeline (a buyer enrichment system I've built for AppSumo and CXL), GitHub has:

  • All the Python scripts and HTML artifacts
  • A VISION.md explaining what the product is and where it's going
  • A README.md covering the full technical architecture
  • A HANDOFF.md covering exactly where things stand, what was just completed, and what's left

That HANDOFF.md is the key. When a session gets too long and starts slowing down (more on that in a second), I close it, start a new one, and hand Claude those three files. It reads them and we're immediately back in it, no re-explaining, no lost context.

The rule I follow: if you built it, it should be on GitHub. Not just for backup. For continuity.

Why Sessions Break Down

Here's something most people don't talk about.

Claude operates within a context window. There's a limit to how much can fit in active memory at once. The longer a session runs, the more context fills up. Eventually it gets slow. Responses get more generic. You can feel it, like the agent is thinking through molasses.

When that happens, you have two options: push through and get worse outputs, or transfer to a new session. I always transfer.

But if you haven't backed everything up, that transfer is painful. You're starting from zero with a full project mid-flight. You're either re-explaining for 20 minutes or losing the thread entirely.

The backup system means transfer is instant. New session, point it at GitHub, done.

The Setup (How to Actually Do This)

Step 1: Create Your Memory Files

You need two core files. Claude loads these automatically at the start of every session.

File 1: Your Profile (user_profile.md)

This is who you are at a level that actually changes how an AI should work with you. Not job titles. Identity.

The best way I've found to create this is an interview exercise. Have Claude run a structured interview with you, asking questions like:

  • What's one thing most people in your field believe that you think is genuinely wrong?
  • What makes your work different from people who just claim the same things?
  • What kind of work puts you in flow state vs. drains you?
  • What would you never do, even if it would work?
  • What do you want your work to feel like in 3 years?

Run 20-30 questions. Let yourself talk. Then have Claude synthesize the answers into a profile that covers your core traits, how you think, what matters to you, and how to work with you effectively.

Use this prompt to start:

I want to build a profile document that helps you understand who I am and 
how to work with me, at a level deeper than just my job title.

Interview me with 20-30 questions across these areas:
- What I believe about my field that most people get wrong
- What drives me, what drains me
- What kind of work feels aligned vs. like a cage
- How I communicate and what I can't stand
- What I'm building and what success actually looks like for me

One question at a time. Let me answer fully before moving to the next.
At the end, synthesize everything into a structured profile markdown file
I can save to my memory folder.

File 2: Your Voice Profile (feedback_writing_voice.md)

Separate from who you are is how you write. This matters more than most people realize. Without it, every piece of content Claude writes for you sounds like a press release.

Same exercise. Interview focused specifically on:

  • What AI tells do you spot immediately?
  • What words and phrases sound like yours vs. generic?
  • Who do you want to write more like and why?
  • How do you handle punctuation, structure, length?
  • What is a hard no, always?

For reference, my hard rules: no em dashes, no hashtags, no "here's the thing," no fake contrarian structure, no bold for emphasis in body copy, write like I talk.

The interview pulls out the rules you have but haven't articulated yet. You'll be surprised what comes up.

Step 2: Set Up the Reference System

For each project you're actively working on, create a reference file in your memory folder that points to GitHub.

Mine looks like this:

reference_icp_pipeline.md:
- Read VISION.md for product context
- Read README.md for technical architecture  
- Read HANDOFF.md for current sprint state
- Links to all three raw GitHub URLs

Now any session working on ICP starts by pulling those files. The memory entry is the pointer. GitHub is the content.

Step 3: Back Up to GitHub Consistently

The moment something meaningful gets built, it goes to GitHub. Not at the end of the week. Not when it feels done. Right now.

I've lost work to context compaction, computer issues, and just forgetting what was in a session that got too long. The only thing that prevents this is treating GitHub as the live source of truth, not a backup destination.

My pattern:

  • Daily: push all modified files. One commit, brief message. Takes two minutes.
  • End of any major work block: commit with a proper message so future-me knows what happened
  • When a session starts slowing down: full push before closing. That's the handoff.
  • When starting something new: check git status first. Make sure you're clean before diving in.

Also: don't just commit the scripts. Commit the docs. Commit the handoff notes. Commit the vision. The code is the least important thing for continuity. The context around the code is what makes the next session work.

Step 4: Write a HANDOFF.md Before You Close Long Sessions

This is the most underrated part.

Before closing a session that's been running a while, have Claude write a HANDOFF.md. It should cover:

  • What was just completed
  • What's in progress
  • Known bugs or issues
  • Where the relevant files are
  • The 5-10 next steps in priority order
  • Any decisions that were made and why

Push it to GitHub. When you start the next session, hand Claude three files: VISION.md, README.md, HANDOFF.md. That's it. You're back up to speed immediately.

What This Actually Looks Like in Practice

New Claude Code session. I type:

"Read VISION.md, README.md, and HANDOFF.md from the ICP repo on GitHub. Then let's pick up where we left off."

Claude reads all three. Knows what the product is, how the technical system works, where we left off, and what the next move is. Knows my voice so it writes in my style. Knows my preferences so it doesn't do things that waste time.

No re-explaining. No context re-building. Just work.

The session doesn't feel like starting over. It feels like resuming.

The Two Things to Get Right

Most people either set up memory and ignore GitHub, or back up to GitHub and never build real memory files. Neither works on its own.

Memory without GitHub: Claude knows how to work with you but has no idea what you're building. Every session on a project feels like onboarding from scratch.

GitHub without memory: Claude has access to everything you've built but treats you like a stranger. Gets your voice wrong, makes decisions you'd never make, misses the preferences you've built up over months.

Together: every session starts with full context on both sides. How to work with you and what you're working on.

That combination is what makes the difference between AI that feels like a tool and AI that feels like a real working relationship.

Quick Setup Checklist

  • [ ] Run the profile interview (20-30 questions, then synthesize into user_profile.md)
  • [ ] Run the voice interview (writing style, hard rules, influences into feedback_writing_voice.md)
  • [ ] Save both files to your Claude memory folder (~/.claude/projects/[your-project]/memory/)
  • [ ] Create a MEMORY.md index file that lists all memory files and what they contain
  • [ ] For each active project: create a reference memory file pointing to GitHub docs
  • [ ] Push everything to a private GitHub repo
  • [ ] Write a HANDOFF.md before any long session closes
  • [ ] Commit and push before starting a new session

One-time setup. Permanent payoff.