memory-management

name	memory-management
description	Persistent memory for Claude across conversations. Use when starting any task, before writing or editing code, before making decisions, when user mentions preferences or conventions, when user corrects your work, or when completing a task that overcame challenges. Ensures Claude never repeats mistakes and always applies learned patterns.
version	2.0.0
license	MIT

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