MCP Server

🚀 StateCLI - AI 智能体的记忆与自我感知层

StateCLI 为 AI 编码智能体赋予记忆、重放和撤销操作的能力，解决了智能体在操作过程中缺乏记忆、无法撤销错误以及对自身影响缺乏感知的问题，是 AI 智能体基础设施的重要组成部分。

🚀 快速开始

直接使用（无需安装）

npx -y statecli-mcp-server

通过 NPM 包安装

npm install -g statecli-mcp-server

启动自动跟踪

cd your-project
statecli watch start --auto-checkpoint

✨ 主要特性

• 🧠 记忆能力：智能体能够记录并重放之前的操作，了解自己做了什么。
• ⏮️ 撤销功能：可以立即修复错误，支持创建检查点和回滚操作。
• 👁️ 自我感知：能够跟踪变化，了解自身操作产生的影响。

📦 安装指南

全局安装

npm install -g statecli-mcp-server

为不同客户端安装

为 Claude Desktop 安装

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加以下内容：

{
  "mcpServers": {
    "statecli": {
      "command": "npx",
      "args": ["-y", "statecli-mcp-server"]
    }
  }
}

为 Windsurf 安装

1. 按下 Ctrl + Shift + P，输入 Open MCP Config。
2. 在配置中添加 StateCLI：

{
  "mcpServers": {
    "statecli": {
      "command": "npx",
      "args": ["-y", "statecli-mcp-server"]
    }
  }
}

3. 重新加载窗口（Ctrl + Shift + P → Reload Window）

为 Cursor / Continue / 其他 MCP 客户端安装

在 MCP 配置中添加：

{
  "mcpServers": {
    "statecli": {
      "command": "npx",
      "args": ["-y", "statecli-mcp-server"]
    }
  }
}

💻 使用示例

基础用法

开发者：自动跟踪模式

启动项目监控：

statecli watch start --auto-checkpoint

此时 StateCLI 会自动执行以下操作：

• 跟踪每个文件的保存操作。
• 每 15 分钟创建一次检查点。
• 允许撤销任何错误操作。
• 显示最近的更改。
• 支持 Windows 系统（v0.4.1+）

查看更改内容：

statecli diff --time 5m

撤销错误操作：

statecli undo

👉 完整开发者指南

AI 智能体：MCP 工具

MCP 配置：

{
  "mcpServers": {
    "statecli": {
      "command": "npx",
      "args": ["-y", "statecli-mcp-server"]
    }
  }
}

高级用法

智能体自我调试模式

// 带有 StateCLI 的智能体调试循环
try {
  await agent.run(task);
} catch (error) {
  // 获取刚刚发生的操作的重放信息
  const replay = await mcp.call("statecli_replay", {
    entity: `task:${task.id}`,
    actor: "ai-agent"
  });
  
  // 分析出错原因
  const analysis = await llm.analyze({
    replay: replay.result,
    error: error.message,
    prompt: "What went wrong in this sequence?"
  });
  
  // 如果可以修复，则撤销操作
  if (analysis.canRetry) {
    await mcp.call("statecli_undo", {
      entity: `task:${task.id}`,
      steps: 1
    });
    
    // 修复后重试
    await agent.runWithFix(task, analysis.fix);
  }
}

📚 详细文档

MCP 工具详情

statecli_replay

• 描述：重放实体的状态变化，逐步展示发生的情况。
• 使用场景：调试、了解过去的行为、查找错误。
• 输入：

{
  "entity": "order:7421",
  "actor": "ai-agent"
}

• 输出：带有时间戳的状态变化的 JSON 数组

statecli_undo

• 描述：撤销状态变化，在出现问题时进行回滚。
• 使用场景：犯了错误、需要重试、想要恢复。
• 输入：

{
  "entity": "order:7421",
  "steps": 3
}

• 输出：撤销操作的确认信息和恢复后的状态

statecli_checkpoint

• 描述：在进行更改之前创建命名检查点。
• 使用场景：即将进行有风险的操作、需要回滚点。
• 输入：

{
  "entity": "order:7421",
  "name": "before-refund"
}

• 输出：用于后续参考的检查点 ID

statecli_log

• 描述：查看实体的状态变化历史。
• 使用场景：需要查看过去的操作、审计跟踪、了解行为。
• 输入：

{
  "entity": "order:7421",
  "since": "1h ago",
  "actor": "ai-agent"
}

• 输出：所有状态变化的 JSON 数组

statecli_track

• 描述：显式跟踪状态变化。
• 使用场景：进行重要的状态修改。
• 输入：

{
  "entity_type": "order",
  "entity_id": "7421",
  "state": { "status": "paid", "amount": 49.99 }
}

• 输出：跟踪变化的确认信息

AI 智能体使用场景

自我调试

const replay = await statecli_replay({ entity: "task:123" });

安全实验

await statecli_checkpoint({ entity: "order:7421", name: "before-refund" });
await agent.processRefund(order);

从过去的操作中学习

const history = await statecli_log({ 
  entity: "order:*", 
  actor: "ai-agent",
  since: "24h ago"
});

智能体之间的协作

await statecli_track({ entity: "task:123", state: {...} });
const log = await statecli_log({ entity: "task:123" });

CLI 使用方法

# 跟踪状态变化
statecli track order 7421 '{"status": "pending"}'

# 重放变化
statecli replay order:7421

# 查看日志
statecli log order:7421

# 创建检查点
statecli checkpoint order:7421 before-refund

# 撤销上一次更改
statecli undo order:7421

🔧 技术细节

性能

• 写入延迟：< 1ms（异步、非阻塞）
• 读取延迟：< 5ms（本地 SQLite）
• 存储：每个状态变化约 100 字节
• 开销：在生产环境中可忽略不计

安全

• 本地优先：默认情况下，所有数据都存储在本地。
• 无外部调用：无需网络依赖。
• 隐私保护：智能体的操作不会离开您的系统。

📄 许可证

本项目采用 MIT 许可证，可免费用于包括商业 AI 智能体在内的所有用途。

文档链接

• GitHub：https://github.com/statecli/mcp-server
• NPM：https://www.npmjs.com/package/statecli-mcp-server
• MCP 注册表：io.github.charo360/statecli

StateCLI - 让 AI 智能体具备自我感知能力

当智能体能够了解自己的行为、撤销错误并从历史中学习时，它们将真正实现自主。

关键词（用于智能体搜索和发现）

state-management, state-replay, time-travel-debugging, undo, rollback, checkpoint, agent-memory, agent-introspection, self-debugging, ai-agent-tools, mcp-server, model-context-protocol, autonomous-agents, agent-observability, state-tracking, langchain-tools, autogpt-plugins, crewai-tools