New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Cognee Database Migrations

by topoteretes in topoteretes/cognee

Explains how cognee's two migration chains run, how to check and repair migration state with cognee-cli, and how to write new Alembic or graph and vector migrations.

Apache-2.0Auto-check: notesDatabases

Install Cognee Database Migrations

skills CLI
$ npx skills add topoteretes/cognee --skill cognee-migrations -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install topoteretes/cognee cognee-migrations --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/topoteretes/cognee.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/cognee-migrations .claude/skills/cognee-migrations && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
cognee-migrations
GitHub stars
32k
Token cost
~2.6k tokens
SKILL.md length
1,130 words
Files
1
Skills in repo
19
Repo updated
First seen
Licence
Apache-2.0

At a glance

Explains how cognee's two migration chains run, how to check and repair migration state with cognee-cli, and how to write new Alembic or graph and vector migrations.

  • Works in 4 steps: Write a module in… → Append Migration(slug=...,… → Make it idempotent and cheap on empty… → …
  • Finding out why a cognee write is blocked by a failed migration
  • SKILL.md covers Use it, Pitfalls, How it works and Extending it
  • Calls uv

What it does

Cognee runs two chains together: Alembic revisions for the relational schema, and data migrations that rewrite content across the graph database, vector database and relational ledger. run_migrations() applies the relational chain first and then the data chain, automatically at API server startup, in the Docker entrypoint and on the first write in an SDK or CLI process, or when you call it yourself. Setting ENABLE_AUTO_MIGRATIONS=false switches the automatic runs off.

For repair, the skill covers cognee-cli current, history, upgrade, downgrade and stamp. A revision on the command line is a data-chain slug, relational targets need --alembic, downgrade asks for confirmation and only reverts migrations that define a down step, and stamp changes just the stored revision, for example before an upgrade when data drifted after a backup restore. A Postgres advisory lock or a SQLite file lock serializes concurrent processes. The excerpt was cut off before the sections on authoring new revisions and moving data between systems.

When your agent uses it

  • Finding out why a cognee write is blocked by a failed migration
  • Checking the stamped revision of each database with cognee-cli current
  • Authoring a new Alembic revision for the relational schema
  • Writing a graph or vector data migration with an undo step

Example prompts

  • “My cognify call fails with a migration error, so show me how to check and repair the state.”
  • “Add an Alembic revision that adds a column to the datasets table.”
  • “I restored a backup and the data drifted from its stamp, so walk me through stamp and upgrade.”

Requirements

  • A cognee installation with cognee-cli
  • Postgres or SQLite as the relational database

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Write a module in cognee/modules/migrations/versions/ with
  2. Append Migration(slug=..., cognee_version=..., up=..., down_revision=, down=...)
  3. Make it idempotent and cheap on empty stores, and crash-safe: re-key
  4. Freeze private copies of any logic you depend on; never import live

What it can do on your machine

Read from SKILL.md and the folder at commit 0ec7a9f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • uv

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use uv, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Cognee Database Migrations loads about 2.6k tokens when it runs. Until then it costs about 100 tokens; SKILL.md has 1,130 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~100
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:158
    live relational engine, so your normal `.env`

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from topoteretes/cognee at commit 0ec7a9f, republished under its Apache-2.0 licence (© topoteretes). 1,130 words, ~2,621 tokens.

Download SKILL.mdSave it as .claude/skills/cognee-migrations/SKILL.md (or your agent's skills folder).
name
cognee-migrations
description
Use when dealing with cognee database migrations — understanding when they run automatically, checking or repairing migration state with cognee-cli upgrade/downgrade/stamp/current, a write blocked by a failed migration, authoring a new Alembic (relational schema) revision or a graph/vector data migration, or moving data between systems (relational DB import, memory export/import).

Database migrations

cognee has two migration chains, run together:

ChainChangesLives inRevision stored in
Relational schema (Alembic)Tables and columns of the relational DB (users, datasets, ACLs, pipeline runs, …)cognee/alembic/ (alembic.ini is in cognee/)alembic_version table
Graph/vector dataCross-store data rewrites (re-keying node ids, adding graph columns) across graph DB, vector DB and relational ledgercognee/modules/migrations/ (registry.py, versions/)Per dataset: dataset_database.migration_revision (access control on). Globally: global_database_version.global_migration_revision (access control off)

Use it

They run by themselves

run_migrations() applies the relational chain first, then the data chain. It runs:

  • at API server startup (and in the Docker entrypoint.sh before gunicorn);
  • on the first write in an SDK or CLI process (remember, add, cognify, improve, memify, memory imports), once per process;
  • when you call await cognee.run_migrations().

A fresh database is built by running the whole chain (no stamping). At head, the first run in each process still does a no-op Alembic upgrade plus a scan of the per-database revision rows; later calls in the same process are skipped by an in-memory flag. ENABLE_AUTO_MIGRATIONS=false turns off all automatic runs; then run cognee-cli upgrade yourself.

Concurrent processes are serialized by a migration lock: a Postgres advisory lock (works across hosts) or a file lock next to the SQLite DB (one host only).

Check and repair
bash
cognee-cli current                   # stamped revision per database, and the last failure
cognee-cli history                   # the data chain, newest first
cognee-cli upgrade                   # relational to head, then data chain to head
cognee-cli upgrade <slug>            # data chain up to and including <slug>
cognee-cli upgrade --alembic <rev>   # pin the relational target
cognee-cli downgrade <slug|base> [--dataset UUID ...] [--alembic REV] [--force]
cognee-cli stamp <head|base|slug> [--dataset UUID ...] [--force]
  • The positional revision is always a data-chain slug; relational targets go through --alembic.
  • downgrade rewrites data and asks for confirmation. It only reverts spans where every migration defines a down(), and leaves the relational schema alone unless you pass --alembic.
  • stamp changes only the stored data-chain revision, without running anything. Use stamp base --dataset <id> and then upgrade when a database's data drifted from its stamp (for example after restoring a backup); the chain is idempotent and converges it.
  • upgrade runs even with ENABLE_AUTO_MIGRATIONS=false.
A write is blocked

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 cognee-cli upgrade. A failed run is retried on the next start or write.

Moving data between systems (not schema migrations)
GoalUse
Turn an existing relational database into a graphmigrate_relational_database(graph_db, schema) (cognee/tasks/ingestion/migrate_relational_database.py), with the source DB set by MIGRATION_DB_PROVIDER / _PATH / _NAME / _HOST / _PORT / _USERNAME / _PASSWORD. Examples: examples/demos/ingestion_and_migration/
Back up a dataset, or move it to another cognee instanceA COGX archive, see below
Export a dataset's graph for other toolsawait cognee.export(dataset, format=...): "json", "graphml" or "cypher" write a file (one way: cognee can't import them back); "pydantic" (default) returns typed DataPoint objects in memory
Import from another memory system (Mem0, Zep/Graphiti, Letta, LangMem)Build a MemorySource (cognee/modules/migration/sources/) and pass it to await cognee.remember(source, dataset_name=...)

There is no tool that moves a whole deployment from one database backend to another.

COGX archives

COGX (Cognee eXchange, cognee/modules/migration/cogx.py) is cognee's portable memory format and the only export format cognee can import back. An archive is a directory with a manifest.json (COGX version, source system, the dataset's data-migration revision) and one JSONL file per record kind (documents, episodes, entities, facts, memories, memory_blocks), plus nodes.jsonl with the raw graph nodes. The Mem0, Zep, Letta and LangMem importers also translate into COGX records first.

