内容
# @putervision/state-memory-mcp
[](https://www.npmjs.com/package/@putervision/state-memory-mcp)
[](https://github.com/putervision/state-memory-mcp/actions/workflows/ci.yml)
[](https://statememorymcp.com)
[](https://github.com/putervision/state-memory-mcp/blob/main/LICENSE)
[](https://nodejs.org)
`@putervision/state-memory-mcp` 是一个零基础设施、确定性的模型上下文协议（MCP）服务器，为 AI 代理提供了一个结构化、持久的图谱，用于跟踪工作流状态 — 任务、决策、制品、计划、阻塞器及其语义关系。官方文档和交互式演示：[statememorymcp.com](https://statememorymcp.com)
使用 `@putervision/state-memory-mcp`，您的 AI 编码助手（例如 Cursor、Claude Code、Gemini 或 Copilot）可以维护长期项目一致性、管理复杂依赖关系，并跨会话审计架构决策。
---
## 主要功能
1. **确定性状态内存**：没有 LLM 参与；所有操作都是结构化的、确定性的和快速的。
2. **SQLite 存储**：零基础设施数据库，持久化项目本地（在 `.state-memory-mcp/` 下）或全局。
3. **58 个核心 MCP 工具**：涵盖 Node CRUD、关系链接、循环依赖拒绝、全文搜索（FTS5）、依赖路径跟踪、阻塞器分析、值分析、数据库管理实用程序、模板脚手架、代理 QoL 上下文工具、会话生命周期跟踪、事件日志、加密 SHA-256 会话审计验证（`verify_audit_chain`）、状态回滚/撤销、复合工作流工具（`bootstrap_session`、`complete_task`、`batch_create_nodes`、`batch_add_edges`）、选择性字段投影（`fields`）、自我修复图修复（`auto_fix`）、动态资源和工作流提示。
4. **交互式 3D HTML 可视化器**：使用交互式、暗黑主题的 WebGL 3D 力导向图可视化器轻松导出或查看您的项目状态图，基于 `3d-force-graph` / Three.js 构建。
5. **安全 SQL 查询**：针对数据库进行安全只读 SELECT 查询，以进行高级分析。
6. **Git 分支感知**：根据 checkout 工作空间 Git 分支动态跟踪和过滤状态。
7. **一键设置**：`state-memory-mcp init` 脚手架数据目录、`.gitignore`、IDE 指令文件和所有主要编辑器的 MCP 配置。
8. **事件源审计轨迹**：每个节点和边突变都记录到一个仅追加的事件表中，包含前后状态快照、会话归属和时间戳。
9. **会话和代理跟踪**：具有代理身份的一流会话生命周期，实现多代理协作和完整的变更 provenance。
10. **持久上下文快照**：保存、列出和 diff 跨会话的上下文快照，以检测漂移并回答“自上次以来发生了什么？”。
---
## 为什么选择 State Memory MCP？（代理价值主张）
AI 编码代理（例如 Cursor、Gemini、Claude 和 Copilot）在严格的上下文窗口和性能限制内运行。将项目工作流状态存储在聊天历史记录中或强制代理重复搜索文件效率低下。`state-memory-mcp` 通过引入结构化、外部状态引擎解决了这个问题：
* **🧠 认知外部化**：基于认知负荷理论，这种方法减轻了代理的额外负荷 ($CL_E$)。通过将状态从模型的权重和活动上下文窗口转移到 SQLite，它将复杂的回忆任务转换为简单的识别任务。只有活动节点的模式和目标变量被分页到上下文中，从而保留注意力预算。
* **🚀 更快的代理执行**：代理不再运行昂贵的多步文本搜索循环或文件扫描来确定下一步。相反，它们可以在毫秒内查询 `get_project_summary` 或 `find_blockers`。它们立即了解当前的阻塞器、目标和未完成的任务，从而在多代理工作流中减少了 **67% 至 74%** 的端到端执行延迟。
* **📉 大幅节省令牌**：在聊天提示中存储日志、决策和任务状态会浪费令牌。通过 `state-memory-mcp`，代理将此状态卸载到本地 SQLite 数据库中，并在需要时仅获取相关子图。这在使用编译的轨迹模型时减少了 **128 倍至 462 倍** 的上下文膨胀和 API 成本。
* **🎯 提高响应质量**：当代理忘记过去的上下文时会出现幻觉和重复工作。分支感知的状态图为所有架构决策、里程碑和任务需求提供了一个单一、清晰的事实来源。代理编写更好的代码，因为它们始终知道 *为什么* 做出了决策。
* **🔒 首跳确定性**：与概率向量 RAG（余弦相似度）不同，`state-memory-mcp` 图查询使用确定性 SQL/CTE 遍历。这消除了在多代理执行管道中传播的“首跳”检索错误。
* **🔗 简化关系建模**：关系使用类型化链接显式映射（例如 `blocks`、`produces`、`depends_on`）。服务器自动验证依赖关系并拒绝循环引用循环，从而维护一个干净、易于导航的项目结构。
* **🤝 超级充电多代理协作**：当部署并行子代理时（例如，一个编写代码，一个运行测试，一个扫描日志），它们缺乏共享内存池。`state-memory-mcp` 作为本地黑板（共享上下文存储），所有子代理在此发布决策、任务和阻塞器更新，确保协调级别的对齐，而无需传递大型聊天历史记录。这将中央 LLM 调用限制在恒定的 $O(1)$（计划 + 总结）而不是随任务步骤线性扩展的 $O(N)$。
* **📈 化合物内存飞轮**：随着您记录更多任务、架构决策和观察结果，状态内存从简单的检查清单转变为丰富的项目智能仓库。未来的代理可以跟踪 `decision_trail`、重用已建立的子图、避免重复过去的失败（记录为阻塞器/观察结果），并立即查询上下文快照以了解代码原理。记录的上下文越多，新代理的入职/发现开销就越少，从而形成一个复合的生产力飞轮。
---
## 快速入门
> **先决条件**：Node.js **>= 18.0.0**
```bash
# 全局安装
npm install -g @putervision/state-memory-mcp
# 导航到您的项目
cd your-project
# 初始化 — 创建 .state-memory-mcp/、更新 .gitignore、
# 脚手架 IDE 指令和 MCP 配置
state-memory-mcp init
# 完成！您的 IDE 现已具有 MCP 配置 + 代理指令。
```
---
## 安装
```bash
# 全局安装（推荐）
npm install -g @putervision/state-memory-mcp
# 直接通过二进制文件运行（全局安装后）
state-memory-mcp run
# 或作为项目开发依赖项安装
npm install --save-dev @putervision/state-memory-mcp
```
---
## 状态内存概念
`state-memory-mcp` 将您的开发工作空间建模为有向无环图（DAG），其中节点代表开发对象，边代表它们的语义关系。
### 📋 节点类型和有效状态值
1. **`task`**：增量工作项或编码 TODO（状态：`pending`、`in_progress`、`done`、`blocked`、`cancelled`）。
2. **`decision`**：架构选择、模式选择和原理（状态：`active`、`accepted`、`deprecated`、`rejected`）。
3. **`artifact`**：编码输出、文档或生成的模式（状态：`current`、`draft`、`deprecated`）。
4. **`plan`**：高级别开发规范和路线图，包含里程碑（状态：`active`、`draft`、`completed`、`archived`）。
5. **`milestone`**：进度检查点，代表一组相关的任务（状态：`upcoming`、`in_progress`、`done`、`delayed`）。
6. **`blocker`**：阻碍任务完成的障碍或错误（状态：`active`、`resolved`、`mitigated`）。
7. **`observation`**：代理记录的上下文发现、代码库注释或运行时约束（状态：`active`、`archived`）。
### 🔗 边关系
节点相互链接以表示工作流连接：
* `depends_on`：声明任务或里程碑依赖于另一个。
* `blocks`：连接阻塞器到它阻碍的任务/里程碑。
* `produces`：连接任务或里程碑到它生成的制品文件。
* `references`：将节点与源文件或文档关联起来。
* `updates` / `contradicts`：跟踪决策的历史链或标记冲突的需求。
* `part_of` / `child_of`：建立层次分组（例如，属于里程碑的任务，属于计划的里程碑）。
* `implements` / `decided_in`：链接任务/制品到其设计决策或计划。
* `extends` / `modifies`：Git 提交跟踪关系。
* `renders_state`：视觉内存验证关系。
*注意：自动强制执行循环检测。如果代理尝试链接节点形成循环（例如，任务 A 阻塞任务 B，而任务 B 依赖于任务 A），服务器立即拒绝边创建。*
### 🧠 高级图查询
公开您的状态为图，使服务器能够运行高级图查询工具：
* **`critical_path`**：计算阻碍里程碑的最长未完成任务链，以便代理了解优先级。
* **`impact_analysis`**：计算节点的“爆炸半径”或受影响的下游依赖链，如果节点（或代码文件）被编辑或删除。
* **`detect_contradictions`**：审计数据库中的逻辑缺陷（例如，已完成的任务仍然有活跃的阻塞器，或相互矛盾的设计决策）。
* **`decision_trail`**：跟踪更新和矛盾的历史链回到原始架构选择。
* **`get_event_log` / `get_node_history`**：查询追加的事件账本并跟踪节点何时、如何以及由谁修改。
* **`undo_last`**：恢复节点上的最后一次突变（回滚）以从下游推理或测试失败中恢复（FSM 状态回溯）。
---
## 理论基础
`state-memory-mcp` 设计用于解决认知科学和多代理系统设计中确定的无状态代理工作流的关键瓶颈：
### 1. 认知外部化（认知负荷理论）
在无状态代理循环中，将上下文窗口填充聊天历史记录、完整模式和系统指南会迅速超过主动注意力预算，导致注意力扩散和约束幻觉。通过将状态与不可简化的复杂性（内在认知负荷，$CL_I$）分离以外的格式和呈现杂乱（额外认知负荷，$CL_E$），`state-memory-mcp` 外部化状态。将状态卸载到本地 SQLite 数据库中减少了 $CL_E$，并将困难的 *回忆* 任务转换为确定性的 *识别* 任务。
### 2. 有限状态机（FSM）形式主义和边界保证
在不受约束的环境中，语言模型会受到贪婪和探索循环的影响。使用状态驱动的图来形式化转换提供了数学上的正确性保证。由此启用的关键执行规则包括：
* **状态回溯**：当下游验证节点识别出执行失败时，它将执行回溯到前面的节点（`undo_last`）而不是尝试在损坏的上下文窗口中恢复。
* **有界执行**：循环检测防止无限执行循环。
* **确定性会话重放**：事件账本使会话重放对于取证和审计成为可能。
### 3. 首跳确定性与概率 RAG
标准向量 RAG 将代码库分成块并使用概率余弦相似度检索它们。如果上下文检索的第一跳返回结构上不正确的上下文，下游模型会放大错误。基于确定性图遍历（使用直接节点和边）将第一个推理步骤置于地面上，避免这种错误传播。
### 4. 实证性能基准
状态上下文协议架构的实证研究显示，在成本、延迟和可靠性方面有显著改善：
* **67% 至 74% 的端到端执行延迟降低**：使用直接服务器到服务器的状态触发（CA-MCP 模式）。
* **恒定的 $O(1)$ 中央 LLM 调用**（计划 + 总结）而不是 $O(N)$ 调用随任务步骤缩放。
* **128 倍至 462 倍的 API 成本降低**：通过从事件日志编译状态转换轨迹来训练更小、更专业的代理模型（3B 至 8B 参数）。
---
## 会话和事件跟踪（v0.3.0）
v0.3.0 中，`state-memory-mcp` 引入了完整的会话管理、变更日志和状态回滚：
### 📋 会话生命周期
使用跟踪会话跟踪并发代理或顺序任务。启动会话会返回一个 `session_id`，它会标记后续的所有图突变：
* `start_session`：使用可选的 `agent_id`（例如 `claude-coder`、`gemini-tester`）和自定义元数据启动会话。
* `end_session`：结束会话并记录完成。
* `list_sessions`：列出活动和已完成的会话。
### 📜 事件源审计轨迹
节点和边的所有突变都记录在仅追加的 `events` 账本中。
* `get_event_log`：查询项目中的事件并过滤。
* `get_node_history`：按时间顺序查看特定节点的所有更新、创建或删除事件。
* `undo_last`：通过恢复其 `before_state` 或删除新创建的节点来恢复节点上的最后一次更改。
### 💾 上下文快照和差异
* `save_snapshot`：将当前图结构（所有节点和边）保存为命名上下文检查点。
* `list_snapshots`：查看历史检查点。
* `diff_snapshots`：比较任意两个检查点。返回节点哪些被添加、删除、更新或状态更改，以及哪些边关系被添加或删除。
### 📈 轨迹导出用于模型训练
* `export_trajectories`：以 JSONL 格式导出项目的时序转换日志，为标准操作规程的细化本地模型提供干净的训练数据。
### 📂 子目录和 Mono-Repo 支持（v0.6.2）
* **多 Repo Git 健全性会计**：`state-memory-mcp doctor` 发现并检查根和嵌套 Git 仓库，跨目录最多可达 4 级，报告活跃分支和干净/脏状态。
* **子目录内存观察**：内存查询工具（`list_nodes`、`search_nodes`）和健康审计（`audit`、`audit_project_db`、`doctor`）观察并审计嵌套 `.state-memory-mcp` 数据库的子目录（`include_subdirectories: true`），并用子项目源标签注释节点（`subproject: <slug>`）。
### 📑 规范驱动开发（SDD）和摄入（v0.6.3）
* **图原生规范**：专用节点类型（`spec`、`requirement`、`acceptance_criterion`、`contract`）和 SDD 边关系（`satisfies`、`verifies`、`specifies`、`violates`、`drifts_from`）。
* `ingest_spec` / `state-memory-mcp spec:ingest <file>`：直接将 Markdown PRD、OpenSpec 文件或 Gherkin（`.feature`）BDD 文件摄入内存图节点。
* `export_spec` / `state-memory-mcp spec:export <specId>`：将图管理的规范和子要求导出回 Markdown 或 Gherkin 文本。
* `get_spec_compliance` / `state-memory-mcp spec:matrix`：计算实时规范合规矩阵和需求覆盖率。
* `scaffold_spec`：在 `.specs/` 中搭建标准功能规范模板。
* `verify_requirement`：标记验收标准为已验证、失败或跳过，可选链接测试观察。
* **Git 规范过时**：自动检测 `.specs/` 或 `docs/specs/` 文件的 Git 提交修改，并标记图规范节点为 `stale`。
---
## CLI 用法
`state-memory-mcp` 带有强大的命令行界面来管理项目数据库：
```bash
# 在您的项目中初始化 state-memory-mcp（创建 .state-memory-mcp/、
# 更新 .gitignore、脚手架 IDE 指令和 MCP 配置）
state-memory-mcp init [--no-git] [--commits <n>] [--no-tasks] [--no-artifacts]
# 启动 MCP 服务器（由 IDE 配置使用）
state-memory-mcp run
# 在您的默认浏览器中查看交互式 3D 图可视化器
state-memory-mcp view --project my-project
# 以 ASCII 格式检查项目节点
state-memory-mcp inspect --project my-project
# 显示项目图 ROI、生产力和令牌节省指标
state-memory-mcp metrics --project my-project
# 导出图数据（支持 HTML、DOT、Mermaid、HTML 格式）
state-memory-mcp export --project my-project --format html --out graph.html
state-memory-mcp export --project my-project --format mermaid
# 从 JSON 文件导入图数据（覆盖现有项目数据）
state-memory-mcp import data.json --project my-project
# 增量扫描 git 历史记录到图
state-memory-mcp scan-git --project my-project --commits 30
# 将项目数据库备份到 SQLite 文件
state-memory-mcp backup --project my-project --out backup.db
# 从 SQLite 备份文件恢复项目数据库（破坏性覆盖）
state-memory-mcp restore backup.db --project my-project
# 审计项目和子目录数据库的完整性、循环和矛盾
state-memory-mcp audit --project my-project
# 运行环境健康检查（Node、SQLite、FTS5、权限、根和子目录 git 仓库、图完整性）
state-memory-mcp doctor --project my-project
```
更新 state-memory-mcp 至最新版本
state-memory-mcp update
# 将外部 SQLite 数据库合并到当前项目数据库
state-memory-mcp merge other-project.db --project my-project [--force]
---
## 自动初始化与 IDE 配置脚手架
通过 `state-memory-mcp run` 启动服务器或通过 `state-memory-mcp init` 启动 CLI 时，引擎会执行 **自动初始化** (`run()`)：
1. **本地存储设置**创建 `.state-memory-mcp/` 目录、数据库存储和 `.gitignore` 文件，以防止数据库锁定冲突。
2. **IDE 配置**：为以下 IDE 搭建或更新 MCP 客户端配置文件：
- **Google Antigravity**：`~/.gemini/antigravity/mcp/state-memory-mcp/`
- **Claude Code CLI & Desktop**：`.clcp.json` /aude_desktop_config - **Cursor**：`.cursor/mcp.json`
- ****：`.vscode/mcp.json`
- **Windsurf & Roo Code / Cline**：`.windsurf/mcp.json` / `.cline/mcp.json`
3. **代理规则与技能**：搭建 `.agents/AGENTS.md` 规则和 `.agents/skills/state-memory-mcp/SKILL.md` 技能说明，以便代理立即了解如何使用服务器。
---
## MCP 配置示例
运行 `state-memory-mcp init` 会自动为您创建这些配置文件。如果您更喜欢手动配置：
### Cursor (`.cursor/mcp.json`)
```json
{
"mcpServers": {
"state-memory-mcp": {
"command": "state-memory-mcp",
"args": ["run"],
"env": {
"STATE_MEMORY_MCP_PROJECT": "-slug"
}
}
}
```
### Google Antigravity IDE (`~/.gemini/antigravity/mcp.json`)
```json
{
"mcpServers": {
"state-memory-mcp": {
"command": "state-memory-mcp",
"args": ["run"],
"env": {
"STATE_MEMORY_MCP_PROJECTyour-project-slug }
}
```
### VS Codevscode/mcp.json`)
{
": {
"statecp": {
": "state-memory-m "args": "env": {
"STATE_MEMORY_MCP "your-project-slug"
}
}
}
```
### Claude Desktop (`claude_desktop`)
- **macOS**: `~/Library/ApplicationClaude/claude_desktop_config.json`
-**: `~/.config/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
{
"Servers": {
"state-memory-mcp": {
"command": "statecp",
" ["run"],
": {
"_MCP_PROJECT": "your-project-slug"
}
}
}
}
```
### Google Antigravity (`~/.geminiravity/settings.json`)
Antigravity (AGY)，自定义 MCP 服务器~/.gemini/antigravity/settings.json`（或工作区本地的 `.agents/settings.json`）中全局配置：
```json "mcpServers": {
"statecp": {
"command": "state-memory",
"args": ["run"],
" {
"STATE_MEMORY_MCP_PROJECT": "-slug"
}
}
}
}
```
---
## `init` 设置的内容
在项目根目录运行 `state-memory-mcp init` 将：
1. 创建 `.state-memory-mcp/` 数据目录
2. 将 `.state-memory-mcp` 添加到您的ignore` 文件中
3. 为以下 IDE 创建/追加指令文件：
**Gemini** (`.gemini/instructions.md`)
- **Cursor** (`.cursor/rules/state-memory-mcp.mdc`)
- **GitHub Copilot** (`.github/copilot-instructions.md`)
- **VS Code** (`.vscode/instructions.md`)
- **Claude Code** (`CLAUDE.md`)
- **Windsurf** (`.windsurfrules`)
4. 为 Cursor 和 创建 MCP 服务器自动注入项目所有操作都是 - 多次运行 `init` 是安全的。
---
## Git 提交历史扫描器
Git 扫描器 (`scanGit`) 直接连接到您的本地 Git 仓库，以自动构建项目的语义工作流图：
- **约定提交解析**：解析中的约定类型标签 `feat:`、`fix:`、`docs:`、`refactor:`）。
- **观察创建每个扫描的生成一个 `observation`，包含提交哈希邮箱、时间戳和修改的文件等元数据 **任务种子**：的提交（例如功能工作的提交）会自动生成关联的 `task点，并通过 `extends链接到提交。
- **工**：扫描器的文件。如果文件频繁修改热度阈扫描器会创建一个` 节点，并使用 `modifies` 关系提交观察到它## 项目种子指南最大限度地实现开发者对齐，请项目后立即播图：
1计划节点**级别的 `plan` 节点，代表您的图：
- `(type: " title: "项目路线图")`
2.里程碑**目标里程碑，代表项目阶段，并将它们链接到计划：
add_node(type: "milestone", title: "v1.0 MVP 发布")`
- `add_edge(source_idvp_id, target roadmap_id, type: "part_of3. **记录核心决策**：创建组件的 `decision` 节点，并将到里程碑：
- `add_node(type: "decision", title: "SQLite 数据库选择", metadata: { "rationale": "简单、本地存储" })`
- `add_edge(source_id: db_choice_id, target_id: mvp_id, type: "decided_in")## 环境变量
| 变量 | 描述 | 默认值 |
|| `STATE_MEMORY_MCP | 存储数据库文件的目录的绝对路径。 | `.state-memory-m（项目本地，在 CWD 中） |
STATE_MEMORY_MCP_PROJECT` | 活动项目的 slug 标识符 从工作目录名称解析 |
| `STATE_MEMORY_MCP_LOG_LEVEL` | 在 `stderr上的日志记录详细程度（`debug`、`info`、`warn`、`error`）。info` |
|_MEMORY_MCP` | 如果启动时无法查询 Git，则分支名称。main` |
---
工具参考（49 个工具）
### 🚀 高级复合工作流工具（4 个工具）
* **`bootstrap_session`**: 结合会话跟踪（`start_session`）、上下文快照生成和顶部未阻塞任务检索的单次会话初始化。
* 输入：`project`、`agent_id`、`metadata`、`task_limit`。
* **`complete_task`**: 单次任务完成，更新任务状态为 `'done'`，可选地创建生成的 `'artifact'` 节点，并通过 `'produces'` 关系链接它们。
* 输入：`task_id`、`artifact_title`、`artifact_metadata`、`tags`、`project`。
* **`batch_create_nodes`**: 在单个事务中原子地创建多个节点，并同步 SQLite FTS5 搜索索引。
* 输入：`nodes`、`project`。
* **`batch_add_edges`**: 在有向无环图循环检查（`hasCycle`）和失败时事务回滚的情况下，原子地创建多个边关系。
* 输入：`edges`、`project`。
### 🟢 节点和关系管理（6 个工具）
* **`add_node`**: 创建一个节点（`task`、`decision`、`artifact`、`plan`、`observation`、`blocker`、`milestone`）。
* 输入：`type`、`title`、`project`、`status`、`metadata`、`tags`。
* **`update_node`**: 修改现有节点的属性（标题、状态、元数据、标签）。
* 输入：`id`、`project`、`title`、`status`、`metadata`、`tags`。
* **`get_node`**: 获取节点的详细信息和所有入站/出站关系。
* 输入：`id`、`project`、`include_edges`。
* **`remove_node`**: 删除节点并自动将删除级联到所有连接的边。
* 输入：`id`、`project`。
* **`add_edge`**: 用类型关系链接两个节点（`depends_on`、`blocks`、`produces`、`references`、`decided_in`、`updates`、`contradicts`、`part_of`、`implements`、`child_of`、`extends`、`modifies`、`renders_state`）。有向依赖类型拒绝循环。
* 输入：`source_id`、`target_id`、`type`、`projectproperties`。
* **`remove_edge`两个节点之间的特定关系。
*`source_id`、`target_id`、`type`、`project` 🔍 搜索和查询（4 个工具）
* **`list_nodes`**: 返回匹配筛选器的节点列表，支持选择性字段投影（`fields`）、紧凑模式、分页、标签和分支跟踪。
* 输入：`type`、`status`、`tags`、`project`、`limit`、`offsetcompact`、`git_branch`、`fields`、`pretty_print`。
* **`search_nodes`**: 对标题、元数据和标签执行快速全文搜索（FTS5）或 TF-IDF 余弦相似度搜索，支持字段投影（`fields`）。
* 输入：`query`、`type`、`status`、`limit`、`algorithm`、`fields`、`pretty_print`、`project`。
* **`get_subgraph`**: 提取节点及其 N 跳邻居节点和连接关系，支持字段投影（`fields`）。
* 输入：`root_id`、`depth`、`edge_types`、`node_types`、`fields`、`pretty_print`、`project`。
* **`query_graph`**: 对底层数据库执行安全、只读的 SELECT SQL 查询。已消毒以阻止危险的 SQLite 函数。
* 输入：`sql`、`params`、`project`。
### 🧠 高级分析和跟踪（8 个工具）
* **`trace_dependencies`**: 计算递归上游（需求）或下游（依赖依赖链。
* 输入：``、`direction`、`edge_types`、``、`project`。
* **`find_block**: 列出活动阻塞节点和它们阻塞的任务/里程碑。
* 输入：`node_id`、`include_transitive`、`project`。
* **`get_project_summary`**: 提供高项目摘要，包含节点分解、任务完成进度、最近的决策和活动阻塞器。
* 输入：`project`。
* **`decision_trail`**: 跟踪导致给定状态的历史决策链（更新/矛盾）。
* 输入：`nodeproject`。
* **`critical_path`**: 计算导致里程碑的最长未完成任务链完成的最小任务集）。
* 输入：`milestone_id`、`project`。
* **`impact**: 计算节点修改或删除时的下游爆炸半径。
* 输入：`node_id`、`project* **`detect_contradictions`**: 扫描项目中的逻辑缺陷（例如，已完成的任务仍然有活动阻塞器，与已接受相矛盾）。
：`project` **`value_metrics`估计的时间和代币节省、图密度、节点数、决策重用率、任务活动阻塞器年龄结构化的 JSON 和 Markdown 报告。
* 输入：`。
### 🤖 QoL 和模板（4 个工具）
* **`get_context_snapshot`**: 双格式上下文快照，返回结构化 JSON 数据（阻塞器、待处理任务）和预渲染的 Markdown，以便快速提示代理。
* 输入：`project`。
find_related_decisions`**: 查找影响给定工件节点（直接或通过里程碑）。
：`artifact_id`、`project`。
find_blocked_tasks`**: 查找直接或传递被决策节点阻塞的所有任务。
* 输入：`decision_id`、`project`。
* **`_template`**: 自动化工作流的架。支持的`fdd`（功能驱动的开发设计里程碑）和 `rfc请求评论作者/审查/决策循环）。
* 输入：`template`、`name`、`project`。
### 🛡️ 管理和备份（6 个工具）
* **`export_graph`**: 将项目图导出为 JSON、DOT、Mermaid 流程图或交互式 HTML 格式。
* 输入：`format`、`project`。
* **`import_graph`**: 从外部文件批量加载边。
* 输入：`nodes`、`edges`、`project`。
* **`backup_project_db`**: 创建在线 SQLite 数据库备份文件以及完整性 SHA-256 校验和文件。
* 输入：`outputPath`、`project`。
* **`restore_project_db`**: 从备份文件恢复数据库，检查结构化 SQLite 完整性和匹配的 SHA-256 校验和文件。
* 输入：`backupPath`、`project`。
* **`audit_project_db`**: 审计数据库结构、外键约束、孤立边、循环和逻辑矛盾。
* 输入：`project`。
* **`merge_project_db`**: 安全地合并两个项目数据库，保持较新的节点（基于 `updated_at`）并验证循环依赖。
* 输入：`sourcePath`、`force`、`project`。
### ⏱️ 事件溯源和轨迹（9 个工具）
* **`start_session`**: 启动跟踪突变的跟踪会话。
* 输入：`agent_id`、`project`、`metadata`。
* **`end_session`**: 结束活动会话。
* 输入：`session_id`、`project`。
* **`get_event_log`**: 检索突变事件日志。
* 输入：`session_id`、`entity_id`、`event_type`、`since`、`until`、`limit`、`offset`、`project`。
* **`get_node_history 获取特定节点的修改历史。
* 输入：_id`、`。
* **``**: 撤销上的最后一个突。
* 输入node_id``。
* **``**: 保存完整的快照。
* 输入：`session、`project` **`list_snap 列出的快照。
输入：`limitproject`。
diff_snapshots`**: 计算两个快（添加、删除、状态/属性 * 输入：_id_a`、`_b`、`。
* **`jectories`**: 以 JSONL 格式迹用于代理训练 * 输入：_id`、`since`、`until`、`limit`、`offset`、`。
### ⚡ 批量和陈旧（8 个工具 **`batch_update`**: 执行原子批量节点状态、元）。
*`ids`、`status`、`metadata``、`project* **`next_tasks`**: 根据优先级、阻塞状态、分支和字段`fields`下一个可运行的任务。
* 输入git_branch`、`、`include_contextfields`、`pretty_print`、`project`。
* **`what**: 报告自会话开始或时间戳图变更集差异 * 输入：`since`、`since_session`、`git_branch`、`project`。
* **`get_stale_nodes`**: 确定已闲置/未触及超过给定阈值的节点。
* 输入：`older_than`、`status``、`git_branch`、`limit`、`project`。
* **`validate_graph`**: 验证图的 结构异常，具有自我修复自动修复选项（`auto_fix: true`）。
* 输入：`checks`、`auto_fix`、`project`。
* **`prune_events`**: 修剪旧于阈值的事件日志，同时保留实体状态 * 输入：``、`dry、`preserve_types``。
*_note`**:创建观察注释现有节点。
输入：`text`、`attach_to``、`project` MCP 资源
`state-memory` 完全模型上下文协议规范，公开只读数据动态 URI 可重用的提示客户端应用程序。
资源和模板
资源为 LLMs的只读state-memory-mcp` 在 `state-memory:///` URI 模式下注册了以下资源：
* **`state-memory:///{project}/summary`**: 返回结构化的项目摘要（计数、任务进度、最近的决策）。
* **`state-memory:///{project}/blockers`**: 返回所有活动阻塞器及其受影响节点的列表。
* **`state-memory:///{project}/tasks/next`**: 返回顶部未阻塞的可运行任务。
* **`state-memory:///{project}/node/{id}`**: 返回单个节点详细信息和连接的关系。
* **`state-memory:///{project}/metrics`**: 返回项目速度和价值创造指标。
* **`state-memory://}/decisions`**: 返回最近接受的决策日志。
* **`state-memory:///{project}/graph.json`**:节点/边数据库导出为原始 JSON。
### 💬 提示
提示重用的工作，简化了代理交互：
* **`session-start`**: 生成启动工作，概述项目摘要、活动阻塞器和即处理任务。
：`project可选）。
* **`handover-summary`**: 为代理会话交接的事件日志生成上下文摘要。
* 参数：`project`（可选）。
* **`task-decomposition`**: 指导模型将里程碑分解为具有依赖关系链接的任务 DAG。
* 参数：`milestone_title`（必需）、`project`（可选）。
* **`post-mortem`**: 滞/取消任务的尸检分析和更新。
*`project`（可选）。
* **`plan-feature 提示代理规划，指导里程碑创建、任务分解、依赖关系映射和设计决策。
* 参数：`feature_name`（必需）、`project`（可选）。
* **`review-decisions`**: 提示代理审查决策日志和逻辑矛盾审计，推荐改进或修复。
* 参数：`project`（可选）。
* **`triage-blockers`活动阻塞器进行分类，帮助分析关键路径并制定。
* 参数：`project`（可选）。
---
交互式 3D HTML 可视化器
`state-memory-m了一个交互式、模式的浏览器 3D 可视化，使用 WebGL.js 来探索项目的 工作流状态图。
### 查看可视化器
要立即生成并在您的默认 Web 浏览器中查看可视化器，请运行：
```bash
state-memory-mcp view --project my-project
```
该命令：
1. 生成一个包含嵌入式图数据集的独立 `viewer.html` 文件。
2. 将其保存在项目数据库文件夹中。
3. 自动在您的默认浏览器中启动该页面。
### 导出可视化工具
要将可视化工具导出到特定文件：
```bash
state-memory-mcp export --project my-project --format html --out ./my-graph.html
```
您可以与您的团队共享导出的HTML文件。该文件包含一个具有响应式的3D 力导向网络图渲染，具备以下功能：
- 交互式缩放、平移和360度旋转。
- 节点和关系的悬停详情。
- 基于类型的不同颜色编码节点。
- 自动力布局。
---
## 升级到 v0.3.0
数据库模式迁移在升级软件包后第一次运行时**自动**运行。无需手动操作，现有节点和边数据将被保留。
* 注意：新的事件账本开始记录升级时刻后的突变；v0.3.0之前发生的历史突变不会被补填。
---
## 测试
```bash
# 运行单元测试和集成测试
npm run test
```
## 许可证 & 作者
由[PuterVision LLC](https://putervision.com)开发和维护。在 [MIT License](LICENSE) 下发布。
### 责任限制
本软件按“原样”提供，不附带任何形式的保证，包括但不限于适销性、特定用途适用性和非侵权保证。在任何情况下，作者或版权持有人均不应对因软件使用或使用引起的任何索赔、损害或其他责任承担责任，无论是合同、侵权还是其他原因。
使用此软件，即表示您承认并同意，作者和贡献者对因执行软件导致的任何数据库损坏、Git仓库修改、数据丢失或其他问题不承担责任。在执行破坏性操作之前，请始终备份您的数据库文件。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器