memory_search

Search stored memories. Default: do NOT call — reach for it only when the user references shared context you lack ("my project", "the script we wrote") or a request is ambiguous in a way stored preferences could resolve. When a hit shapes your reply, announce it ("Using your stored preference for…") — non-negotiable. (Full policy: the server instructions block.)

Returns ranked hits with snippets. Per-hit fields the model should branch on:

• relevance (high/medium/low) + matched_leg (lexical/semantic/both) — relevance is how much of your query wording the hit literally contains, not how good it is; on a semantic leg it is low by construction, so read them together.

• staleness_verdict (fresh / spot_check_recommended / spot_check_required) — rolled-up signal; != fresh, act on path_drift below.

• match_terms — which query words actually hit.

• path_drift_missing (int) + path_drift ({checked, missing, verified} when drift detected) — body-cited paths gone. claim_anchored_missing (added when non-empty) is the escalating subset: memory_update those, memory_verify the rest. Prose-scraped missing rides fresh — evidence, not a tier.

• commit_drift_count (int, when applicable) — commits since last_verified_at on the memory's origin repo. Non-zero means the project moved even if calendar-fresh.

• depends_on_resolved (when present) — bounded auto-pull of depends_on link targets (max 3 per hit, max 10 per call). Each entry: {id, scopes, summary, link_note}. Surfaces context the query wouldn't on its own; saves a memory_show round-trip. OMITTED when the hit has no depends_on links.

• recent_negative_outcomes (when present) — list of recent ignored/contradicted events for this memory (max two, one per outcome). The user already rejected this; don't re-surface unless you have new reason. OMITTED when none.

Parameters:

• query: nouns a memory would contain (tool, file, error names) — vocabulary is the lever, not question phrasing. Weak hits: re-query, different nouns.

• scopes (optional): filter to scope union.

• max_results (default 5, cap 50).

• expand_top=True: inline the full body of the top hit when it has high relevance or a decisive score lead over the runner-up — saves a memory_show round trip and surfaces the full path_drift + commit_drift detail.

• auto_scope=True (default): filter to current repo+worktree; memories with no recorded origin always pass as global. Set False for explicit cross-project queries.

• since_prior_session=False (default): when True, filter to memories whose updated is strictly after the prior session boundary (latest event from a different session_id in the log). The semantic is 'what has changed in the current session, since the last activity by other sessions' — i.e. this session's intra-session diff. A /loop iteration uses this to track what IT has written/updated; for what the prior iteration did, call episode_handoff instead. Returns empty when there's no prior session in the log; distinguish 'nothing new' (results=[]) from 'no baseline' by also calling memory_scope_overview and checking curation_pending_new_since_last_session is None.

• mode (optional, default from config; package default hybrid): keyword, bm25, semantic (needs an embeddings extra), or hybrid (RRF of all three; picks the extra up automatically). With no extra installed every mode is lexical, so see query.

Outcome is recorded automatically via the use_token within ~2 turns; only call memory_record_use to override (ignored / contradicted / corrected).