How do I migrate AI agent state between frameworks?

Use StateWeave to export agent state from any supported framework (LangGraph, MCP, CrewAI, AutoGen, DSPy, LlamaIndex, OpenAI Agents, Haystack, Letta, Semantic Kernel) into a Universal Schema, then import it into any other framework. Install with pip install stateweave.

What happens to non-portable state during migration?

StateWeave never silently drops state. Non-portable elements like database connections, credentials, and framework internals are explicitly flagged with severity, reason, and remediation guidance in non_portable_warnings.

How do I add support for a new agent framework?

Subclass StateWeaveAdapter and implement four methods: framework_name, export_state, import_state, and list_agents. Your new adapter instantly gets compatibility with all existing adapters through the star topology.

StateWeave — Cross-Framework Agent State Portability

The Problem

Every migration erases your agent's brain

Without a standard, switching frameworks means losing everything your agent learned.

Without StateWeave

# Agent accumulated 8 messages, 4 findings
# Switch from LangGraph → MCP...

conversation_history  → lost
working_memory        → lost
research_findings     → lost
confidence_score      → lost
tool_results          → lost

# Start over from scratch.

With StateWeave

# Export → Encrypt → Import. Done.

payload = adapter.export_state("agent-1")
mcp_adapter.import_state(payload)

conversation_history  → preserved ✓
working_memory        → preserved ✓
research_findings     → preserved ✓
confidence_score      → preserved ✓
tool_results          → preserved ✓

Architecture

N adapters, not N² translations

Star topology. Every framework translates to one Universal Schema. Adding a framework = one adapter.

Star topology — each framework only needs to translate to the Universal Schema. Adding framework N costs 1 adapter, gives N-1 migration paths.

Code

Export. Import. Done.

Export state, import state. Encrypted, validated, with explicit non-portable warnings.

export.py

from stateweave.adapters.langgraph_adapter import LangGraphAdapter
from stateweave.core.serializer import StateWeaveSerializer

# Pass your LangGraph checkpointer instance
adapter = LangGraphAdapter(checkpointer=my_checkpointer)
payload = adapter.export_state("my-thread-id")

serializer = StateWeaveSerializer()
raw_bytes = serializer.dumps(payload)

from stateweave.adapters.mcp_adapter import MCPAdapter

mcp_adapter = MCPAdapter()
mcp_adapter.import_state(payload)

# Agent resumes with its full context intact.
# Conversation history, working memory, goals — all preserved.

from stateweave.core.encryption import EncryptionFacade
from stateweave.core.migration import MigrationEngine

key = EncryptionFacade.generate_key()
engine = MigrationEngine(encryption=EncryptionFacade(key))

result = engine.export_state(
    adapter=langgraph_adapter,
    agent_id="my-agent",
    encrypt=True,
)

engine.import_state(
    adapter=mcp_adapter,
    encrypted_data=result.encrypted_data,
    nonce=result.nonce,
)

from stateweave.core.diff import diff_payloads

diff = diff_payloads(state_before, state_after)
print(diff.to_report())

# ═════════════════════════════════════════
#  STATEWEAVE DIFF REPORT
# ═════════════════════════════════════════
#  Changes: 5 (+2 -1 ~2)
#  [working_memory]
#    + working_memory.new_task: "research"
#    ~ confidence: 0.7 → 0.95

Frameworks

Growing adapter ecosystem

Star topology. One adapter per framework = instant compatibility with all others.

Framework	Export	Import	Tier
LangGraph	✓	✓	🟢 Tier 1
MCP	✓	✓	🟢 Tier 1
CrewAI	✓	✓	🟢 Tier 1
AutoGen	✓	✓	🟢 Tier 1
DSPy	✓	✓	🟡 Tier 2
OpenAI Agents	✓	✓	🟡 Tier 2
LlamaIndex	✓	✓	🔵 Community
Haystack	✓	✓	🔵 Community
Letta / MemGPT	✓	✓	🔵 Community
Semantic Kernel	✓	✓	🔵 Community
Custom	✓	✓	Extensible

🟢 Tier 1 = Core team, guaranteed stability · 🟡 Tier 2 = Actively maintained · 🔵 Community = Best-effort

MCP Server

Ships as an MCP Server

Any MCP-compatible assistant can export, import, and diff agent state directly.

Tools

export_agent_state Export cognitive state from any framework

import_agent_state Import into target framework with validation

diff_agent_states Detailed change report between two states

Resources

schemas/v1 Universal Schema specification

migrations/history Migration history log

agents/{id}/snapshot Live agent state snapshot

Encryption

Encrypted. Validated. Zero silent loss.

AES-256-GCM

Authenticated encryption. Unique nonce per operation. Ciphertext bound to agent metadata.

Ed25519 Signing

Digital signatures verify sender identity and detect tampering. Sign, verify, and attach to payloads.

PBKDF2 · 600K

OWASP-recommended key derivation. Passphrase-based with versioned key IDs.

Credential Stripping

API keys, OAuth tokens, and passwords are flagged as non-portable and stripped on export.

