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

This project uses state-memory-mcp with project slug "behavior-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

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