Procedural-memory recall (pre-tool-call hook)
Procedural-memory recall for a pre-tool-call hook.
Fires the symbol tripwire on the in-flight action (or explicit entities)
and returns the lesson/procedure insights past sessions recorded about
those symbols — advisory, not a mandate. data: list[Memory] carries the matched
rows (type: "lesson" | "procedure"); mode=compose additionally runs an LLM
relevance gate over task and assembles a markdown block into context, while
mode=retrieve returns the raw matched rows and leaves context null. Scope is
enforced server-side from the request’s scope axes (user_id / group_ids /
agent_id / app_id).
Unlike POST /v1/memories/search, this endpoint is not metered against the
monthly quota — the hook is meant to be called freely before every tool use.
Authorizations
Body
POST /v1/memories/trigger — procedural-memory recall for a pre-tool-call hook.
An agent calls this right before (or just after) a tool runs to pull the
lesson/procedure insights that past sessions recorded about the symbols
it's touching — what worked, what didn't. Recall fires on the symbol tripwire,
never a semantic query: the server extracts greppable identifiers from action
(tool / args / output) or takes them
straight from entities, and matches them exactly against directives'
trigger_entities.
What comes back is advisory, not a mandate — ranked :class:Memory rows
(type: "lesson" | "procedure") in the shared :class:SearchResponse, with the
assembled markdown in context under mode="compose".
Scope follows "scope by what you pass": every axis you supply ANDs; org_id
is derived server-side from your API key. At least one of user_id / agent_id / app_id /
group_ids is required — an unscoped org-wide recall is rejected.
Namespace the agent is working in right now — repo, customer account, service (whatever was passed at ingest). Narrows recall to directives learned under that namespace plus global ones (ingested with no namespace) — it never hides global directives, so it is always safe to pass. Unrelated to the tenancy axes.
256"MemHub-Backend"
Pipeline depth selector.
compose(default) — symbol-tripwire recall plus an LLM relevance-gate step that keeps only the insights relevant totask, then assembles a markdown block.datacarries the gated rows;contextcarries the markdown. One LLM call.retrieve— recall only. No LLM, cheaper and faster.datacarries the matched rows;contextis null.
retrieve, compose Response
Successful Response
POST /v1/memories/search response.
data is always populated — both modes return the ranked
Memory rows from retrieval. context is populated only when
mode='compose' with the assembled markdown block from the
LLM context-selection step. stage_timings is always present
for per-stage latency attribution.
Note that under mode='compose' the rows in data are the
retrieval candidates — a possibly larger set than the subset
the LLM selected and wove into context. Useful for showing
"everything we found" alongside "what we sent to the model."
Ranked Memory rows from retrieval. Populated for both modes. Semantic rows (fact/artifact/episode) are ordered by score desc; when include requests lesson/procedure, those directive rows are precision-gated (not vector-scored, score is null) and lead the list ahead of the semantic rows. For mode=compose, the semantic rows are the candidates considered by the context-selection step — a (possibly larger) superset of what ended up in context.