Set up Cognee with an AI agent

name: cognee
description: Use when building AI memory systems, integrating knowledge graphs
  into agents, ingesting and retrieving documents, managing multi-user datasets,
  or deploying persistent memory backends. Reach for Cognee when you need to
  give LLM agents long-term, connected memory beyond simple RAG.
metadata:
  mintlify-proj: cognee
  version: "1.0"

Cognee Skill Reference

Product Summary

Cognee is an open-source memory layer for AI agents that combines vector search with knowledge graphs. It transforms raw documents into searchable, connected memory through a three-store architecture: relational (metadata/provenance), vector (embeddings), and graph (entities/relationships). Use it from Python, REST API, CLI, or MCP-compatible clients (Claude, Cursor, Cline). The core workflow is remember (ingest data), recall (query memory), improve (enrich graph), and forget (delete). Key files: .env for configuration, Python SDK via import cognee, HTTP API at /api/v1/*, MCP server at cognee-mcp. Primary docs: https://docs.cognee.ai

When to Use

• Ingesting documents: Call remember() to store text, files, URLs, or code repositories as permanent graph memory or fast session memory
• Querying with context: Use recall() to ask questions and get LLM-written answers with graph-backed retrieval (semantic + structural)
• Building agent memory: Decorate agent functions with @cognee.agent_memory to attach persistent memory retrieval and trace recording
• Session-based conversations: Pass session_id to remember() and recall() for fast conversational memory that bridges into the permanent graph
• Multi-user/multi-tenant: Configure datasets, permissions, and roles for isolated data access across users
• Deployment: Use Docker, REST API, or MCP server to expose memory to multiple clients or agents
• Graph enrichment: Call improve() to add derived structures (summaries, global context index) or bridge session memory into permanent storage
• Cleanup: Use forget() to delete specific items, entire datasets, or all user data

Quick Reference

Core Operations

Operation	Purpose	Example
remember()	Store data (permanent or session)	await cognee.remember("text", dataset_name="docs")
recall()	Query memory with auto-routing	await cognee.recall("What is X?", datasets=["docs"])
improve()	Enrich graph, bridge sessions	await cognee.improve(dataset_name="docs")
forget()	Delete items/datasets/user data	await cognee.forget(dataset_name="docs")
serve()	Connect to remote Cognee instance	await cognee.serve(url="...", api_key="...")

Configuration (.env)

Variable	Default	Purpose
LLM_PROVIDER	openai	LLM: openai, azure, anthropic, ollama, bedrock, custom
LLM_MODEL	openai/gpt-5.6-luna	Model in provider/model-name format
LLM_API_KEY	—	API key for LLM provider
EMBEDDING_PROVIDER	openai	Embeddings: openai, ollama, fastembed, gemini, bedrock
EMBEDDING_MODEL	openai/text-embedding-3-large	Embedding model
EMBEDDING_DIMENSIONS	3072 (fallback)	Must match vector store
DB_PROVIDER	sqlite	Relational: sqlite, postgres
VECTOR_DB_PROVIDER	lancedb	Vector store: lancedb, pgvector, qdrant, chromadb
GRAPH_DATABASE_PROVIDER	ladybug	Graph: ladybug, neo4j, memgraph, neptune
SYSTEM_ROOT_DIRECTORY	.cognee_system	Cognee-managed databases
DATA_ROOT_DIRECTORY	.data_storage	Raw ingested source files
CACHING	true	Enable session memory cache
CACHE_BACKEND	sqlite	Cache: sqlite, redis

Search Types (for recall())

Type	Source	Use When
HYBRID_COMPLETION	Vector + Graph	Default; semantic + structural reasoning
RAG_COMPLETION	Vector	Traditional semantic search + LLM answer
GRAPH_COMPLETION	Graph	Entity/relationship traversal
CHUNKS_LEXICAL	Lexical	Keyword search (no embeddings)
TEMPORAL	Vector + Graph	Time-aware queries
CYPHER	Graph	Direct Cypher queries
BROAD	Graph + Vector	Whole-dataset questions (counts, lists)

File Formats Supported

Built-in: .py, .js, .ts, .go, .rs, .java, .txt, .md, .json, .xml, .yaml, .pdf, .png, .jpg, .mp3, .wav, .csv

With extras: .docx, .xlsx, .pptx, .html, .eml (install cognee[docs] or cognee[scraping])

Decision Guidance

When to Use remember() vs Session Memory

Scenario	Use
Store documents for long-term retrieval	remember(data, dataset_name="...") (permanent)
Fast conversational memory in one session	remember(data, session_id="chat_1") (session)
Bridge session into permanent graph later	improve(dataset_name="...", session_ids=["chat_1"])
Lightweight, no graph overhead	Session memory (writes to cache only)
Need graph structure immediately	Permanent memory (runs full pipeline)

When to Use Which Search Type

Question Type	Search Type
"What is X?" (semantic match)	HYBRID_COMPLETION (default)
"Find exact phrase" (quoted)	CHUNKS_LEXICAL
"When did X happen?" (time-aware)	TEMPORAL
"List all entities of type Y"	BROAD
"Traverse relationships from X"	GRAPH_COMPLETION
"Custom Cypher query"	CYPHER

When to Use Python SDK vs REST API vs MCP

Use Case	Interface
Local Python agent/notebook	Python SDK (import cognee)
Deployed service, multiple clients	REST API (/api/v1/*)
IDE integration (Claude Code, Cursor)	MCP server (cognee-mcp)
Shared knowledge graph across teams	Cognee Cloud + REST API

Workflow

1. Setup & Configuration

• Create .env with LLM_API_KEY and optional database/embedding overrides
• Cognee loads .env once at import; restart Python after changes
• Verify with cognee-cli demo (no API key needed; uses local GLiNER + fastembed)

2. Ingest Data (Remember)

import cognee

# Permanent memory (full pipeline)
result = await cognee.remember(
    "Your text or file path",
    dataset_name="docs"
)

# Session memory (fast, optional bridge)
await cognee.remember(
    "Quick note",
    session_id="chat_1"
)

3. Query Memory (Recall)

# Auto-routed search (default)
answers = await cognee.recall(
    "What is X?",
    datasets=["docs"]
)

# Explicit search type
answers = await cognee.recall(
    "What is X?",
    datasets=["docs"],
    query_type=SearchType.GRAPH_COMPLETION
)

4. Enrich & Bridge (Improve)

# Bridge session into permanent graph
await cognee.improve(
    dataset_name="docs",
    session_ids=["chat_1"]
)

5. Cleanup (Forget)

# Delete one item
await cognee.forget(dataset_name="docs", data_id="item_uuid")

# Delete entire dataset
await cognee.forget(dataset_name="docs")

# Delete all user data
await cognee.forget()

6. Deploy (Optional)

# REST API server
docker run -e LLM_API_KEY=... -p 8000:8000 cognee/cognee:main

# MCP server (for IDE integration)
cognee-mcp --port 5000

Common Gotchas

• Embedding dimensions mismatch: If you change EMBEDDING_MODEL or EMBEDDING_DIMENSIONS, run cognee.prune.prune_system(metadata=True) before next cognify() to clear incompatible vectors
• Session memory disabled: If CACHING=false, remember(..., session_id=...) cannot persist session content; enable it or use permanent memory
• File paths in session mode: remember(..., session_id=...) does not fetch URLs or read files; pass text directly or use permanent mode
• Concurrent writes to embedded databases: SQLite, LanceDB, and Ladybug must not be shared across processes; use external stores (Postgres, Neo4j, Qdrant) for multi-process deployments
• Graph not indexed yet: If recall() returns a "memory_indexing" marker, the graph is still building; wait for DATASET_PROCESSING_COMPLETED status before relying on graph-backed results
• Ontology too broad: Public ontologies (Wikidata, DBpedia) are too large; always use a curated subset relevant to your domain
• Provenance tracking overhead: PROVENANCE_TRACKING=true adds audit-ledger entries for every document/chunk/entity; leave off by default unless you need full lineage
• Conflict detection: IMPROVE_REVIEW_CONFLICTS=true (default) detects contradictions; set to false to skip if you don't need conflict resolution
• LLM-free mode: Set GRAPH_EXTRACTOR="gliner_demo" to extract graphs without an LLM key (uses local GLiNER model)

Verification Checklist

Before submitting work with Cognee:

• .env is in project root and contains LLM_API_KEY (or GRAPH_EXTRACTOR="gliner_demo" for LLM-free mode)
• remember() completed with status="completed" or status="session_stored" (check result.status)
• Dataset status is DATASET_PROCESSING_COMPLETED before calling recall() on permanent memory
• recall() returns results with source field indicating retrieval source (graph, session, trace, etc.)
• Session memory is bridged to permanent graph via improve() if long-term persistence is needed
• Permissions are configured correctly for multi-user scenarios (use cognee.datasets API)
• Embedding dimensions match between EMBEDDING_DIMENSIONS and vector store configuration
• No concurrent writes to embedded databases (SQLite, LanceDB, Ladybug) from multiple processes
• Ontology (if used) is a curated subset, not a full public ontology
• Cleanup is tested: forget() removes data as expected

Resources

Comprehensive navigation: https://docs.cognee.ai/llms.txt

Critical documentation pages:

1. Core Concepts Overview — Architecture, building blocks, main operations
2. Python API Reference — Complete SDK reference for remember, recall, improve, forget
3. Setup Configuration — LLM, embedding, database configuration with copy-paste .env blocks

---

For additional documentation and navigation, see: https://docs.cognee.ai/llms.txt