# Schema Evolution Migrator

> |

- **Type:** Skill
- **Install:** `agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-schema-evolution-migrator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AnthonyAlcaraz](https://agentstack.voostack.com/s/anthonyalcaraz)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AnthonyAlcaraz](https://github.com/AnthonyAlcaraz)
- **Source:** https://github.com/AnthonyAlcaraz/agentic-graph-rag-skills/tree/main/skills/optimization/schema-evolution-migrator
- **Website:** https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

## Install

```sh
agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-schema-evolution-migrator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Schema Evolution Migrator

## Overview

A knowledge graph in production is not a static artifact. New data arrives
continuously, schemas evolve, and nodes accumulate that no longer represent
current reality. Without deliberate lifecycle management the graph grows stale,
queries slow down, and the agent's reasoning degrades — not because the agent
changed but because the knowledge it depends on did.

Graph databases have no `ALTER TABLE`, and the schema-optional nature of property
graphs means schema drift happens silently. This skill packages the four
operational concerns from the chapter:

- **Schema evolution** — Neo4j-Migrations (Flyway/Liquibase for graphs); the
  migration history is itself a subgraph. Every change must be **N-1
  compatible**: the previous application version keeps working until it is
  replaced (Example 8-7).
- **Lifecycle** — append-only with TTL (CrowdStrike's Threat Graph never
  updates, only adds: 40+ PB, trillions of events/day, 70M req/s) and temporal
  invalidation (Graphiti/Zep bitemporal: invalidate the old edge, do not delete
  it, so historical queries still traverse it — Example 8-8).
- **Incremental updates** — LightRAG-style `MERGE ON CREATE / ON MATCH`; update
  cost is proportional to the new data, not the whole graph, so a deployment
  event is reflected within seconds instead of a nightly rebuild (Example 8-9).
- **Deployment** — a staged rollout coordinating three independently versioned
  components (schema, data, agent code) with `depends_on` ordering and a canary
  gate (Example 8-10).

## When to Use

- A production graph needs a schema change (new relationship type, new
  constraint) deployed alongside agent-code changes.
- A dependency changed and you must record the new fact without losing the old
  one for causal reasoning.
- Snapshot nodes are accumulating and you need a retention policy.
- You are coordinating a release across graph schema, data backfill, and agent
  code and want a manifest that enforces the ordering.

Phrases that should invoke this skill: "migrate the graph schema", "temporal
invalidation", "incremental graph update", "deployment manifest", "N-1
compatibility", "staged rollout", "TTL the knowledge graph".

## When NOT to Use

- **One-time graph construction.** Initial build is not evolution; use the
  Chapter-3 construction pattern.
- **Relational migrations.** Flyway/Liquibase handle SQL; this is graph-native
  (MERGE, DETACH, constraints).
- **Splitting/merging node types.** As of the book no graph DB natively supports
  these; Nautilus/Geo-X compile them to Cypher/APOC externally. Plan the schema
  carefully upfront and budget engineering time.
- **Model routing / cost / latency.** Those are the other Ch8 skills.

## Process

| Step | Input | Action | Output | Verification |
|------|-------|--------|--------|--------------|
| 1 | (design) | `lib.monitored_by_migration()` | V003 migration + rollback | N-1 compatible; rollback present |
| 2 | Dependency change | `lib.temporal_invalidate_cypher(...)` | SET t_invalid + MERGE new edge | Sets t_invalid, never DELETE |
| 3 | Deployment event JSON | `lib.incremental_merge_cypher(event)` | 3-statement merge | Uses ON CREATE/ON MATCH; invalidates gone deps |
| 4 | resources + interval | `lib.snapshot_growth_per_day(n, m)` | Nodes/day estimate | 200 @ 5-min = 57,600 |
| 5 | node class | `lib.RETENTION_POLICY[class]` | Retention rule | hub = permanent; snapshot = aggressive TTL |
| 6 | release name | `lib.staged_rollout_manifest(release)` | 4-phase manifest | depends_on ordering enforced |
| 7 | manifest | `lib.validate_manifest(manifest)` | valid + problems | Fails on mis-ordering or missing canary |

## Rationalizations

| Agent rationalization | Documented rebuttal |
|-----------------------|---------------------|
| "Just delete the old dependency edge." | Delete destroys the historical record the agent needs for causal reasoning ("what did the infra look like before the change"). Invalidate with t_invalid; historical queries filter on validity windows (Example 8-8). |
| "Deploy the schema migration and the code together." | If the code deploys before the migration it references relationship types that do not exist; if the migration renames an edge before the old code is gone, the old code breaks. Stage it: migration first with N-1 compatibility, then code, then cleanup (Example 8-10). |
| "Rebuild the graph nightly to stay current." | A full rebuild is expensive and creates a stale-or-inconsistent window. LightRAG incremental merge costs in proportion to the new data, not the graph size — the event lands in seconds (Example 8-9). |
| "Aggressive TTL everywhere keeps the graph small." | Overpruning deletes the incident history the failure-prediction agent trains on. TTL snapshots aggressively; retain incident and hub nodes long (RETENTION_POLICY; Ch8 pitfall). |
| "Drop the legacy property as soon as the new code ships." | A code path may still reference it. The manifest delays schema cleanup (7 days) until no code references the deprecated element (Example 8-10). |

