memory-search

Memory Search

How every agent should read the gutt knowledge graph: one strong first pass, judged for relevance, deepened only when it falls short. This is the most-used memory operation and the foundation skill — other memory skills cross-reference it rather than restate it. Its job is to surface the answer as fast as possible when it exists, and to say so plainly when it doesn't.

Hard rules (non-negotiable — read first)

1. One adaptive pass first. Open with a single pass — search_memory_nodes and search_memory_facts in parallel, on your best phrasing. Never open with traversal, schema calls, or fetch_lessons_learned.
2. Relevance gate. Answer only from results that genuinely fit the question. If nothing on-topic comes back, say "no relevant memory found" — never assemble an answer out of loosely-matching distractors.
3. Reformulate, don't paginate. If the first pass is weak, rephrase the query and re-run nodes+facts (up to 2 more times, accumulating). Stop early if a rephrase returns essentially the same weak results. Never fetch page 2 just because has_more is true — a different phrasing beats pagination. The identifier pair (rule 7) inverts this: a rephrase leaves the exact route and cannot stand in for a pair that came back empty — report that as its own finding, never with the near-miss keys a phrasing returned — and a pair with has_more is paged, because the route matches a term rather than ranking by meaning.
4. Summary-first. Read summaries (node summary, lesson summary, search title) before fetching any full episode body. Full bodies only to cite or recover a crucial missing detail.
5. Count caps, not truncation. No summary_only / max_chars parameter exists — bound context with max_nodes / max_facts / limit and by choosing summary-shaped tools. Never invent a truncation flag.
6. Bare tool names. Call search_memory_nodes etc. by bare name; the mcp__…__ prefix varies per install — use whatever your tool list surfaces.
7. Identifier lane. When the question carries an identifier — a prefix of up to ten characters, a hyphen and digits, whether the user typed it or you lifted it from the ticket, report or result in hand — call both search_memory_nodes and search_memory_facts with that identifier as the entire query and no agent_id, center_node_id or center_on_user. Any extra word, and any of those three, drops the call off the exact route and onto look-alike keys. One pair per identifier, first, and in addition to the phrasings — never instead of them. A list of items is not one question: a skill working through a slice says which of its keys get a pair, and when.