What is the push operation
The.push operation uploads a local dataset’s already-built knowledge graph to Cognee Cloud or another remote Cognee instance.
Unlike a raw-data sync, push() ships the graph you already extracted locally. Cognee exports the dataset to a COGX archive, uploads it, and imports it on the remote instance so entities and relationships can be preserved.
It is available from both the Python SDK and the CLI:
Where push fits
- Use
push()when you have built a graph locally and want the same graph available remotely. - Use it when local graph extraction has already done the expensive LLM work and you want the remote side to preserve that result.
- Use it after Remember or Cognify, not before them.
- Use syncing a local instance instead when you want to send raw data and let the remote instance rebuild memory itself.
What happens under the hood
- Resolve the local dataset - Cognee finds the dataset by name or UUID and checks that it can be read.
- Export the graph - the dataset’s graph is exported as a COGX archive.
- Upload the archive - the archive is sent to the configured remote Cognee instance.
- Import remotely - the remote instance imports the archive into the target dataset.
- Report the result - Cognee returns the remote status, target dataset, graph size, and any pipeline run id.
The dataset must already have a knowledge graph. If the export finds no graph nodes, run
cognee.remember() or cognee.cognify() on the dataset first.Import modes
push() supports three remote import modes:
The default mode is
preserve, which is the graph-preserving path.
Authentication
push() uses the same remote credential stack as cognee.serve():
- Explicit
urlandapi_keyarguments - An active
cognee.serve()connection COGNEE_SERVICE_URLandCOGNEE_API_KEYenvironment variables- Saved credentials from a previous
servelogin
push() raises an authentication error instead of uploading anywhere implicitly.
Examples and details
Push with the Python SDK
Push with the Python SDK
Push with the CLI
Push with the CLI
Push to a different remote dataset
Push to a different remote dataset
Use
target_dataset when the remote dataset should have a different name from the local dataset.Run large imports in the background
Run large imports in the background
For larger graphs, schedule the remote import in the background and track the returned pipeline run id.
Push to an explicit remote instance
Push to an explicit remote instance
If you do not want to rely on a saved
serve login, pass the remote URL and API key directly.