| 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.