Use it to back up and restore a dataset, or to copy one to another cognee instance:

python
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")
  • A restore defaults to mode="preserve": the archived graph is written back as-is, with no LLM calls. mode="hybrid" also re-cognifies the raw content; mode="re-derive" ignores the archived graph and extracts again (costs LLM tokens).
  • cognee.push() / cognee-cli push does the same to Cognee Cloud: it exports to COGX, packs it as a .cogx.tar.gz and uploads it, and the receiving instance restores it (preserve mode unless you pass mode=).
  • export(..., include_permissions=True) also writes permissions.json with the dataset owner and ACL grants, including password hashes, so the restore recreates working accounts. Treat that archive as a secret.
  • An archive written by a newer major COGX version is rejected with a ValueError; upgrade cognee on the importing side.
Show full SKILL.md (461 more words)Show less

Pitfalls

  • Never regenerate cognee/alembic/frozen_schema.py. It is the certified base schema the initial revision builds from, pinned by cognee/tests/unit/test_frozen_schema_seal.py. Schema changes ship as new revisions at head.
  • Never hand-type an Alembic revision id. Hand-typed patterns (a1b2c3d4e5f6, …) already collided with a downstream chain that vendors this one (b2c3d4e5f6a7). Generate ids with alembic revision.
  • Never rename, remove, or reorder a data-chain entry. The slug is what deployed databases store; an unknown stored slug disables the chain for that database.
  • A model change and its migration land together. CI's "Migration/Model Lockstep Guard" fails otherwise.
  • The relational schema cannot be downgraded below the data-bookkeeping revisions unless the data chain goes to base in the same call.
  • alembic.ini is always the packaged one; COGNEE_ALEMBIC_PATH or --alembic-path only changes the scripts directory (for vendored chains).

How it works

