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

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