Cognee

Source documentation, not instructions for this website. Review permissions before running any commands.

import cognee
from cognee import SearchType

await cognee.add(
    "Your text, file path, URL, or list of inputs",
    dataset_name="main",
    node_set=["default_memory"],
)
await cognee.cognify(datasets="main")
results = await cognee.search(
    "What are the key insights?",
    query_type=SearchType.GRAPH_COMPLETION,
    datasets="main",
)

await cognee.add("notes.md", dataset_name="research")
await cognee.add("https://example.com", dataset_name="research")
await cognee.add(["paper.pdf", "summary.txt"], dataset_name="research")

await cognee.add(
    "Customer prefers concise weekly summaries and Slack delivery.",
    dataset_name="customer_success",
    node_set=["preferences", "customer_123", "weekly_reports"],
)

await cognee.cognify(datasets="research")

await cognee.cognify(
    datasets="research",
    temporal_cognify=True,
    chunk_size=1024,
    custom_prompt="Extract companies, products, and partnerships.",
)

results = await cognee.search(
    "What changed in Q1 2024?",
    query_type=SearchType.TEMPORAL,
    datasets="research",
    top_k=10,
)

results = await cognee.search(
    query_text="What are this customer's reporting preferences?",
    query_type=SearchType.GRAPH_COMPLETION,
    datasets="customer_success",
    node_name=["preferences", "customer_123"],
)

await cognee.memify(dataset="research")

from typing import Any
from pydantic import SkipValidation
from cognee.infrastructure.engine import DataPoint
from cognee.tasks.storage import add_data_points

class ScientificPaper(DataPoint):
    title: str
    authors: list[str]
    methodology: str
    findings: list[str]
    cites: SkipValidation[Any] = None
    metadata: dict = {"index_fields": ["title", "findings"]}

paper = ScientificPaper(
    title="Graph Memory for Agents",
    authors=["A. Researcher"],
    methodology="Knowledge graph + vector retrieval",
    findings=["Improved cross-session recall", "Better multi-hop retrieval"],
)

await add_data_points([paper])

from cognee.modules.pipelines.tasks.task import Task

async def my_task(data):
    return data

await cognee.run_custom_pipeline(
    tasks=[Task(my_task)],
    data="input",
    dataset="research",
)

await cognee.add(
    [
        "Alice prefers terse answers and email follow-ups.",
        "Alice escalates billing issues to finance first.",
        "Bob prefers detailed technical explanations."
    ],
    dataset_name="agent_memory",
    node_set=["crm", "user_profiles"],
)

await cognee.cognify(datasets="agent_memory")

results = await cognee.search(
    query_text="How should I respond to Alice?",
    datasets="agent_memory",
    node_name=["crm", "user_profiles"],
)

name: cognee
description: >
  Use this skill whenever the user asks about Cognee, AI memory, persistent agent memory,
  self-improving agents, agents learning from feednack, knowledge graphs, graph-based RAG,
  long-term memory for agents, short-term memory for agents, personalization, personas,
  temporal search,  temporal knowledge graphs, ontology-based extraction, ontology grounding,
  feedback, Cypher search, natural-language graph search, chunk search, RAG search, cross-session memory,
  session feedback, feedback loops, session based memory, redis based memory, knowledge promotion.
  Also use when the user describes the workflow such as:
  "turn documents into a knowledge graph", "build memory from files", "search my graph",
  "extract entities and relations", "sync data into a graph", "update graph memory",
  "store memories for an agent", "help my agent learn over time", "visualize a knowledge
  graph built from documents", "let the agent learn", "adaptive agents", "personalized agents",
  "session based personalization", "find important ontologies", "find custom pydantic models",
  "isolate agentic behaviour", "add permission control to retrieval", "reduce context bloating".

---
name: cognee
description: >
  Use this skill whenever the user asks about Cognee, AI memory, persistent agent memory,
  self-improving agents, agents learning from feednack, knowledge graphs, graph-based RAG,
  long-term memory for agents, short-term memory for agents, personalization, personas,
  temporal search,  temporal knowledge graphs, ontology-based extraction, ontology grounding,
  feedback, Cypher search, natural-language graph search, chunk search, RAG search, cross-session memory,
  session feedback, feedback loops, session based memory, redis based memory, knowledge promotion.
  Also use when the user describes the workflow such as:
  "turn documents into a knowledge graph", "build memory from files", "search my graph",
  "extract entities and relations", "sync data into a graph", "update graph memory",
  "store memories for an agent", "help my agent learn over time", "visualize a knowledge
  graph built from documents", "let the agent learn", "adaptive agents", "personalized agents",
  "session based personalization", "find important ontologies", "find custom pydantic models",
  "isolate agentic behaviour", "add permission control to retrieval", "reduce context bloating".
---

# Cognee

Use this skill for **Cognee-specific Python API help** and for mapping user goals to the right Cognee workflow.

## When to apply this skill

