Skip to content

Commit f103bc4

Browse files
bilgeyucelbilgeyucel
authored
Add the cognee integration page (#500)
* Add the cognee integration page * add missing logo * Add the cognee integration page * add missing logo
1 parent c3e0226 commit f103bc4

2 files changed

Lines changed: 153 additions & 0 deletions

File tree

‎integrations/cognee.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
layout: integration
3+
name: Cognee
4+
description: Add persistent, knowledge-graph-backed memory to your Haystack agents and pipelines with Cognee
5+
authors:
6+
- name: deepset
7+
socials:
8+
github: deepset-ai
9+
twitter: haystack_ai
10+
linkedin: https://www.linkedin.com/company/deepset-ai/
11+
- name: Cognee
12+
socials:
13+
github: topoteretes
14+
twitter: cognee_ai
15+
linkedin: https://www.linkedin.com/company/cognee-ai/
16+
pypi: https://pypi.org/project/cognee-haystack/
17+
repo: https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/cognee
18+
type: Memory Store
19+
report_issue: https://github.com/deepset-ai/haystack-core-integrations/issues
20+
logo: /logos/cognee.png
21+
version: Haystack 2.0
22+
toc: true
23+
---
24+
25+
### **Table of Contents**
26+
27+
- [Overview](#overview)
28+
- [Installation](#installation)
29+
- [Usage](#usage)
30+
- [Available Classes](#available-classes)
31+
- [Use in a Pipeline](#use-in-a-pipeline)
32+
- [License](#license)
33+
34+
## Overview
35+
36+
[Cognee](https://www.cognee.ai/) provides open-source, knowledge-graph-backed memory for AI agents and assistants. It helps Haystack applications store facts, conversation history, and contextual knowledge as a semantic graph, then retrieve the most relevant memories using graph-completion or other search strategies.
37+
38+
The `cognee-haystack` package is part of [Haystack Core Integrations](https://github.com/deepset-ai/haystack-core-integrations) and provides:
39+
40+
- `CogneeMemoryStore`: A persistent memory store backed by Cognee's knowledge graph API.
41+
- `CogneeRetriever`: A pipeline component for retrieving memories from Cognee as system `ChatMessage` objects.
42+
- `CogneeWriter`: A pipeline component for writing `ChatMessage` memories to Cognee.
43+
44+
Cognee supports two memory tiers:
45+
46+
- **Permanent knowledge graph** — rich semantic storage backed by an LLM extraction step; supports graph-completion queries and cross-session recall.
47+
- **Session cache** — fast, LLM-free writes scoped to a single session; can be promoted to the permanent graph later via `CogneeMemoryStore.improve()`.
48+
49+
## Installation
50+
51+
Install the integration:
52+
53+
```bash
54+
pip install cognee-haystack
55+
```
56+
57+
Set your LLM API key (used by Cognee for knowledge graph extraction and queries):
58+
59+
```bash
60+
export LLM_API_KEY="your-llm-api-key"
61+
```
62+
63+
Optionally, set a separate embedding API key (defaults to `LLM_API_KEY` when unset):
64+
65+
```bash
66+
export EMBEDDING_API_KEY="your-embedding-api-key"
67+
```
68+
69+
Cognee reads LLM provider, database, and vector-store settings from environment variables. See the [Cognee documentation](https://docs.cognee.ai) for the full list of configuration options.
70+
71+
## Usage
72+
73+
### Available Classes
74+
75+
- [`CogneeRetriever`](https://docs.haystack.deepset.ai/docs/cogneeretriever): Retrieves memories from Cognee as system `ChatMessage` objects.
76+
- [`CogneeWriter`](https://docs.haystack.deepset.ai/docs/cogneewriter): Writes `ChatMessage` objects to Cognee.
77+
- [`CogneeMemoryStore`](https://docs.haystack.deepset.ai/reference/integrations-cognee#cogneememorystore): The underlying store that wraps Cognee's V2 memory API (`remember`, `recall`, `improve`, `forget`).
78+
79+
### Use in a Pipeline
80+
81+
Use `CogneeRetriever` and `CogneeWriter` for explicit pipeline control over when memories are stored and retrieved.
82+
83+
The example below seeds long-lived facts into the permanent knowledge graph, then runs an agent pipeline that retrieves relevant context before each response. `cognee.recall` auto-captures each turn as a session QA entry, so no `CogneeWriter` is needed inside the agent pipeline for session memory.
84+
85+
```python
86+
from haystack import Pipeline
87+
from haystack.components.agents import Agent
88+
from haystack.components.converters import OutputAdapter
89+
from haystack.components.generators.chat import OpenAIChatGenerator
90+
from haystack.dataclasses import ChatMessage
91+
92+
from haystack_integrations.components.retrievers.cognee import CogneeRetriever
93+
from haystack_integrations.components.writers.cognee import CogneeWriter
94+
from haystack_integrations.memory_stores.cognee import CogneeMemoryStore
95+
96+
# Seed long-lived facts into the permanent knowledge graph (no session_id).
97+
seed_store = CogneeMemoryStore(dataset_name="my_agent_memory", self_improvement=False)
98+
persistent_writer = CogneeWriter(memory_store=seed_store)
99+
persistent_writer.run(
100+
messages=[
101+
ChatMessage.from_user("Alice is a senior data scientist specialising in NLP."),
102+
ChatMessage.from_user("Alice's current project is a documentation search system built with Haystack."),
103+
ChatMessage.from_user("Alice prefers concise answers with Python code examples."),
104+
]
105+
)
106+
107+
# Build the agent pipeline with a session-scoped store.
108+
SESSION = "alice_session_1"
109+
chat_store = CogneeMemoryStore(dataset_name="my_agent_memory", session_id=SESSION)
110+
111+
pipeline = Pipeline()
112+
pipeline.add_component("retriever", CogneeRetriever(memory_store=chat_store))
113+
pipeline.add_component(
114+
"memory_context",
115+
OutputAdapter(
116+
template="{{ memories + user_messages }}",
117+
output_type=list[ChatMessage],
118+
unsafe=True,
119+
),
120+
)
121+
pipeline.add_component(
122+
"agent",
123+
Agent(
124+
chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
125+
system_prompt=(
126+
"You are a helpful assistant with long-term memory. "
127+
"System messages at the start of the conversation contain relevant memories. "
128+
"Be concise; prefer short answers and Python code examples."
129+
),
130+
),
131+
)
132+
133+
pipeline.connect("retriever.messages", "memory_context.memories")
134+
pipeline.connect("memory_context.output", "agent.messages")
135+
136+
query = "What project is Alice currently working on?"
137+
result = pipeline.run(
138+
{
139+
"retriever": {"query": query},
140+
"memory_context": {"user_messages": [ChatMessage.from_user(query)]},
141+
}
142+
)
143+
print(result["agent"]["last_message"].text)
144+
145+
# After the session, promote the session cache into the permanent graph.
146+
chat_store.improve()
147+
```
148+
149+
For a full four-phase demo (persistent seeding → session seeding → agent chat → graph promotion), see the [example script](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/cognee/examples/demo_memory_agent.py).
150+
151+
## License
152+
153+
`cognee-haystack` is distributed under the terms of the [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) license.

‎logos/cognee.png‎

1.18 MB
Loading

0 commit comments

Comments
 (0)