Skip to main content

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 by SearchType (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. With only_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. 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.

Recall

Auto-routed search

Search configuration

Retriever settings

Cognify

What builds the graph