feat: pre-tool-call recall (trigger / preToolHook)

[sgonz-xtrace]

Summary

Adds a client for the new POST /v1/memories/trigger endpoint, which recalls the lesson / procedure insights past sessions recorded about the symbols an in-flight tool call is touching. It's purpose-built for a pre-tool-call hook: recall fires on the symbols the agent is about to act on (not a semantic query), and the endpoint is not metered against the monthly quota, so it's safe to call before every tool use.

This PR is purely additive — no existing type, method, or behavior changes.

What's new

memories.trigger(body, ctx?) — thin wrapper over the endpoint. Throws on HTTP errors, symmetric with search().

memories.preToolHook(signal, opts) — ergonomic sugar for the hook hot path:

• Fails soft. A network error, timeout, or abort returns { context: "", memories: [], degraded: true } so a recall hiccup can never stall the agent's tool loop (the endpoint itself also fails soft server-side).
• Fails loud on caller bugs. Missing scope axis or missing firing signal throw synchronously, before any network call — those are misconfiguration, not transient failures.
• mode: "compose" (default) returns the server-assembled, inject-ready block in context; mode: "retrieve" returns raw matched rows and renders the block client-side.
• Accepts the in-flight tool call ({ tool, args, output? }) or pre-extracted { entities }.
• Optional timeoutMs for a hard client-side cap (opt-in — the server already bounds recall and fails soft).

renderLessonProcedurePrompt(rows) — deterministic, no-LLM renderer for the retrieve-mode block.

Types — LessonProcedureType, LessonProcedureDetails, LessonMemory, ProcedureMemory, ActionContext, TriggerRequest, TriggerResponse, all exported.

Usage

// Before the agent runs a tool, pull what past sessions learned about it.
const { context } = await client.memories.preToolHook(
  { tool: "Edit", args: { file_path: "tool_loop.py" } },
  { user_id: "alice", task: "fix finalize-on-abort in the tool loop" },
);
if (context) systemPrompt += `\n\n${context}`;

Design notes

• The lesson / procedure row types reuse the shared memory shape but deliberately do not join the Memory union — they're only ever returned by this endpoint, so keeping them separate leaves search / list / recall type narrowing untouched.
• preToolHook is the recommended entry point for hooks; trigger is the lower-level escape hatch when you want raw errors and full control over the request.

Testing

Adds src/trigger.test.ts (9 tests) covering both modes, the compose context pass-through, retrieve-mode client rendering, fail-soft on error, the two validation throws, and aborted-signal handling. Full suite (55 tests) and tsc --noEmit pass.

[xtrace-memhub-staging]

MemHub Code Review — 1 issue(s) found

MemHub Code Review found 1 issue(s): 1 medium.

Advisory — informational only; this check does not block merge.