How I Made Claude Code Remember Everything

# What Claude actually ran:
go test -short ./handler/admin/...
# in: ~/code/api-gateway/     ← WRONG REPO
# should be: ~/code/auth-service/

~/.claude/
├── settings.json              ← The nervous system (hooks wiring)
│
├── rules/                     ← Tier 1: Behavioral guardrails
│   ├── agent-behavior.md      #   Auto-save protocol, knowledge routing
│   ├── error-recovery.md      #   Reflexion protocol, retry budgets
│   ├── grader-pipeline.md     #   Per-service quality gates
│   └── workflow-discipline.md #   Worktree-first, branch naming
│
├── projects/*/memory/         ← Tier 2: Corrections & project facts
│   ├── MEMORY.md              #   Index file (loaded every session)
│   └── *.md                   #   Individual memory files
│
├── skills/                    ← Tier 3: Reusable procedures
│   ├── SKILL_INDEX.md         #   Trigger-based index
│   └── */SKILL.md             #   15+ skill files
│
├── scripts/                   ← 25 bash scripts (enforcement layer)
│   ├── guard-*.sh             #   5 PreToolUse guards
│   ├── detect-*.sh            #   Correction & change detection
│   ├── post-stop-*.sh         #   Session-end reflection
│   ├── nudge-learn.sh         #   Periodic learning nudge
│   └── pre-compact-*.sh       #   Context compaction recovery
│
└── tools/                     ← Cross-session search
    ├── recall_index.py        #   JSONL → SQLite FTS5 indexer
    └── recall_search.py       #   BM25 search with recency boost

// file: ~/.claude/settings.json (the real one, running in production right now)
{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "python3 ~/.claude/tools/recall_index.py; bash ~/.claude/scripts/detect-external-changes.sh; echo \"Branch: $(git branch --show-current) | Uncommitted: $(git status --short | wc -l) files\""
      }]
    }],
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [
        { "type": "command", "command": "bash ~/.claude/scripts/detect-correction.sh" },
        { "type": "command", "command": "bash ~/.claude/scripts/nudge-learn.sh" }
      ]
    }],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash ~/.claude/scripts/guard-force-push.sh" },
          { "type": "command", "command": "bash ~/.claude/scripts/guard-dangerous-commands.sh" },
          { "type": "command", "command": "bash ~/.claude/scripts/guard-aws-env.sh" },
          { "type": "command", "command": "bash ~/.claude/scripts/guard-commit-master.sh" }
        ]
      },
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "bash ~/.claude/scripts/guard-worktree.sh" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "bash ~/.claude/scripts/guard-worktree.sh" }]
      }
    ],
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{ "type": "command", "command": "bash ~/.claude/scripts/post-edit-gofmt.sh" }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "bash ~/.claude/scripts/post-stop-reflect.sh" }
      ]
    }]
  }
}

#!/bin/bash
# file: ~/.claude/scripts/guard-commit-master.sh
# Guard: block git commit on master/main — must be in a feature branch
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
[[ -z "$COMMAND" ]] && exit 0

if echo "$COMMAND" | grep -qE 'git\s+commit'; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    if [[ "$BRANCH" == "master" || "$BRANCH" == "main" ]]; then
        echo "BLOCKED: Cannot commit on $BRANCH. Use a worktree branch."
        echo "  Use EnterWorktree with a ticket name (e.g., PROJ-1234-description)."
        exit 2
    fi
fi

exit 0

#!/bin/bash
# file: ~/.claude/scripts/guard-worktree.sh
# Guard: block code edits if not in a git worktree
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)

# Allow editing .claude/ config files anywhere
if [[ "$FILE_PATH" == *"/.claude/"* ]]; then
    exit 0
fi

# Allow editing home directory dotfiles (not in a repo)
if [[ "$FILE_PATH" == "$HOME/"* ]] && [[ "$FILE_PATH" != *"/code/"* ]]; then
    exit 0
fi

# Allow if not in a git repo at all
if ! git rev-parse --is-inside-work-tree &>/dev/null 2>&1; then
    exit 0
fi

# Check if in a worktree (git-dir contains /worktrees/ for worktree checkouts)
GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
if [[ "$GIT_DIR" == *"/worktrees/"* ]]; then
    exit 0
fi

echo "BLOCKED: Not in a worktree. Call EnterWorktree before editing source files."
exit 2

#!/bin/bash
# file: ~/.claude/scripts/guard-aws-env.sh
# Blocks profile/table prefix mismatches in DynamoDB commands
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
[[ -z "$COMMAND" ]] && exit 0

# Block inline credentials — force profile usage
if echo "$COMMAND" | grep -qE 'AWS_SECRET_ACCESS_KEY='; then
    echo "BLOCKED: Inline AWS credentials detected. Use AWS_PROFILE instead."
    exit 2
fi