Apply this skill whenever the user wants to do any of the following with Cognee:

- ingest text, files, URLs, repos, or datasets
- build or rebuild a knowledge graph
- search documents, chunks, summaries, triplets, or graph context
- choose a `SearchType`
- enrich an existing graph with `memify`
- define custom graph extraction models or `DataPoint` types
- run custom task pipelines
- configure LLM, graph DB, vector DB, or storage settings
- tag and scope memory with `node_set` / NodeSets
- build persistent memory for agents across sessions
- create feedback loops or self-improving agent workflows
- work with temporal extraction, ontologies, Cypher, or natural-language graph queries
- manage datasets, sessions, feedback, pruning, updates, or visualization

If the user’s intent is “store information in memory and query it later,” prefer Cognee’s core flow:
**add -> cognify -> search**

## Core workflow

```python
import cognee
from cognee import SearchType

await cognee.add(
    "Your text, file path, URL, or list of inputs",
    dataset_name="main",
    node_set=["default_memory"],
)
await cognee.cognify(datasets="main")
results = await cognee.search(
    "What are the key insights?",
    query_type=SearchType.GRAPH_COMPLETION,
    datasets="main",
)
```

## Default guidance

When helping with Cognee:

1. Start with the **simplest working path** unless the user explicitly asks for advanced configuration.
2. Prefer the standard workflow:
   - `add(...)` to ingest
   - `cognify(...)` to build the graph
   - `search(...)` to query it
3. Treat Cognee APIs as **async**.
4. Use `dataset_name` / `datasets` to keep work organized when the user has multiple sources.
5. Use `node_set` when the user wants lightweight tagging, project scoping, per-user memory buckets, or subgraph filtering.
6. Recommend advanced features only when they match the task:
   - `memify(...)` for enriching an existing graph
   - `temporal_cognify=True` for time-aware extraction
   - custom graph models or `DataPoint` types for domain-specific extraction
   - custom pipelines for non-default task orchestration
   - feedback loops for retrieval improvement
   - visualization tools for graph inspection

## Common tasks

### Add data

Use `cognee.add(...)` for text, files, URLs, or mixed inputs.

```python
await cognee.add("notes.md", dataset_name="research")
await cognee.add("https://example.com", dataset_name="research")
await cognee.add(["paper.pdf", "summary.txt"], dataset_name="research")
```

Use `node_set` when the user wants data grouped into logical memory buckets.

```python
await cognee.add(
    "Customer prefers concise weekly summaries and Slack delivery.",
    dataset_name="customer_success",
    node_set=["preferences", "customer_123", "weekly_reports"],
)
```

### Build the graph

Use `cognee.cognify(...)` after ingestion.

```python
await cognee.cognify(datasets="research")
```

Use these options when relevant:

```python
await cognee.cognify(
    datasets="research",
    temporal_cognify=True,
    chunk_size=1024,
    custom_prompt="Extract companies, products, and partnerships.",
)
```

### Search the graph

Use `cognee.search(...)` and pick the search mode that matches the request.

```python
results = await cognee.search(
    "What changed in Q1 2024?",
    query_type=SearchType.TEMPORAL,
    datasets="research",
    top_k=10,
)
```

### Scope search with NodeSets

Use NodeSets when the user wants to search only a subset of memory such as one project, one customer, one user, or one workflow.

```python
results = await cognee.search(
    query_text="What are this customer's reporting preferences?",
    query_type=SearchType.GRAPH_COMPLETION,
    datasets="customer_success",
    node_name=["preferences", "customer_123"],
)
```

### Enrich an existing graph

Use `memify(...)` when the user wants to improve or extend an already-built graph without restarting the full workflow.

```python
await cognee.memify(dataset="research")
```

### Create domain-specific structures

Use custom models when the user wants extraction shaped around a schema.

```python
from typing import Any
from pydantic import SkipValidation
from cognee.infrastructure.engine import DataPoint
from cognee.tasks.storage import add_data_points

class ScientificPaper(DataPoint):
    title: str
    authors: list[str]
    methodology: str
    findings: list[str]
    cites: SkipValidation[Any] = None
    metadata: dict = {"index_fields": ["title", "findings"]}

paper = ScientificPaper(
    title="Graph Memory for Agents",
    authors=["A. Researcher"],
    methodology="Knowledge graph + vector retrieval",
    findings=["Improved cross-session recall", "Better multi-hop retrieval"],
)

await add_data_points([paper])
```

### Run custom pipelines

Use `run_custom_pipeline(...)` when the user needs explicit sequential task control.

```python
from cognee.modules.pipelines.tasks.task import Task

async def my_task(data):
    return data

await cognee.run_custom_pipeline(
    tasks=[Task(my_task)],
    data="input",
    dataset="research",
)
```

## DataPoints

A `DataPoint` is the **atomic unit of knowledge** in Cognee.

Use this concept whenever the user asks how Cognee represents structured data internally or how to insert graph objects directly.

