feat: directive recall + pre-tool-use hook

[felix-xtrace]

What

Adds the @xtraceai/memory surface for procedural-memory directive recall — the read side of the directive loop now live on the VecDB memory API. An agent can recall the situated lesson/procedure directives keyed to what it's about to touch, and the AI SDK integration fires it automatically before each tool call.

API

// 1. Typed method
const { data, context } = await client.memories.recallDirectives({
  action: { tool: "Edit", args: { file_path: "tool_loop.py" } }, // the in-flight call
  user_id: "alice",
  mode: "retrieve",            // fast stage-1 tripwire (default); "compose" = + LLM gate
});

// 2. AI SDK pre-tool-use hook — recall fires before each tool runs, injected into the result
import { withDirectiveRecall } from "@xtraceai/memory/ai-sdk";
streamText({
  model: openai("gpt-4o-mini"),
  tools: withDirectiveRecall(myTools, { client, user_id: "alice" }),
  messages,
});

• memories.recallDirectives({ action | entities, task, mode }) — sugar over POST /v1/memories/search with include:[lesson,procedure]. Defaults mode:"retrieve" (the right lane for a per-tool-call hook). A client-side firing-rule guard throws if neither a non-empty action nor entities is given (mirrors the server's 422 — directives fire on symbols, not a query).
• renderDirectivesPrompt(directives) — deterministic inject-ready markdown (for retrieve, where the server doesn't pre-render).
• withDirectiveRecall(tools, opts) (ai-sdk) — wraps a tools object so each tool's {name, args} recalls its directives before it runs and prepends them to the result; directiveContextForToolCall() is the underlying primitive. Fails soft — a recall hiccup never breaks a tool; tools without execute pass through.
• Types: ActionContext, DirectiveDetails, DirectiveMemory, DirectiveListEnvelope, RecallDirectivesParams — self-contained, so the core Memory discriminated union and its render path are untouched.

Tests

7 new (src/directives.test.ts): body shape + retrieve default, the firing-rule guard (incl. fieldless action), explicit-entities + compose + task, render output, and the AI SDK wrapper (recall-before-exec + inject + pass-through + fail-soft). typecheck + full suite (53) + build all green.

Note on the branch

Built on main (the hand-written SDK) for the fast path. The repo has a Stainless-generated next (v0.2.0) line in flight; when that lands, the directive types should flow from the OpenAPI spec (which the API already emits) and the recallDirectives sugar + ai-sdk hook re-port as hand layers on top.

🤖 Generated with Claude Code