Migration Guide Template

Migrations lower blood pressure. They explain what’s changing, why it matters, and how to get through the upgrade with verifications and rollbacks close at hand.

❌ DO NOT COPY: Guidance & Constraints

• Keep the frontmatter complete (title, description, icon, versionFrom, versionTo, and optional releaseDate). Readers should know at a glance what versions they are moving between.
• Start with context: summary table + “Should you upgrade?” checklist. Highlight deadlines with <Warning> and call out optional paths with <Tip>.
• Break the body into Plan → Migrate → Validate. Use numbered headings inside Migrate and put rollback instructions directly after any risky step.
• When porting older migration guides, keep existing change tables, screenshots, and warnings. Slot them into this format unless the upgrade path has materially changed.
• Document breaking changes with an Old behavior vs New behavior table. Use <Info icon="check"> for mandatory verification steps.
• Optional flow diagrams are allowed, but only when a left-to-right Mermaid (graph LR) clarifies the upgrade path.
• End with two CTA cards (left = deep dive reference, right = applied example) and keep the comment reminder for reviewers.

✅ COPY THIS: Content Skeleton

Paste the block below, swap placeholders, and delete optional sections only after you’ve confirmed they aren’t needed.

---
title: [Migration title]
description: [Why this upgrade matters]
icon: "arrows-rotate"
versionFrom: "[current version]"
versionTo: "[target version]"
releaseDate: "[YYYY-MM-DD]" # Optional
---

# [Migration headline: state the move]

| Scope | Effort | Downtime |
| --- | --- | --- |
| [Platform/OSS/etc.] | [Low/Medium/High] ([~time]) | [Expected downtime impact] |

<Info>
  **Should you upgrade?**
  - [Criteria 1]
  - [Criteria 2]
  - [Criteria 3]
</Info>

<Warning>
  [Breaking deadline or critical change. Remove if not needed.]
</Warning>

## Timeline

- [Date]: [Milestone]
- [Date]: [Milestone]

{/* Optional: delete if not needed */}
```mermaid
graph LR
A[Plan] */} B[Migrate]
B */} C[Validate]
C */} D[Roll back if needed]

Plan

• [Actionable preparatory step]
• [Stakeholder alignment or backup note]

Migrate

1.

pip install mem0ai==[version]
npm install mem0ai@[version]

[Optional hint or staging strategy.]

Run [verification command] and confirm it reports [expected output].

2.

- memory_filters = true
+ filters = true

Breaking change:[Explain the new behavior and what to update].

Rollback:[Describe how to revert this specific step].

3.

[Code snippet showing new behavior]

[Describe logs, metrics, or sample response that proves success].

Validate

• [Smoke test or script] returns expected result.
• [Dashboard or metric] shows [desired signal].
• [End-to-end scenario] passes with [new behavior].

Breaking changes

Rollback plan

1. [Step-by-step rollback instructions]
2. [Restore backups or redeploy previous image]
3. [Validation after rollback]

Known issues

• [Issue name]: [Status]. [Workaround or link].
• [Issue name]: [Status]. [Workaround or link].

After you migrate

• [Link to feature guide showing new capabilities]
• [Link to cookbook or integration that benefits from the upgrade]

---

## ✅ Publish Checklist
- [ ] Versions (`versionFrom`, `versionTo`) and timelines are accurate.
- [ ] Every breaking change is highlighted via table or `<Warning>`.
- [ ] Rollback instructions are present and placed immediately after risky steps.
- [ ] Verification steps use `<Info icon="check">` and are actionable.
- [ ] Optional sections (Mermaid, tips) removed if unused.
- [ ] Final `<CardGroup>` contains exactly two cards with valid links.