Non-Portable Warnings

Every non-transferable element is documented with severity, reason, and remediation. Never silent.

REST API + Docker

Deploy behind your firewall. Dockerfile and docker-compose included.

v0.3 Features

Delta transport. State merge. Compliance.

Ship only state diffs. Merge parallel agents. Enforce compliance with 10 automated scanners.

Delta Transport

Send only state differences instead of full payloads. SHA-256 hash verification prevents base mismatch.

State Merge (CRDT)

Merge parallel agents with conflict resolution: Last-Writer-Wins, Union, or Manual review.

UCE Compliance

10 automated scanners enforce schema integrity, encryption, import discipline, and test coverage. Zero false passes.

Auto-Detection

stateweave detect identifies source framework from raw state via fingerprinting heuristics.

Migration Reports

HTML, Markdown, and JSON reports with fidelity scores, audit trails, and non-portable analysis.

Observability

Structured JSON logging, in-memory metrics, and trace_operation context manager for monitoring.

Schema

One canonical format

Every framework translates to and from the Universal Schema. Star topology, not mesh.

StateWeavePayload

StateWeavePayload(
  stateweave_version="0.3.0",
  source_framework="langgraph",
  cognitive_state=CognitiveState(
    conversation_history=[...],
    working_memory={...},
    goal_tree={...},
    tool_results_cache={...},
    trust_parameters={...},
    long_term_memory={...},
    episodic_memory=[...],
  ),
  metadata=AgentMetadata(...),
  audit_trail=[...],
  non_portable_warnings=[...],
)

conversation_history

Complete message thread — human, AI, system, tool messages

working_memory

Current task state, key-value pairs, active research context

goal_tree

Active goals, sub-goals, completion status

tool_results_cache

Cached outputs from web searches, file reads, API responses

trust_parameters

Confidence scores, reliability metrics, source credibility

audit_trail

Full operation history — every export, import, migration logged

Extend

One adapter, N connections

Subclass one ABC. Implement four methods. Instant compatibility with the entire ecosystem.

my_adapter.py

from stateweave.adapters.base import StateWeaveAdapter
from stateweave.schema.v1 import StateWeavePayload, AgentInfo

class MyFrameworkAdapter(StateWeaveAdapter):
    @property
    def framework_name(self) -> str:
        return "my-framework"

    def export_state(self, agent_id: str, **kwargs) -> StateWeavePayload:
        # Framework state → Universal Schema
        ...

    def import_state(self, payload: StateWeavePayload, **kwargs):
        # Universal Schema → framework state
        ...

    def list_agents(self) -> list[AgentInfo]:
        # Return discoverable agents
        ...

FAQ

Common questions

Install with pip install stateweave. Use the source framework's adapter to export_state(), then the target framework's adapter to import_state(). All cognitive state — conversation history, working memory, goals, tool results — transfers through the Universal Schema.

StateWeave never silently drops data. Non-portable elements (database connections, credentials, framework internals) are stripped and documented in non_portable_warnings with severity, reason, and remediation guidance.

Yes. AES-256-GCM authenticated encryption with PBKDF2 key derivation (600K iterations). Each operation gets a unique nonce. Ciphertext is bound to agent metadata via associated data.

Subclass StateWeaveAdapter and implement framework_name, export_state, import_state, and list_agents. That's it — your framework gets instant migration paths to every existing adapter through the star topology.

Yes. StateWeave ships as an MCP Server with three tools: export_agent_state, import_agent_state, and diff_agent_states. Any MCP-compatible AI assistant can use StateWeave directly.

Apache 2.0. Use it, modify it, ship it. Includes a patent shield and retaliation clause. Every component — adapters, serializer, encryption, diff engine, MCP server — is open source.

Your agent switches frameworks.
Its brain doesn't break.

Every migration erases your agent's brain

N adapters, not N² translations

Export. Import. Done.

Growing adapter ecosystem

Ships as an MCP Server

Tools

Resources

Encrypted. Validated. Zero silent loss.

AES-256-GCM

Ed25519 Signing

PBKDF2 · 600K

Credential Stripping

Non-Portable Warnings

REST API + Docker

Delta transport. State merge. Compliance.

Delta Transport

State Merge (CRDT)

UCE Compliance

Auto-Detection

Migration Reports

Observability

One canonical format

One adapter, N connections

Common questions

Build a new adapter

Your agent switches frameworks. Its brain doesn't break.

Every migration erases your agent's brain

N adapters, not N² translations

Export. Import. Done.

Growing adapter ecosystem

Ships as an MCP Server

Tools

Resources

Encrypted. Validated. Zero silent loss.

AES-256-GCM

Ed25519 Signing

PBKDF2 · 600K

Credential Stripping

Non-Portable Warnings

REST API + Docker

Delta transport. State merge. Compliance.

Delta Transport

State Merge (CRDT)

UCE Compliance

Auto-Detection

Migration Reports

Observability

One canonical format

One adapter, N connections

Common questions

Build a new adapter

Your agent switches frameworks.
Its brain doesn't break.