StateWeave

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  LangGraph  │     │    MCP      │     │   CrewAI    │     │   AutoGen   │
│   Adapter   │     │   Adapter   │     │   Adapter   │     │   Adapter   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       └───────────┬───────┴───────────┬───────┘                   │
                   │                   │                           │
                   ▼                   ▼                           ▼
            ┌──────────────────────────────────────────────────────────┐
            │              🧶  Universal Schema v1                     │
            │                                                          │
            │  conversation_history  ·  working_memory  ·  goal_tree   │
            │  tool_results_cache  ·  trust_parameters  ·  audit_trail │
            └──────────────────────────────────────────────────────────┘

$ pip install stateweave
$ python examples/full_demo.py

━━ 1. Export from LangGraph ━━
  ✓ Exported 4 messages
  ✓ Source framework: langgraph

━━ 2. Import into MCP ━━
  ✓ Imported into mcp
  ✓ Messages preserved: 4

━━ 3. Verify Round-Trip ━━
  ✓ Zero data loss: YES

━━ 4. Diff Agent States ━━
  Summary: 7 added, 4 removed, 7 modified

━━ 5. Time Travel ━━
  ✓ Checkpoint v1 (initial-research)
  ✓ Checkpoint v2 (after-drug-discovery)
  ✓ Rolled back → 4 msgs

━━ 6. Encryption (AES-256-GCM) ━━
  ✓ 1,733 bytes → 1,749 bytes encrypted
  ✓ Decrypted: 4 messages intact

━━ 7. Non-Portable Warnings ━━
  ✓ No non-portable warnings (clean export)

7/7 steps passed. Everything runs from PyPI.

$ stateweave migrate --from langgraph --to crewai --agent my-agent

  🧶 StateWeave Migrate: langgraph → crewai
  ════════════════════════════════════════════════

  ━━ Step 1: Export from langgraph ━━
    ✓ Exported 12 messages, 5 memory keys (0.01s)

  ━━ Step 2: Validate payload ━━
    ✓ Payload valid — all schema checks passed

  ━━ Step 3: Import into crewai ━━
    ✓ Imported into crewai (0.00s)

  ━━ Step 4: Verify round-trip ━━
    ✓ Messages: 12 → 12 (zero loss)
    ✓ Memory keys: 5 → 5 (zero loss)

  ────────────────────────────────────────────────
  ✅ Migration complete: langgraph → crewai (0.01s)

import stateweave
stateweave.auto(verbose=True)  # Auto-checkpoint + confidence alerts + session summary card.

  ┌──────────────────────────────────────────────┐
  │  🧶 StateWeave Session Summary               │
  ├──────────────────────────────────────────────┤
  │  Agent: my-agent                              │
  │    Steps: 12         Checkpoints: 3           │
  │    Confidence: 87%   ▲                        │
  │  ✅ No alerts — agent ran clean               │
  │  💡 Run: stateweave report                    │
  └──────────────────────────────────────────────┘

stateweave log my-agent           # Beautiful checkpoint history with confidence sparkline
stateweave blame my-agent confidence  # Which checkpoint changed confidence? Value history.
stateweave stash my-agent         # Save current state (like git stash)
stateweave pop my-agent           # Restore stashed state
stateweave replay my-agent        # Step-by-step state debugger
stateweave watch                  # Live agent health dashboard (htop for agent brains)
stateweave ci my-agent            # CI regression detection — exits non-zero on failure

pip install stateweave

{
  "mcpServers": {
    "stateweave": {
      "command": "python3",
      "args": ["-m", "stateweave.mcp_server"]
    }
  }
}

from stateweave import LangGraphAdapter, MCPAdapter, diff_payloads

# Set up a LangGraph agent with some state
lg = LangGraphAdapter()
lg._agents["my-agent"] = {
    "messages": [
        {"type": "human", "content": "What's the weather?"},
        {"type": "ai", "content": "It's 72°F and sunny!"},
    ],
    "current_task": "weather_check",
}

# Export from LangGraph
payload = lg.export_state("my-agent")
print(f"Exported: {len(payload.cognitive_state.conversation_history)} messages")

from stateweave import MCPAdapter

# Import into MCP
mcp_adapter = MCPAdapter()
mcp_adapter.import_state(payload)

