Skip to main content

​
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: 
await cognee.push("onboarding")

cognee push onboarding

​
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

  1. Resolve the local dataset - Cognee finds the dataset by name or UUID and checks that it can be read.
  2. Export the graph - the dataset’s graph is exported as a COGX archive.
  3. Upload the archive - the archive is sent to the configured remote Cognee instance.
  4. Import remotely - the remote instance imports the archive into the target dataset.
  5. 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:
ModeRemote behaviorLLM calls
preserveMap the exported entities and facts directly into the remote graphNone
hybridPreserve the exported graph and also cognify the raw contentYes
re-deriveIgnore the exported graph and rebuild from the raw content remotelyYes
The default mode is preserve, which is the graph-preserving path.

​
Authentication

push() uses the same remote credential stack as cognee.serve():
  1. Explicit url and api_key arguments
  2. An active cognee.serve() connection
  3. COGNEE_SERVICE_URL and COGNEE_API_KEY environment variables
  4. Saved credentials from a previous serve login
If no remote credentials are available, push() raises an authentication error instead of uploading anywhere implicitly.

​
Examples and details

Push with the Python SDK

import cognee

# Build a graph locally.
await cognee.remember("docs/handbook.pdf", dataset="onboarding")

# Log in once so push can reuse the remote credentials.
await cognee.serve()

# Push the local graph to the remote dataset with the same name.
result = await cognee.push("onboarding")

print(result.target_dataset)
print(result.num_nodes, result.num_edges)

# Build local memory first.
cognee remember docs/handbook.pdf --dataset-name onboarding

# Log in once.
cognee serve

# Push the graph to the remote instance.
cognee push onboarding
Use target_dataset when the remote dataset should have a different name from the local dataset.
await cognee.push(
    "onboarding",
    target_dataset="prod_onboarding",
)

cognee push onboarding --target-dataset prod_onboarding
For larger graphs, schedule the remote import in the background and track the returned pipeline run id.
result = await cognee.push(
    "onboarding",
    run_in_background=True,
)

print(result.pipeline_run_id)

cognee push onboarding --background
If you do not want to rely on a saved serve login, pass the remote URL and API key directly.
await cognee.push(
    "onboarding",
    url="https://your-instance.cognee.ai",
    api_key="your-api-key",
)

cognee push onboarding \
  --url https://your-instance.cognee.ai \
  --api-key your-api-key

​
See also