run_migrations() (cognee/modules/migrations/startup.py) takes the migration lock, decides fresh vs existing (a users or alembic_version table exists), runs Alembic in-process on a worker thread, then walks the data chain per database with runner.run_database_migrations, stamping after every step. After the chain, it syncs vector-adapter storage when the recorded cognee_version differs from the library's (versions/adapter_storage_migration.py, not a chain entry).

  • Relational: cognee/alembic.ini, cognee/alembic/env.py, cognee/alembic/versions/, cognee/alembic/frozen_schema.py
  • Data chain: cognee/modules/migrations/ (README.md is the authoring contract; registry.py, migration.py, runner.py, startup.py, versions/)
  • CLI: cognee/cli/commands/migrate_command.py

Extending it

A new Alembic revision
bash
cd cognee                              # the directory with alembic.ini
uv run alembic revision -m "add foo to data"

The DB URL comes from the live relational engine, so your normal .env settings apply. Follow the recent revisions (for example versions/e7f9a1c3d5b8_add_data_dataset_created_index.py):

  • Idempotent and guarded: inspect first (sa.inspect(op.get_bind())) and skip when the table is missing or the column/index already exists.
  • Branch on dialect (conn.dialect.name == "postgresql") for Postgres-only SQL. For Postgres enums use postgresql.ENUM(..., create_type=False) and create the type up front with checkfirst.
  • SQLite cannot drop or alter columns in place: use op.batch_alter_table(...).
  • Indexes: plain CREATE INDEX IF NOT EXISTS inside the migration transaction, not CONCURRENTLY (which releases the version-row lock and lets concurrent workers into the same build). Repair invalid Postgres indexes via pg_index.indisvalid.
  • A new model module outside the usual import path must be imported in cognee/alembic/env.py, or autogenerate will not see it.
A new data migration

Read cognee/modules/migrations/README.md first. In short:

  1. Write a module in cognee/modules/migrations/versions/ with async def migrate(context) (and optionally async def downgrade(context)); step 2 registers them as up= / down=.
  2. Append Migration(slug=..., cognee_version=..., up=..., down_revision=<previous slug>, down=...) to MIGRATIONS in registry.py. The chain is validated at import (linear, unique slugs).
  3. Make it idempotent and cheap on empty stores, and crash-safe: re-key derived stores (vectors, ledger) first and rename in the graph last.
  4. Freeze private copies of any logic you depend on; never import live models that may change later.
Tests
  • cognee/tests/e2e/migrations/test_migration_model_lockstep.py (+ schema_baseline.json): the lockstep CI job.
  • cognee/tests/unit/test_run_migrations.py: single Alembic head, startup behaviour.
  • cognee/tests/unit/test_frozen_schema_seal.py: frozen schema fingerprint.
  • cognee/tests/unit/modules/migrations/: data-chain unit tests.
  • cognee/tests/migrations/test_migration_lockstep.py: data chain against real stores (seed, down, up, verify).

© topoteretes, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/cognee-migrations of topoteretes/cognee.

Open the folder on GitHubat commit 0ec7a9f

Compare with similar skills

Cognee Database Migrations next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Cognee Database Migrations compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Cognee Database Migrations this skilltopoteretes/cognee32k—~2.6kAutomated safety check: NotesApache-2.0
SQL Database Support for pRESTprest/prest4.6k—~1.6kAutomated safety check: PassMIT
Migrationgocronx-team/gocron801—~1.1kAutomated safety check: PassMIT
Neon Postgresusenotra/notra256—~4.1kAutomated safety check: NotesAGPL-3.0
Monstermq Broker Configvogler75/monster-mq143—~2.2kAutomated safety check: PassGPL-3.0
Neon Postgresneondatabase/agent-skills100—~4.1kAutomated safety check: NotesApache-2.0

Similar skills

  • SQL Database Support for pREST

    prest/prest

    Guides classifying, gap-analyzing and scaffolding support for a new SQL database in pREST, from Postgres-compatible variants to entirely new dialects.

    4.6k GitHub stars~1.6k tokensUpdated today
    DatabasesAuto-check passed

  • Migration

    gocronx-team/gocron

    Create, review, or verify gocron database migrations across SQLite, MySQL, and PostgreSQL.

    801 GitHub stars~1.1k tokensUpdated yesterday
    DatabasesAuto-check passed

  • Neon Postgres

    usenotra/notra

    Guides and best practices for working with Lakebase Postgres, the database behind Neon.

    256 GitHub stars~4.1k tokensUpdated today
    DatabasesAuto-check: notes

  • Monstermq Broker Config

    vogler75/monster-mq

    Guide for configuring, deploying, and operating the MonsterMQ broker.

    143 GitHub stars~2.2k tokensUpdated today
    DevOps & CloudAuto-check passed

  • Neon Postgres

    neondatabase/agent-skills

    Official

    Guides and best practices for working with Lakebase Postgres on Neon: connections, pooled vs direct, schema migrations, branching, autoscaling, scale-to-zero, instant restore, read replicas, IP…

    100 GitHub stars~4.1k tokensUpdated yesterday
    DatabasesAuto-check: notes

  • Prisma 8 Contract-First ORM

    prisma/orm

    Official

    Routes Prisma 8 tasks such as contracts, migrations, queries and upgrades to the right reference files for projects on the contract-first @prisma/orm packages.

    48k GitHub stars~3.8k tokensUpdated today
    DatabasesAuto-check: notes

More from topoteretes/cognee

All 19 skills in this repo

  • Cognee CLI Memory Commands

    topoteretes/cognee

    Drives cognee from the terminal with remember, recall, forget and improve memory commands, dataset and config management and database migrations.

    32k GitHub stars~2.2k tokensUpdated today
    Auto-check: notes

  • Cognee Community Packages

    topoteretes/cognee

    Guide to using and contributing cognee community packages: database adapters, data-source connectors, custom tasks and retrievers, and Keywords AI observability.

    32k GitHub stars~1.2k tokensUpdated today
    Auto-check passed

  • Cognee Custom Graph Models

    topoteretes/cognee

    Defines the shape of cognee's knowledge graph with graph_model: DataPoint node classes, identity and index fields, typed edges and fixes for duplicated nodes.

    32k GitHub stars~2.5k tokensUpdated today
    Auto-check passed

  • Cognee Custom Pipelines

    topoteretes/cognee

    Shows how to write custom cognee tasks, chain them into pipelines, store custom DataPoints and run enrichment over the existing graph.

    32k GitHub stars~2.8k tokensUpdated today
    Auto-check passed

  • Cognee Docker Setup

    topoteretes/cognee

    Runs the Cognee AI memory platform in Docker, from a one-file prebuilt image to a full compose stack with UI, MCP server, Postgres and Neo4j.

    32k GitHub stars~901 tokensUpdated today
    Auto-check: notes

  • Cognee Forget

    topoteretes/cognee

    Removes data from cognee memory with forget(), finding the right dataset and document first and choosing between one document, a dataset or only the graph and vector memory.

    32k GitHub stars~1.9k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Cognee Database Migrations

What does Cognee Database Migrations do?

Explains how cognee's two migration chains run, how to check and repair migration state with cognee-cli, and how to write new Alembic or graph and vector migrations. Cognee runs two chains together: Alembic revisions for the relational schema, and data migrations that rewrite content across the graph database, vector database and relational ledger. run_migrations() applies the relational chain first and then the data chain, automatically at API server startup, in the Docker entrypoint and on the first write in an SDK or CLI process, or when you call it yourself.

When should I use Cognee Database Migrations?

Cognee Database Migrations fits situations like: finding out why a cognee write is blocked by a failed migration; checking the stamped revision of each database with cognee-cli current; authoring a new Alembic revision for the relational schema; writing a graph or vector data migration with an undo step.

How do I install Cognee Database Migrations in Claude Code?

Run `npx skills add topoteretes/cognee --skill cognee-migrations -a claude-code`. Or copy the skill folder (.agents/skills/cognee-migrations in topoteretes/cognee) into .claude/skills/cognee-migrations in your project. Claude Code loads it when a task matches its description.

How do I install Cognee Database Migrations in Codex?

Run `npx skills add topoteretes/cognee --skill cognee-migrations -a codex`. Or copy the skill folder (.agents/skills/cognee-migrations in topoteretes/cognee) into .agents/skills/cognee-migrations in your project. Codex loads it when a task matches its description.

Can I use Cognee Database Migrations in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add topoteretes/cognee --skill cognee-migrations -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/cognee-migrations, .gemini/skills/cognee-migrations, .github/skills/cognee-migrations and .opencode/skills/cognee-migrations in your project.

What does Cognee Database Migrations need to run?

Going by SKILL.md and its folder, Cognee Database Migrations needs the command-line tools its instructions call (uv). Our summary lists: A cognee installation with cognee-cli; Postgres or SQLite as the relational database.

Does Cognee Database Migrations access the network?

SKILL.md contains no URLs. Its commands use uv, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Cognee Database Migrations safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Cognee Database Migrations use?

Cognee Database Migrations is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Cognee Database Migrations use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Cognee Database Migrations?

Skills that share tags, products or a category with Cognee Database Migrations: SQL Database Support for pREST (prest/prest, 4.6k stars), Migration (gocronx-team/gocron, 801 stars), Neon Postgres (usenotra/notra, 256 stars) and Monstermq Broker Config (vogler75/monster-mq, 143 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Cognee Database Migrations?

topoteretes (a GitHub organization) maintains it in topoteretes/cognee, which has 31,919 GitHub stars. The repository holds 19 skills in this directory. The repository was last updated on October 9, 2026.

Source: topoteretes/cognee on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.