# https://github.com/topoteretes/cognee Project Manual Generated at: 2026-06-20 19:51:54 UTC ## Table of Contents - [Overview, Core Operations, and System Architecture](#page-overview) - [Multi-User Access Control, Tenants, and Datasets](#page-permissions) - [Retrieval System, Search Modes, and Evaluation](#page-retrieval) - [Deployment, LLM and Database Configuration, and Extensibility](#page-deployment) ## Overview, Core Operations, and System Architecture ### Related Pages Related topics: [Multi-User Access Control, Tenants, and Datasets](#page-permissions), [Retrieval System, Search Modes, and Evaluation](#page-retrieval), [Deployment, LLM and Database Configuration, and Extensibility](#page-deployment)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/topoteretes/cognee/blob/main/README.md) - [cognee-mcp/README.md](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/README.md) - [cognee-mcp/src/server.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py) - [cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py) - [cognee/tasks/summarization/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md) - [cognee/tasks/codingagents/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/codingagents/README.md) - [cognee/tasks/web_scraper/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/web_scraper/README.md) - [examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md) - [examples/pocs/disambiguation/README.md](https://github.com/topoteretes/cognee/blob/main/examples/pocs/disambiguation/README.md)
# Overview, Core Operations, and System Architecture ## 1. Purpose and Scope Cognee is an open-source AI memory platform that gives AI agents persistent long-term memory across sessions. It ingests data in any format, builds a self-hosted knowledge graph, and lets every agent recall, connect, and act with full context. Source: [README.md]() The platform is designed around four pillars: - **Knowledge infrastructure** — unified ingestion, graph/vector search, local execution, ontology grounding, and multimodal support. - **Persistent and learning agents** — feedback loops, context management, cross-agent knowledge sharing. - **Reliable and trustworthy agents** — agentic user/tenant isolation, traceability, OTEL collector, audit trails. - **Domain knowledge enablement** — analysts and teams can place and enable agents with proprietary context. Source: [README.md]() Cognee is shipped both as a Python SDK (`cognee`) and as an MCP server (`cognee-mcp`), exposing the same primitives (`add`, `cognify`, `search`, `memify`) to LLMs, agents, and developer tools. Source: [cognee-mcp/README.md]() ## 2. Core Operations The user-facing API is small and stable. Every higher-level feature is composed from these primitives. ### 2.1 `add` — Ingestion `cognee.add()` accepts text, file paths, URLs, multimedia, and structured data, registers a dataset, and stages raw content for transformation. The MCP server implements this as the `cognify` tool, which performs type classification, permission validation, text chunking, entity extraction, relationship detection, graph construction, and content summarization in one background task. Source: [cognee-mcp/src/server.py]() > Community note: a known class of bugs surfaces when JSON inputs are uploaded to `cognify` (see issue #3079). Filename-collision and ACL-related edge cases around `cognee.add()` are tracked in issues #2846 and #2847, where a non-owner calling `add` with an existing dataset name silently creates a new owner-scoped dataset. ### 2.2 `cognify` — Knowledge Graph Construction `cognee.cognify()` (executed by the `cognify` MCP tool) is the central transformation pipeline: 1. Classifies document types and structures. 2. Validates processing rights. 3. Splits content into semantically meaningful chunks. 4. Extracts entities (people, places, organizations, concepts). 5. Detects relationships between entities. 6. Builds a semantic knowledge graph with embeddings. 7. Generates hierarchical summaries for navigation. Source: [cognee-mcp/src/server.py]() Optional parameters `graph_model_file`, `graph_model_name`, and `custom_prompt` allow overriding the schema and the LLM extraction prompt. Source: [cognee-mcp/src/server.py]() > Community note: v1.1.0 introduced the Global Context Index and initial Postgres multi-user graph support to improve how `cognify` output is shared across users. Issue #2847 documents that `cognify` can silently skip data attached by non-owner users even when the dataset row is correctly attached. ### 2.3 `search` — Multi-Mode Retrieval The `search` operation supports several modes described in the MCP server tool docs: | Mode | Description | |------|-------------| | `GRAPH_COMPLETION` | LLM response grounded on graph context | | `RAG_COMPLETION` | LLM response grounded on document chunks | | `CHUNKS` | Raw text chunks from the knowledge graph | | `SUMMARIES` | Pre-generated hierarchical summaries | | `CODE` | Structured code knowledge in JSON format | | `CYPHER` | Direct graph-database queries | | `FEELING_LUCKY` | Automatically selects the best mode | Source: [cognee-mcp/src/server.py]() `top_k` defaults to 10 and is case-insensitive. Retrieval-quality benchmarking across these modes is an open enhancement request (issue #2913), and `SearchType.TEMPORAL` is positioned as a foundation for future freshness policies (issue #3004). ACL-aware resolution on `cognee.search` for non-owners is tracked in issue #2845, where name-based lookup returns `DatasetNotFoundError` instead of consulting permissions. ### 2.4 `memify` — Enrichment `memify` is the enrichment pipeline. It includes the coding-rule association task by default, extracting developer rules from text and linking them to their source `DocumentChunk` via `rule_associated_from` edges. Source: [cognee/tasks/codingagents/README.md]() Summarization is the final step of `cognify` (Task #4) and produces `TextSummary` and `CodeSummary` nodes that extend `DataPoint`. Source: [cognee/tasks/summarization/README.md]() ## 3. System Architecture The runtime is layered: an HTTP/CLI surface, an MCP interface for agents, a pipeline orchestrator, and pluggable storage backends. ```mermaid flowchart LR A[Client / Agent] -->|add / cognify / search / memify| B[MCP Server or SDK] B --> C[Pipeline Tasks] C --> D[LLM Gateway
LiteLLM] C --> E[Vector DB
ChromaDB, others] C --> F[Graph DB
Kuzu, Neo4j, etc.] C --> G[Relational DB
SQLite / Postgres] B --> H[Web Scraper] H --> C ``` - The **MCP server** (`cognee-mcp/src/server.py`) exposes the same primitives to LLM agents and provides graph-backed retrieval helpers via `cognee-mcp/src/retrieval_utils.py`, which normalizes node shapes from different graph adapters into a uniform dictionary for downstream rendering. - The **pipeline orchestrator** composes tasks like `web_scraper_task`, `extract_graph_from_data`, `summarize_text`, and `add_rule_associations`. Source: [cognee/tasks/web_scraper/README.md](), [cognee/tasks/summarization/README.md](), [cognee/tasks/codingagents/README.md]() - **Storage is pluggable**: graph backends include Kuzu (default), Neo4j, and Neptune Analytics; vector backends include ChromaDB; relational storage supports SQLite and Postgres, with multi-user Postgres graph support added in v1.1.0. > Community note: LiteLLM ignores `LLM_ENDPOINT` for OpenAI-compatible APIs (issue #2842); users have to set `OPENAI_API_BASE` to route to a custom OpenAI-compatible endpoint. ## 4. Configuration, Backends, and Deployment Cognee is configured primarily through environment variables. The minimum requirement is `LLM_API_KEY`; common optional keys include `LLM_PROVIDER`, `LLM_MODEL`, `VECTOR_DB_PROVIDER`, `GRAPH_DATABASE_PROVIDER`, and rate-limit knobs (`LLM_RATE_LIMIT_ENABLED`, `LLM_RATE_LIMIT_REQUESTS`). Source: [cognee-mcp/src/server.py]() The `examples/` tree is organized by intent: - `demos/` for broad feature walk-throughs (e.g., `simple_cognee_example.py`, `web_url_content_ingestion_example.py`). - `guides/` for focused how-tos (e.g., `agent_memory_quickstart.py`, `temporal_recall.py`, `custom_data_models.py`). - `custom_pipelines/` for end-to-end pipeline composition (e.g., `memify_coding_agent_rule_extraction_example.py`). - `database_examples/` for per-backend smoke tests (Kuzu, Neo4j, Neptune Analytics, ChromaDB, Postgres). - `pocs/` for research work, including entity disambiguation experiments that bias extraction toward canonical entities via vector lookup over `Entity_name`. Source: [examples/README.md](), [examples/pocs/disambiguation/README.md]() Deployment targets include Cognee Cloud, Modal, Railway, Fly.io, Render, and Daytona sandboxes; deploy scripts live under `distributed/deploy/`. Source: [README.md]() Release history (v1.1.0 → v1.1.2) emphasizes reliability: schema fixes for silent varchar truncation (v1.1.1.dev0), Postgres multi-user graph support and simplified backend ACL (v1.1.0), agent lifecycle and visualization refinements (v1.1.1), and search-quality/UX polish (v1.1.2). Source: [README.md]() ## See Also - [MCP Server & Agent Tooling](cognee-mcp/README.md) - [Summarization Pipeline](cognee/tasks/summarization/README.md) - [Coding Agents / Rule Extraction](cognee/tasks/codingagents/README.md) - [Web Scraper Task](cognee/tasks/web_scraper/README.md) - [Examples Catalog](examples/README.md) - [Entity Disambiguation POC](examples/pocs/disambiguation/README.md) --- ## Multi-User Access Control, Tenants, and Datasets ### Related Pages Related topics: [Overview, Core Operations, and System Architecture](#page-overview), [Deployment, LLM and Database Configuration, and Extensibility](#page-deployment)
Related Source Files The following source files were used to generate this page: - [cognee/modules/users/models/ACL.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/ACL.py) - [cognee/modules/users/models/Permission.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/Permission.py) - [cognee/modules/users/models/Tenant.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/Tenant.py) - [cognee/modules/users/models/Role.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/Role.py) - [cognee/modules/users/models/User.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/User.py) - [cognee/modules/users/models/UserTenant.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/UserTenant.py) - [examples/configurations/permissions_example/](https://github.com/topoteretes/cognee/tree/main/examples/configurations/permissions_example) - [cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py) - [README.md](https://github.com/topoteretes/cognee/blob/main/README.md)
# Multi-User Access Control, Tenants, and Datasets ## Overview and Purpose Cognee ships an optional, backend-enforced access control layer that lets multiple users share a single deployment without leaking memories across accounts. The v1.1.0 release notes summarize the goal: introduce "initial Postgres multi-user graph support" while "simplifying backend access control configuration" ([README.md](https://github.com/topoteretes/cognee/blob/main/README.md)). When enabled, every `cognee.add`, `cognee.cognify`, and `cognee.search` call can be scoped to a user, a tenant, and a permission set so that data ingestion and retrieval are tenant-aware by default. The model is built on six persistent entities that together express who is calling Cognee, which tenant they belong to, what role they play there, and which datasets they can read or write. The system relies on these entities plus the `ENABLE_BACKEND_ACCESS_CONTROL` flag, which is documented alongside the `configurations/permissions_example/` recipes ([examples/configurations/permissions_example/](https://github.com/topoteretes/cognee/tree/main/examples/configurations/permissions_example)). The MCP server also exposes graph-backed retrieval helpers that consume the same ACL context, normalizing node shapes before returning them to the client ([cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py)). ## Core Data Models ### User, Tenant, and UserTenant `User` is the root identity record. Each `User` is associated with one or more `Tenant` records through the `UserTenant` join model, which carries the user's `role_id` and `tenant_id` foreign keys plus the relationship metadata ([cognee/modules/users/models/User.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/User.py), [cognee/modules/users/models/Tenant.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/Tenant.py), [cognee/modules/users/models/UserTenant.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/UserTenant.py)). `Tenant` is the top-level isolation boundary: a tenant owns datasets, roles, and ACLs, so two users in different tenants never share a graph node. The classic pattern in the permissions example demonstrates an "owner" and a "non-owner" user attaching data to a shared dataset via `cognee.add(data, dataset_name=str(shared_uuid), user=bob)` — see the workflow described in community issue [#2846](https://github.com/topoteretes/cognee/issues/2846). ### Role and Permission `Role` groups a set of `Permission` records so a tenant administrator can grant capabilities at the role level rather than per user. `Permission` defines the primitive verbs the system understands (for example `read`, `write`, `delete`) and is keyed by a string identifier plus optional `metadata` ([cognee/modules/users/models/Role.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/Role.py), [cognee/modules/users/models/Permission.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/Permission.py)). A `UserTenant` row references the role, so the chain `User → UserTenant → Role → Permission` is what the ACL layer evaluates when a request comes in. ### ACL `ACL` is the row that actually links a principal (typically a `User`) to a protected resource (a `Dataset`) with a specific `Permission`. It is the lookup table consulted by the helper function `get_authorized_dataset` referenced in issue [#2845](https://github.com/topoteretes/cognee/issues/2845), which resolves a dataset name into a resource the caller is allowed to see ([cognee/modules/users/models/ACL.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/ACL.py)). The MCP retrieval utilities use a related normalization step that flattens graph node shapes into plain dictionaries so that ACL-filtered result sets are returned consistently to clients ([cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py)). ## Dataset Resolution and ACL Enforcement Datasets are the user-visible unit of sharing. A non-owner user is expected to address a shared dataset by its UUID — that is the only key that bypasses the default "create a new owner-scoped dataset" path. The `cognee.add`, `cognee.search`, and `cognee.cognify` entry points accept a `user` argument; the ACL layer then checks `UserTenant` membership and, for the target dataset, the matching `ACL` row. The data flow looks like this: ```mermaid flowchart LR Client[Client SDK call
cognee.add / search / cognify] --> Resolve{Resolve
dataset} Resolve -- "name + user" --> ACLCheck[ACL lookup
get_authorized_dataset] Resolve -- "UUID" --> Direct[Direct row lookup] ACLCheck -- "allowed" --> Op[Perform operation] ACLCheck -- "denied / missing" --> Deny[DatasetNotFoundError] Direct --> Op ``` When `ENABLE_BACKEND_ACCESS_CONTROL` is on, every `cognee.search(query="...", datasets=['shared_dataset_name'], user=non_owner)` call is expected to route through the ACL-aware resolver, so a user with explicit `read` permission can retrieve data even though they do not own the dataset ([#2845](https://github.com/topoteretes/cognee/issues/2845)). ## Configuration and Known Limitations Enable the feature by setting `ENABLE_BACKEND_ACCESS_CONTROL=true` in `.env` and following one of the four scripts in [`examples/configurations/permissions_example/`](https://github.com/topoteretes/cognee/tree/main/examples/configurations/permissions_example). The example recipes cover owner/non-owner, role-based, and shared-dataset patterns. The community has surfaced three related bugs that the wiki reader should be aware of before relying on this layer: | Issue | Symptom | Workaround | |---|---|---| | [#2845](https://github.com/topoteretes/cognee/issues/2845) | `cognee.search` with `datasets=[name]` and `user=non_owner` raises `DatasetNotFoundError` instead of resolving via the ACL. | Pass the dataset UUID instead of the name. | | [#2846](https://github.com/topoteretes/cognee/issues/2846) | `cognee.add` with `dataset_name='shared_name'` and a non-owner `user` silently creates a new owner-scoped dataset. | Pass `dataset_name=str(shared_uuid)` so the resolver matches the existing row. | | [#2847](https://github.com/topoteretes/cognee/issues/2847) | `cognee.cognify` silently skips data attached by a non-owner. | Verify ACL rows and dataset ownership before invoking `cognify`. | Together these issues show that name-based resolution is not fully ACL-aware at the time of writing; UUID-based addressing is the most reliable way to address a shared dataset today. The v1.1.2 release notes emphasize "reliability, search quality, and user experience improvements," which is consistent with the team continuing to harden this surface ([v1.1.2 release notes](https://github.com/topoteretes/cognee/releases/tag/v1.1.2)). ## See Also - [README.md](https://github.com/topoteretes/cognee/blob/main/README.md) — top-level project overview - [examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md) — catalog of demos, guides, and configuration recipes - [cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py) — MCP-side normalization of ACL-filtered graph nodes - [cognee/tasks/summarization/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md) — cognify pipeline step that runs after ACL-filtered ingestion --- ## Retrieval System, Search Modes, and Evaluation ### Related Pages Related topics: [Overview, Core Operations, and System Architecture](#page-overview), [Deployment, LLM and Database Configuration, and Extensibility](#page-deployment)
Related Source Files The following source files were used to generate this page: - [cognee/api/v1/search/search.py](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/search/search.py) - [cognee/modules/search/types/SearchType.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/search/types/SearchType.py) - [cognee/modules/search/methods/search.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/search/methods/search.py) - [cognee/modules/search/operations/select_search_type.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/search/operations/select_search_type.py) - [cognee/modules/search/models/Query.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/search/models/Query.py) - [cognee/modules/search/models/Result.py](https://github.com/topoteretes/cognee/blob/main/cognee/modules/search/models/Result.py) - [cognee-mcp/src/server.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py) - [cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py) - [cognee/tasks/summarization/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md) - [README.md](https://github.com/topoteretes/cognee/blob/main/README.md) - [examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md)
# Retrieval System, Search Modes, and Evaluation ## Overview Cognee's retrieval system is the read-side counterpart to its ingestion and `cognify()` pipeline. After data is added and the knowledge graph is built, `cognee.search()` provides the primary entry point for recalling information. The system is designed as a multi-mode retrieval layer that combines vector similarity, graph traversal, pre-computed summaries, and LLM-based completion behind a single API. The public surface lives under `cognee/api/v1/search/` and `cognee/modules/search/`, while an MCP-compatible variant is exposed in `cognee-mcp/src/server.py` and supported by helper utilities in `cognee-mcp/src/retrieval_utils.py`. Source: [cognee-mcp/src/server.py](), [cognee-mcp/src/retrieval_utils.py](). The retrieval layer is intentionally mode-aware: rather than collapsing every query into a single ranking algorithm, Cognee lets callers pick a `SearchType` that best matches their intent. This design is also what enables `FEELING_LUCKY`, where the system itself decides which mode to use for a given natural-language query. Source: [cognee-mcp/src/server.py](). ## Search Modes Cognee enumerates its retrieval strategies in `cognee/modules/search/types/SearchType.py` and documents them in the MCP server docstrings. The supported modes and their intended use cases are summarized below. | Mode | Backend mechanism | Typical latency | Best for | |------|-------------------|-----------------|----------| | `GRAPH_COMPLETION` | LLM reasoning over graph context | Slow | Complex Q&A, analysis, insights | | `RAG_COMPLETION` | LLM over retrieved chunks (no graph) | Medium | Direct document fact-finding | | `CHUNKS` | Vector similarity over chunk embeddings | Fast | Passage and citation lookup | | `SUMMARIES` | Pre-generated hierarchical summaries | Fast | Document overviews and abstracts | | `CODE` | Code-aware index | Medium | Functions, classes, implementation patterns | | `CYPHER` | Direct graph database query | Variable | Advanced graph traversals, debugging | | `FEELING_LUCKY` | LLM-driven mode selection | Variable | General-purpose queries | | `TEMPORAL` | Time-bounded graph traversal | Variable | Before/after/between events | Source: [cognee/modules/search/types/SearchType.py](), [cognee-mcp/src/server.py](). Community issue #3004 proposes extending the temporal model with explicit freshness policies so that older or superseded memories can be down-weighted in agent-memory contexts, indicating that temporal retrieval is an area of active development. Source: [GitHub Issue #3004](https://github.com/topoteretes/cognee/issues/3004). ## Search Execution Flow A `cognee.search()` call is decomposed into a `Query` object, dispatched through a mode selector, executed against the appropriate backend, and normalized into a `Result`. ```mermaid flowchart LR A["cognee.search()"] --> B["select_search_type"] B --> C{"query_type"} C -->|GRAPH_COMPLETION / RAG_COMPLETION| D["LLM completion
(graph or chunks)"] C -->|CHUNKS / SUMMARIES| E["Vector DB lookup"] C -->|CODE| F["Code index"] C -->|CYPHER| G["Graph DB query"] C -->|TEMPORAL| H["Time-bounded graph traversal"] C -->|FEELING_LUCKY| I["LLM picks mode"] D --> J["Result normalization"] E --> J F --> J G --> J H --> J I --> J J --> K["cognee Result"] ``` The selector in `cognee/modules/search/operations/select_search_type.py` chooses the execution branch, while `cognee/modules/search/methods/search.py` orchestrates the actual retrieval. The `Query` and `Result` data classes in `cognee/modules/search/models/` define the typed contract between callers and the engine. The MCP server adds a thin adapter layer that normalizes graph node shapes (handles both dict-like and attribute-like nodes, and inline JSON `properties` strings) before returning results, as implemented in `cognee-mcp/src/retrieval_utils.py`. Source: [cognee/modules/search/operations/select_search_type.py](), [cognee/modules/search/methods/search.py](), [cognee/modules/search/models/Query.py](), [cognee/modules/search/models/Result.py](), [cognee-mcp/src/retrieval_utils.py](). The release notes for v1.1.2 explicitly call out "search quality" as a focus area, indicating that the retrieval path continues to receive reliability and ranking improvements. Source: [v1.1.2 Release Notes](https://github.com/topoteretes/cognee/releases/tag/v1.1.2). ## Configuration, Prerequisites, and Known Failure Modes All LLM-backed modes (`GRAPH_COMPLETION`, `RAG_COMPLETION`, `FEELING_LUCKY`) require a configured `LLM_API_KEY`; the configured `LLM_PROVIDER`, `LLM_MODEL`, `VECTOR_DB_PROVIDER`, and `GRAPH_DATABASE_PROVIDER` must match the backends used during `cognify()`. Optional rate limiting is controlled by `LLM_RATE_LIMIT_ENABLED` and `LLM_RATE_LIMIT_REQUESTS`. Source: [cognee-mcp/src/server.py](). Several known failure modes are worth highlighting because they affect retrieval correctness in production: - **ACL resolution on shared datasets.** Non-owner users with explicit `read` permission can fail with `DatasetNotFoundError` when calling `cognee.search()` by dataset name; the ACL-aware lookup path is not consistently used. Source: [GitHub Issue #2845](https://github.com/topoteretes/cognee/issues/2845). - **Multi-tenant ingestion gaps.** Data added by non-owners may be silently skipped by `cognify()`, and `cognee.add()` can silently create a new owner-scoped dataset instead of writing to the shared one. These issues surface only at retrieval time, as missing context. Source: [GitHub Issue #2846](https://github.com/topoteretes/cognee/issues/2846), [GitHub Issue #2847](https://github.com/topoteretes/cognee/issues/2847). - **Custom LLM endpoints.** LiteLLM may ignore a custom `LLM_ENDPOINT` and fall back to `api.openai.com`, which causes LLM-backed search modes to fail or produce unexpected results when targeting OpenAI-compatible providers. Source: [GitHub Issue #2842](https://github.com/topoteretes/cognee/issues/2842). ## Evaluation Cognee ships an `evals/` directory used by the team to track retrieval quality, and contributors have called for expanded coverage that scores each search mode independently (e.g., retrieval recall, faithfulness, latency) rather than only end-to-end answers. The `examples/` directory also includes benchmark-style demos such as `evals/`-adjacent scripts and a `feedback_score_shifting_example.py` that shows how feedback nudges retrieval scores over time. Source: [GitHub Issue #2913](https://github.com/topoteretes/cognee/issues/2913), [examples/README.md](). For practitioners, a practical evaluation loop is: (1) lock `VECTOR_DB_PROVIDER` and `GRAPH_DATABASE_PROVIDER` to a reproducible configuration, (2) run the same query set across multiple `SearchType` values, (3) compare top-k results against a held-out gold set, and (4) use the `feedback_score_shifting` workflow to observe how the importance-weight task (`guides/importance_weight.py`) re-ranks nodes across iterations. Source: [examples/README.md](). ## See Also - [Cognee README](https://github.com/topoteretes/cognee/blob/main/README.md) — project overview, quickstart, and deployment options - [Summarization module](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md) — produces the `SUMMARIES` retrieval targets - [Examples catalog](https://github.com/topoteretes/cognee/blob/main/examples/README.md) — guided demos including temporal recall, custom prompts, and importance weighting - [Release v1.1.2 notes](https://github.com/topoteretes/cognee/releases/tag/v1.1.2) — recent search quality improvements --- ## Deployment, LLM and Database Configuration, and Extensibility ### Related Pages Related topics: [Overview, Core Operations, and System Architecture](#page-overview), [Multi-User Access Control, Tenants, and Datasets](#page-permissions), [Retrieval System, Search Modes, and Evaluation](#page-retrieval)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/topoteretes/cognee/blob/main/README.md) - [cognee-mcp/src/server.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py) - [cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py) - [examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md) - [cognee/tasks/summarization/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md) - [cognee/tasks/codingagents/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/codingagents/README.md) - [cognee/tasks/web_scraper/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/web_scraper/README.md) - [examples/pocs/disambiguation/README.md](https://github.com/topoteretes/cognee/blob/main/examples/pocs/disambiguation/README.md)
# Deployment, LLM and Database Configuration, and Extensibility This page covers how to deploy Cognee, configure its LLM provider and database backends, and extend the framework with custom models, prompts, tasks, and pipelines. The information is sourced from the root `README.md`, the `examples/` tree, the `cognee-mcp` server module, and the per-task READMEs that document the available configuration knobs. ## Deployment Options Cognee supports both a fully managed service and several self-hosted PaaS targets. The deployment matrix from the root README is summarized below. | Platform | Best For | Command | |----------|----------|---------| | **Cognee Cloud** | Managed service, no infrastructure to maintain | Sign up at [cognee.ai](https://www.cognee.ai) or `await cognee.serve()` | | **Modal** | Serverless, auto-scaling, GPU workloads | `bash distributed/deploy/modal-deploy.sh` | | **Railway** | Simplest PaaS, native Postgres | `railway init && railway up` | | **Fly.io** | Edge deployment, persistent volumes | `bash distributed/deploy/fly-deploy.sh` | | **Render** | Simple PaaS with managed Postgres | Deploy to Render button | | **Daytona** | Cloud sandboxes (SDK or CLI) | See `distributed/deploy/daytona_sandbox.py` | For local development the standard Python install is used: ```bash uv pip install cognee ``` The complete deployment scripts and worker configurations live under `distributed/`. The MCP server itself can also be started locally and exposes both `cognify` and `search` tools that delegate to the same Cognee pipelines. Source: [README.md:1-200](). ## LLM Configuration Cognee routes LLM calls through a pluggable gateway that supports rate limiting, custom endpoints, and provider switching via environment variables. The MCP server documents the following required and optional variables: | Variable | Required | Purpose | |----------|----------|---------| | `LLM_API_KEY` | Yes | API key for the selected LLM provider | | `LLM_PROVIDER` | No | Provider switch (e.g., `openai`, `custom`) | | `LLM_MODEL` | No | Specific model name to use | | `LLM_ENDPOINT` | No | Custom OpenAI-compatible base URL | | `VECTOR_DB_PROVIDER` | No | Vector database backend selector | | `GRAPH_DATABASE_PROVIDER` | No | Graph database backend selector | | `LLM_RATE_LIMIT_ENABLED` | No | Enable rate limiting (default: `False`) | | `LLM_RATE_LIMIT_REQUESTS` | No | Max requests per interval (default: `60`) | Source: [cognee-mcp/src/server.py:1-200](); [cognee-mcp/src/retrieval_utils.py:1-100](). > **Community note (issue #2842):** when targeting a custom OpenAI-compatible endpoint, users have reported that `LLM_ENDPOINT` is sometimes ignored and traffic still goes to `api.openai.com`. Verify provider and endpoint variables together when using non-OpenAI backends. Custom prompts can also be injected directly into the `cognify` task. The MCP `cognify` tool accepts a `custom_prompt` argument that overrides the default entity-extraction prompt, allowing domain-specific guidance to be passed to the LLM. Source: [cognee-mcp/src/server.py:1-200](). ## Database and Backend Configuration Cognee separates vector and graph storage so each can be swapped independently. The `examples/database_examples/` folder provides end-to-end smoke tests for each supported backend. | Backend | Type | Example Script | |---------|------|----------------| | Ladybug | Graph (default) | `database_examples/ladybug_example.py` | | Neo4j | Graph | `database_examples/neo4j_example.py` | | Neptune Analytics | Graph | `database_examples/neptune_analytics_example.py` | | ChromaDB | Vector | `database_examples/chromadb_example.py` | | Postgres (pgvector) | Vector / hybrid | `database_examples/postgres_example.py` | The `examples/configurations/database_examples/` folder contains four additional graph configurations and one hybrid setup for users running multi-backend deployments. The accompanying guide at `examples/README.md` documents how to copy `.env.example` to `.env` and switch providers. Source: [examples/README.md:1-200](); [examples/README.md:200-400](). ## Extensibility Cognee is designed to be extended at every layer of the pipeline. The diagram below shows the main extension points and their relationship to the default `cognify` flow. ```mermaid flowchart LR A[Raw Data] --> B[cognee.add] B --> C[Chunking] C --> D[Graph Extraction] D --> E[Summarization] E --> F[Storage: Vector + Graph] F --> G[cognee.search] G --> H[SearchType backend] D -.custom graph model.-> D1[custom_graph_model.py] D -.custom prompt.-> D2[custom_prompts.py] C -.custom DataPoint.-> D3[custom_data_models.py] E -.custom task.-> D4[custom_tasks_and_pipelines.py] D -.disambiguation POC.-> D5[pocs/disambiguation] ``` The most common extension points are: - **Custom data models** — subclass `DataPoint` to add new node types; see `examples/guides/custom_data_models.py`. Source: [examples/README.md:100-300](). - **Custom graph model** — supply a `graph_model_file` and `graph_model_name` to `cognify` (also exposed via the MCP `cognify` tool) to replace the default `KnowledgeGraph` schema. Source: [cognee-mcp/src/server.py:1-200](); [examples/README.md:100-300](). - **Custom prompts** — pass `custom_prompt` to `cognify` to override the entity-extraction prompt without changing code. Source: [cognee-mcp/src/server.py:1-200](). - **Custom tasks and pipelines** — author new `Task` subclasses and compose them via the `Pipeline` API; see `examples/guides/custom_tasks_and_pipelines.py` and the `custom_pipelines/` directory. Source: [examples/README.md:100-400](). - **Specialized ingestion** — plug in additional ingestion modules such as the web scraper (`cognee/tasks/web_scraper/`), the summarization pipeline (`cognee/tasks/summarization/`), or the coding-agent rule extractor (`cognee/tasks/codingagents/`). Source: [cognee/tasks/web_scraper/README.md:1-200](); [cognee/tasks/summarization/README.md:1-200](); [cognee/tasks/codingagents/README.md:1-200](). - **Disambiguation POCs** — the `examples/pocs/disambiguation/` and `examples/pocs/post_extraction_canonicalization/` folders show how to swap the default extraction step with one that injects vector-retrieved entity candidates into the prompt to reduce duplicate nodes. Source: [examples/pocs/disambiguation/README.md:1-200](). ## Common Failure Modes and Mitigations A few recurring issues surface across the community evidence and the source docs: - **Custom `LLM_ENDPOINT` ignored** (issue #2842): when targeting OpenAI-compatible APIs, confirm `LLM_PROVIDER` matches the endpoint and that any required headers are set; otherwise LiteLLM may fall back to the default OpenAI host. - **Schema truncation** (release v1.1.1.dev0): user text fields could be silently truncated by the underlying varchar size; the patch introduces a safe migration and earlier validation, so users upgrading should run the new migrations. - **ACL and dataset ownership** (issues #2845, #2846, #2847): non-owner `cognee.add`, `cognee.search`, and `cognify` calls may silently misroute to owner-scoped datasets or skip rows. Multi-tenant deployments should use the `get_authorized_dataset` lookup path and verify dataset ownership before relying on the UUID workaround. - **JSON ingestion errors** (issue #3079): malformed JSON during `cognify` can surface as opaque upload errors; pre-validating input files and reviewing the summarization step's structured-output handling (see [cognee/tasks/summarization/README.md]()) is the recommended mitigation. ## See Also - Cognee MCP Server tools (`cognee-mcp/src/server.py`) - Examples index (`examples/README.md`) - Summarization pipeline (`cognee/tasks/summarization/README.md`) - Coding-agent rule extraction (`cognee/tasks/codingagents/README.md`) - Web scraper module (`cognee/tasks/web_scraper/README.md`) - Disambiguation POC (`examples/pocs/disambiguation/README.md`) --- --- ## Pitfall Log Project: topoteretes/cognee Summary: Found 32 structured pitfall item(s), including 10 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/2913 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/3079 ## 3. Configuration risk - Configuration risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/3154 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing dataset name - User impact: Developers may expose sensitive permissions or credentials: cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing dataset name - Evidence: failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/2846 ## 5. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: cognee.search ignores ACL when resolving dataset by name for non-owners - User impact: Developers may expose sensitive permissions or credentials: cognee.search ignores ACL when resolving dataset by name for non-owners - Evidence: failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/2845 ## 6. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: cognify pipeline silently skips data added by non-owner users - User impact: Developers may expose sensitive permissions or credentials: cognify pipeline silently skips data added by non-owner users - Evidence: failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/2847 ## 7. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/3004 ## 8. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/2846 ## 9. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/2845 ## 10. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/2847 ## 11. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v1.0.8 - User impact: Upgrade or migration may change expected behavior: v1.0.8 - Evidence: failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.0.8 ## 12. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v1.0.9 - User impact: Upgrade or migration may change expected behavior: v1.0.9 - Evidence: failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.0.9 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v1.1.0.dev1 - User impact: Upgrade or migration may change expected behavior: v1.1.0.dev1 - Evidence: failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.0.dev1 ## 14. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/2976 ## 15. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: LiteLLM ignores custom LLM_ENDPOINT for OpenAI-compatible APIs - User impact: Developers may misconfigure credentials, environment, or host setup: LiteLLM ignores custom LLM_ENDPOINT for OpenAI-compatible APIs - Evidence: failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/2842 ## 16. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: [Bug]: JSON issue while adding the file for Cognify the data - User impact: Developers may misconfigure credentials, environment, or host setup: [Bug]: JSON issue while adding the file for Cognify the data - Evidence: failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/3079 ## 17. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: [Feature]: Temporal freshness policies for stale and superseded memories - User impact: Developers may misconfigure credentials, environment, or host setup: [Feature]: Temporal freshness policies for stale and superseded memories - Evidence: failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/3004 ## 18. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v1.1.0 - User impact: Upgrade or migration may change expected behavior: v1.1.0 - Evidence: failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.0 ## 19. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v1.1.1 - User impact: Upgrade or migration may change expected behavior: v1.1.1 - Evidence: failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.1 ## 20. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: v1.1.1.dev0 - User impact: Upgrade or migration may change expected behavior: v1.1.1.dev0 - Evidence: failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.1.dev0 ## 21. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/2933 ## 22. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/topoteretes/cognee ## 23. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this runtime risk before relying on the project: PR Review: feat/staging-bridge-fix — Fix None reactions crash - User impact: Developers may hit a documented source-backed failure mode: PR Review: feat/staging-bridge-fix — Fix None reactions crash - Evidence: failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/3065 ## 24. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/topoteretes/cognee/issues/3065 ## 25. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: v1.0.7 - User impact: Upgrade or migration may change expected behavior: v1.0.7 - Evidence: failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.0.7 ## 26. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: v1.1.0.dev0 - User impact: Upgrade or migration may change expected behavior: v1.1.0.dev0 - Evidence: failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.0.dev0 ## 27. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: v1.1.2 - User impact: Upgrade or migration may change expected behavior: v1.1.2 - Evidence: failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.2 ## 28. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/topoteretes/cognee ## 29. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/topoteretes/cognee ## 30. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/topoteretes/cognee ## 31. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/topoteretes/cognee ## 32. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/topoteretes/cognee