THE COMPLETE GUIDE

Give Your AI Long-Term Memory

Claude Code Feb 2026 Memory Architecture

AI assistants forget everything between sessions. You explain your project, your preferences, your tech stack—and next session, it's all gone. This guide shows you how to build a two-layer memory system that gives Claude Code persistent context across every conversation.

The Problem: AI Amnesia

Every time you start a new Claude Code session, you're talking to a blank slate. It doesn't know your project structure, your coding preferences, or what you worked on yesterday.

🔄

Repetitive Onboarding

"I'm using SvelteKit with Supabase and Tailwind..." Every. Single. Session. You waste time re-explaining context that should already be known.

📁

Scattered Context

Session logs in one folder, learnings in another, project state somewhere else. Claude reads some files, misses others. Important context falls through the cracks.

🧠

Lost Learnings

You correct Claude's approach, it learns... then forgets next session. The same mistakes repeat. The same corrections are needed.

Project Drift

"Where did we leave off?" Claude doesn't know. You don't remember either. Projects stall because continuity breaks between sessions.

THE CORE INSIGHT

Claude Code has a context window—it can read files at the start of each session. The problem isn't that Claude can't remember. It's that we don't give it the right information in the right format.

The solution: Structure your context into a predictable system that Claude reads automatically, every session, without you thinking about it.

Two-Layer Memory Architecture

Human memory has two layers: working memory (what you're actively thinking about) and long-term memory (everything you've learned). AI needs the same structure.

LAYER 1

Working Memory

CLAUDE.md

Single consolidated file loaded automatically every session

  • Who you are and your preferences
  • All active projects with current state
  • Tech stack and coding patterns
  • Accumulated learnings and corrections
  • What happened in recent sessions
~20KB Immediate context
complements
LAYER 2

Long-Term Memory

Vector Search (ChromaDB)

Semantic search across all historical sessions

  • Full session transcripts indexed as embeddings
  • Search by meaning, not just keywords
  • "Find when we discussed X" → instant retrieval
  • Months of context, searchable in milliseconds
80+ sessions Searchable archive

How They Work Together

1
Session starts

Claude automatically reads CLAUDE.md—instant context about you and all projects

2
During session

If needed, Claude searches long-term memory: "When did we set up Stripe?" → vector search retrieves that session

3
Session ends

/close skill updates CLAUDE.md with learnings and project state, archives session to vector store

Working Memory: CLAUDE.md

CLAUDE.md is a single file that contains everything Claude needs to know at the start of every session. No scattered files. No complex folder structures. One file, always loaded.

Why One Big File?

We tried the "organized folders" approach: session logs in /sessions/, learnings in /memory/, project state in /by-topic/. It failed. Claude would read some files, miss others. Critical context got lost.

A single consolidated file solves this. Claude Code automatically loads CLAUDE.md from your project root. Everything is in one place, every time.

Structure

Organize CLAUDE.md into logical sections. Here's a proven structure:

1
User Context

Who you are, timezone, communication preferences

2-6
Active Projects

Each project gets a section: description, current state, next steps, key files

7
Business Model & Revenue

Pricing, target audience, monetization strategy

8
Tech Stack & Patterns

Languages, frameworks, deployment, coding conventions

9
Session Learnings

Preferences discovered, patterns that work, things to avoid

10-11
Quick Reference

File paths, API endpoints, external resources

12
Current Project State

Detailed state of active work, open threads, recent session log

Section 12 is the handoff mechanism. It gets updated at the end of every session with what was accomplished, what's in progress, and what's next. This is how continuity happens—Claude reads Section 12 and knows exactly where you left off.
FILE SIZE

Our CLAUDE.md is ~20KB (477 lines). Claude handles this easily. The context window is massive—a 20KB file is nothing compared to reading 10 scattered files.

20KB / 200K context
LEARNINGS SECTION EXAMPLE
## 9. Session Learnings

### Preferences Discovered
- Stay on Opus for main conversation,
  Haiku for delegated tasks (2026-01-26)
- Blog style: problem-first, code after
  concepts (2026-01-12)

### Patterns That Work
- SVG animation: stroke-dashoffset for
  draw-in effect (2026-02-01)
- Two-stage LLM insight: metrics first,
  then domain expertise (2026-01-31)

### Avoid
- Don't suggest Airtable when user
  already uses Supabase (2026-01-31)
- Logo design: Don't just put checkmarks
  in shapes—think conceptually (2026-02-01)
SECTION 12: PROJECT STATE
## 12. Current Project State

**Last active:** verified.my (2026-02-01)

### verified.my — Logo exploration

**Current state:**
- 10 logo concepts at /demo
- Navbar using text-only placeholder
- Stripe OAuth flow implemented

**Open threads:**
- [ ] Pick logo concept (1-10)
- [ ] Test Stripe Connect flow
- [ ] Register domain

**Recent Sessions:**
- **2026-02-01:** Logo exploration
- **2026-01-31:** Stripe integration

Long-Term Memory: Vector Search

Working memory handles the current state. But what about that session from three weeks ago where you solved a tricky deployment issue? That's where vector search comes in.

