State Weave

🧶 StateWeave

git for agent brains.

When your agent goes wrong, see exactly where and why. Then rewind.

______________________________________________________________________

StateWeave 是 git 对于代理大脑——调试、时间旅行和跨10个框架迁移代理状态。当一个20步的自主工作流在步骤15脱轨时，看看到底发生了什么变化，倒退到步骤14，然后重放。从LangGraph导出，导入CrewAI，数据零丢失。检查点、回滚、差异、加密、签名——所有这些都通过一个通用模式完成。

当你的特工产生幻觉、崩溃或漂移时-- stateweave why 显示了出错的确切状态转换。当您的企业需要审计代理行为时，每个状态更改都会进行版本控制、签名和加密。

为什么选择StateWeave？

StateWeave解决了AI代理生态系统中的三个关键问题：

🔍 调试 --代理工作流是不确定的。当它们出错时，您需要暂停、倒退、检查和回放，而不是重新启动。 stateweave why 显示了导致失败的确切状态转换。代理认知的版本控制。

🔒 安全 --Agent状态包含Agent的整个认知历史。StateWeave在静态加密（AES-256-GCM），对有效载荷进行签名（Ed25519），在导出时剥离凭据，并执行合规政策。

🔄 可移植性 --每个框架都有持久性，没有一个框架具有可移植性。StateWeave的 通用架构 --代理认知状态的规范表示——允许您在10个框架中的任何一个框架之间移动状态。一个模式，N个适配器，零数据丢失（对任何不可移植的东西都有明确的警告）。

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

星形拓扑，而不是网格。 N个适配器，而不是N²转换对。添加一个新框架=一个适配器，与其他所有内容即时兼容。

看到它工作

$ 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.

现在试试： pip install stateweave && stateweave quickstart --10秒内完成零代码演示。 或者运行完整的7步演示： python examples/full_demo.py

一个命令迁移

$ 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都会打印一个丰富的会话摘要：

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

git样式CLI

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

与Claude桌面/光标一起使用

添加到MCP配置(~/.cursor/mcp.json 或克劳德桌面设置）：

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

Claude和Cursor现在可以直接导出、导入和区分您的代理状态。

导出代理人所在州

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

框架支持

层级定义： 🟢 第1级 =核心团队保持稳定。 🟡 第2层 =积极维护，补丁可能会滞后。 🔵 社区 =社区尽最大努力。

调试代理失败

当你的特工产生幻觉、崩溃或漂移时-- stateweave why 向您准确显示发生了什么：

$ 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

查看完整演示： python examples/viral_demo.py

MCP 服务器

StateWeave作为MCP服务器发布——任何兼容MCP的AI助手都可以直接使用它。

工具

资源

提示

通用模式

每个代理的状态都表示为 StateWeavePayload:

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
)

安全

• AES-256-GCM 每次操作使用唯一随机数进行身份验证加密
• PBKDF2 密钥推导（600K迭代，推荐OWASP）
• Ed25519有效载荷签名 --数字签名验证发送者身份并检测篡改
• 凭证剥离 -API密钥、令牌和密码被标记为不可移植，并在导出过程中被剥离
• 非便携式警告 --每个不能完全传输的状态都有明确的记录（没有无声的数据丢失）
• 关联数据 --使用AAD加密，将密文绑定到特定的代理元数据

有效载荷签名

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())

内容可寻址存储（SHA-256）、父哈希链、版本之间的增量压缩。

A2A桥

桥之间 代理2代理（A2A）协议 以及StateWeave。A2A定义了代理如何通信——StateWeave添加了代理所知道的内容：

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()

州合并（CRDT基金会）

合并并行代理的状态：

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

不可移植状态

并非所有内容都可以在框架之间转移。StateWeave诚实地处理这个问题：

所有非便携式元素都出现在 payload.non_portable_warnings[] 严重性、原因和补救指导。

零损失翻译

没有映射到通用字段的框架特定状态是 不是默默地掉下来的 --它保存在 cognitive_state.framework_specific:

# 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)

三层状态处理：

构建自定义适配器

扩展 StateWeaveAdapter 添加对任何框架的支持：

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
        ...

UCE adapter_contract 扫描仪会自动验证所有适配器是否正确实现了ABC。

命令行界面

# ── 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

合规性（UCE）

StateWeave通过 通用合规引擎 --12个自动扫描仪，在发货前发现架构违规：

# Run UCE locally
python scripts/uce.py

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

为什么不自己序列化为JSON？

你可以——而且它适用于一个框架。以下是你需要构建的内容：

StateWeave的存在是因为框架之间的转换层是每个团队都要重建的无聊、容易出错的工作。我们曾经建造过一次。

贡献

我们欢迎捐款！最具影响力的贡献方式是 构建新的框架适配器。参见 构建自定义适配器 上面。

开发设置

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？

将徽章添加到项目的README中：

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


许可证

Apache 2.0 --使用它，修改它，运送它。包括专利盾牌。

______________________________________________________________________

🧶 StateWeave — git for agent brains.