search_memory

WHOSE memory to search. Omit for MY own (the default). "here" = the place I am standing in, which returns what the place itself remembers. A friend's id = what they have chosen to share — their private memories never leak. You can also pass a typed reference like "place:loc_x" or "thing:thg_x".

What I am trying to remember, in plain words — ask it as a QUESTION ("what do I usually order here?", "what have I learned about Kim's cooking?"), not as keywords. OMIT for a pure filtered listing, which comes back newest-first instead of by relevance.

Several angles at once (max 5) — each runs as its own search and the results are merged and de-duped into one ranked list. Use it to triangulate in ONE call. The filters below apply to every angle.

WHEN it happened. A keyword — "today", "yesterday", "this_week" — resolved server-side in MY timezone, so just say "yesterday" and let the server do the date math.

Lower time bound as epoch MILLISECONDS (inclusive). The machine-facing form of `timeframe` — use it when you are continuing from a timestamp you already hold. Wins over `timeframe`.

Upper time bound as epoch MILLISECONDS (exclusive). Wins over `timeframe`.

Only memories that involved ANY of these — someone who was actually THERE. Ids or typed refs; I never list myself, I am always included automatically.

Only memories that involved ALL of these at once — "the last time Kim and I were both here".

Only memories of something this actor DID.

Only memories ABOUT any of these — talked about, not necessarily present. Different from `with`: "what do I know about Kim" vs "when was I actually with Kim".

Only memories made at this EXACT place. "here" = where I am now. This is how you ask "what do I usually order AT THIS SHOP" as opposed to "what do I like generally".

Only memories made at this place OR anywhere inside it — pass a city or region id to sweep everything under it. "here" = where I am now.

observation = something that happened; reflection = an insight I drew; plan = how I intend to carry out a goal; goal = something I intend to do. Omit for all.

agent = memories I wrote in my own voice; system = the factual backbone the world recorded.

Only memories at least this significant (1 mundane … 10 life-defining).

memories = ranked hits (default). counts = totals only, no bodies — ask for this FIRST when you only need to know whether anything happened. context = the rich self-picture for reflection (my own memory only).

Max results (default 10, max 50).

How the memories come back. "formatted" (default) = easy-to-read text with the elapsed time worked out for me ("2 hours ago"), the weekday and date, and real names instead of ids — so I do not have to reconstruct WHEN or WHO from raw fields. "raw" = the underlying JSON, for when I need exact ids/timestamps to feed back into another call.

Opaque page cursor from a previous result — pass it back unchanged for the next page.

Hard relevance floor for semantic hits (0–1). Omit to use the query-adaptive floor, which is almost always right; set it only to force a stricter or looser cut.

Everything new since my last sweep — the heartbeat's read. Pass {} to continue from where I left off. Reading does NOT advance the watermark: pass { ack: <nextCursor> } once you have actually used the results, so a run that dies re-reads instead of losing them.

Pass through the number begin_beat handed back, unchanged, on every call until commit_beat. Leave it out entirely when acting on something the person just asked for.