## Red Flags

- **A migration that is not N-1 compatible ships without a two-phase plan.**
  The previous app version will break the moment the migration lands.
- **Invalidation uses DELETE.** The historical edge is gone; causal reasoning
  over past states silently loses data.
- **Incremental merge without ON CREATE/ON MATCH.** Either duplicates nodes or
  overwrites enrichment; the upsert semantics are the point.
- **Manifest with agent_code before schema_migration.** The staged-rollout
  ordering is inverted; `validate_manifest` must fail it.
- **Schema cleanup with no delay.** Legacy schema dropped while code still
  references it. CLI `--help` exiting non-zero is the same class of seam break.

## Non-Negotiable Verification

Before shipping a graph change built on this skill:

1. **Run the benchmark battery.**
   ```
   python cli.py benchmark
   ```
   Confirms N-1 compatibility, invalidate-not-delete, the Fischer growth math
   (200 @ 5-min = 57,600), incremental upsert semantics, and that a mis-ordered
   manifest fails validation.

2. **Read the migration and its rollback.**
   ```
   python cli.py migration
   ```
   Confirm the forward migration adds MONITORED_BY + the uniqueness constraint
   and the rollback removes both.

3. **Validate the deployment manifest.**
   ```
   python cli.py manifest --release r1 | python cli.py validate --manifest /dev/stdin
   ```
   (or `python cli.py validate`) — confirm valid=true and the phases are
   schema -> data -> code -> cleanup with a canary on the code phase.

4. **Domain test in the notebook.** Run `notebooks/ch8-optimization.ipynb`;
   confirm the schema-evolution section generates the MONITORED_BY migration and
   ingests the checkout-service stripe-python 3.2.1 -> 3.3.0 deployment event.

## Security Posture

- **Emits Cypher; runs nothing.** `lib.py` builds migration/merge text and a
  manifest dict. Apply migrations through Neo4j-Migrations with review, not by
  piping generated Cypher straight into a production database.
- **Parameterized incremental merge.** The Example 8-9 statements use `$params`,
  not string interpolation of event data — keep it that way; a deployment event
  from an untrusted source is an injection surface if interpolated into Cypher.
- **Migrations are irreversible-ish.** Always ship the rollback and take a
  backup/snapshot before applying; a DETACH DELETE in a hard cleanup cannot be
  undone from the graph alone.
- **N-1 discipline is a safety property.** Skipping it risks a production outage
  window where old code meets new schema; treat the N-1 flag as a gate, not a
  hint.

## Composition

- **Feeds** the Chapter-7 canary/staging mechanics: the manifest's
  `promotion_criteria` (p95 = -0.02) connect to the
  self-evolution deployment gates.
- **Uses** the temporal model shared with `subgraph-access-control` retention:
  invalidated edges carry validity windows the compliance audit can query.
- **Pairs with** `cost-performance-scorer`: the canary promotion criteria are
  the same cost/quality signals scored there.

## Source Attribution

Distilled from *Agentic GraphRAG* (O'Reilly, by Anthony Alcaraz and Sam Julien),
Chapter 8 — Optimization, "Production Systems and Maintenance". Key references:

- Neo4j-Migrations (Michael Simons) — Flyway/Liquibase for graphs; Example 8-7
- Daschner Kubernetes init-container migration pattern; N-1 compatibility
- Hausler & Klettke — Nautilus / Geo-X (2025) evolution language
- CrowdStrike Threat Graph (append-only + TTL; 40+ PB, 70M req/s)
- Graphiti / Zep bitemporal temporal invalidation (Example 8-8)
- Fischer — temporal infrastructure graph on Neo4j (200 @ 5-min = 57,600/day)
- LightRAG incremental update (Example 8-9)
- Example 8-10 deployment manifest (staged rollout)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AnthonyAlcaraz](https://github.com/AnthonyAlcaraz)
- **Source:** [AnthonyAlcaraz/agentic-graph-rag-skills](https://github.com/AnthonyAlcaraz/agentic-graph-rag-skills)
- **License:** MIT
- **Homepage:** https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-anthonyalcaraz-agentic-graph-rag-skills-schema-evolution-migrator
- Seller: https://agentstack.voostack.com/s/anthonyalcaraz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.