memory_search
Retrieve relevant stored memories and preferences when context is missing or ambiguous. Results include relevance and staleness signals, so you can resolve requests using verified project knowledge.
Instructions
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) — how much of your query wording the hit literally contains, not how good it is. Weak hits: re-query with different nouns.staleness_verdict(fresh / spot_check_recommended / spot_check_required) — rolled-up signal; != fresh, act onpath_driftbelow.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-scrapedmissingridesfresh— 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 ofdepends_onlink 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 nodepends_onlinks.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 highrelevanceor 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 whoseupdatedis 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 checkingcuration_pending_new_since_last_session is None.mode(optional, default from config; package defaulthybrid):keyword,bm25, orhybrid(RRF fusion of both). Every mode is deterministic lexical ranking, so vocabulary is the lever — seequery.
Outcome is recorded automatically via the use_token within ~2 turns; only call memory_record_use to override (ignored / contradicted / corrected).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| query | Yes | ||
| scopes | No | ||
| auto_scope | No | ||
| expand_top | No | ||
| max_results | No | ||
| since_prior_session | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |