# State Memory MCP

> Teaches the agent to use the state-memory-mcp MCP server to track workflow state, tasks, decisions, blockers, artifacts, plans, milestones, and their semantic relationships in a persistent graph database.

- Skill: `putervision/state-memory-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add putervision/state-memory-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/putervision/state-memory-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: putervision (https://skillmd.com/u/putervision)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/putervision/state-memory-mcp

---


# State Memory (state-memory-mcp) — 13 Consolidated Tools

This project uses `state-memory-mcp` with project slug `"world-model-mcp"` to provide AI agents with a structured, persistent graph for tracking workflow state.

### 1. Priority Order & Mandatory Checklist
Before doing any coding or investigation, you MUST run this sequence:
1. `manage_sessions(action: "start")` — Start a tracking session with an `agent_id` for full change attribution.
2. `get_analytics(action: "summary")` — Understand current project state, active branches, and overall progress.
3. `manage_specs(action: "compliance")` — Check real-time requirement coverage matrix and unfulfilled criteria.
4. `manage_tasks(action: "next")` — Query prioritized runnable tasks (sorted by downstream impact and age).
5. `manage_tasks(action: "find_blockers")` — Identify any active blockers preventing progress.
6. `manage_nodes(action: "list")` — Find pending tasks, past decisions, or milestones.
7. `query_graph(action: "trace")` — Trace what depends on or blocks a task.

### 2. Complete 13 Consolidated MCP Tools Reference

| # | Tool Name | Key Actions | Description |
|---|---|---|---|
| 1 | **`manage_nodes`** | `create`, `update`, `get`, `remove`, `list`, `search`, `batch_create`, `batch_update`, `add_note` | Graph node CRUD, full-text / TF-IDF search, atomic batch operations, and quick notes. |
| 2 | **`manage_edges`** | `add`, `remove`, `batch_add`, `link_visual` | Manage typed graph relationships and link tasks/artifacts to visual memory state IDs. |
| 3 | **`manage_sessions`** | `start`, `end`, `list`, `bootstrap` | Agent tracking sessions, attribution, and single-turn context bootstrapping. |
| 4 | **`manage_tasks`** | `next`, `complete`, `find_blocked`, `find_stale`, `find_blockers`, `find_similar_blockers`, `auto_prune` | Prioritized task queue, task completion, blocker detection, and automated stale pruning. |
| 5 | **`manage_snapshots`** | `save`, `list`, `diff`, `get_state`, `revert`, `undo`, `get_history` | Graph checkpoints, visual diffs, point-in-time state reconstruction, and rollbacks. |
| 6 | **`manage_specs`** | `scaffold`, `ingest`, `export`, `compliance`, `verify`, `decompose_feature`, `template` | Spec-Driven Development (SDD), PRD parsing, acceptance verification, and FDD/RFC templates. |
| 7 | **`manage_database`** | `backup`, `restore`, `audit`, `merge`, `branch_diff`, `branch_merge` | SQLite maintenance, physical backups, integrity audits, and Git branch state diffs/merges. |
| 8 | **`manage_data`** | `export_graph`, `export_issues`, `export_trajectories`, `export_joint_trajectories`, `export_synergy_metrics`, `import_graph`, `import_issues`, `import_spec` | Bulk import/export of graph formats, GitHub/Jira issues, ML trajectories, and ROI synergy metrics. |
| 9 | **`query_graph`** | `subgraph`, `trace`, `raw`, `natural_language` | Graph traversal, upstream/downstream dependency tracing, raw SQL queries, and natural language search. |
| 10 | **`get_analytics`** | `summary`, `velocity`, `burndown`, `value_metrics`, `cognitive_load`, `critical_path`, `context_snapshot`, `decision_trail`, `find_related_decisions`, `contradictions` | Analytics suite: project overview, velocity, burndown, token ROI, cognitive load, and decision trails. |
| 11 | **`get_events`** | `log`, `changelog`, `post_mortem` | Append-only event log queries, session changelogs, and automated session post-mortems. |
| 12 | **`run_diagnostics`** | `validate`, `doctor`, `check_refs`, `audit_chain`, `compact`, `archive`, `prune_events`, `version` | Graph integrity validation, doctor health checks, SHA-256 hash audits, compaction, and archiving. |
| 13 | **`use_blackboard`** | `post`, `read` | Asynchronous multi-agent notice board for inter-agent coordination with TTL expiration. |

### 3. Node Types & Edge Relationships

**Node Types:**
- `task` — Incremental items of work or coding TODOs.
- `decision` — Architectural choices, pattern selections, and rationale.
- `artifact` — Files, documentation, or schemas generated by tasks.
- `plan` — High-level development specifications and roadmaps.
- `milestone` — Progress checkpoints representing grouped sets of tasks.
- `blocker` — Impediments or bugs preventing task completion.
- `observation` — Contextual findings, notes, or runtime constraints.
- `spec` — Feature specification or PRD document container.
- `requirement` — Formal functional or non-functional requirement.
- `acceptance_criterion` — Testable acceptance criterion for a requirement.
- `visual_state` — Visual state link representing UI layout state.

**Edge Types:**
- `depends_on` — Task/milestone depends on another node.
- `blocks` — Blocker stalls a task/milestone.
- `produces` — Task/milestone generates an artifact.
- `references` — Node references documentation or source files.
- `updates` / `contradicts` — Decision history and conflict tracking.
- `part_of` / `child_of` — Hierarchical groupings (tasks in milestones, milestones in plans).
- `implements` / `decided_in` / `satisfies` — Links tasks/artifacts to design decisions, plans, or spec requirements.
- `renders_state` — Visual memory verification relationship.
- `blocked_by_visual_state` — Blocker caused by UI layout failure.
- `verifies` / `verifies_visual_state` — Verification link connecting tests/evidence to requirements.

### 4. Workflow Patterns

**Session Lifecycle:**
1. `manage_sessions(action: "start", agent_id: "my-agent")` → get `session_id`
2. Pass `session_id` to graph mutations (`manage_nodes`, `manage_edges`)
3. `manage_sessions(action: "end", session_id: session_id)` when work is complete

**Task Decomposition:**
1. Decompose user requests into task nodes with `manage_nodes(action: "create", type: "task", title: "...")`
2. Connect related tasks with `manage_edges(action: "add", type: "depends_on", source_id: A, target_id: B)`
3. Group under milestones with `manage_edges(action: "add", type: "part_of", source_id: task, target_id: milestone)`

**Codebase Seeding (on first init):**
If the project has no Plan or Milestone nodes:
1. Read README and core files to understand the roadmap and architecture.
2. Create a `plan` node (e.g., "Project Roadmap") with `manage_nodes(action: "create", type: "plan", title: "...")`.
3. Add `milestone` nodes for key phases, connecting with `part_of` edges.
4. Create `decision` nodes for core technical choices, linking with `decided_in` edges.

### 5. CLI Commands Reference
```bash
state-memory-mcp init          # Initialize in current project
state-memory-mcp init-global   # Re-initialize across all projects in ~/.state-memory-mcp/projects.json
state-memory-mcp run           # Stdio MCP server (used by IDEs)
state-memory-mcp inspect -p X  # ASCII table of project nodes
state-memory-mcp metrics -p X  # ROI and token savings analytics
state-memory-mcp view -p X     # Open 3D graph visualizer in browser
state-memory-mcp export -p X -f [json|dot|mermaid|html]  # Export graph
state-memory-mcp scan-git -p X # Incrementally scan git history
state-memory-mcp backup -p X   # Back up the database
state-memory-mcp audit -p X    # Run integrity checks
state-memory-mcp doctor        # Verify system health and SQLite environment
```