State Memory MCP

@putervision/state-memory-mcp

@putervision/state-memory-mcp 是一个无需基础设施、结果确定的 Model Context Protocol（MCP）服务，为 AI 编码助手（如 Cursor、Claude Code、Gemini 或 Copilot）提供结构化、持久化的 SQLite 图，用于跟踪工作流状态，包括任务、决策、制品、计划、阻碍因素及其语义关系。

🌐 官方文档与网站：statememorymcp.com

---

⚡ 快速开始与安装

前提条件：Node.js >= 18.18.0

# 1. Install globally
npm install -g @putervision/state-memory-mcp

# 2. Navigate to your project directory
cd your-project

# 3. Initialize state-memory-mcp
# Creates .state-memory-mcp/, updates .gitignore, registers project,
# and scaffolds IDE instructions and MCP configs for Cursor, Claude, VS Code, Windsurf, etc.
state-memory-mcp init

# Done! Restart your IDE or Agent Manager to activate.

其他选项

# Run directly via binary (after global install)
state-memory-mcp run

# Re-initialize across all registered workspace projects
state-memory-mcp init-global

---

🌟 主要亮点

• 🧠 确定性状态记忆与紧凑型 TaskSlice：记忆操作无需大模型参与；通过 SQLite 图进行快速、确定性的遍历，并提取小于 1 KB 的 TaskSlice，用于 System 1 快速路径评估。
• ⚡ 13 个生产级整合 MCP 工具：涵盖完整的 CRUD、关系关联、DAG 环路检查、FTS5 搜索、TF-IDF RAG、时间回溯历史回滚、规范驱动开发以及自动修复验证。
• 📉 高效的上下文管理与决策阈值：将上下文转存到本地 SQLite 数据库；将低于 0.70 的常规决策筛选到仅追加的事件日志中，以防图膨胀，同时保留重要性较高的轮次。
• 🚀 延迟降低 67%–74%：无需再进行多步文件扫描循环；Agent 可在毫秒内检索无阻碍任务及阻碍因素。
• 🤝 多 Agent 黑板：共享上下文存储，允许并行子 Agent 安全地发布决策、任务和阻碍因素更新。
• 🎨 交互式 3D 可视化工具：基于浏览器的深色模式 3D WebGL 力导向图可视化工具（state-memory-mcp view）。
• 🔗 双 MCP 协同：与 @putervision/vision-memory-mcp 搭配使用，实现视觉状态缓存、感知哈希和加密多模态证据包。
• 🛡️ 100% 本地且私密：本地优先架构；所有状态都保存在工作区内的 .state-memory-mcp/ 中。

---

🛠️ MCP 工具套件

@putervision/state-memory-mcp 提供 13 个适用于生产环境的整合型 MCP 工具，分为 5 个核心工作流领域：

• 图与关系：manage_nodes（节点 CRUD、FTS5/TF-IDF 向量搜索、原子批量变更、观察笔记、带阈值的快速决策记录）、manage_edges（带类型的 DAG 链接、多模态视觉状态关联）。
• 任务执行与工作队列：manage_tasks（拓扑排序依赖队列、阻塞项检测、带产物的任务完成、自动清理）、manage_sessions（Agent 归属、轮次跟踪、上下文引导）。
• 规范驱动开发（SDD）：manage_specs（PRD/RFC 解析、需求分解为任务、实时验收标准验证、合规评分）。
• 分析、审计与诊断：get_analytics（速度、燃尽图、Token 投资回报率、认知负荷、关键路径）、get_events（SHA-256 防篡改事件账本）、run_diagnostics（DAG 验证、健康检查、AST 引用完整性）。
• 数据、快照与多 Agent：manage_snapshots（检查点、时间回溯撤销）、manage_database（备份、校验和审计、VCS 分支合并）、manage_data（批量导入/导出、包含交错快速决策事件的 ML 轨迹）、query_graph（子图、依赖追踪、原始 SQL、小于 1 KB 的 compact_slice）、use_blackboard（多 Agent 异步主题板）。