# Catch profile/table prefix mismatch
if echo "$COMMAND" | grep -qE 'dynamodb.*(scan|query|get-item|put-item)'; then
    if echo "$COMMAND" | grep -qE '(PROFILE=stage|--profile stage)' && \
       echo "$COMMAND" | grep -qE '(prod-|prd-)myapp'; then
        echo "BLOCKED: Stage profile but production table name detected."
        echo "  Stage tables use prefix: stg-myapp-"
        exit 2
    fi
    if echo "$COMMAND" | grep -qE '(PROFILE=prod|--profile prod)' && \
       echo "$COMMAND" | grep -q 'stg-myapp'; then
        echo "BLOCKED: Prod profile but staging table name detected."
        echo "  Prod tables use prefix: prd-myapp-"
        exit 2
    fi
fi

exit 0

#!/bin/bash
# file: ~/.claude/scripts/detect-correction.sh
# Runs on every prompt — must be fast (<200ms)
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""' 2>/dev/null)
[ -z "$PROMPT" ] && exit 0

# Correction patterns (Chinese + English)
if echo "$PROMPT" | grep -qiE \
  '不是這|不要這|不要用|不對|錯了|搞錯|你搞|重來|重做|別這樣|wrong|not what I|don.t do that|that.s wrong|stop doing|no[,.].*instead|no[,.].*use'; then

  # Create marker so Stop hook knows corrections happened
  touch ~/.claude/sessions/.correction-detected

  cat << 'JSONEOF'
{"additionalContext": "User correction detected. MANDATORY: After fixing this, save the correction as a feedback memory BEFORE continuing. Include Why and How-to-apply."}
JSONEOF
fi

exit 0

#!/bin/bash
# file: ~/.claude/scripts/nudge-learn.sh
# Hermes-style periodic nudge
COUNTER_FILE="$HOME/.claude/sessions/.prompt-counter"
NUDGE_INTERVAL=15

if [[ -f "$COUNTER_FILE" ]]; then
    COUNT=$(cat "$COUNTER_FILE" 2>/dev/null | tr -d ' \n')
    COUNT=$((COUNT + 1))
else
    COUNT=1
fi
echo "$COUNT" > "$COUNTER_FILE"

if [[ $((COUNT % NUDGE_INTERVAL)) -eq 0 ]]; then
    cat << 'JSONEOF'
{"additionalContext": "LEARNING REVIEW (periodic). Check:\n- Stuck? Run /recall — a past session may have the answer.\n- User corrected you? Save to memory.\n- Complex task solved (5+ tool calls)? Save as skill.\nOnly act if something is genuinely worth saving."}
JSONEOF
fi

exit 0

#!/bin/bash
# file: ~/.claude/scripts/post-stop-reflect.sh (simplified)
INPUT=$(cat)

# Self-gate: only block once per session
GATE_FILE="$HOME/.claude/sessions/.stop-reflected"
if [[ -f "$GATE_FILE" ]]; then
    echo '{"decision": "approve"}'
    exit 0
fi

CORRECTIONS_DETECTED=false
if [[ -f ~/.claude/sessions/.correction-detected ]]; then
    CORRECTIONS_DETECTED=true
    rm -f ~/.claude/sessions/.correction-detected
fi

# Check if session was substantial (>30KB transcript)
SUBSTANTIAL=false
TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
if [[ -n "$TRANSCRIPT" ]] && [[ -f "$TRANSCRIPT" ]]; then
    SIZE=$(wc -c < "$TRANSCRIPT" 2>/dev/null | tr -d ' ')
    [[ "$SIZE" -gt 30000 ]] && SUBSTANTIAL=true
fi

