MCP verbs

These are the seven verbs the MCP server advertises to every connected agent. Each verb’s description below is the exact text an agent receives at call time. Parameters marked server-populated are resolved from your authenticated token — you never pass them.

recall

Search the owner’s durable memories. Call this before answering anything that may have prior context — at task start, and whenever a stored fact, preference, or past decision could change your answer. Memories only: long-form reference docs are NOT here — search those with search_references. Query by free text; tags narrows to memories carrying any of the supplied tags. Pass include_ids: true to prefix each result with its memory id, so a memory that turns out to be wrong can be passed straight to flag_memory.

Parameter	Type	Required	Description
agent_id	string	server-populated	Server-populated from your authenticated token, not supplied by you — it identifies the calling agent.
query	string	optional	Free-text search over the owner’s durable memories; matches are ranked by relevance.
tags	string[]	optional	Narrow the search to memories carrying any of these tags.
include_ids	boolean	optional	When true, prefix each result with its memory id, so a memory that turns out to be wrong can be passed straight to flag_memory.
limit	number	optional	Maximum number of memories to return.

remember

Save a durable fact, preference, or decision the moment you learn it — not transient chatter. Fire-and-forget: submit and move on; the curator files it asynchronously (dedupe, merge, link — no need to check first). Give it a short title and a self-contained body; add tags so it surfaces in the right context. Caller-supplied is_global / requires_approval are ignored.

Parameter	Type	Required	Description
agent_id	string	server-populated	Server-populated from your authenticated token, not supplied by you — it stamps the calling agent’s identity onto the memory for ownership and dashboard filtering.
title	string	required	Short, self-describing headline for the memory — what you’d scan for to find it later.
body	string	required	The full fact, preference, or decision, written to stand alone — it must make sense with none of the surrounding conversation for context.
applies_to	string[]	optional	Optional scope hints — the projects, paths, or contexts this memory is relevant to.
confidence	string	optional	Optional confidence note (e.g. ‘high’, ‘tentative’), passed to the curator when it files the memory.
tags	string[]	optional	Tags to file the memory under, so it surfaces in the right context later.

flag_memory

A recalled memory is wrong, misleading, or outdated — flag it with a short free-text reason (required: say why). The flag routes the memory to human review and demotes it below unflagged matches in recall; it never edits, archives, or deletes, and there is no ‘this was useful’ counterpart. Use it sparingly, only when a memory actively led you astray.

Parameter	Type	Required	Description
agent_id	string	server-populated	Server-populated from your authenticated token, not supplied by you — it records which agent raised the flag.
memory_id	string	required	The id of the memory to flag — take it from a recall result fetched with include_ids: true.
reason	string	required	Why the memory is wrong, misleading, or outdated (required). Free text, recorded for the human reviewer.

store_handoff

Hand work off: persist a handoff document so another agent — on any harness — can resume your work later. Call it when pausing mid-task or ending a session that isn’t finished. The document must carry exactly these five sections — Start & intent, Journey, Current state, What’s left, Open questions — or it is rejected. The other side picks it up with list_handoffs then claim_handoff.

Parameter	Type	Required	Description
title	string	required	A short, human-scannable title for the handoff, shown in the takeover picker.
document_md	string	required	The handoff document in Markdown. It must contain exactly the five required sections — Start & intent, Journey, Current state, What’s left, Open questions — or it is rejected.
project_key	string	optional	Optional project this handoff belongs to, used to scope the takeover picker to the right project.
source_ref	string	optional	Optional stable reference to where the work lives — a harness conversation/run id, or a cwd-prefixed absolute path — so the next agent can resume in place.
cwd	string	optional	Optional working directory the handoff was created in, used as a default takeover filter.
harness	string	optional	Optional name of the harness the handoff was created in (e.g. claude-code, codex), recorded for context.
tags	string[]	optional	Optional labels for the handoff, to aid discovery in the picker.

list_handoffs

Take over work, step 1: list the unclaimed handoffs waiting to be picked up, then claim_handoff the one you want. Default scope is the caller’s current project_key + cwd when both are supplied; drop either filter to broaden when nothing matches.

Parameter	Type	Required	Description
project_key	string	optional	Restrict to handoffs for this project. The default scope is the caller’s current project; drop this filter to broaden when nothing matches.
cwd	string	optional	Restrict to handoffs created in this working directory; drop it to broaden the search.
harness	string	optional	Restrict to handoffs created in this harness; drop it to broaden across harnesses.
limit	integer	optional	Maximum number of handoffs to return.

claim_handoff

Take over work, step 2 (after list_handoffs): atomically claim a handoff and receive its document to resume from. Claims race — 404 if the id is unknown; 409 if another agent claimed first (the existing claim is included so you can say who has it and since when).

Parameter	Type	Required	Description
handoff_id	string	required	The id of the handoff to claim, taken from a list_handoffs result.
claiming_agent_id	string	optional	Optional identity of the agent taking over, recorded on the claim so others see who has it.
claiming_harness	string	optional	Optional harness the takeover is happening in, recorded on the claim.
claiming_source_ref	string	optional	Optional stable reference to where the resumed work now lives — a conversation/run id, or a cwd-prefixed absolute path.
claiming_cwd	string	optional	Optional working directory the takeover is happening in.

search_references

Search the long-form reference documents (background material the operator filed under references/ — specs, manuals, design notes). References are deliberately NOT auto-recalled and never appear in recall results, so search here when the task needs that depth. Returns each match’s vault path + the query-relevant section.

Parameter	Type	Required	Description
query	string	required	What to look up across the operator’s long-form reference documents.
limit	integer	optional	Maximum number of reference matches to return.