Consult

POST /memories/consult answers a query with the most relevant memories in the namespace.

How consult retrieves

Retrieval fans out per fact type — knowledge, experience, signal, and decision by default; types narrows it. Each lane runs the same four methods in parallel:

• Semantic — embedding similarity against the query.
• Lexical — BM25 full-text search for exact terms the embedding may miss.
• Graph — link expansion from strong hits to connected facts.
• Temporal — time-anchored retrieval, only when the query implies a period.

The lanes merge into one ranked list per method, plus a community list when communities have been built for the namespace. A community summary is an aggregate over the whole namespace, so that list is left out when the query is scoped to tags. Those lists are fused with Reciprocal Rank Fusion, the fused set is reranked, and the survivors are scored by relevance, recency, and corroboration. Standing decisions never decay below neutral recency, so policy stays findable long after it was made.

The Consult Analyzer in the app shows the same pipeline as four stages: Parallel Retrieval → RRF Fusion → Combined Scoring → Final Results.

Budget

budget trades latency for depth:

max_tokens caps the size of the result set, so the response drops straight into a prompt.

Filtering and extras

• types — restrict fact types. The REST endpoint defaults to all four; pass ["knowledge", "experience", "decision"] to exclude synthesized signals.
• tags + tags_match — filter by chronicle-time tags (any, all, or the _strict variants that exclude untagged memories). tag_groups composes boolean tag expressions.
• query_timestamp — anchor "recent" to a different point in time.
• include options — raw source chunks and the source facts behind signals can be inlined in the response, each with its own token cap. Entity inclusion returns names and ids only; read an entity's signals from GET /entities/{id}.
• trace — return scoring detail for debugging retrieval.

Reading the response

Two flags on the response say what happened to it:

• truncated — the token budget dropped whole results, source facts, or chunk text. Raise max_tokens, or the relevant include cap, to see the rest.
• degraded — a provider was unreachable and consult answered from the arms that survived: without embeddings retrieval is lexical only, without the reranker the fused RRF order stands. The results are real, just ranked with less signal than usual.