CogneeRetriever

Retrieve memories from a Cognee knowledge graph as ChatMessage objects.

Key Features

• Searches a Cognee knowledge graph and returns matching memories as ChatMessage instances.
• Supports multiple Cognee search strategies (for example, GRAPH_COMPLETION, CHUNKS, SUMMARIES).
• Scopes searches to a specific user by passing a user ID.
• Configurable top_k to limit the number of results returned.
• Works with CogneeWriter to form a complete memory read/write pair in agent pipelines.

Configuration

1. Drag the CogneeRetriever component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   1. Configure the memory_store with a CogneeMemoryStore, setting the search_type, top_k, and dataset_name.
   2. Optionally set a top_k on the retriever itself to override the store's default.

Connections

CogneeRetriever receives a natural-language query string and returns a list of ChatMessage objects containing the matching memories.

Use this component in agent pipelines to give the agent access to previously stored knowledge. Connect its messages output to a component that uses the retrieved context, such as a prompt builder.

Source Code

To check this component's source code, open memory_retriever.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  CogneeRetriever:
    type: haystack_integrations.components.retrievers.cognee.memory_retriever.CogneeRetriever
    init_parameters:
      memory_store:
        type: haystack_integrations.memory_stores.cognee.memory_store.CogneeMemoryStore
        init_parameters:
          search_type: GRAPH_COMPLETION
          top_k: 5
          dataset_name: haystack_memory
          session_id:
          self_improvement: true
          timeout: 300
      top_k: 5

Using the Component in a Pipeline

This is an example of a query pipeline that retrieves memories from Cognee to provide context for generating an answer.

# haystack-pipeline
components:
  CogneeRetriever:
    type: haystack_integrations.components.retrievers.cognee.memory_retriever.CogneeRetriever
    init_parameters:
      memory_store:
        type: haystack_integrations.memory_stores.cognee.memory_store.CogneeMemoryStore
        init_parameters:
          search_type: GRAPH_COMPLETION
          top_k: 5
          dataset_name: haystack_memory
          session_id:
          self_improvement: true
          timeout: 300
      top_k: 5

  llm:
    type: haystack.components.generators.chat.openai.OpenAIChatGenerator
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - OPENAI_API_KEY
        strict: false
      model: gpt-4o-mini

connections:
- sender: CogneeRetriever.messages
  receiver: llm.messages

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - CogneeRetriever.query

outputs:
  replies: llm.replies

Parameters

Inputs

Parameter	Type	Description
query	str	Natural-language query to search the Cognee knowledge graph.
top_k	Optional[int]	Per-call override for the maximum number of results to return. Falls back to the retriever's top_k, then the store's default.
user_id	Optional[str]	Cognee user UUID to scope the search to a specific user.

Outputs

Parameter	Type	Description
messages	List[ChatMessage]	The matching memories as ChatMessage objects.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
memory_store	CogneeMemoryStore		The backing CogneeMemoryStore to query. Configure it with search_type, top_k, dataset_name, and optionally session_id.
top_k	Optional[int]	None	Default maximum results to return. Falls back to the store's top_k when None.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
query	str		Natural-language query to search the Cognee knowledge graph.
top_k	Optional[int]	None	Per-call override for the number of results to return.
user_id	Optional[str]	None	Cognee user UUID to scope the search to a specific user.

Related Information

• CogneeWriter
• Pipeline Components