Give Your AI Long-Term Memory
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.
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.
Working Memory
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
Long-Term Memory
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
How They Work Together
Claude automatically reads CLAUDE.md—instant context about you and all projects
If needed, Claude searches long-term memory: "When did we set up Stripe?" → vector search retrieves that session
/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:
Who you are, timezone, communication preferences
Each project gets a section: description, current state, next steps, key files
Pricing, target audience, monetization strategy
Languages, frameworks, deployment, coding conventions
Preferences discovered, patterns that work, things to avoid
File paths, API endpoints, external resources
Detailed state of active work, open threads, recent session log
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.
## 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)## 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 integrationLong-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 log saved to /sessions/
Text converted to embeddings
Added to ChromaDB
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.pyto rebuild the database,search.pyto 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:
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.
# 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..."# Rebuild the vector database
$ python reindex.py
Scanning /sessions...
Found 80 session files
Processing embeddings...
Indexed 80 documents
Database ready at:
~/.claude/chroma_db/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
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.
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.
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.
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:
Or invoke manually with /close
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
Create CLAUDE.md
Create CLAUDE.md in your project root with the sections structure shown above.
# 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 happenedCreate /close Skill
Create the skill file at .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 threadsSet Up Vector Search (Optional)
For long-term memory, set up the vector search system:
# Create virtual environment
python -m venv ~/.claude/venv
source ~/.claude/venv/bin/activate
# Install packages
pip install chromadb sentence-transformersimport 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")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] + "...")# 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"' >> ~/.zshrcTroubleshooting
Vector search returns 0 results
- Check symlink:
ls -la ~/.claude/compacted-summaries - Verify it points to actual sessions folder
- If broken:
rm ~/.claude/compacted-summaries && ln -s /correct/path ~/.claude/compacted-summaries - Reindex:
python reindex.py
Claude doesn't read CLAUDE.md
- Ensure file is named exactly
CLAUDE.md(case-sensitive) - Place in project root (same level as package.json, .git)
- Check that Claude Code is opened in that directory
Learnings not being captured
- Explicitly run
/closeto test - Ensure Section 9 has the expected format with headers
- Check skill file exists at
.claude/skills/close/SKILL.md
Context getting lost mid-session
- Watch for "context getting full" warnings
- Save state mid-session: update Section 12 manually
- Consider splitting into shorter sessions
- Use agents for heavy searches to avoid context bloat
Git push failing in /close
- Check remote exists:
git remote -v - Ensure SSH keys or tokens are configured
- Test manually:
git push - If no remote needed, remove push from /close skill
Duplicate entries in learnings
- Skill should check before adding: "No duplicates"
- Add this rule to SKILL.md: "Check if learning already exists before adding"
- 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.
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
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
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.
| Feature | This Memory System | OpenClaw |
|---|---|---|
| Vector search | Yes (ChromaDB) | No |
| Cross-session memory | Yes | No |
| Multi-channel (WhatsApp, etc.) | No | Yes |
| Voice wake / Canvas | No | Yes |
| Always-on daemon | No | Yes |
| Session notes (markdown) | Yes | No |
| Auto-retrieval triggers | Yes | No |
| Works with Claude Code | Native | Via CLI |