Memory Search Toolkit

Overview

A skill that enables Claude Code to search, recall, and leverage past conversation context, project decisions, and coding patterns across sessions. Builds persistent memory of your project — including architectural decisions, debugging solutions, user preferences, and code patterns — so Claude doesn't lose context between conversations.

When to Use

• Starting a new session on an ongoing project
• Recalling past decisions ("Why did we choose PostgreSQL over MongoDB?")
• Finding previous debugging solutions
• Maintaining consistency across sessions
• Avoiding repeating work that was already done
• Understanding the history of a codebase feature

Quick Start

Copy
# Search for past context
claude "What did we decide about the authentication approach?"

# Recall debugging history
claude "How did we fix the rate limiting issue last time?"

# Find previous implementations
claude "Have we implemented pagination before? Show me the pattern we used"

Core Principle

Receive instruction → Search memory for context → Then proceed

Always check memory before starting work. Past decisions, patterns, and solutions accelerate current work.

Memory Types

1. Project Decisions

Architectural and design choices with rationale:

Copy
## Decision: Use JWT with refresh tokens
- Date: 2024-01-15
- Context: Needed stateless auth for microservices
- Alternatives considered: Session-based, OAuth2 only
- Rationale: Stateless reduces DB load, refresh tokens add security
- Trade-offs: Slightly more complex client logic

2. Coding Patterns

Established patterns in the codebase:

Copy
## Pattern: Service Layer Error Handling
- All service methods throw CustomError with status code
- Controllers catch and format to JSON response
- Never expose stack traces to clients
- Log full error details server-side

3. Debugging Solutions

Previously solved issues:

Copy
## Bug: Connection pool exhaustion
- Symptoms: Random 500 errors under load
- Root cause: Missing connection.release() in error paths
- Fix: Wrapped all queries in try/finally with release
- Prevention: Added connection pool monitoring

4. User Preferences

Personal and team conventions:

Copy
## Preferences
- Always use single quotes in TypeScript
- Prefer functional components with hooks
- Use Tailwind CSS, not CSS modules
- Write tests with React Testing Library, not Enzyme
- Commit messages follow Conventional Commits

Memory Storage

CLAUDE.md (Project-Level)

The primary memory file, loaded automatically every session:

Copy
# Project Memory

## Architecture
- Next.js 14 + App Router
- PostgreSQL with Prisma ORM
- Redis for caching and sessions
- Deployed on AWS ECS

## Conventions
- API routes in src/app/api/
- Shared types in src/types/
- Utilities in src/lib/
- Components follow atomic design

## Key Decisions
- Chose Prisma over Drizzle (better migration support)
- Using Server Components by default (client only when needed)
- Rate limiting via Redis sliding window

Memory Directory (Topic Files)

For detailed notes, create topic-specific files:

.claude/memory/
├── MEMORY.md          # Index file (auto-loaded)
├── architecture.md    # Architecture decisions
├── debugging.md       # Past debugging solutions
├── patterns.md        # Coding patterns
├── api-design.md      # API conventions
└── performance.md     # Performance findings

Auto-Memory

Claude Code can automatically save important patterns:

Copy
# What to save automatically:
- Confirmed patterns across multiple interactions
- Architecture decisions with rationale
- User preferences for tools and style
- Solutions to recurring problems
- Important file paths and project structure

# What NOT to save:
- Session-specific temporary context
- Incomplete or speculative information
- Anything that contradicts existing docs

Search Strategies

By Topic

Copy
# Search for authentication-related memories
claude "Search memory for authentication decisions"

# Search for performance patterns
claude "What performance optimizations have we applied?"

By Time

Copy
# Find recent decisions
claude "What architectural decisions were made this week?"

# Find historical context
claude "What was the original database design?"

By Problem Type

Copy
# Find similar bugs
claude "Have we seen connection timeout errors before?"

# Find similar features
claude "Have we built a file upload feature? What approach did we use?"

Memory Lifecycle

Creating Memories

Save important context when:

• A significant decision is made
• A tricky bug is solved
• A new pattern is established
• User expresses a preference
• An architectural boundary is defined

Updating Memories

Modify when:

• A decision is reversed or evolved
• A better solution is found
• A pattern is refined
• Technology is upgraded

Retiring Memories

Remove when:

• A feature is fully deprecated
• A technology is no longer used
• Information is factually wrong
• Notes are superseded by better documentation

Context Continuity

Session Handoff

When starting a new session, Claude should:

1. Read CLAUDE.md — Load project context and conventions
2. Check recent memory — What was the last session working on?
3. Scan git log — What changed since the last interaction?
4. Review open issues — What needs attention?

Cross-Session Consistency

Copy
## Consistency Rules
- Always follow established patterns (check memory first)
- Reference past decisions when making new ones
- Update memory when patterns evolve
- Flag when a new approach contradicts a past decision

Best Practices

1. Write memories immediately — Don't wait until the end of a session
2. Be specific — "Use bcrypt with 12 rounds" not "hash passwords"
3. Include rationale — Future-you needs to know why, not just what
4. Keep memory concise — Summaries, not full transcripts
5. Organize by topic — Separate files for architecture, debugging, patterns
6. Update, don't duplicate — Modify existing entries rather than creating new ones
7. Link to code — Reference file paths and line numbers
8. Review periodically — Remove stale or incorrect memories
9. Distinguish facts from opinions — Mark preferences vs requirements
10. Use memory as documentation — If it's worth remembering, it's worth documenting