recall
Retrieve top-k agent memories from inspeximus ranked by relevance and accrued value, not recency, to load relevant prior knowledge before reasoning.
Instructions
Retrieve the top-k memories by RELEVANCE × accrued VALUE (not recency). Use this to load relevant prior
knowledge before reasoning. Records the read-path guards quarantined (instruction-shaped text, 3.5.0)
are left out unless include_quarantined is set; keyword-stuffed records never outrank clean ones.
include_archive also searches the archive segments beside the store (old captured mechanics moved
out by --archive); it opens every segment, so it is slower and off by default.
Compact by default: each hit is a small projection — {id, text, score, value, tags} — dropping internal
bookkeeping fields the model doesn't reason over, which keeps recall cheap to drop into a prompt. FULL TEXT IS
KEPT (no truncation by default). Pass snippet_chars>0 to opt into snippet truncation (flags truncated; then
use get(id) for full text) — note that truncation can cut off a corrected value past the boundary, so it is
off by default. Set full=True to return complete records (all fields). k is hard-capped for safety.
mmr (0..1, off by default) reranks for DIVERSITY so you don't get k near-duplicate memories — 1.0 = pure
relevance, lower = more diverse (deterministic Maximal Marginal Relevance, zero-LLM). trusted_only=True (needs
a configured trust root: INSPEXIMUS_TRUST_SEEDS on this server) returns only memories anchored to a trusted
signing key or source — a deterministic defense against injected/poisoned memories from untrusted writers.
With no trust root configured the call is an error, not an empty list that reads as "nothing trusted
matched". resolve_conflicts=True (or server-wide
INSPEXIMUS_READ_RESOLVER=1) resolves near-duplicate same-subject candidates at read time by value BIRTH — an
un-keyed restatement of a superseded value is demoted below the correction instead of out-ranking it; the
surviving hit carries resolved_over ids. Deterministic, zero-LLM.
(Standard progressive-disclosure / small-to-big retrieval practice, not a inspeximus-specific technique.)
with_warrant=True adds a warrant tier to every hit — earned (outcome credit that did not come
from the record grading itself, or a memory that GRADUATED to semantic through the corroboration
bar), corroborated (>=2 distinct sources, or distinct verified keys under strict_corroboration,
but no outcome credit yet), or unwarranted (single self-asserted, no lineage, or retracted).
BRANCH ON IT: unwarranted means no independent channel backs this memory, so it may inform your
reasoning but should not by itself drive an action. It is deliberately a discrete state rather than
a low score, because a low score reads downstream as a weak "yes" and gets acted on anyway.
Additive: ordering, membership and every other field are identical with it on or off.
PROJECT SCOPE: when this server runs with --project <name>, recall returns only that project's memories
plus any memory carrying no project stamp (memories written before you adopted a scope stay reachable —
adopting one narrows what you see without hiding what you already had). all_projects=True is the escape
hatch for "I know I wrote this somewhere": it searches EVERY project in the store. Each hit then carries
the project it belongs to, so a cross-project answer says where it came from. Call where_am_i() to see
which store and scope you are on, and projects() to list the scopes present.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| mmr | No | ||
| full | No | ||
| query | Yes | ||
| user_id | No | ||
| agent_id | No | ||
| rerank_by | No | ||
| session_id | No | ||
| all_projects | No | ||
| trusted_only | No | ||
| with_warrant | No | ||
| snippet_chars | No | ||
| include_archive | No | ||
| resolve_conflicts | No | ||
| include_quarantined | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |