mazarbul

Overview Schema Source Related Servers Discussions Admin

recall

Search long-term memory for facts matching a query about users, people, places, organizations, or events, then use ranked hits to ground answers before responding.

Instructions

Search long-term memory for facts matching a query — about the user OR any person, place, organization, or event in the graph. CALL THIS before answering anything that depends on stored context (names, roles, projects, history, people, places, decisions); Mazarbul persists across sessions and clients, your conversation context does not. It is a SEED-FINDER: ground answers on each hit's text and entities[] — feed an entity name into get/neighbors/relations for the authoritative structured facts — not on the raw rank. fusedScore is a blended relevance score where rank ORDER is the signal, not absolute magnitude (normalized to [0,1] under the default weighted fusion, or a small reciprocal-rank value under rrf), so read each hit's text rather than blindly taking hit[0]. A miss is cheap; a confident hallucination is not. Recall ALWAYS returns its best-ranked candidates even when nothing strongly matches, so low, flat scores across unrelated hits usually mean the subject is NOT in memory — confirm a name with entities/get before treating a hit as fact, and use relations/neighbors (not recall) for the AUTHORITATIVE list of what mentions or links a known entity. Pass compact: true, maxTokens, or both to shrink the returned payload when you only need seeds to traverse. Returns ranked hits with citable ULIDs.

Input Schema

Name	Required	Description
`at`	No	RFC 3339 UTC instant to scope the query. Bi-temporal valid-time anchor. Optional.
`asOf`	No	RFC 3339 UTC instant. Hides any event whose transaction time is later than this anchor, answering 'what did we know on X?'. Bi-temporal transaction-time anchor. Optional.
`near`	No	Restrict results to episodes citing entities within a geographic radius of a named place. Both fields required when present.
`kinds`	No	Restrict hits to these record kinds (set semantics). Omit for the default mix of episodes + vault documents. Pass ["documentRevision"] for document-only recall, ["episode"] to exclude documents.
`limit`	No	Maximum number of hits to return. Defaults to 10.
`query`	Yes	Natural-language question or keyword phrase to search the event log for.
`anchor`	No	Entity ULID. When set, restricts candidates to episodes that cite entities within anchorDepth hops of this anchor (default depth 1, max 6). Useful when you already hold an entity anchor and want topically-adjacent recalls without widening to all memory. Requires navigate to be wired; gracefully degrades to full recall when it is not.
`scopes`	No	Scopes to read from: project, personal, team. Defaults to project+personal. Unknown values are rejected.
`source`	No	Constrain hits to these origin sources (set semantics, OR across values). Matches a hit's eventSource — the originating event's source tag, e.g. "remember", "extractor/v1", or a connector tag like "connector:granola". A bare connector name ("granola") matches its "connector:granola" / "connector/granola" forms too. Filtered AFTER ranking, so survivors keep their unfiltered rank order. An unknown source yields an empty hits array (not an error).
`compact`	No	Return a reduced per-hit envelope — {name, kind, snippet, fusedScore, entities} plus source for document hits — dropping the full text, the per-lane score components, confidence, citations, and createTime. Use when you only need anchors to seed-then-traverse (feed an entity name into get/neighbors/relations); cuts token cost sharply. Off by default (verbose).
`explain`	No	When true, attach per-lane candidate counts and total wall-clock time under the optional '_meta' key in the response. Off by default.
`noGraph`	No	Skip the graph traversal lane when true (vector + FTS only). Off by default.
`maxTokens`	No	Soft cap on the total estimated tokens across all returned hits (estimated at ~4 bytes/token). Hits are dropped lowest-fusedScore-first until the payload fits; the single top-ranked hit is always returned even when it alone exceeds the cap. Combine with compact for the smallest payload. Omit for no cap.
`anchorDepth`	No	Hop radius around the anchor entity (1..6). Defaults to 1 (immediate neighbourhood). Ignored when anchor is absent.
`currentDate`	No	Caller's "now" anchor (RFC 3339 UTC or YYYY-MM-DD) the rewriter uses to resolve relative phrases like "two months ago" into an absolute timestamp. Folded into 'at' only when 'at' is unset. Requires rewriteQuery=true to take effect.
`asOfEventUID`	No	Event ULID. Resolves to that event's createTime and uses it as the asOf anchor. Mutually exclusive with 'asOf' and 'at'; supply at most one of the three.
`rewriteQuery`	No	Expand the query via the query-rewrite-v1 LLM prompt before retrieval. Off by default.
`minConfidence`	No	Filter out hits whose writer confidence is below this value. Defaults to 0.
`embedDeadlineMs`	No	Per-call deadline in milliseconds for the query-embedding step. When the embedder does not respond within this window the call degrades to FTS-only and surfaces MAZ-RECALL-001. Absent means no per-call deadline (the session context deadline still applies).
`hasPrimarySource`	No	Keep only hits grounded in a primary source: the hit (or one of its entity anchors) is the subject of a recorded source_ref or of an active has_primary_source edge (#207/#208). Filtered AFTER ranking. Off by default.

Output Schema

Name	Required	Description
`hits`	Yes	Ranked hits. In compact mode (compact=true) each hit carries only {name, kind, snippet, fusedScore, entities} plus source for document hits; the verbose-only fields (hitType, text, confidence, components, citations, createTime) are omitted, so only that subset is guaranteed present.
`lanes`	Yes	The retrieval lanes that actually contributed to this result: ["vector","fts","graph","nameEmb"] for full hybrid, or a subset like ["fts"] when degraded. Always present.
`degraded`	Yes	True when recall ran BELOW full hybrid because the embedder was unavailable: FTS(+graph)-only, no dense-vector lane. Semantic matching did not run, so treat low, flat scores cautiously and lean on the entities/get tools to confirm. Restart the embedder (e.g. Ollama) to restore full hybrid.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 31, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses that recall ALWAYS returns best-ranked candidates even on weak matches, that flat low scores indicate absence, that fusedScore magnitude is meaningless versus rank order, and that embedding can degrade to FTS-only. These are non-obvious retrieval behaviors an agent could easily misread.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the trigger and the seed-finder framing before any caveats, and nearly every sentence carries a distinct instruction. It is dense and long, but the length is buying genuine behavioral guidance rather than restating the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter retrieval tool with no annotations, the description covers the critical interpretive risks (rank semantics, empty-ish results, traversal alternatives) and an output schema covers return values. It is silent on the bi-temporal (at/asOf), scope, and geographic filtering capabilities, which are significant but fully documented in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema does the heavy lifting and baseline is 3. The description adds decision-level meaning beyond the schema by recommending compact/maxTokens together for the smallest payload and by framing compact output as the seed-traversal mode, which turns a mechanical flag into a workflow choice.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search long-term memory for facts matching a query') and immediately widens scope ('about the user OR any person, place, organization, or event in the graph'). It also distinguishes itself from siblings by naming get/neighbors/relations as the tools for authoritative structured facts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('CALL THIS before answering anything that depends on stored context') and an explicit exclusion ('use relations/neighbors (not recall) for the AUTHORITATIVE list of what mentions or links a known entity'). The seed-then-traverse workflow tells the agent exactly how this tool chains into others.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.