memory-management

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

1. 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.
2. 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.
3. Cite applied rules inline — When a rule influences your work: (applied from memory: ). Place the citation next to the action it influenced, not at the end of unrelated text.
4. User says "recall" / "remember" / "store this" → use Claude Recall — When the user says any of these keywords, ALWAYS use mcp__claude-recall__store_memory. Do NOT write to the native memory directory (~/.claude/projects/*/memory/) for these requests. Claude Recall is the user's preferred memory system.
5. Ask before storing — Before calling store_memory, tell the user what you plan to store and ask for confirmation
6. Capture corrections immediately — User fixes are highest priority (still ask first)
7. 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

1. Corrections - User explicitly fixed a mistake (HIGHEST)
2. DevOps - Git, testing, deploy, architecture patterns
3. Preferences - Code style, tool choices, conventions
4. 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:

• claude-recall skills list — see generated skills
• claude-recall skills generate --force — force regeneration
• claude-recall skills clean --force — remove all auto-generated skills

Automatic Capture Hooks

Claude Recall registers hooks on six Claude Code events for automatic capture, just-in-time rule injection, and outcome tracking — no MCP tool call needed:

Hook	Event	What it does
correction-detector	UserPromptSubmit	Captures user corrections, preferences, and project knowledge from natural language
memory-stop	Stop	Captures 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
session-end-checkpoint	SessionEnd	Auto-saves a {completed, remaining, blockers} task checkpoint when the session ends voluntarily (clear, prompt_input_exit, logout). Spawns a detached worker so it stays within Claude Code's 1.5s SessionEnd timeout. Pi has the equivalent via the session_shutdown event handler.
rule-injector	PreToolUse	Just-in-time rule injection. Before each tool call, searches active rules for matches against tool_name + tool_input and injects the top 3 (excluding raw failures) as a <system-reminder> block adjacent to the action. Closes the rule-loading gap: rules are surfaced at the moment of decision, not 50,000 tokens upstream from where attention has moved on. Each injection is logged to rule_injection_events for outcome correlation. Pi has the equivalent via per-turn injection in the before_agent_start handler.
rule-injection-resolver	PostToolUse / PostToolUseFailure	Resolves recorded rule_injection_events with the tool outcome (success/failure). Together with the injector, this becomes the new "is this rule actually helpful" signal — replacing the broken (applied from memory: ...) citation regex.

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
• Auto-checkpoint quality gate: refuses to save when the LLM detects the task was already complete — manual checkpoints stay sticky
• Always exits 0 — hooks never block Claude

Setup: Run claude-recall setup --install to register hooks in .claude/settings.json. After an upgrade whose release notes mention new or changed hooks (a hooksVersion bump), re-run it in each active project — it's idempotent, so when hooks are already current it's a no-op and touches nothing.

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