putervision 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:
manage_sessions(action: "start")— Start a tracking session with anagent_idfor full change attribution.get_analytics(action: "summary")— Understand current project state, active branches, and overall progress.manage_specs(action: "compliance")— Check real-time requirement coverage matrix and unfulfilled criteria.manage_tasks(action: "next")— Query prioritized runnable tasks (sorted by downstream impact and age).manage_tasks(action: "find_blockers")— Identify any active blockers preventing progress.manage_nodes(action: "list")— Find pending tasks, past decisions, or milestones.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:
manage_sessions(action: "start", agent_id: "my-agent")→ getsession_id- Pass
session_idto graph mutations (manage_nodes,manage_edges) manage_sessions(action: "end", session_id: session_id)when work is complete
Task Decomposition:
- Decompose user requests into task nodes with
manage_nodes(action: "create", type: "task", title: "...") - Connect related tasks with
manage_edges(action: "add", type: "depends_on", source_id: A, target_id: B) - 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:
- Read README and core files to understand the roadmap and architecture.
- Create a
plannode (e.g., "Project Roadmap") withmanage_nodes(action: "create", type: "plan", title: "..."). - Add
milestonenodes for key phases, connecting withpart_ofedges. - Create
decisionnodes for core technical choices, linking withdecided_inedges.
5. CLI Commands Reference
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