Key ideas:

- A `DataPoint` is a Pydantic model that represents one meaningful unit of information.
- It can carry both **content** and **context**, including indexing hints and relationship fields.
- When inserted directly, DataPoints can become graph nodes and edges while also contributing searchable vector fields.
- `metadata = {"index_fields": [...]}` controls which fields should be embedded for semantic search.
- Relationship fields can point to other DataPoints, letting you define graph structure programmatically.
- DataPoints are ideal when the user already has structured objects and does **not** want to rely only on text extraction.

Use `DataPoint` when the user wants:

- schema-shaped memory
- exact control over graph structure
- programmatic relationship creation
- custom domain entities such as papers, customers, incidents, policies, products, or workflows

Prefer plain `add(...) -> cognify(...)` for unstructured documents.
Prefer `DataPoint` models plus `add_data_points(...)` when the user already has structured Python objects and wants direct graph insertion.

## NodeSets

Use NodeSets when the user wants a lightweight way to **tag, group, and scope memory**.

A NodeSet starts as a simple list of tags passed through `node_set=[...]` during `add(...)`, but after `cognify()` those tags become first-class graph nodes that help organize retrieval.

### Why NodeSets matter

- They let the user organize memory by project, team, customer, workflow, topic, or environment.
- They make it easy to search only a relevant subgraph instead of the full dataset.
- They are especially useful in agent systems where one memory store contains many users, jobs, or tasks.

### Good NodeSet patterns

- per customer: `["customer_123"]`
- per workflow: `["support_bot", "refund_flow"]`
- per topic: `["contracts", "vendor_risk"]`
- per environment: `["prod", "staging"]`
- per user memory: `["user_42", "preferences"]`

### Example

```python
await cognee.add(
    [
        "Alice prefers terse answers and email follow-ups.",
        "Alice escalates billing issues to finance first.",
        "Bob prefers detailed technical explanations."
    ],
    dataset_name="agent_memory",
    node_set=["crm", "user_profiles"],
)

await cognee.cognify(datasets="agent_memory")

results = await cognee.search(
    query_text="How should I respond to Alice?",
    datasets="agent_memory",
    node_name=["crm", "user_profiles"],
)
```

Use NodeSets by default whenever the user says things like:

- “scope memory by customer”
- “separate projects without making separate databases”
- “let the agent search only its own memories”
- “group facts by workflow or team”

## SearchType selection guide

Use these defaults:

- `GRAPH_COMPLETION`: best default for graph-aware Q&A
- `RAG_COMPLETION`: traditional RAG over document chunks
- `CHUNKS`: fast semantic retrieval without completion
- `CHUNKS_LEXICAL`: exact-term / keyword matching
- `SUMMARIES`: overview of documents
- `TRIPLET_COMPLETION`: subject-predicate-object style graph Q&A
- `GRAPH_SUMMARY_COMPLETION`: graph + summary-based answers
- `GRAPH_COMPLETION_COT`: deeper reasoning over graph context
- `GRAPH_COMPLETION_CONTEXT_EXTENSION`: broader graph context retrieval
- `CYPHER`: raw Cypher queries when enabled
- `NATURAL_LANGUAGE`: natural language to graph query
- `TEMPORAL`: time-aware graph search
- `CODING_RULES`: code rules and patterns
- `CODE`: deterministic code fact lookup, graph traversal, paths, and impact analysis
- `FEELING_LUCKY`: let Cognee choose automatically
- `FEEDBACK`: apply feedback to improve later retrieval behavior

## Agentic workflows and feedback-driven improvement

Use Cognee as the **memory layer for agent systems** that need to improve over time through better recall, better reuse of prior work, and better retrieval of successful past behavior.

The key idea is simple:

- keep the **agent workflow itself constant**
- keep the **prompt and tools constant**
- change only what the agent can remember and retrieve

This means “improvement” comes from **memory reuse and retrieval quality**, not from changing the model or retraining it.

### What Cognee gives agentic workflows

Cognee helps agent systems:

- store observations, decisions, outcomes, and learned patterns as memory
- retrieve graph-aware context instead of relying only on flat chunk search
- reuse prior investigations, plans, and successful resolutions
- preserve short-term context through sessions
- consolidate useful session history into long-term knowledge
- scope memory by user, customer, workflow, team, or environment with datasets and NodeSets
- improve future behavior through feedback loops and memory enrichment

### The general feedback pattern

A strong way to explain Cognee in agent systems is:

1. **Baseline condition**
   The agent searches the existing knowledge graph and acts using only current stored knowledge.

2. **Feedback-enabled condition**
   The agent uses the same prompt and the same tools, but now benefits from:
   - **short-term memory** from cached or sessionized interactions
   - **long-term memory** created by periodically persisting useful sessions back into the graph

3. **Improvement mechanism**
   Future runs become faster or better because the agent can retrieve:
   - similar prior cases
   - successful resolutions