---
name: auto-recall-memory
description: |
  Before solving any non-trivial task, query the memory MCP for similar past
  patterns, lessons, ADRs, and incidents. Surface relevant prior context to
  the active reasoning. Pairs with learning-loop (which writes lessons) to
  form a closed feedback loop: every session benefits from every prior session.

  Use when:
  - Starting any non-trivial task (debug, design, refactor)
  - Encountering an unfamiliar codebase / framework
  - Symptom feels familiar but you can't place it
  - About to make an architectural decision
  - Onboarding to a project (load institutional memory)
---

# Auto-Recall Memory — Stand on Yesterday's Shoulders

The complement to `learning-loop`. Where learning-loop *writes* lessons,
auto-recall-memory *reads* them at the right moment so you don't repeat
mistakes or rebuild what already exists.

## When to Recall (recall triggers)

```
EXPLICIT TRIGGERS (always recall)
- User says: "we tried this before", "déjà vu", "haven't we done X"
- Task verb: debug / migrate / scale / deploy / refactor
- Filename matches past ADR or lesson tag

IMPLICIT TRIGGERS (recall preventively)
- Codebase has files matching <project>/.claude/memory/* or similar
- Stack signature matches a tagged stack (postgres + redis + node)
- Error message has high lexical similarity to past memory entries
- Repo path matches a project tagged in memory

NOT a trigger
- Trivial single-line edits
- Greeting / chit-chat
- Tasks where memory would just add noise
```

## Recall Protocol

```
STEP 1 — DERIVE query terms
  From the active prompt + open files + recent errors, extract:
    - Technology tokens (postgres, react, k8s, terraform, ...)
    - Action tokens (debug, migrate, scale, ...)
    - Error fingerprints (exception class, code, top-of-stack module)
    - Project / repo identifier

STEP 2 — QUERY memory MCP
  Call mcp__memory__search_nodes with the strongest 3-5 query terms.
  Then mcp__memory__open_nodes for the top 3 hits to read full content.

STEP 3 — RANK relevance
  Score each hit:
    + same project: +3
    + same tech stack: +2
    + matching error fingerprint: +2
    + recency (< 90 days): +1
    + severity tagged "high": +1
  Drop hits scoring < 3.

STEP 4 — SURFACE
  Post a compact "📚 RECALL" panel before executing the task:

    📚 RECALL — found <n> relevant prior lessons
       [<slug-1>] <one-line lesson>
                  Last seen: <date>  Tags: <tags>
       [<slug-2>] ...
       (Reply with `recall <slug>` for full detail.)

STEP 5 — APPLY
  Let the recalled context influence the plan:
    - Avoid known dead-ends ("we tried X, didn't work because Y")
    - Reuse known-good patterns
    - Honor project conventions ("our team always uses ... for ...")

STEP 6 — UPDATE on new info
  If the task uncovers that a recalled lesson is stale or wrong,
  hand off to `learning-loop` to mark it superseded.
```

## Recall Output Format

Compact (default):
```
📚 RECALL (3 hits)
  [oauth-aud-claim] Some IdPs return 'aud' as string OR array. Normalize before compare.
  [pg-numeric-precision] Postgres NUMERIC('rounding') quirks at boundary cases.
  [react-stale-closure] useCallback without deps array stalemates state.
```

Detailed (on user request `recall <slug>`):
```
SLUG:   oauth-aud-claim
LESSON: Some OAuth IdPs return 'aud' claim as string OR array; normalize to array on the server before comparison or you'll get inconsistent rejection.
EVIDENCE: <past incident reference>
APPLIES-WHEN: integrating new OAuth provider; debugging unexplained auth rejections
LAST-UPDATED: 2026-03-14
TAGS: auth, oauth, gotcha
```

## Anti-Patterns

- Surfacing every match (signal-to-noise destroys utility)
- Recalling stale lessons (> 12 months for fast-moving tech) without flagging
- Letting recall dominate fresh thinking (recall INFORMS, doesn't dictate)
- Recall on trivial tasks (CLAUDE: this isn't worth the cycles)
- Treating memory as commands ("you must use X") — it's data for judgment
- Recalling without checking the lesson still applies (tech moves on)

## Integration

- Auto-invoked by `intent-classifier` hook when triggers match
- Output feeds `learning-loop` for stale-detection updates
- Pairs with `consensus-voting`: voters get recalled context as input