---
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)
```python
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)
```python
# 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)
```python
# Bridge session into permanent graph
await cognee.improve(
    dataset_name="docs",
    session_ids=["chat_1"]
)
```

### 5. Cleanup (Forget)
```python
# 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)
```bash
# 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](https://docs.cognee.ai/core-concepts/overview) — Architecture, building blocks, main operations
2. [Python API Reference](https://docs.cognee.ai/python-api/index) — Complete SDK reference for remember, recall, improve, forget
3. [Setup Configuration](https://docs.cognee.ai/setup-configuration/overview) — LLM, embedding, database configuration with copy-paste `.env` blocks

---

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