How It Works

Vector search converts text into mathematical representations (embeddings) that capture meaning. When you search "Stripe webhook setup", it finds sessions that discuss Stripe webhooks—even if they use different words like "payment callbacks" or "event handling".

📝
Session ends

Session log saved to /sessions/

🔢
Indexing

Text converted to embeddings

💾
Stored

Added to ChromaDB

🔍
Query

Semantic search retrieves relevant sessions

The Stack

  • ChromaDB: Local vector database. No cloud dependency, no API costs. Runs on your machine.
  • Sentence Transformers: Converts text to embeddings locally using all-MiniLM-L6-v2. Fast and accurate.
  • Python scripts: reindex.py to rebuild the database, search.py to query it.

When To Use It

Long-term memory is for retrieval, not constant loading. You don't read 80 sessions every time. You search when you need specific historical context:

"When did we set up the payment flow?" → Returns session from 2026-01-15
"How did we solve the auth bug?" → Returns session with the fix
"What decisions did we make about pricing?" → Returns multiple relevant sessions
WHY VECTOR SEARCH?

Keyword search fails when you don't remember exact words. "That thing with the dashboard" finds nothing.

Vector search understands meaning. "Dashboard performance issue" finds sessions about "admin panel slow loading" because the concepts are similar.

SEARCHING MEMORY
# From command line
$ memory-search "stripe webhook"

# Results:
1. [0.89] 2026-01-15-103000.md
   "Set up Stripe webhook endpoint..."

2. [0.82] 2026-01-20-142000.md
   "Debugging payment callbacks..."

3. [0.74] 2026-01-28-091500.md
   "Added retry logic for events..."
REINDEXING
# Rebuild the vector database
$ python reindex.py

Scanning /sessions...
Found 80 session files
Processing embeddings...
Indexed 80 documents

Database ready at:
~/.claude/chroma_db/
Sessions indexed 80+
Search latency <100ms
Storage ~50MB

Session Management: The /close Skill

Memory only works if you keep it updated. The /close skill automates this—capturing learnings, updating project state, and committing changes at the end of every session.

What /close Does

1

Capture Learnings

Scans the session for learning moments: corrections you made, preferences you stated, patterns that worked. Adds them to Section 9 of CLAUDE.md with dates.

2

Update Project State

Replaces Section 12 with current state: what's built, what's working, open threads, key decisions, files to know. This is the handoff for next session.

3

Archive Session

Creates a session log at /sessions/YYYY-MM-DD-HHMMSS.md with TL;DR, accomplishments, and files modified. Gets indexed into vector search.

4

Commit & Push

Stages CLAUDE.md and session file, commits with descriptive message, pushes to remote. Your memory is version-controlled and backed up.

Auto-Triggers

The /close skill runs automatically when you say:

"bye" "goodbye" "thanks" "done" "that's all" "gotta go" "goodnight"

Or invoke manually with /close

EXAMPLE /close OUTPUT
Session closed & pushed.

Learnings captured:
- Logo exploration: think conceptually, not just shape variations (2026-02-01)

Project state updated: verified.my

Committed: session: 2026-02-01 logo exploration
  - Created 10 conceptual logo designs
  - Simplified navbar to text-only
  - Updated project state: verified.my

Open threads:
- Pick logo concept (1-10) and finalize
- Test Stripe Connect flow with real credentials
- Register verified.my domain

See you next time! 👋

Setup Guide

STEP 1

Create CLAUDE.md

Create CLAUDE.md in your project root with the sections structure shown above.

MINIMAL CLAUDE.MD
# Project Name

## 1. Context
Brief description of you and this project.

## 2. Tech Stack
- Language/Framework
- Database
- Deployment

## 3. Current State
What's built, what's in progress.

## 4. Learnings
### Patterns That Work
- (none yet)

### Avoid
- (none yet)

## 5. Session Log

**YYYY-MM-DD:** What happened
STEP 2

Create /close Skill

Create the skill file at .claude/skills/close/SKILL.md:

.claude/skills/close/SKILL.md
---
name: close
description: Session closer. Updates CLAUDE.md and commits.
---

# Session Close

**AUTO-TRIGGER** on: bye, thanks, done, goodnight, etc.

## Steps

1. **Capture Learnings** — Scan session for corrections,
   preferences, patterns. Add to Section 9 with date.

2. **Update Section 12** — Replace with current project state:
   - What's built/working
   - Open threads with checkboxes
   - Key decisions made
   - Recent session summary

3. **Archive** — Save to /sessions/YYYY-MM-DD-HHMMSS.md

4. **Commit & Push**
   ```
   git add CLAUDE.md sessions/
   git commit -m "session: [date] [summary]"
   git push
   ```

5. **Confirm** — Output summary of learnings and open threads
STEP 3

Set Up Vector Search (Optional)

For long-term memory, set up the vector search system:

INSTALL DEPENDENCIES
# Create virtual environment
python -m venv ~/.claude/venv
source ~/.claude/venv/bin/activate

# Install packages
pip install chromadb sentence-transformers
reindex.py
import chromadb
from sentence_transformers import SentenceTransformer
from pathlib import Path

