What is the search operation
search runs one retrieval strategy (a SearchType) over the stored memory. recall picks the strategy for you and adds session sources. Call search directly when you want a specific strategy and its options.
Search types
Unified orchestration across 17 retrieval strategies selected bySearchType
(crates/search/src/types/search_type.rs):
GraphCompletion, GraphCompletionCot, GraphCompletionContextExtension,
GraphCompletionDecomposition, GraphSummaryCompletion, GraphReport,
RagCompletion, Chunks,
Summaries, Temporal, Cypher, NaturalLanguage, FeelingLucky, Feedback,
CodingRules, ChunksLexical, HybridCompletion (default; combines vector search over
chunks/summaries/entities/edge-facts and 1-hop graph-neighborhood expansion
around matched entities, then answers via LLM completion; tuning knobs in
Configuration: hybrid retriever knobs).
TRIPLET_COMPLETION and its TripletRetriever were removed with no alias:
"TRIPLET_COMPLETION" is now an unknown search type in serde, the bindings
(validation error) and the CLI; use GRAPH_COMPLETION or HYBRID_COMPLETION
instead. A database that still holds a Triplet_text collection keeps serving
every other type.
A hybrid search falls back to GraphCompletion (with a warning) when it sets
node_type (other than NodeSet), neighborhood_depth or a positive
feedback_influence (an unset one takes DEFAULT_FEEDBACK_INFLUENCE, so a
positive default falls back too), or when neither the DocumentChunk_text nor the
DltRow_text collection exists (checked only on a non-empty graph);
setting wide_search_top_k or triplet_distance_penalty with hybrid is an
error. The CLI’s -t/--query-type exposes only a subset — see
CLI Reference. Entry: cognee-search
(SearchBuilder / SearchOrchestrator).
Result shapes
Two results changed shape, a breaking change. Withonly_context, the
completion types return the prompt the completion would have sent — the user
prompt as the Text result, with user_prompt / system_prompt on the
response (and prompts, one per dataset, for a multi-dataset search that does
not combine context) — while other types still return their bare context
(GraphReport returns the bare report text).
GraphCompletion and GraphSummaryCompletion over an empty graph, and
ChunksLexical with no chunks, now fail with SearchError::NotFound. The
bindings also forward node_name_filter_operator (nodeNameFilterOperator in
TypeScript and Java) to combine node_name filters with "OR" (default) or
"AND".
Triplet ranking
The graph retrievers (GraphCompletion and its CoT, context-extension and
summary variants) rank triplets around the vector-search hits. A triplet’s
score sums its source node’s, target node’s and edge’s cosine
distances, each scaled by 2 - importance_weight (0.5 when absent) and, with
feedback_influence > 0, blended with its feedback_weight (higher feedback
ranks better). An element with no vector match takes triplet_distance_penalty
(6.5) before that scaling — 9.75 at the default weight — and is not blended.
importance_weight is not clamped: above about 1.69 the scaled
penalty is blended like a real match, and above 2 it turns negative and ranks
first. Both are breaking changes to the ranking.
Neighborhood projection
By default the graph retrievers rank only the edges touching a hit.neighborhood_depth (a positive integer; the CLI’s --neighborhood-depth, the
bindings’ neighborhoodDepth search and recall option, neighborhood_depth in
the Python binding) switches to neighborhood projection: load the depth-hop
neighborhood of the nearest neighborhood_seed_top_k hits
(--neighborhood-seed-top-k / neighborhoodSeedTopK; all of them when unset),
score the nodes the expansion found against the query (VectorDB::score_by_ids;
an adapter without it leaves them at the distance penalty), and rank every
loaded edge. Larger depths load more of the graph. Combined with node_name,
which disables the seed search, it returns no triplets. The graph
retrievers used to ignore neighborhood_depth, so a request that sets it now
ranks differently, and a non-positive neighborhood_depth or
neighborhood_seed_top_k is rejected for every search type.
References
include_references (SearchRequest::include_references; the bindings’
includeReferences search and recall option; default off, and anything but a
JSON true is off) turns on references: RAG and the graph
completion family then attach structured evidence references to each result
(the chunks, graph nodes and edges placed in the completion’s context, in rank
order), and RAG text answers gain an Evidence: block; a recall puts them in
each result’s metadata.evidence. Graph edges are cited through the
edge-evidence ledger. Off leaves
the answer unchanged. The CLI has no flag for it. A binding’s recall result
also carries normalizedResults: one entry (kind, text, score, metadata, …)
per graph item, in order.
Structured answers
response_schema (SearchRequest::response_schema, and now
RecallOptions::response_schema for recall()) is a JSON Schema
the completion retrievers (RAG, hybrid and the graph completion family) shape
their answer to, returned as SearchOutput::Structured. Only a structural
subset is supported (a root type: "object"
with non-empty properties; primitives, arrays, enums, unions via anyOf or
a type list, and $defs references; at most 10 levels deep and 200
properties in total). A schema outside it is refused before anything is
searched, with SearchError::InvalidResponseSchema and a
response_schema: <reason> message, where it used to reach the LLM as-is.
This is a breaking change, as are the new SearchError variant (exhaustive
matches need an arm) and the new RecallOptions field (struct literals need
..Default::default()).
The answer is conformed to the schema: absent optional fields
become null (a schema default is not applied) and undeclared
keys are dropped. An answer that does not match is re-asked inside the
structured-output retry budget; if it still does not match, the search fails
with SearchError::LlmError. Checking is strict: a string is never coerced
to a number or a boolean. A recall with a schema returns the answer itself as its one graph
item (score 1.0). Neither the CLI nor the bindings expose response_schema,
so set it from the Rust API; a binding’s normalizedResults therefore never
holds the STRUCTURED entry (answer in structured, no score) that
cognee_search::build_structured_entry builds for such an answer.
Batch triplet search
brute_force_triplet_search_batch (in cognee_search::graph_retrieval) is
a batch mode: several queries share one graph load and
come back as one ranked list each. It searches every vector
collection without a limit and loads the whole graph (or the NodeSet subgraph),
so it costs far more than a single search on a large store —
search.triplet_neighbor_cap does not bound it, wide_search_top_k and
node_name (in the vector search) do not apply, and with neighborhood_depth
set it returns no triplets. It skips Triplet_text, whose ids are
never graph nodes. It runs batch mode even for one query; call
brute_force_triplet_search for a single query.
Decomposition
GraphCompletionDecomposition (GraphCompletionDecompositionRetriever) is the batch search’s main caller. One structured LLM
call splits the question into at most five sub-questions (falling back to the
question itself when the call fails), one batch search fetches their triplets, and
the batches are merged without duplicates. With
retriever_specific_config.decomposition_mode "answer_per_subquery" (the
default) each sub-question is answered over its own triplets, concurrently, and
the question is answered over those answers; "combined_triplets_context" answers
once over the merged triplets. Each context item carries a decomposition entry
(the sub-questions and the triplet’s rank in each) so the completion can rebuild
the per-sub-question contexts. An empty graph is NotFound, and a batch of
queries is rejected.
Graph report
GraphReport (GraphReportRetriever) ignores the query and reports on the whole graph from get_graph_data: the
top-top_k hubs (default 10) by normalised degree plus normalised PageRank
(networkx’s defaults, computed here), entity-to-entity edges across different node
sets, and EXTRACTED vs DERIVED edge counts, followed by LLM-suggested questions.
NodeSet containers and belongs_to_set edges are left out and parallel edges
count once. Its context is one item holding the Markdown report and the
structured hubs, connections and counts. An empty graph gets a fixed report,
not NotFound. PageRank is always computed, falling back to degree alone only
if it does not converge.
Temporal
Temporal is HybridCompletion reranked by the time window the question asks
about (TemporalHybridRetriever; it
replaces the Event-based TemporalRetriever, a breaking change). The hybrid
candidate fetch — chunks and entities at candidate_top_k, default 4 × top_k,
settable as retriever_specific_config.candidate_top_k — runs concurrently with
an LLM call that extracts the window (UTC, start inclusive, end exclusive;
relative dates are not resolved, so no clock is read). The chunks attached to the
Timestamp nodes inside the window join the candidates, the candidates attached
to one — directly, or for a chunk through an entity it contains — move to the
front, tightest date first (for “18 March 1965” a chunk dated that day beats one
that only says “1965”; dates at least as precise as the question keep their
similarity order), and the same cut plain hybrid uses keeps top_k. With nothing
to rerank by it answers with the plain hybrid result and records why:
empty_graph, no_time_constraint / invalid_interval (no window),
no_temporal_match, no_candidate_overlap (TemporalHybridRetriever::retrieve
returns these diagnostics with the context). An LLM or transport failure while
extracting the window fails the search instead of falling back, an empty graph
returns an empty context rather than NotFound, batch queries are rejected, and
search.triplet_neighbor_cap no longer applies to Temporal (search.hybrid
does). The Timestamp nodes are default cognify’s. A graph an older build
wrote with the removed event-graph temporal cognify
pipeline holds Event nodes nothing reads, so it gets plain hybrid answers. Under an attached
AclDb, Temporal results are no longer filtered by dataset membership: with
per-dataset storage it runs in each
dataset’s own databases, and over the shared store it runs unscoped like every
other type.
Related
Recall
Auto-routed search
Search configuration
Retriever settings
Cognify
What builds the graph