👉 完整的参数规范、返回架构和示例负载，请参阅 工具参考指南 和 正式 API 参考。

---

🚀 架构与状态图生命周期

                      AI Agent Prompt / Task
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Agent Session Attribution       │ ──▶ manage_sessions(action: "start")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Context & Task Prioritization   │ ──▶ get_analytics(action: "summary")
               │                                 │ ──▶ manage_tasks(action: "next")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Deterministic Graph Mutation   │ ──▶ manage_nodes(action: "create"|"update")
               │  (Tasks, Decisions, Blockers)   │ ──▶ manage_edges(action: "add"|"link_visual")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Spec & Integrity Verification  │ ──▶ manage_specs(action: "compliance"|"verify")
               │                                 │ ──▶ run_diagnostics(action: "validate")
               └────────────────┬────────────────┘
                                │
                                ▼
               ┌─────────────────────────────────┐
               │  Persistent SQLite Storage      │ ──▶ .state-memory-mcp/graph.db (WAL mode)
               │  Append-Only Event Ledger       │ ──▶ SHA-256 Cryptographic Audit Chain
               └─────────────────────────────────┘

📚 文档目录

在 docs/ 目录中查看专门指南和深入解析：

指南	描述
🏗️ 架构与代码库提炼	高价值架构概览、模块清单、数据流和设计决策。
🚀 v0.10 → v1.0 迁移指南	分步迁移指南、旧版工具映射表和 STATE_MEMORY_COMPAT 模式。
💡 价值主张与理论	认知外化、FSM 形式化、首跳确定性与基准指标。
📋 状态记忆概念	节点类型（task、decision、blocker……）、状态值、带类型的边和种子数据指南。
⚙️ 配置与 IDE 设置	自动初始化详情、环境变量表和编辑器配置（Cursor、VS Code、Claude、Antigravity、Windsurf）。
🛠️ CLI 命令参考	CLI 标志（init、run、view、inspect、metrics、audit、doctor、backup、restore、merge）与 Git 扫描器。
⏱️ 会话、快照与 SDD	会话生命周期、事件审计轨迹、快照、轨迹、子目录支持与规范驱动开发。
🧰 工具、资源与提示词	全部 13 个整合型 MCP 工具、只读 state-memory:/// 资源和提示词模板的完整参考。
📘 正式 API 参考	所有 MCP 端点的正式参数、返回架构和代码签名。
🎨 3D 可视化工具指南	查看和导出交互式 WebGL 3D 力导向图可视化工具。
🗄️ 数据库架构	SQLite 表、列、索引和架构迁移历史。

---

📖 Agent 手册：5 步标准工作流

当自主 AI Agent 进入包含 state-memory-mcp 的代码库时：

1. Orient & Bootstrap ──▶ manage_sessions(action: "start") + get_analytics(action: "summary")
2. Task Selection     ──▶ manage_tasks(action: "next") + manage_tasks(action: "find_blockers")
3. Trace Context      ──▶ query_graph(action: "trace") + manage_specs(action: "compliance")
4. Execute & Record   ──▶ manage_nodes(action: "create", type: "decision") + manage_edges(action: "link_visual")
5. Validate & Close   ──▶ run_diagnostics(action: "validate") + manage_tasks(action: "complete") + manage_sessions(action: "end")

---

🧪 测试

# Run full unit, integration, and performance benchmark test suite across all 113 test files (418 tests)
npm run test

---

⚖️ 许可证与免责声明

由 PuterVision 开发并维护。基于 MIT License 发布。

• 本地存储保证：所有图数据、决策记录和事件日志都 100% 保留在你的工作区中。绝不会传输遥测数据或项目数据。
• 商标与非关联声明：产品名称（Cursor、Claude Code、Gemini、Windsurf、VS Code、GitHub、SQLite）均归其各自所有者所有，仅用于识别兼容性。