Debugging Workflow

Debugging is where persistent memory pays off most visibly. Without it, every debugging session starts from scratch — you describe the symptoms to your AI, it proposes the usual suspects, you rule them out one by one, you eventually find the root cause. Next time similar symptoms appear: repeat from the beginning.

With persistent memory, your AI walks in knowing what you've already ruled out, what the root causes have been before, and what patterns have appeared across past incidents. The investigation starts where the last one left off.

The basic pattern

# Search for similar symptoms
mx memories search --query "describe what you're seeing" --timeline

# Look for past root causes in this component
mx memories search --query "component-name error" --brief

# Get synthesized context on this area
mx memories digest --query "component-name" --digest-format structured

# Find any tagged gotchas
mx memories search --query "component-name" --topics "gotcha" --brief

# What you've ruled out
mx memories create \
  --conversation-id "conv_your_incident" \
  --content "Investigating auth latency spike. Ruled out: Redis (normal load), network (no packet loss), cert renewal (wasn't due). Auth service logs show token validation slow but no errors. Suspicion: recent key rotation?" \
  --topics "in-progress"

mx memories create \
  --conversation-id "conv_your_incident" \
  --content "Root cause: JWT signing key was rotated at 14:30 UTC. Old tokens hitting fallback verification path that's O(n) per claim instead of O(1). Fix: added the previous key to the verification key set with a 24-hour TTL (commit a3c7e1f, PR #412). Symptoms: auth latency >500ms for any request with a token issued before 14:30. Future warning: any key rotation will cause this — need to add the outgoing key to the verification set before removing it." \
  --topics "completed,gotcha"

Recognizing patterns across incidents

The real power comes when similar issues keep appearing. Your AI can synthesize across all past incidents and tell you what the pattern is.

Say your CI keeps failing with lockfile issues in various forms. You've hit it five times in different contexts. Before you investigate the sixth:

mx memories search --query "lockfile CI failure package manager" --timeline

If those incidents were captured when they happened, this returns a chronological picture of every lockfile failure, what caused each one, how each was fixed, and whether there's a common root cause.

Your AI reads across those results and can tell you: "Based on four previous incidents, this is almost always npm/pnpm cross-contamination in the monorepo. The consistent fix is running npm install in an isolated directory rather than inside the monorepo tree."

That synthesis only works if the individual incidents were saved. Each one needs enough detail — symptoms, root cause, fix — for future pattern-matching to work.

What to save after finding a root cause

The best root-cause memories include all of this:

• The symptoms — what was observable before you knew the cause
• What you ruled out — saves future investigations from re-investigating dead ends
• The actual root cause — specific, not vague
• The fix — including commit hashes and PR references
• Future warning signs — what to look for if this class of problem appears again
• Related issues — if this matches a previous incident, link it

mx memories create \
  --conversation-id "NEW" \
  --content "Bug: payments webhook handler failing intermittently in production (issue #523).
Symptoms: 'signature mismatch' errors, ~2% of webhooks. No pattern in timing or amount.
Ruled out: clock skew (NTP in sync), network issues (no latency), Stripe API changes (changelog shows none).
Root cause: load balancer was stripping the 'Stripe-Signature' header when it contained certain characters. Our nginx config had 'proxy_set_header' that only forwarded whitelisted headers, and Stripe-Signature wasn't on the list.
Fix: added Stripe-Signature to the proxy_set_header whitelist. Commit 9e4c02a, PR #527.
Warning sign: any future intermittent signature mismatch errors should check load balancer header forwarding first — this is easy to miss because it looks like an auth problem." \
  --topics "gotcha,payments,completed"

The two-session pattern

For complex bugs, it's common to investigate, get stuck, and come back later. Memory makes this seamless.

End of first session:

mx memories create \
  --conversation-id "conv_investigation" \
  --content "Pausing investigation of race condition in session creation. Ruled out: DB constraint violations (logs clean), connection pool exhaustion (max 20, saw 12 active), network timeouts.
  Current hypothesis: two concurrent requests for the same user can both pass the 'session exists?' check before either creates the session. Need to reproduce with concurrent load test. Next step: write a test that fires 10 concurrent session creation requests for the same user ID and confirm we see duplicates." \
  --topics "in-progress"

Start of second session:

mx memories recap --recent 24h

Your AI walks in knowing exactly where you were. You don't re-explain. You don't re-rule-out what you already ruled out. The session picks up exactly at the hypothesis you left off with.

Debugging someone else's code

When you need to debug a component you didn't build:

# Get the history and context for this component
mx memories digest --query "component-name" --digest-format structured

# Find any previously diagnosed bugs
mx memories search --query "component-name bug" --timeline

# Find architectural decisions that might explain the behavior
mx memories search --query "component-name design decision" --brief

This gives you the context an experienced team member would have — the architectural reasoning, the known sharp edges, the previous bugs — without the weeks of exposure it would otherwise take to acquire.

Integration with Claude Code

If you use Claude Code, you can build the search step into the start of every debugging session. In your CLAUDE.md:

## When starting a debugging session

Before investigating any bug:
1. Run `mx memories search --query "[describe the symptoms]" --timeline`
2. Run `mx memories search --query "[component name] gotcha" --brief`
3. Share the results as context before proposing any investigation steps

Now every debugging session starts with your relevant history already loaded.

Next steps

• Session start ritual — Loading context at the start of any session
• Capturing memories that actually help — How to write root-cause memories that stay useful
• Team workflows — How teams pool knowledge during incidents