# The agent resumes with its memories intact

from stateweave.middleware import auto_checkpoint

# Simple: checkpoint every 5 steps
@auto_checkpoint(every_n_steps=5)
def run_agent(payload):
    return payload

# Smart: only checkpoint on significant state changes
@auto_checkpoint(strategy="on_significant_delta", delta_threshold=3)
def smart_agent(payload):
    return payload

# Manual: zero overhead, checkpoint when you decide
@auto_checkpoint(strategy="manual_only")
def hot_path_agent(payload):
    return payload

from stateweave import EncryptionFacade, MigrationEngine

# Set up encrypted migration
key = EncryptionFacade.generate_key()
engine = MigrationEngine(
    encryption=EncryptionFacade(key)
)

# Full pipeline: export → validate → encrypt → transport
result = engine.export_state(
    adapter=langgraph_adapter,
    agent_id="my-agent",
    encrypt=True,
)

# Decrypt → validate → import on the other side
engine.import_state(
    adapter=mcp_adapter,
    encrypted_data=result.encrypted_data,
    nonce=result.nonce,
)

from stateweave 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'
#     ~ working_memory.confidence: 0.7 → 0.95

$ stateweave why my-agent

🔍 StateWeave Autopsy: my-agent
══════════════════════════════════════════
  Checkpoints: 5 versions
  Latest: v5 (2026-03-20 14:23:01)

📊 State Evolution
──────────────────────────────────────────
  v1 → v2: 3 changes (+2 added, ~1 modified)
  v2 → v3: 7 changes (+4 added, ~2 modified, -1 removed)  ← BIGGEST
  v3 → v4: 1 change (~1 modified)
  v4 → v5: 2 changes (+1 added, ~1 modified)

🩺 Diagnosis
  Biggest change: v2 → v3 (7 changes)
  Label: after-tool-failure
  💡 Recommendation: stateweave rollback my-agent 2

from stateweave.core.timetravel import CheckpointStore

store = CheckpointStore()
restored = store.rollback("my-agent", version=2)
# Agent brain restored to pre-failure state

StateWeavePayload(
    stateweave_version="0.3.15",
    source_framework="langgraph",
    exported_at=datetime,
    cognitive_state=CognitiveState(
        conversation_history=[...],   # Full message history
        working_memory={...},         # Current task state
        goal_tree={...},              # Active goals
        tool_results_cache={...},     # Cached tool outputs
        trust_parameters={...},       # Confidence scores
        long_term_memory={...},       # Persistent knowledge
        episodic_memory=[...],        # Past experiences
    ),
    metadata=AgentMetadata(
        agent_id="my-agent",
        access_policy="private",
    ),
    audit_trail=[...],               # Full operation history
    non_portable_warnings=[...],     # Explicit data loss docs
)

from stateweave import EncryptionFacade

# Generate a signing key pair
private_key, public_key = EncryptionFacade.generate_signing_keypair()

# Sign serialized payload
signature = EncryptionFacade.sign(payload_bytes, private_key)

# Verify on receipt
is_authentic = EncryptionFacade.verify(payload_bytes, signature, public_key)

from stateweave.core.delta import create_delta, apply_delta

# Create delta: only the differences
delta = create_delta(old_payload, new_payload)

# Apply delta on the receiver side
updated = apply_delta(base_payload, delta)

from stateweave.core.timetravel import CheckpointStore

store = CheckpointStore()

# Save a checkpoint
store.checkpoint(payload, label="before-experiment")

# View history
print(store.format_history("my-agent"))

# Roll back to a previous version
restored = store.rollback("my-agent", version=3)

# Branch from a checkpoint
store.branch("my-agent", version=3, new_agent_id="my-agent-experiment")

# Diff two versions
diff = store.diff_versions("my-agent", version_a=1, version_b=5)
print(diff.to_report())

from stateweave.a2a import A2ABridge

bridge = A2ABridge()

# Package state for A2A handoff
artifact = bridge.create_transfer_artifact(payload)

# Extract state from received A2A message
extracted = bridge.extract_payload(a2a_message_parts)

# Generate AgentCard skill for capability advertisement
caps = bridge.get_agent_capabilities()
skill = caps.to_agent_card_skill()