# Initialize
model = SentenceTransformer('all-MiniLM-L6-v2')
client = chromadb.PersistentClient(path=str(Path.home() / '.claude/chroma_db'))
collection = client.get_or_create_collection('sessions')

# Index sessions
sessions_dir = Path.home() / '.claude/compacted-summaries'
for file in sessions_dir.glob('*.md'):
    content = file.read_text()
    embedding = model.encode(content).tolist()
    collection.upsert(
        ids=[file.name],
        documents=[content],
        embeddings=[embedding]
    )
    print(f"Indexed: {file.name}")

print(f"Total: {collection.count()} documents")
search.py
import sys
import chromadb
from sentence_transformers import SentenceTransformer
from pathlib import Path

query = ' '.join(sys.argv[1:])
model = SentenceTransformer('all-MiniLM-L6-v2')
client = chromadb.PersistentClient(path=str(Path.home() / '.claude/chroma_db'))
collection = client.get_collection('sessions')

# Search
results = collection.query(
    query_embeddings=[model.encode(query).tolist()],
    n_results=5
)

# Display
for i, (doc, dist) in enumerate(zip(results['documents'][0], results['distances'][0])):
    score = 1 - dist  # Convert distance to similarity
    print(f"\n[{score:.2f}] {results['ids'][0][i]}")
    print(doc[:200] + "...")
SYMLINK SESSIONS FOLDER
# Point vector search to your sessions
ln -s /path/to/project/sessions ~/.claude/compacted-summaries

# Create search alias
echo 'alias memory-search="python ~/.claude/search.py"' >> ~/.zshrc

Troubleshooting

Vector search returns 0 results

Cause: Symlink pointing to wrong path, or sessions not indexed.
Fix:
  1. Check symlink: ls -la ~/.claude/compacted-summaries
  2. Verify it points to actual sessions folder
  3. If broken: rm ~/.claude/compacted-summaries && ln -s /correct/path ~/.claude/compacted-summaries
  4. Reindex: python reindex.py

Claude doesn't read CLAUDE.md

Cause: File not in project root, or wrong filename.
Fix:
  1. Ensure file is named exactly CLAUDE.md (case-sensitive)
  2. Place in project root (same level as package.json, .git)
  3. Check that Claude Code is opened in that directory

Learnings not being captured

Cause: /close skill not triggering, or Section 9 format wrong.
Fix:
  1. Explicitly run /close to test
  2. Ensure Section 9 has the expected format with headers
  3. Check skill file exists at .claude/skills/close/SKILL.md

Context getting lost mid-session

Cause: Long session hitting context limits.
Fix:
  1. Watch for "context getting full" warnings
  2. Save state mid-session: update Section 12 manually
  3. Consider splitting into shorter sessions
  4. Use agents for heavy searches to avoid context bloat

Git push failing in /close

Cause: No remote configured, or auth issues.
Fix:
  1. Check remote exists: git remote -v
  2. Ensure SSH keys or tokens are configured
  3. Test manually: git push
  4. If no remote needed, remove push from /close skill

Duplicate entries in learnings

Cause: /close adding same learning multiple times.
Fix:
  1. Skill should check before adding: "No duplicates"
  2. Add this rule to SKILL.md: "Check if learning already exists before adding"
  3. Manually remove duplicates and they won't recur

How This Differs From OpenClaw

OpenClaw is the viral AI assistant that took GitHub by storm—60,000+ stars in 72 hours. It's an incredible project, but it solves a different problem than this memory system.

THIS GUIDE

Two-Layer Memory

Purpose: Long-term memory for development sessions

  • Vector search across months of session history
  • Hybrid BM25 + semantic retrieval
  • "What did we decide about X?" → instant answer
  • Auto-triggers when you mention projects
  • Designed for Claude Code workflows
FOCUS Remembering past work
OPENCLAW

Multi-Channel Assistant

Purpose: Personal AI assistant across messaging platforms

  • WhatsApp, Telegram, Slack, Discord, iMessage
  • Voice wake, canvas, browser automation
  • Session context within conversations
  • Skills and tools ecosystem
  • Runs as an always-on daemon
FOCUS Talk to AI anywhere

The Key Difference

OpenClaw has /compact (summarize current session) and session pruning, but no persistent memory across sessions. When you /reset, context is gone. There's no vector database, no cross-session search, no "remember when we built X."

This memory system fills that gap. It's specifically designed for developers who use Claude Code and want their AI to remember project history, decisions, and learnings across every session.

+

You Can Use Both

They're complementary, not competing. Use OpenClaw for "talk to AI from WhatsApp." Use this memory system for "remember what we built last month." The two don't conflict—they solve different problems.

FeatureThis Memory SystemOpenClaw
Vector searchYes (ChromaDB)No
Cross-session memoryYesNo
Multi-channel (WhatsApp, etc.)NoYes
Voice wake / CanvasNoYes
Always-on daemonNoYes
Session notes (markdown)YesNo
Auto-retrieval triggersYesNo
Works with Claude CodeNativeVia CLI

Frequently Asked Questions