Operation · Retrieve

The read path into memory.

Retrieve answers an agent’s request for relevant context: the right topics, optional neighborhood, and the current (or historical) field values. It is not only a read — every successful retrieval reinforces the topics it touches so MemState learns what stays active.

Next: Revise API reference

Retrieve materializes S_t: the executor’s staged read model over the same durable D_t — semantic candidate selection first (which topic ids to load), then optional structural expansion (edges and field refs) and temporal expansion (field histories when requested). Defaults return current field heads; enabling history preserves query soundness against the append-only trace. See GEM state and value history.

How it works

Client calls POST /v1/query. The request carries a query string, which stages to run, and how much context to return per result.
The query is embedded. MemState computes a vector for the query text once and reuses it when the semantic stage needs to pick candidate topic ids.
Candidates are chosen. With semantic on, the store uses vector KNN when available, otherwise cosine over loaded topic vectors, both capped by top_k. Archived topics are filtered out.
Each candidate becomes a bundle. MemState attaches the requested fields, expands neighbors if asked, and optionally returns full value history.
Salience is reinforced. Every touched topic gets its salience bumped and an entry appended to its topic-level audit trail.
The response returns a list of topic bundles (structured memory per topic) plus a short summary_text. Bundles may include an internal similarity field when the semantic stage ran; the contract is the topic payload, not a standalone score table.

Three retrieval modes, composable

Retrieval has three modes that can be used independently or together. The default is to run all three.

⚲

Semantic

Narrow to the topics whose title and summary text best match the question, using embeddings only inside this stage. The answer you ship is still the topic bundles.

🔗

Structural

Expand each candidate through its typed links and surface the requested fields. Answers "what's around it?"

🕒

Temporal

Return the full value history of each returned field. Answers "how did it change over time?"

Flow

Candidates flow through optional stages. Every touched topic is reinforced before the response returns.

Request fields

Field	Role	Default
`q`	Query text used for embedding and summary generation.	Required
`stages[]`	Which of `semantic`, `structural`, `temporal` to run.	All three
`explain`	Return full field histories when `temporal` is enabled.	`false`
`top_k`	Maximum number of candidate topics returned.	`8`
`topic_ids`	Optional allowlist of candidate topic ids.	None
`field_names`	Optional subset of fields to return per candidate.	All fields

Candidate selection

With semantic enabled: vector KNN selects candidates; cosine fallback runs if KNN is unavailable.
With semantic disabled and topic_ids provided: the allowlist is the candidate set.
With semantic disabled and no allowlist: the first top_k loaded embedding topics are used.
When both semantic and topic_ids are provided: candidate selection runs first, then the allowlist filter is applied.
Archived topics are skipped from results by default.

Side effects

Retrieve is a read-with-reinforcement operation, not a pure read. Each returned topic has its salience bumped and its topic-level audit log receives a query_bump entry. This is how the system learns what stays active.

Edge cases

Condition	Behavior
No embeddings available.	Falls back to the allowlist or returns an empty candidate list.
Archived candidate.	Skipped from the response.
Invalid auth key.	HTTP 401 before the executor runs.

Code map

memstate.api.main.query_op
memstate.core.executor.Executor.query
memstate.core.executor.Executor._field_bundle
memstate.store.graph_store.vector_knn_topic_ids

Next: Revise