memory-debugging

name	memory-debugging
description	Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: "why is X failing?", "where does this error come from?", "trace this bug", "who calls this method?", "this endpoint returns 500".
metadata	{"version":"0.0.1"}

Debugging with hoangsa-memory

Find the origin of a bug by walking the graph backwards from the symptom. Recall locates the suspect symbol; memory_symbol_context walks its callers until you reach the real cause.

When to Use

• "Why is this function failing?"
• "Trace where this error comes from"
• "Who calls this method?"
• "This endpoint returns 500, what's upstream?"
• Any investigation that starts with a symptom and wants a root cause.

Workflow

1. resources/read hoangsa-memory://memory/LESSONS.md           → known-bug lessons first
2. memory_recall({query: "<error or symptom>"})        → find the suspect
3. memory_symbol_context({fqn: <suspect>})             → callers / callees
4. memory_impact({fqn, direction: "up"})               → full upstream
5. Read the suspect + its callers carefully
6. After the fix: memory_remember_lesson

1. Check LESSONS.md first

A past session may have hit this bug. LESSONS.md entries are keyed on trigger strings — scan for anything matching the symptom. If a lesson says "this exact error comes from X", start there.

resources/read { uri: "hoangsa-memory://memory/LESSONS.md" }

2. Recall the symptom

Feed the error message literally. Retrieval is strongest on exact tokens (function names, error strings, log lines). For example:

memory_recall { query: "connection refused retry pool exhausted" }

Include the error type, a noun from the failing operation, and any concrete identifier (module, handler, queue name).

3. Drill with symbol_context

Once recall returns a candidate FQN:

memory_symbol_context { fqn: "pool::checkout" }

Pay special attention to:

• callers — who invoked the failing path. Bugs often live in the caller's assumptions, not the callee.
• callees — what the suspect delegates to. The actual throw site may be 1–2 hops deeper.
• references — non-call uses. A misconfigured trait impl, a generic bound violation, a type that escapes.

4. Walk upstream when stuck

If context doesn't make the cause obvious, run:

memory_impact { fqn: <suspect>, direction: "up", depth: 3 }

The depth-1 callers are the contexts in which the bug manifests. Often the bug is "caller A passes a value the callee doesn't handle"; seeing all callers at once exposes the outlier.

5. Read the code

Once you have a narrow set of suspect files, use Read with line ranges from the graph results — don't load whole files. The graph already gave you path:line for every hit.

6. Reflect after the fix

When the fix lands and tests pass, if the bug is durable and non-obvious (not a typo), persist a lesson:

memory_remember_lesson {
  trigger: "seeing ETIMEDOUT from the pool on cold start",
  advice: "pool::checkout has a 5s dial timeout; raise it or pre-warm
           via pool::ensure_min in the init path."
}

Keep the trigger as a situation description, not a command. Lessons fire on situation match; imperatives don't match future recalls.

Anti-patterns

• Recalling the fix instead of the symptom. "Fix retry on connection failure" matches the wrong chunks. Search what you see (the error), not what you want (the fix).
• Reading whole files on a guess. The graph gives exact path:line; use it. Reading a 2000-line file to find a 5-line bug burns context.
• Fix-then-forget. If the bug was subtle and the fix was non-obvious, a lesson saves 30 minutes next time. If the bug was a typo, skip.
• Assuming the top recall hit is the bug. Top-ranked ≠ guilty. Read the top 3 chunks; the guilty one is often #2 because the retriever rewarded surface similarity over actual behaviour.

When the symptom isn't indexed

If the error message lives in a dependency (e.g. reqwest: connection refused), recall won't find it — the error text isn't in your code. Recall for the call site instead: "reqwest get client" or the wrapper function's name. The graph will lead you to the caller, which is in your code.