memory-v1

Query Memory

Advanced query: multi-domain, metadata filters, same response shape as /memory/read.

post/api/v1/memory/query

Request

  • Base URL: https://core.mnemoverse.com
  • URL: https://core.mnemoverse.com/api/v1/memory/query
  • Auth: one of:
    • API key in header X-Api-Key
    • HTTP bearer

Request body

querystring required

Natural language query.

domainsstring[] nullable

Filter by multiple domains (null = all).

top_kinteger

Max items to return. Cap aligned with ReadRequestSchema (500).

min_relevancenumber

Min relevance threshold.

include_associationsboolean

Expand via Hebbian associations.

conceptsstring[]

Concept hints.

include_historyboolean

Return superseded revisions alongside live ones; each carries superseded_by, and every item carries supersedes when it replaced something. History is returned in the domain where each revision is stored: a read scoped to the successor's domain does not include a cross-domain predecessor — use an unscoped read or GET /memory/atoms/{id}. History items compete under normal ranking, min_relevance and top_k/limit — include_history grants eligibility, not chain completeness; for the chain itself use GET /memory/atoms/{id}/chain, which spends a 64-LOOKUP budget per call (resolved revisions AND dangling-pointer misses both count) and sets truncated when the budget ran out — so truncated means the walk stopped early, not that the chain necessarily holds more than 64 revisions. One exception to the domain rule above: when a fingerprint matches a revision that has been replaced, the live tip is returned alongside it even if that tip lives in another domain — the episodic index is domain-blind, and this makes it two atoms rather than one. No effect until the read-side supersession filter is enabled (nothing is hidden before then, so nothing needs unhiding), and inert for xroom:<room_id> domains, whose atoms cannot be superseded at all.

diversitynumber

0 (default) leaves the ranking as it is: the ranked candidates are cut to top_k. A value above 0 turns the cut into a maximal marginal relevance selection: items are picked one at a time, each the one that best trades its relevance against its cosine similarity to the items already picked (weight diversity on the similarity, 1 - diversity on relevance), so a near-copy of something already in the answer loses its slot to the next distinct item. 1 means similarity alone decides after the first pick. Applied after outcome feedback and recency have re-ranked, on the ranked pool of up to 200 candidates that cleared min_relevance, and only when top_k is below 200 (at 200 or more the plain cut applies); pinned fingerprint revisions and the association-reserved slots are unchanged. It changes which items are returned, not their scores.

Response

Successful Response

episodic_hitboolean required

True if an exact episodic (fingerprint) match was found.

query_conceptsstring[] required

Concepts extracted or used for the query.

expanded_conceptsstring[] required

Concepts expanded via Hebbian associations.

search_time_msnumber required

Search duration in milliseconds.

timingsobject nullable

Per-phase wall times in ms + call counters (TRACING_SPEC §2). Present only when the request set include_timings=true; an absent phase key means the phase was skipped.

Example response

{
  "episodic_hit": false,
  "expanded_concepts": [
    "rotation",
    "symmetry",
    "grid"
  ],
  "items": [],
  "query_concepts": [
    "rotation",
    "symmetry"
  ],
  "search_time_ms": 12.5
}

Changes

No recorded changes to this operation across all 1 revision of this API.