if [[ "$SUBSTANTIAL" == "true" ]] || [[ "$CORRECTIONS_DETECTED" == "true" ]]; then
    touch "$GATE_FILE"  # Only block once
    MSG="MANDATORY SESSION REFLECTION:\n\n"
    if [[ "$CORRECTIONS_DETECTED" == "true" ]]; then
        MSG="${MSG}CORRECTIONS DETECTED — save each as feedback memory NOW.\n\n"
    fi
    MSG="${MSG}1) Reusable patterns? → /learn\n"
    MSG="${MSG}2) Mistakes to prevent? → feedback memory\n"
    MSG="${MSG}3) New user preferences? → user memory\n"

    MSG_ESCAPED=$(echo -e "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')
    echo "{\"decision\": \"block\", \"reason\": \"Save learnings first\", \"systemMessage\": $MSG_ESCAPED}"
else
    echo '{"decision": "approve"}'
fi

<!-- file: ~/.claude/rules/agent-behavior.md -->
---
paths:
  - "src/**"
  - "cmd/**"
  - "internal/**"
  - "handler/**"
  - "service/**"
---

## Auto-Save (MANDATORY — not optional)

Do NOT ask permission. Do NOT skip. Do NOT defer to end of session.

### On User Correction — Save IMMEDIATELY
1. Fix the issue
2. **Immediately** save the correction as feedback
3. Classify: behavioral → rules/, project fact → memory/, procedure → skills/
4. Include **Why** and **How to apply**

### On Error Recovery — Save After Resolving
When you recover from a failure that took 2+ attempts:
1. Save the recovery pattern via /learn

<!-- file: ~/.claude/rules/error-recovery.md -->

## On ANY Failure, STOP and Reflect

1. **Recall**: "Have I seen this before?" → Run /recall with the error
2. **Diagnose**: "Root cause, not symptom."
3. **Plan**: "What specific change will fix this?"
4. **Check**: "Am I retrying the same thing expecting different results?"
5. **Learn**: "Worth capturing via /learn?"

## Retry Budget
- **3 attempts** max at the same approach. Then pivot.
- **2 approaches fail** → Ask the user.
- **Same failure twice** → Auto-save as feedback memory.

<!-- file: memory/blog-quality-feedback.md -->
---
name: blog-quality-feedback
description: Articles must teach, not summarize. Depth non-negotiable.
type: feedback
---

Conrad rejected the first batch of blog articles as low quality.

Specific issues:
- Too short (4-5 min read) — good tech articles are 10-20 min
- Surface-level — reads like a README, not a teaching article
- No actionable takeaways
- Pseudo-code instead of real code

**Why:** Conrad's brand is "backend engineer who teaches through depth."
Shallow articles undermine credibility.

**How to apply:** Every article must pass BLOG_QUALITY.md quality bar.

<!-- file: ~/.claude/skills/deploy-staging/SKILL.md -->
---
name: deploy-staging
description: Trigger staging deployment after Build completes
allowed-tools: Bash(gh *), Bash(aws *)
model: sonnet
---

# Step 1: Wait for Build and Publish
gh run list --workflow "Build and Publish" --branch master --limit 1 \
  --repo my-org/api-gateway \
  --json databaseId,status,conclusion,headSha

# Step 2: Trigger staging deployment
gh workflow run "Deploy to staging" \
  --repo my-org/api-gateway \
  -f environment=stg

# Step 3: Monitor deployment pipeline
aws codepipeline get-pipeline-state \
  --name myapp-staging-pipeline \
  --profile stage --region us-west-2

# file: ~/.claude/tools/recall_index.py
CHUNK_TARGET_CHARS = 3000
CHUNK_OVERLAP_CHARS = 500

def chunk_turns(turns: list[dict], target_chars=CHUNK_TARGET_CHARS):
    """Chunk conversation turns into searchable segments."""
    chunks = []
    current_chunk = []
    current_chars = 0

    for turn in turns:
        text = f"{turn['role'].upper()}: {turn['text']}"

        if current_chars + len(text) > target_chars and current_chunk:
            chunk_text = "\n\n".join(current_chunk)
            chunks.append({
                "content": chunk_text,
                "has_code": bool(re.search(r"```|func |def |class ", chunk_text)),
                "has_error": bool(re.search(
                    r"error|panic|FAIL|nil pointer", chunk_text, re.IGNORECASE
                )),
            })
            # Keep last item as overlap for context continuity
            current_chunk = [current_chunk[-1]] if current_chunk else []
            current_chars = len(current_chunk[0]) if current_chunk else 0

        current_chunk.append(text)
        current_chars += len(text)

    return chunks

# file: ~/.claude/tools/recall_search.py
def recency_boost(session_date_str: str, half_life_days: float = 30.0) -> float:
    """Sessions from 30 days ago get 50% weight. Recent work matters more."""
    session_date = datetime.fromisoformat(session_date_str)
    age_days = (datetime.now() - session_date).total_seconds() / 86400
    return 2 ** (-age_days / half_life_days)

# Combined: score = bm25_score * (0.7 + 0.3 * recency)

#!/bin/bash
# file: ~/.claude/scripts/guard-main.sh
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
[[ -z "$CMD" ]] && exit 0

if echo "$CMD" | grep -qE 'git\s+(commit|push)'; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
        echo "BLOCKED: Use a feature branch, not $BRANCH"
        exit 2
    fi
fi
exit 0

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "bash ~/.claude/scripts/guard-main.sh" }]
    }]
  }
}

<!-- file: ~/.claude/projects/<your-project>/memory/corrections.md -->
---
name: corrections
description: Things Claude got wrong that it should remember
type: feedback
---

## This repo uses pnpm, not npm
**Why:** npm causes lockfile conflicts in our monorepo
**How to apply:** Always use pnpm for install, add, remove commands

## API prefix is /api/v2/, not /api/v1/
**Why:** v1 was deprecated in 2024, still in some old docs
**How to apply:** All new endpoints and test URLs use /api/v2/