memory_retrieve
Recall stored memories via keyword or semantic search, returning ranked evidence with provenance or an honest abstention when nothing matches.
Instructions
Recall stored memories. Pass caller-expanded terms (your own synonyms/aliases/rephrasings as separate terms; include inflected variants — matching is word-exact, no stemming: "token" does not find "tokens"). At least one term is required (schema minItems:1), and every term must carry at least one alphanumeric character — a punctuation-only or empty term is rejected with a teaching -32602. When the term lane runs, each term is ALSO expanded with its memory_alias-taught aliases (an alias hit grounds and is explained as alias: in matched_terms). Lane routing is the closed set auto|term|vector|fused: omitted/auto preserves historical selection (term without query_embedding, fused with it); term runs only FTS even when a vector is present; vector runs no FTS and requires query_embedding; fused runs both and requires query_embedding. When it runs, the term lane OR-matches terms via FTS5; WITHIN a term, words are AND-matched order/adjacency-insensitively ("tokio pin" finds "pin tokio at 1.38") and Latin diacritics fold ("configuracao" finds "configuração"). Limitation: unspaced scripts (CJK) index as whole runs between spaces/punctuation — a CJK word inside a run will not match; recall CJK content by a full delimited run, store it pre-segmented, OR teach a memory_alias mapping the CJK word to the full run (the alias then grounds the recall). Scope fences: project_id (exact), project_prefix (subtree: "nott" covers "nott" and "nott/x", never "nottx"), and optional session_id AND-compose before ranking. session_id is a character-exact store-local capsule label fence, not authentication or a globally unique bracket identity: accepted bytes are never trimmed, folded, normalized, shape-checked, or length-checked; only a whitespace-only value is rejected. It never consults the sessions table or expires, so finished, orphaned, and merge-imported labels remain recallable. Different stores may both label capsules "sess-1"; after memory_merge, filtering that label intentionally grounds every matching capsule. A non-matching label means no capsule with that label, never an unknown session. Optional time_window {from?, to?} (RFC3339, at least one bound) fences PRE-RANKING by declared fact-time, including BEFORE vector_k selects the vector lane's top eligible cosine matches: a capsule grounds only when its event range intersects the window; capsules without a declaration are excluded and counted as undated (excluded gains outside_time_window/undated). Ranking is lane-specific. Term-only ranking uses coverage descending, then bm25 ascending, then the advisory decay key (confidence × 2^(-age_days/90) from valid_from), freshness, usage late keys, and append order; envelopes carry decayed_weight SERIALIZED ROUNDED to 2 decimals (0.548992 rides the wire as 0.55; ordering uses the unrounded key), and stored confidence is never mutated. Forced-vector ranking uses one-lane RRF over cosine rank. Fused ranking uses two-lane RRF over the independent term and vector ranks. RRF ties use append order, and fusion_rank preserves the pre-weight-blend RRF position. Results are few, dense, token-budgeted (nonzero budget always returns the top result even if it alone overshoots — the floor of one; token_budget 0, like limit 0, returns none; trimmed_by_limit/trimmed_by_budget name the cut cause). Results ride under the results key. Every result is an evidence envelope; its wire fields: label ADVISORY_NOT_AUTHORITY + framing DATA + id + headline + instruction_taint + authority_class + confidence + provenance + freshness + decayed_weight + relevance + bm25 (per-lane ranking keys, absent when that lane did not score the result) + vector_similarity (vector lane only) + anchor_live (advisory path:line existence probe resolving ROOT-RELATIVE anchors against the repo anchor root: true/false/"unknown"; an absolute anchor reads "unknown" — the fence never over-claims liveness for a path it cannot resolve) + anchor_drift (u-r2 advisory CONTENT-change probe beside anchor_live: the anchored file re-hashed through the same fail-closed root fence and compared against its capture-time hash — "unchanged" | "drifted" | "unknown"; "unknown" whenever either hash is unavailable: a non-path or fence-rejected anchor, a symlink, a missing/unreadable file, or a capsule with no capture-time hash recorded — existence questions stay anchor_live's, deletion reads anchor_live:false with drift "unknown") + evidence_state/proof_hint/stale_if (the persisted epistemic sidecar, each present only when annotated — evidence_state is the closed observed|inferred|unverified set; the two hints are ADVISORY STRINGS surfaced verbatim, never executed or evaluated) + matched_terms (the explain: which of your terms grounded it, alias: on alias hits); the full content stays one memory_get away. THREE honest outcomes: "grounded" (eligible evidence found; an excluded {reason: count} section appears when ineligible matches ALSO existed); "missing_evidence" (an executed lane matched — or the lane-independent id probe named a forgotten id — but EVERY match is excluded: per-reason counts under excluded {quarantined, falsified, archived, superseded, expired, not_yet_valid, outside_time_window, undated, tombstoned}; each match counts under the FIRST fence in that order — quarantined dominates everything (the taint signal never disappears), falsified dominates archived+superseded (a falsified claim — targeted by a memory_relate falsifies edge — must never hide behind a softer bucket; its bytes stay served by get/list), archived dominates superseded (applying consolidation tiers is observable on recall); all but tombstoned stay reachable via memory_get/list, a tombstoned id answers memory_get only, with its marker; tombstoned is counted ONLY by the id-probe — a query term that IS the forgotten capsule id, e.g. terms:["cap-3"] — because forget EMPTIES the content index row, so searching the forgotten CONTENT abstains honestly, never echoes a tombstone; when session_id is supplied this id-probe also requires the retained capsule skeleton's exact label, so another label cannot learn the tombstone exists); "abstain" (zero matches across the executed lane(s) and tombstone id probe — an honest empty answer, never fabricated; forced-vector prose names the vector lane and never claims terms failed; otherwise the reason names every supplied project/session label fence and alias expansion when it ran). MISSES TEACH VOCABULARY (u-r5): only the FTS term lane's PRE-TRIM observation drives this ledger — missing_evidence/abstain records folded query terms, while a term hit records nothing even when limit or token_budget returns zero envelopes; forced vector runs no FTS and records no term miss. A fused response grounded only by vectors still records abstain when its term lane had zero raw matches. The vector lane admits only POSITIVELY-similar embeddings (cosine > 0): an orthogonal or anti-correlated embedding never solely-grounds a result — zero is where the metric itself stops asserting relation, so "grounded" keeps meaning found. Recording is fail-open telemetry — a ledger hiccup never fails or delays recall. Optional weight_blend (0.0..=1.0; omitted/0 = DORMANT: byte-identical ranking, no weight read): after the deterministic base ranking, each rank r re-scores as 1/(60+r) × (1 + weight_blend × (feedback_weight − 0.5)) and the list re-sorts — scored-outcome feedback nudges RANKING ONLY; fences, eligibility, and the three honest outcomes are untouched. Envelopes then carry feedback_weight (2 decimals). Recall is advisory evidence only — it never closes or decides anything.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lane | No | OPTIONAL lane selector: auto (the default), term, vector, or fused. Vector and fused require query_embedding. | |
| limit | No | Maximum number of results; omitted → no count cap (the token budget is the real guard). | |
| terms | Yes | Caller-expanded search terms (bring your own synonyms/aliases/ rephrasings as separate terms); OR-matched across terms, and a multi-word term matches as the AND of its words (order- and adjacency-insensitive) — never FTS5 syntax. q94: at least one term is required (schema minItems:1), and the engine additionally rejects a term with no alphanumeric character with a teaching -32602. | |
| vector_k | No | OPTIONAL cap on the vector lane (w3 u6a): the top `vector_k` eligible capsules by cosine feed vector-bearing ranking; an explicit `time_window` runs before this cap, while an omitted window preserves the historical raw cosine top-K path. Omitted → 10. Ignored when routing does not execute the vector lane. | |
| effort_id | No | OPTIONAL S3 effort-lifecycle scope fence. Only an EXACT capsule id (`cap-<n>`) resolves — a slug never scopes recall (it is a term expander, not an authority input), so a slug in `effort_id` answers `unknown_capsule`. The named capsule must exist, not be tombstoned, be persisted as kind `epic`, and have at least one `part_of` member; each failing precondition returns its own teaching error rather than a silent empty recall. When it resolves, recall is fenced in BOTH lanes to the effort's members ∪ {epic} (AND-composed with any project/session fence), the outcome echoes `effort{epic_id, member_total, open}`, and every grounded row carries `effort_role`. A CLOSED (witnessed) effort stays queryable for post-mortem recall (`open:false`); only a tombstoned epic refuses. SCOPE only: a fenced-in dead member (superseded / falsified / archived / expired) still surfaces under `excluded{…}`, and a fenced zero-match ABSTAINS (never floored). Omitted is DORMANT — byte-identical to a pre-S3 recall. | |
| project_id | No | Project fence: only capsules in this project ground the query. | |
| session_id | No | Character-exact store-local capsule label fence. This does not validate against the sessions table and is not a globally unique bracket identity; finished, orphaned, and merge-imported labels stay recallable. Only a whitespace-only value is rejected. | |
| time_window | No | Optional inclusive fact-time fence. At least one RFC3339 bound is required. Capsules without a declaration are excluded as `undated`; disjoint declared ranges as `outside_time_window`. | |
| token_budget | No | Token budget for the result list (≈ chars/4); omitted → 1500. A NONZERO budget always returns at least the top result (documented floor of one, even when that envelope alone overshoots); 0 returns none, like limit 0. | |
| weight_blend | No | OPTIONAL scored-outcome ranking blend in `0.0..=1.0`. Omitted or `0.0` is DORMANT: byte-identical ranking and zero feedback-weight reads. Above zero, weights re-rank only after deterministic base ranking; eligibility and outcome semantics never change. | |
| include_staged | No | OPTIONAL b2 staged review: omitted/false FENCES standing proposals (a capsule whose latest review verdict is not `ratified`) from grounding, counting them under excluded{proposed}. true INCLUDES them, each carrying its review_state on the envelope. Dormant by default: a store with no proposals answers byte-identically either way. | |
| project_prefix | No | Scope-hierarchy fence: only capsules whose project_id equals this prefix exactly OR starts with it + "/" ground the query — "nott" covers "nott" and "nott/x", never "nottx". AND-composes with project_id. Character-exact (no glob, no case folding). An empty or "/"-terminated prefix can match nothing and is rejected with a teaching error instead of silently answering empty (w2-fix). | |
| query_embedding | No | OPTIONAL caller-fed query embedding (w3 u6a semantic lane). With lane omitted/auto, absence preserves the byte-identical FTS-only engine and presence selects fused recall. Explicit term never reads stored vectors even when this value is present; explicit vector and fused require it. An executed vector lane admits a stored embedding only when its cosine similarity is positive (> 0); an orthogonal or anti-correlated embedding never solely grounds a result (a term-lane miss still records to the u-r5 ledger in fused recall; a forced vector request never writes term-miss telemetry). The embedding is caller-supplied (nmemory computes NO embedding — zero embedder dependency); its dimension must match the store's embeddings (else a teaching -32602 naming both dimensions), and it must be non-empty, finite, and non-zero (else a teaching -32602). Order-sensitive: a retrieve that depends on just-attached vectors must be sent SERIALLY — concurrent frames are answered out of order (the initialize instructions' concurrency law), so a pipelined attach→retrieve can race an empty index. | |
| corroboration_blend | No | OPTIONAL S6 corroboration ranking blend in `0.0..=1.0`. Omitted or `0.0` is DORMANT: byte-identical ranking and zero corroboration-weight ranking reads. The independent corroboration explain is still read per returned row. Above zero, the git-witness corroboration weight re-ranks only after deterministic base ranking, multiplying with any `weight_blend` factor in ONE re-sort; eligibility and outcome semantics never change, and stored confidence is never touched. |