Skip to content
Get packs

Guide · Agent skill

How to use the Cognee Database Migrations agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

This guide explains the cognee-migrations agent skill, a set of instructions that teaches an AI coding agent how cognee upgrades and repairs its own databases. It is for developers who run cognee in production, contributors who write migrations, and teams who move memory data between cognee instances. After reading, you will know how to install the skill, which natural requests trigger it, and which cognee-cli commands it helps the agent use safely.

Cognee Database Migrationstopoteretes/cognee · Apache-2.0

Quick start

  1. 1Install cognee and cognee-cli. Make sure cognee is installed and the cognee-cli command is available in your terminal. The skill requires both.
  2. 2Add the skill folder. Unzip the downloaded skill and place it in ~/.claude/skills/ for personal use or .claude/skills/ inside your project.
  3. 3Check migration state. Run cognee-cli current to see the stamped revision per database and any last failure.
  4. 4Ask for what you need. Describe the problem in plain language, such as a blocked write or a need to back up a dataset, and the agent will use the relevant commands.
  5. 5Apply the fix and verify. After a fix, run cognee-cli upgrade to bring data to head, then check cognee-cli current again.

What the cognee-migrations skill makes the agent do

cognee has two migration chains that run together. The relational schema chain uses Alembic to change tables and columns in the relational database, such as users, datasets, ACLs and pipeline runs. The graph and vector data chain rewrites data across the graph DB, vector DB and relational ledger, for example re-keying node ids.

The skill tells the agent when these chains run automatically, how to check or repair their state with cognee-cli, how to recover when a failed migration blocks writes, how to author new revisions, and how to export, back up or import memory data.

Install the skill (ZIP download or Claude upload)

Download the skill ZIP from this page and unzip it. The skill's file is SKILL.md. Put the unzipped skill folder in one of these locations:

  • Personal skills folder: ~/.claude/skills/
  • Project skills folder: .claude/skills/ inside your project
  • Or, in the Claude apps, upload it under Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need to name the skill. The skill's description covers requests about migrations, such as understanding when they run, checking or repairing migration state, a write blocked by a failed migration, authoring a new Alembic revision or data migration, or moving data between systems.

Examples of requests that match:

  • Why did my cognee writes start failing after the upgrade?
  • Check the migration status of my cognee database and tell me what failed.
  • Help me roll back the data migration for one dataset.
  • Write a new Alembic revision for a schema change in the cognee codebase.
  • Back up my cognee dataset as a COGX archive and restore it on another instance.

Check and repair migration state with cognee-cli

The skill documents these cognee-cli commands. The positional revision is always a data-chain slug; relational targets go through --alembic. Downgrade rewrites data and asks for confirmation, and it only reverts spans where every migration defines a down(). Stamp changes only the stored data-chain revision without running anything.

  • current shows the stamped revision per database and the last failure.
  • history lists the data chain, newest first.
  • upgrade moves the relational schema and data chain to head.
  • stamp base --dataset <id> followed by upgrade is used when a database's data drifted from its stamp, for example after restoring a backup.
cognee-cli current cognee-cli history cognee-cli upgrade cognee-cli upgrade <slug> cognee-cli upgrade --alembic <rev> cognee-cli downgrade <slug|base> [--dataset UUID ...] [--alembic REV] [--force] cognee-cli stamp <head|base|slug> [--dataset UUID ...] [--force]

Recover when a write is blocked by a failed migration

If a dataset's data migration failed, writes to that dataset are refused until it succeeds. With access control off, any failure blocks all writes. The server still starts. Run cognee-cli current to see the error, fix the cause, then run cognee-cli upgrade. A failed run is retried on the next start or write.

Move data between systems and back up memory

Schema migrations are only one part. The skill also covers moving data. A COGX archive is cognee's portable memory format and the only export format cognee can import back. Other export formats (json, graphml, cypher) are one-way. Importers exist for Mem0, Zep/Graphiti, Letta and LangMem through a MemorySource.

A restore defaults to preserve mode, which writes the archived graph back with no LLM calls. Hybrid mode also re-cognifies raw content, and re-derive mode extracts again and costs LLM tokens.

  • Relational DB to graph: migrate_relational_database, configured with MIGRATION_DB_* variables
  • Backup or copy a dataset: COGX archive
  • Export a graph for other tools: cognee.export with json, graphml or cypher
  • Import from another memory system: MemorySource passed to cognee.remember
from cognee.migration import COGXArchiveSource await cognee.export("my_dataset", format="cogx", destination="backup_cogx") await cognee.remember(COGXArchiveSource("backup_cogx"), dataset_name="my_dataset")

Safety notes: scripts, network and secrets

The skill is documented as running no scripts. It does use the network: cognee.push() and cognee-cli push upload a COGX archive to Cognee Cloud, and relational imports connect to a source database using MIGRATION_DB_* credentials. Only provide source database credentials when you import a relational database.

An export made with include_permissions=True writes permissions.json, which includes dataset owner and ACL grants with password hashes. Treat that file as a secret. The skill also says there is no tool that moves a whole deployment from one database backend to another, and attempting it manually risks data loss.

  • Never regenerate cognee/alembic/frozen_schema.py.
  • Never hand-type an Alembic revision id; generate ids with alembic revision.
  • Never rename, remove or reorder a data-chain entry.

What people use it for

  • Diagnosing why writes to one dataset are refused after a failed data migration.
  • Rolling back the data migration for a single dataset with a confirmed downgrade.
  • Backing up a dataset as a COGX archive and restoring it to another cognee instance in preserve mode.
  • Importing memory from Mem0, Zep, Letta or LangMem into cognee through a MemorySource.
  • Authoring a new Alembic revision for a schema change in the cognee codebase.

Frequently asked questions

Is the cognee-migrations skill free and what is its licence?

The listing states the licence is Apache-2.0. The skill is a SKILL.md file that you download from this page and add to your agent's skills folder.

What do I need to use the cognee-migrations skill?

You need cognee installed with the cognee-cli command available, and a relational database such as SQLite or Postgres. A graph DB and vector DB are optional, depending on your setup. Alembic is needed only if you author new schema revisions.

Where do I put the skill so Claude can find it?

Unzip the skill and place it in ~/.claude/skills/ for personal use, or in .claude/skills/ inside a project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

Do cognee migrations run automatically?

Yes. run_migrations() applies the relational chain and then the data chain at API server startup, on the first write in each SDK or CLI process, and when you call cognee.run_migrations(). Set ENABLE_AUTO_MIGRATIONS=false to turn off automatic runs, then run cognee-cli upgrade yourself.

How do I fix a write that is blocked by a failed migration?

Run cognee-cli current to see the error, fix its cause, then run cognee-cli upgrade. A failed run is also retried on the next start or write. The server still starts while writes are refused.

Can I move a whole cognee deployment to a different database backend?

The skill states that no tool exists for moving a whole deployment from one database backend to another, and that doing it manually risks data loss. For copying a dataset between cognee instances, use a COGX archive instead.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers running cognee in production who need to upgrade, roll back or repair a database, and contributors writing new migrations. It is not needed if you only call cognee's add and search functions, because migrations run on their own. If you need to move an entire deployment between database backends, pick a different approach, since the skill says no tool does this safely.

Download the skill