# topoteretes/cognee architecture

> Architecture diagram of the GitHub repository topoteretes/cognee, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/topoteretes/cognee
- Repository: https://github.com/topoteretes/cognee
- Video tour (about a minute): https://gitdiagram.com/topoteretes/cognee/video

## Overview

Cognee is an open-source AI memory platform: callers add text or documents, Cognee builds persistent searchable memory, and callers retrieve relevant evidence across sessions. The graph highlights that workflow, its pipeline and storage foundations, plus the documented agent/MCP interface. README statements and sampled excerpts support the main flow; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`cognee/__init__.py`](https://github.com/topoteretes/cognee/blob/main/cognee/__init__.py) (Recall), [`cognee/modules/pipelines/operations/pipeline.py`](https://github.com/topoteretes/cognee/blob/main/cognee/modules/pipelines/operations/pipeline.py) (Pipeline Runner), [`cognee-mcp/src/server.py`](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py) (MCP Server), [`cognee/infrastructure/databases/graph/graph_db_interface.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/graph_db_interface.py) (Graph Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Memory API"]
  node_remember["Remember<br/>[__init__.py]"]
  node_recall["Recall<br/>[__init__.py]"]
  node_query_router["Recall API Route<br/>[query_router.py]"]
  node_custom_pipeline["Custom Pipeline Entry"]
end

subgraph group_processing["Memory Processing"]
  node_pipeline["Pipeline Runner<br/>[pipeline.py]"]
  node_pipeline_task["Pipeline Tasks<br/>[task.py]"]
  node_ingestion_storage["Input File Storage"]
  node_schema_ingestion["Database Schema Ingestion"]
end

subgraph group_storage["Memory Storage"]
  node_graph_store[("Graph Store")]
  node_graph_engine["Graph Engine Factory"]
  node_vector_store[("Vector Store")]
  node_vector_engine["Vector Engine Factory"]
  node_unified_store["Unified Store"]
  node_file_storage["File Storage Manager<br/>[StorageManager.py]"]
  node_relational_engine["Relational Engine"]
  node_hybrid_adapter["Hybrid Graph Adapter"]
end

subgraph group_platform["Platform Foundations"]
  node_graph_config["Graph Configuration<br/>[config.py]"]
  node_relational_config["Relational Configuration<br/>[config.py]"]
  node_engine_cache["Engine Cache"]
  node_embedding_config["Embedding Configuration<br/>[config.py]"]
  node_llm_config["LLM Configuration<br/>[config.py]"]
  node_llm_errors["LLM Errors<br/>[exceptions.py]"]
  node_user_model["User and Tenant Identity<br/>[User.py]"]
  node_context["Global Context"]
  node_logging["Logging<br/>[logging_utils.py]"]
  node_usage_logging["Usage Logging<br/>[usage_logger.py]"]
end

subgraph group_agents["Agent Interfaces"]
  node_mcp_server["MCP Server<br/>[server.py]"]
  node_mcp_client["Cognee MCP Client<br/>[cognee_client.py]"]
end

node_caller(("Application or Agent"))

node_caller -->|"submits memory"| node_remember
node_remember -->|"builds memory"| node_pipeline
node_custom_pipeline -->|"invokes"| node_pipeline
node_pipeline -->|"executes tasks"| node_pipeline_task
node_pipeline -.->|"persists graph"| node_graph_store
node_pipeline -.->|"stores embeddings"| node_vector_store
node_caller -->|"queries memory"| node_recall
node_recall -.->|"available through API"| node_query_router
node_recall -->|"retrieves graph context"| node_graph_store
node_recall -->|"retrieves vector context"| node_vector_store
node_graph_engine -->|"uses configuration"| node_graph_config
node_graph_engine -->|"uses cache"| node_engine_cache
node_vector_engine -->|"uses cache"| node_engine_cache
node_vector_engine -->|"gets embedding engine"| node_embedding_config
node_unified_store -->|"uses interface"| node_graph_store
node_unified_store -->|"uses interface"| node_vector_store
node_schema_ingestion -->|"loads configuration"| node_relational_config
node_mcp_client -->|"serves tools"| node_mcp_server
node_mcp_server -->|"stores memory"| node_remember
node_mcp_server -.->|"queries memory"| node_recall

click node_remember "https://github.com/topoteretes/cognee/blob/main/cognee/__init__.py"
click node_recall "https://github.com/topoteretes/cognee/blob/main/cognee/__init__.py"
click node_query_router "https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/recall/query_router.py"
click node_custom_pipeline "https://github.com/topoteretes/cognee/blob/main/cognee/modules/run_custom_pipeline/run_custom_pipeline.py"
click node_pipeline "https://github.com/topoteretes/cognee/blob/main/cognee/modules/pipelines/operations/pipeline.py"
click node_pipeline_task "https://github.com/topoteretes/cognee/blob/main/cognee/modules/pipelines/tasks/task.py"
click node_ingestion_storage "https://github.com/topoteretes/cognee/blob/main/cognee/tasks/ingestion/save_data_item_to_storage.py"
click node_schema_ingestion "https://github.com/topoteretes/cognee/blob/main/cognee/tasks/schema/ingest_database_schema.py"
click node_graph_store "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/graph_db_interface.py"
click node_graph_engine "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/get_graph_engine.py"
click node_vector_store "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/vector_db_interface.py"
click node_vector_engine "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/create_vector_engine.py"
click node_unified_store "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/unified/unified_store_engine.py"
click node_file_storage "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/files/storage/StorageManager.py"
click node_relational_engine "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/relational/get_relational_engine.py"
click node_graph_config "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/config.py"
click node_hybrid_adapter "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/hybrid/neptune_analytics/NeptuneAnalyticsAdapter.py"
click node_relational_config "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/relational/config.py"
click node_engine_cache "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/utils/closing_lru_cache.py"
click node_embedding_config "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/embeddings/config.py"
click node_llm_config "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/llm/config.py"
click node_llm_errors "https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/llm/exceptions.py"
click node_user_model "https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/User.py"
click node_context "https://github.com/topoteretes/cognee/blob/main/cognee/context_global_variables.py"
click node_logging "https://github.com/topoteretes/cognee/blob/main/cognee/shared/logging_utils.py"
click node_usage_logging "https://github.com/topoteretes/cognee/blob/main/cognee/shared/usage_logger.py"
click node_mcp_server "https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py"
click node_mcp_client "https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/cognee_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_remember,node_recall,node_query_router,node_custom_pipeline toneBlue
class node_pipeline,node_pipeline_task,node_ingestion_storage,node_schema_ingestion toneAmber
class node_graph_store,node_graph_engine,node_vector_store,node_vector_engine,node_unified_store,node_file_storage,node_relational_engine,node_hybrid_adapter toneMint
class node_graph_config,node_relational_config,node_engine_cache,node_embedding_config,node_llm_config,node_llm_errors,node_user_model,node_context,node_logging,node_usage_logging toneRose
class node_mcp_server,node_mcp_client,node_caller toneIndigo
```

## Components

### Memory API

- [Remember](https://github.com/topoteretes/cognee/blob/main/cognee/__init__.py): `cognee/__init__.py`
- [Recall](https://github.com/topoteretes/cognee/blob/main/cognee/__init__.py): `cognee/__init__.py`
- [Recall API Route](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/recall/query_router.py): `cognee/api/v1/recall/query_router.py`
- [Custom Pipeline Entry](https://github.com/topoteretes/cognee/blob/main/cognee/modules/run_custom_pipeline/run_custom_pipeline.py): `cognee/modules/run_custom_pipeline/run_custom_pipeline.py`

### Memory Processing

- [Pipeline Runner](https://github.com/topoteretes/cognee/blob/main/cognee/modules/pipelines/operations/pipeline.py): `cognee/modules/pipelines/operations/pipeline.py`
- [Pipeline Tasks](https://github.com/topoteretes/cognee/blob/main/cognee/modules/pipelines/tasks/task.py): `cognee/modules/pipelines/tasks/task.py`
- [Input File Storage](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/ingestion/save_data_item_to_storage.py): `cognee/tasks/ingestion/save_data_item_to_storage.py`
- [Database Schema Ingestion](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/schema/ingest_database_schema.py): `cognee/tasks/schema/ingest_database_schema.py`

### Memory Storage

- [Graph Store](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/graph_db_interface.py): `cognee/infrastructure/databases/graph/graph_db_interface.py`
- [Graph Engine Factory](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/get_graph_engine.py): `cognee/infrastructure/databases/graph/get_graph_engine.py`
- [Vector Store](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/vector_db_interface.py): `cognee/infrastructure/databases/vector/vector_db_interface.py`
- [Vector Engine Factory](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/create_vector_engine.py): `cognee/infrastructure/databases/vector/create_vector_engine.py`
- [Unified Store](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/unified/unified_store_engine.py): `cognee/infrastructure/databases/unified/unified_store_engine.py`
- [File Storage Manager](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/files/storage/StorageManager.py): `cognee/infrastructure/files/storage/StorageManager.py`
- [Relational Engine](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/relational/get_relational_engine.py): `cognee/infrastructure/databases/relational/get_relational_engine.py`
- [Hybrid Graph Adapter](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/hybrid/neptune_analytics/NeptuneAnalyticsAdapter.py): `cognee/infrastructure/databases/hybrid/neptune_analytics/NeptuneAnalyticsAdapter.py`

### Platform Foundations

- [Graph Configuration](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/graph/config.py): `cognee/infrastructure/databases/graph/config.py`
- [Relational Configuration](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/relational/config.py): `cognee/infrastructure/databases/relational/config.py`
- [Engine Cache](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/utils/closing_lru_cache.py): `cognee/infrastructure/databases/utils/closing_lru_cache.py`
- [Embedding Configuration](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/embeddings/config.py): `cognee/infrastructure/databases/vector/embeddings/config.py`
- [LLM Configuration](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/llm/config.py): `cognee/infrastructure/llm/config.py`
- [LLM Errors](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/llm/exceptions.py): `cognee/infrastructure/llm/exceptions.py`
- [User and Tenant Identity](https://github.com/topoteretes/cognee/blob/main/cognee/modules/users/models/User.py): `cognee/modules/users/models/User.py`
- [Global Context](https://github.com/topoteretes/cognee/blob/main/cognee/context_global_variables.py): `cognee/context_global_variables.py`
- [Logging](https://github.com/topoteretes/cognee/blob/main/cognee/shared/logging_utils.py): `cognee/shared/logging_utils.py`
- [Usage Logging](https://github.com/topoteretes/cognee/blob/main/cognee/shared/usage_logger.py): `cognee/shared/usage_logger.py`

### Agent Interfaces

- [MCP Server](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py): `cognee-mcp/src/server.py`
- [Cognee MCP Client](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/cognee_client.py): `cognee-mcp/src/cognee_client.py`

### Other components

- **Application or Agent**

## Connections

- Application or Agent → Remember: submits memory (evidence: `README.md`)
- Remember → Pipeline Runner: builds memory (evidence: `README.md`)
- Custom Pipeline Entry → Pipeline Runner: invokes (evidence: `cognee/modules/run_custom_pipeline/run_custom_pipeline.py`)
- Pipeline Runner → Pipeline Tasks: executes tasks (evidence: `cognee/modules/pipelines/operations/pipeline.py`)
- Pipeline Runner → Graph Store: persists graph
- Pipeline Runner → Vector Store: stores embeddings
- Application or Agent → Recall: queries memory (evidence: `README.md`)
- Recall → Recall API Route: available through API
- Recall → Graph Store: retrieves graph context (evidence: `README.md`)
- Recall → Vector Store: retrieves vector context (evidence: `README.md`)
- Graph Engine Factory → Graph Configuration: uses configuration (evidence: `cognee/infrastructure/databases/graph/get_graph_engine.py`)
- Graph Engine Factory → Engine Cache: uses cache (evidence: `cognee/infrastructure/databases/graph/get_graph_engine.py`)
- Vector Engine Factory → Engine Cache: uses cache (evidence: `cognee/infrastructure/databases/vector/create_vector_engine.py`)
- Vector Engine Factory → Embedding Configuration: gets embedding engine (evidence: `cognee/infrastructure/databases/vector/create_vector_engine.py`)
- Unified Store → Graph Store: uses interface (evidence: `cognee/infrastructure/databases/unified/unified_store_engine.py`)
- Unified Store → Vector Store: uses interface (evidence: `cognee/infrastructure/databases/unified/unified_store_engine.py`)
- Database Schema Ingestion → Relational Configuration: loads configuration (evidence: `cognee/tasks/schema/ingest_database_schema.py`)
- Cognee MCP Client → MCP Server: serves tools (evidence: `cognee-mcp/src/server.py`)
- MCP Server → Remember: stores memory (evidence: `cognee-mcp/src/server.py`)
- MCP Server → Recall: queries memory (evidence: `cognee-mcp/src/server.py`)