from stateweave.core.merge import merge_payloads, ConflictResolutionPolicy

result = merge_payloads(
    agent_a_state, agent_b_state,
    policy=ConflictResolutionPolicy.LAST_WRITER_WINS,
)
merged_payload = result.payload

# LangGraph internals survive the round-trip
payload = lg_adapter.export_state("my-thread")
print(payload.cognitive_state.framework_specific)
# {"__channel_versions__": {"messages": 5}, "checkpoint_id": "ckpt-abc"}

# Import back into LangGraph — internal state is restored
target = LangGraphAdapter()
target.import_state(payload)

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:
        # Translate your framework's state → Universal Schema
        ...

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

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

# ── Get started in 10 seconds ──
stateweave quickstart              # zero-code demo: checkpoint, diff, rollback
stateweave init                    # set up project config (.stateweave/config.toml)

# ── One-command migration ──
stateweave migrate --from langgraph --to crewai --agent my-agent
stateweave benchmark               # round-trip fidelity test across all 10 frameworks

# ── Debug agent failures ──
stateweave why my-agent            # autopsy: what changed and where it went wrong
stateweave doctor                  # diagnostic health checks
stateweave replay my-agent         # step-by-step state debugger

# ── git-style state management ──
stateweave log my-agent            # checkpoint history with confidence sparkline
stateweave blame my-agent confidence  # trace which checkpoint changed a key
stateweave stash my-agent          # save current state (like git stash)
stateweave pop my-agent            # restore stashed state

# ── Version control for agent state ──
stateweave checkpoint state.json --label "before-experiment"
stateweave history my-agent
stateweave rollback my-agent 3 -o restored.json
stateweave diff before.json after.json

# ── Export / Import ──
stateweave export -f langgraph -a my-agent -o state.json
stateweave import -f crewai --payload state.json
stateweave detect state.json       # auto-detect source framework
stateweave inspect state.json      # pretty-print payload with structured summary

# ── Monitoring ──
stateweave watch                   # live agent health dashboard (htop for brains)
stateweave status my-agent         # agent state summary
stateweave stats                   # aggregate dashboard: agents, checkpoints, store size
stateweave ci my-agent             # CI regression detection (exits non-zero on failure)

# ── Utilities ──
stateweave try                     # interactive migration picker
stateweave report                  # shareable markdown report for PRs/Slack
stateweave hook install            # install git pre-commit hook (auto-runs ci)
stateweave version                 # version, adapters, encryption status
stateweave adapters                # list all 10 framework adapters
stateweave scan                    # scan for installed frameworks
stateweave schema -o schema.json   # dump Universal Schema as JSON Schema
stateweave validate state.json     # validate a payload file
stateweave generate-adapter my-framework  # scaffold new adapter
stateweave completions bash        # generate shell completions (bash/zsh/fish)

# ── Maintenance ──
stateweave clean --keep 5          # prune old checkpoints (keep latest 5)
stateweave config list             # view config without editing TOML
stateweave config set --key framework --value langgraph
stateweave upgrade                 # check for new versions on PyPI
stateweave env                     # full environment snapshot (Python, frameworks, store)
stateweave search "confidence"     # search checkpoint history for key/value
stateweave compare my-agent 1 3    # visual diff between two checkpoint versions

# Run UCE locally
python scripts/uce.py

# Run in CI mode (exit 1 on failure)
python scripts/uce.py --mode=CI --json

git clone https://github.com/GDWN-BLDR/stateweave.git
cd stateweave
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run UCE
python scripts/uce.py

stateweave/
├── schema/        # Universal Schema (Pydantic models)
├── core/          # Engine (serializer, encryption, diff, delta, timetravel, environment, doctor)
├── adapters/      # Framework adapters (10 frameworks)
├── a2a/           # A2A protocol bridge
├── middleware/    # Auto-checkpoint middleware
├── playground/    # Interactive playground (REST API + UI)
├── registry/      # Schema registry (publish, search, discover)
├── templates/     # Project scaffolding (create-stateweave-agent)
├── mcp_server/    # MCP Server implementation
└── compliance/    # UCE scanners

[![StateWeave](https://img.shields.io/badge/state-StateWeave-7c3aed)](https://github.com/GDWN-BLDR/stateweave)