Memory Management

Persistent memory system that ensures Claude never repeats mistakes and always applies learned patterns across conversations.

4 Tools

• mcp__claude-recall__load_rules

• Load all active rules before starting work. No query needed.

• mcp__claude-recall__store_memory

• Store a rule or learning. Immediately active in this conversation.

• mcp__claude-recall__search_memory

• Search memories by keyword. Use to find specific memories before making decisions.

• mcp__claude-recall__delete_memory

• Delete a specific memory by ID. Use search_memory first to find the ID.

When to Use

Loading (Recall)

• First action of every session — Call load_rules before ANY tool call, including Read/Glob/Grep. Rules must inform exploration, not just editing.

• After context compression — If context was compressed or conversation is long, call load_rules again. Earlier rules may have been lost.

• Switching task areas — When moving from one domain to another (e.g., tests → database → CI), call search_memory with the new area as query.

• Before modifying a file — Call search_memory with the file path or module name to check for file-specific conventions.

Storing (Capture)

• When user corrects your work - Call store_memory with metadata.type: "correction"

• When user mentions preferences - Call store_memory with metadata.type: "preference"

• After overcoming a challenge - Call store_memory with metadata.type: "failure"

• DevOps/workflow rules - Call store_memory with metadata.type: "devops"

Key Directives

• ALWAYS load rules before acting — Call load_rules as your very first action in a session, before even reading files. Rules inform how you explore, not just how you edit.

• ACT on loaded rules — After loading, state which rules apply to your current task before proceeding. If a rule conflicts with your plan, follow the rule. If none apply, say so. Loading without applying is the same as not loading.

• Cite applied rules inline — When a rule influences your work: (applied from memory: )

• Ask before storing — Before calling store_memory , tell the user what you plan to store and ask for confirmation

• Capture corrections immediately — User fixes are highest priority (still ask first)

• Never store secrets — No API keys, passwords, tokens, or PII

Quick Reference

Load Rules (Before Every Task)

mcp__claude-recall__load_rules({})

Returns all active preferences, corrections, failures, and devops rules in one call. Deterministic and complete.

Store Memory (When Something Important Happens)

mcp__claude-recall__store_memory({ "content": "Description of what to remember", "metadata": { "type": "preference|correction|devops|failure" } })

Returns the stored rule with an activeRule field and _directive to apply it immediately. No need to call load_rules again.

Same-Session Rules

When you call store_memory , the response includes:

• activeRule : The stored content formatted as a rule

• _directive : Instructions to apply the rule immediately

This means rules stored mid-conversation are active right away without reloading.

What Gets Stored

Automatic Capture (You Don't Need to Store)

The system auto-captures when users say:

• "I prefer X" / "Always use X" / "Never do X" -> Preferences

• "We use X for Y" / "Tests go in X" -> Project conventions

• "This is a [type] project" -> Project context

Manual Storage Required

Store these explicitly:

Corrections (highest priority):

User: "No, put tests in tests/ not tests/" -> Store: "CORRECTION: Test files go in tests/ directory, not tests/" metadata: { "type": "correction" }

Complex workflows:

-> Store: "Deploy process: 1) npm test 2) docker build 3) push to ECR 4) kubectl apply" metadata: { "type": "devops" }

Learning cycles (fail -> fix -> success):

-> Store: "REST API failed due to CORS. Solution: Use GraphQL endpoint instead." metadata: { "type": "failure" }

Memory Priority Order

• Corrections - User explicitly fixed a mistake (HIGHEST)

• DevOps - Git, testing, deploy, architecture patterns

• Preferences - Code style, tool choices, conventions

• Failures - Learning cycles and past mistakes

What NOT to Store

Never store:

• API keys, tokens, passwords, secrets

• Personal emails, phone numbers, addresses

• Database connection strings with credentials

• Any sensitive configuration values

Safe to store:

• "We use JWT for auth" (pattern, not credentials)

• "API base URL is https://api.example.com" (non-sensitive)

• "PostgreSQL for production, SQLite for tests" (tool choice)

Skill Crystallization

As memories accumulate, Claude Recall automatically generates skill files in .claude/skills/auto-*/ . These load natively in future sessions — no tool call needed.

How it works: After each store_memory , the system checks if any topic has enough memories to form a skill (3+ for most types, 5+ for preferences). If so, it writes a SKILL.md file that Claude Code loads automatically.

CLI commands:

• npx claude-recall skills list — see generated skills

• npx claude-recall skills generate --force — force regeneration

• npx claude-recall skills clean --force — remove all auto-generated skills

Automatic Capture Hooks

Claude Recall registers hooks on three Claude Code events to capture memories automatically — no MCP tool call needed:

Hook Event What it captures

correction-detector

UserPromptSubmit User corrections, preferences, and project knowledge from natural language

memory-stop

Stop Corrections, preferences, failures, and devops patterns from the last 6 transcript entries

precompact-preserve

PreCompact Broader sweep of up to 50 transcript entries before context compression

Key behaviors:

• LLM-first classification via Claude Haiku — detects natural statements like "we use tabs here" or "tests go in tests/" that regex would miss

• Automatic zero-config: picks up ANTHROPIC_API_KEY from the Claude Code session environment

• Silent regex fallback when API key is unavailable or API call fails

• Batch classification: Stop and PreCompact hooks send all texts in a single API call

• Near-duplicate detection via Jaccard similarity (55% threshold) prevents redundant storage

• Per-event limits: 3 (Stop), 5 (PreCompact) to prevent DB flooding

• Always exits 0 — hooks never block Claude

Setup: Run npx claude-recall setup --install to register hooks in .claude/settings.json .

Example Workflows

Starting a New Task

1. User: "Add user authentication"

2. Load rules first: mcp__claude-recall__load_rules({})

3. Response includes:

   Preferences

   • auth_method: JWT with httpOnly cookies

   Corrections

   • Never use localStorage for auth tokens

4. Implement using JWT + httpOnly cookies (not sessions, not localStorage)

5. User approves -> Done (no need to store, just applied existing knowledge)

User Corrects Your Work

1. You: Created auth with localStorage tokens

2. User: "No, we always use httpOnly cookies for security"

3. Fix the code

4. Ask: "I'd like to remember: always use httpOnly cookies for auth tokens, never localStorage. Store this?"

5. User: "Yes"

6. Store the correction: mcp__claude-recall__store_memory({ "content": "CORRECTION: Always use httpOnly cookies for auth tokens, never localStorage", "metadata": { "type": "correction" } })

7. Response includes activeRule - apply it immediately

Overcoming a Challenge

1. Tried: Redis sessions for auth Failed: "Session sync issues in k8s cluster"

2. User suggested: "Try stateless JWT"

3. Implemented JWT -> Works!

4. Ask: "I'd like to remember: Redis sessions fail in k8s due to sync issues; use stateless JWT instead. Store this?"

5. User: "Yes"

6. Store the learning: mcp__claude-recall__store_memory({ "content": "Auth in k8s: Redis sessions failed (sync issues). JWT stateless tokens work correctly.", "metadata": { "type": "failure", "learning_cycle": true } })

Troubleshooting

Load rules returns nothing:

• This may be a new project with no history yet

• Store rules as you learn them with store_memory

Automatic capture missed something:

• Store it manually with appropriate type

• Future load_rules calls will find it

The Learning Loop: Load rules -> Apply -> Execute -> Capture outcomes -> Better next time