Production Ready v0.8.2 • 80 Core MCP Tools

State Memory MCP

Name: @putervision/state-memory-mcp
Author: PuterVision LLC

A zero-infrastructure, deterministic workflow state graph server for AI agents. Track tasks, design decisions, session histories, and blockers locally to supercharge agent context and eliminate memory bloat.

Get Started Explore Documentation Calculate ROI

RESEARCH PAPER GROUNDED

Theoretical Foundations, Technical Architecture & Capabilities

📦 What State Memory MCP Provides

A zero-infrastructure, deterministic Model Context Protocol (MCP) server for developer AI agents (Cursor, Gemini, Claude Code, Windsurf). It provides persistent long-term state memory, managing task execution DAGs, architectural decision logs, artifact outputs, milestones, active blockers, and Spec-Driven Development contracts across multi-turn sessions.

🧠 Cognitive Externalization ($CL = ICL + ECL$)

Grounded in Cognitive Load Theory, it externalizes workflow state from the AI's active context window into project-local SQLite storage (`.state-memory-mcp/state.db`). By serving per-node scoped context ($C_v = \{\text{local SOP for } v, \text{ variables required by } v\}$), it drives Extraneous Cognitive Load (ECL) to zero and converts expensive recall into instant recognition.

⚡ Context-Aware MCP (CA-MCP) Reactor Engine

Shifts step-by-step control away from centralized LLM planners. The central language model acts only as strategic planner and summarizer ($N_{\text{LLM}} = 2$), while stateful MCP server reactors communicate asynchronously over a Shared Context Store (SCS), yielding 67% to 74% execution latency reductions.

🔒 Cryptographic SHA-256 Session Auditing

Every node mutation, edge link, and state transition is cryptographically bound into an append-only event ledger ($H_n = \text{SHA-256}(H_{n-1} \parallel \text{event}_n)$). Built-in mathematical verification (`verify_audit_chain`) provides tamper-evident audit trails designed to support enterprise AI governance and record-keeping frameworks.

🎯 Spec-Driven Development & First-Hop Determinism

Replaces probabilistic vector chunking (Vector RAG) with relationship-aware symbol graph traversals (`depends_on`, `blocks`, `produces`, `satisfies`). Includes built-in AST spec ingestion for Markdown PRDs, OpenSpec, and Gherkin BDD `.feature` files with real-time drift detection and hard SQL cycle rejection.

📊 Tangible Developer Value & 3D Visualizer

Reduces context bloat and API token costs by 128× to 462× when utilizing compiled trajectory models. Features first-class Git branch awareness, auto-healing graph repair (`auto_fix`), and an interactive WebGL 3D Force-Directed Graph visualizer launched via `state-memory-mcp view`.

Interactive 3D Force-Directed Graph Visualizer for state-memory-mcp showing node dependencies and task state graph

Interactive 3D Force-Directed Graph Visualizer state-memory-mcp view

💡 Why State Memory MCP?

Offload your development state from the agent's chat history into a structured, high-performance local database.

🧠 Cognitive Externalization

Separates intrinsic task complexity from presentation clutter. Relocates state to SQLite, turning recall into simple recognition.

🚀 Faster Agent Executions

Eliminates expensive search loops. Reduces end-to-end execution latency by 67% to 74% in multi-agent workflows.

📉 Massive Token Savings

Keeps history in SQLite. Reduces API usage costs by 128× to 462× when utilizing compiled trajectory models.

🎯 Higher Response Quality

Provides a branch-aware, single source of truth for architectural decisions. Prevents agent hallucinations and redundant work.

🔒 First-Hop Determinism

Graph queries use deterministic SQL, not probabilistic vector search, avoiding cascading hallucination loops.

🔗 Simplified Relationships

Defines precise task, decision, and blocker relationships with automatic cycle rejection to guarantee a clean graph structure.

🤝 Multi-Agent Blackboard

Limits central LLM invocations to O(1) instead of O(N) by letting parallel subagents update and sync state directly on SQLite.

📈 Compounding Flywheel

Accumulating decisions and historical tasks builds deep project context. Future agents onboard faster and avoid repeating past design pitfalls.

📊 Workflow Value & ROI Estimator

Lays out the ballpark value, tokens saved, and developer time recovered by persisting project workflow state graphs.

Accepted Design Decisions (Avoided Context Switches) 10

Structural Dependencies Mapped (Avoided Manual Lookups) 25

Blockers Logged & Resolved (Avoided Stall Times) 5

Average Graph Size (Captured Context Tokens) 4,000

Development Sessions (Reused Context Across Sessions) 8

Target LLM Model (For Cost Savings)

Estimated Developer Time Saved

3.0 hours

Estimated Session Tokens Saved

32,000 tokens

Estimated API Cost Saved

$0.10

Moderate ROI

* Legal & Financial Disclaimer: ROI metrics, token savings estimates, and developer time reductions generated by this calculator are for illustrative, hypothetical modeling purposes only based on baseline model context window formulas. Actual token consumption, latency reductions, and cost savings depend on specific LLM provider API pricing, prompt frequencies, project complexity, and agent execution architectures. PuterVision LLC does not guarantee specific monetary savings or productivity gains.

🧱 Anatomy of the Workflow State Memory

A strongly-typed, SQLite-backed vocabulary designed to represent software development states.

📋 Nodes (Entity Types)

The 7 nodes that structure your workspace context:

Task: Active developer TODOs and checklist checkpoints.
Decision: Architectural choices, trade-offs, and design rationale.
Artifact: Output files, packages, database schemas, and configs.
Plan: Multi-phase roadmaps and feature implementation specifications.
Blocker: Active bugs or missing dependencies stalling progress.
Milestone: Groups of related tasks representing progress stages.
Observation: General discoveries, runtime behaviors, and notes.

🔗 Edges (Relationship Mappings)

Connects workflow nodes via explicit semantic relationships:

depends_on: Direct node-to-node dependency.
blocks / produces: Declares blockers or generated files.
references / updates: Relates code/docs or replaces decisions.
contradicts: Flags conflicting decisions or code states.
part_of / child_of: Hierarchical plan and milestone nesting.
implements / decided_in: Links tasks to specifications or decisions.

🧠 Advanced Graph Analytics

Empowers agents to perform complex, automated analysis over your workspace state.

🧭 Critical Path Analysis

Finds the exact chain of uncompleted, blocking tasks delaying a milestone so agents can prioritize resolving them.

💥 Blast Radius Analysis

Calculates the downstream impact of changing an artifact, task, or architectural decision before editing code.

🔍 Contradiction Audits

Scans the database for anomalies, such as completed tasks with active blockers or contradicting accepted decisions.

🗺️ Decision Trails

Traces the historical lineage of updates and contradictions to reconstruct the "why" behind old design choices.

⚡ Research-Backed Performance

State-graph-driven Model Context Protocol architectures yield massive, measured improvements in production environments.

67% - 74%

Latency Reduction

Direct server-to-server updates bypass latency-inducing round-trips to the central model.

128x - 462x

Cost Savings

Using trajectory event logs to compile procedures into smaller, local models lowers API usage costs.

O(1)

Central Model Invocations

Limits central planner calls to just start (Plan) and end (Summarize), preventing context decay.

* Disclaimer: Performance benchmarks and cost reduction figures are illustrative estimates derived from stateful context store research and average model API rates. Actual execution latency drops and cost savings depend on your specific agent architecture, prompt frequency, and context payload size.

🛠️ Core Features

A zero-infrastructure, deterministic framework built for AI coding assistants.

⛓️ Deterministic Logic

No LLM hallucination in data retrieval. Every node CRUD operation, cycle check, and lookup is written in plain SQL/JavaScript.

🛡️ Path & SQL Sanitization

Strict path resolve guards prevent file access escaping the workspace, and regex filters block administrative SQLite queries.

🌲 Git Branch Awareness

Dynamically isolates node tasks and planning logs depending on the checked out git branch, preventing main branch noise.

🕶️ 3D WebGL Visualization

Instantly launch interactive 360-degree dark mode force-directed graphs in your default web browser to inspect node links visually.

📜 Event Audit Trail

Every node/edge change is logged to an append-only events table with before/after state snapshots and chronological node history.

🔐 Session Identity

Track sessions with agent identity and custom metadata to verify provenance and see who performed what change when.

📂 Sub-Directory & Mono-Repo Support

Discovers nested Git repositories and sub-directory memory databases up to 4 levels deep, auditing health and observing sub-project memory graphs automatically.

📑 Spec-Driven Development (SDD)

Parse Markdown PRDs and Gherkin BDD specs into graph nodes, tracking requirement coverage, spec drift, and acceptance criteria verification in real-time.

🔌 Full MCP Specification Compliance

Equipped with complete spec features including annotations, resources, and custom prompts.

📁 Exposed Graph Resources

Provides read-only contexts using RFC 6570 templates under the state-memory:/// URI scheme:

state-memory:///{project}/summary

Project state counts, task breakdowns, progress rates, and recent decisions.
state-memory:///{project}/blockers

Lists active blockers and what transitively blocked tasks they stall.
state-memory:///{project}/decisions

Logs accepted decisions and updates histories.
state-memory:///{project}/events

Lists recent project events and state-transition mutation ledger.
state-memory:///{project}/sessions

Lists active and past sessions with executing agent identities.

💬 Reusable Prompts

Template instructions that automatically fetch state data to bootstrap workflows:

session-start

Bootstraps your coding agent with current project summary, blockers list, and immediate pending tasks.
plan-feature

Guides feature development scaffolding, milestone breakdowns, and design RFC decisions.
triage-blockers

Guides triaging active blockers and resolving critical path dependency chains.

📚 Architecture & Complete Tool Reference

Complete suite of 80 Model Context Protocol (MCP) tools for persistent state graph management.

FULL 80 MCP TOOL SUITE

Complete Tool Definitions & Function Signatures

🚀 Session & Administration (8 Tools)

start_session, end_session, list_sessions, get_project_summary, backup_project_db, restore_project_db, audit_project_db, merge_project_db.

How to Leverage: Call start_session at turn 1 to scope all task mutations to a unique ledger. Use get_project_summary to retrieve overall completion %, unblocked tasks, and active blockers in milliseconds instead of reading hundreds of files.

⚡ View JSON Payload Example

// Request
{ "project": "my-app", "agent_id": "cursor-01" }

// Response
{ "session_id": "sess_01KYBJ0", "status": "started" }

📋 Task & Node Mutations (11 Tools)

next_tasks, find_blockers, add_node, update_node, get_node, remove_node, add_edge, remove_edge, batch_update, batch_create_nodes, batch_add_edges.

How to Leverage: Create task nodes for actionable code steps, decision nodes for architectural choices, and blocker nodes when stuck. Calling update_node(status: "done") automatically unblocks downstream tasks.

⚡ View JSON Payload Example

// Request
{ "project": "my-app", "type": "decision", "title": "Use Argon2id" }

// Response
{ "id": "node_01KYBJ", "status": "done" }

🔍 Graph Traversal & Cognitive Load (11 Tools)

search_nodes, get_subgraph, trace_dependencies, critical_path, decision_trail, impact_analysis, detect_contradictions, get_stale_nodes, validate_graph, get_cognitive_load, traceback_to_node.

How to Leverage: Use get_cognitive_load to monitor extraneous prompt load ($ECL$). If a test or build fails, call traceback_to_node to reset execution back to a known validated state without prompt hallucination.

⚡ View JSON Payload Example

// Request
{ "project": "my-app", "target_node_id": "task_schema_01" }

// Response
{ "success": true, "status": "in_progress" }

📜 Audit Ledger & CA-MCP Reactors (11 Tools)

verify_audit_chain, subscribe_context_changes, get_event_log, get_node_history, undo_last, prune_events, what_changed, add_note, bootstrap_session, complete_task.

How to Leverage: Execute verify_audit_chain in CI/CD pre-commit hooks to verify SHA-256 event integrity ($H_n = \text{SHA-256}(H_{n-1} \parallel \text{event}_n)$). Use subscribe_context_changes for CA-MCP $N_{\text{LLM}}=2$ subagent reactors.

⚡ View JSON Payload Example

// Request
{ "project": "my-app" }

// Response
{ "valid": true, "total_events": 148, "message": "Cryptographic audit chain verified." }

📸 Snapshots & Fine-Tuning Trajectories (14 Tools)

save_snapshot, list_snapshots, diff_snapshots, get_context_snapshot, export_trajectories, scaffold_template, value_metrics, export_graph, import_graph, query_graph, find_related_decisions, find_blocked_tasks, ingest_spec, export_spec.

How to Leverage: Use export_trajectories to export JSONL training datasets to fine-tune local 3B–8B parameter models, compiling procedural workflow SOPs into weights for 100× lower runtime token costs.

⚡ View JSON Payload Example

// Request
{ "project": "my-app", "format": "jsonl" }

// Response
{ "exported_count": 42, "file_path": "./trajectories.jsonl" }

📑 Spec Compliance (4 Tools)

ingest_spec, export_spec, calculate_spec_compliance, verify_requirement.

How to Leverage: Parse Markdown PRDs or Gherkin BDD specifications into graph nodes and continuously track acceptance criteria verification rates against active codebase changes.

⚡ View JSON Payload Example

// Request
{ "project": "my-app", "criterion_id": "crit_01", "status": "verified" }

// Response
{ "success": true, "compliance_pct": 100.0 }

🗄️ Database Schema Reference

Complete SQL schema definitions for nodes, edges, events, sessions, snapshots, and FTS5 triggers.

View Database Schema →

📁 Local Storage Architecture

Directory hierarchy for .state-memory-mcp/, global storage fallback, permissions (`0o700`/`0o600`), and path validation security.

View Storage Architecture →

📘 Formal MCP Tool API Reference

Formal OpenAPI & JSON-RPC 2.0 schema specifications, input parameter types, and example payloads for all 76 MCP tools.

View Formal API Reference →

📦 Programmatic Library API

Exported TypeScript library module (@putervision/state-memory-mcp/lib) for embedding engines directly in Node.js applications.

View Library Exports →

⚙️ Client & IDE Integrations

Zero manual effort: state-memory-mcp init automatically scaffolds config files for all supported IDEs.

⚡ Recommended: 1-Step Auto-Scaffolding

Run state-memory-mcp init inside your repository. It automatically generates and updates configuration files across all your installed agent environments, including workspace agent rules (.agents/AGENTS.md) and skill documentation (.agents/skills/state-memory-mcp/SKILL.md).

state-memory-mcp init

👽 Google Antigravity

Global: ~/.gemini/config/mcp_config.json
Workspace: .agents/settings.json

{
  "mcpServers": {
    "state-memory-mcp": {
      "command": "state-memory-mcp",
      "args": ["run"]
    }
  }
}

🤖 Claude Code & Desktop

One-line CLI: claude mcp add state-memory-mcp -- state-memory-mcp run
Desktop config: claude_desktop_config.json

{
  "mcpServers": {
    "state-memory-mcp": {
      "command": "state-memory-mcp",
      "args": ["run"]
    }
  }
}

🪄 Cursor & VS Code

Cursor: .cursor/mcp.json
VS Code: .vscode/mcp.json

{
  "mcpServers": {
    "state-memory-mcp": {
      "command": "state-memory-mcp",
      "args": ["run"],
      "env": {
        "STATE_MEMORY_MCP_PROJECT": "my-project"
      }
    }
  }
}

🌊 Windsurf & Roo / Cline

Windsurf: .windsurf/mcp.json or ~/.codeium/windsurf/mcp_config.json
Roo Code / Cline: .cline/mcp.json

{
  "mcpServers": {
    "state-memory-mcp": {
      "command": "state-memory-mcp",
      "args": ["run"]
    }
  }
}

🚀 Quickstart

Get state-memory-mcp configured globally in 10 seconds.

1. Install @putervision/state-memory-mcp globally

npm install -g @putervision/state-memory-mcp

2. Initialize inside your project repository

state-memory-mcp init

3. Display value metrics from CLI

state-memory-mcp metrics

4. Run environment & system health check

state-memory-mcp doctor

State Memory MCP

Theoretical Foundations, Technical Architecture & Capabilities

📦 What State Memory MCP Provides

🧠 Cognitive Externalization ($CL = ICL + ECL$)

⚡ Context-Aware MCP (CA-MCP) Reactor Engine

🔒 Cryptographic SHA-256 Session Auditing

🎯 Spec-Driven Development & First-Hop Determinism

📊 Tangible Developer Value & 3D Visualizer

💡 Why State Memory MCP?

🧠 Cognitive Externalization

🚀 Faster Agent Executions

📉 Massive Token Savings

🎯 Higher Response Quality

🔒 First-Hop Determinism

🔗 Simplified Relationships

🤝 Multi-Agent Blackboard

📈 Compounding Flywheel

📊 Workflow Value & ROI Estimator

🧱 Anatomy of the Workflow State Memory

📋 Nodes (Entity Types)

🔗 Edges (Relationship Mappings)

🧠 Advanced Graph Analytics

🧭 Critical Path Analysis

💥 Blast Radius Analysis

🔍 Contradiction Audits

🗺️ Decision Trails

⚡ Research-Backed Performance

Latency Reduction

Cost Savings

Central Model Invocations

🛠️ Core Features

⛓️ Deterministic Logic

🛡️ Path & SQL Sanitization

🌲 Git Branch Awareness

🕶️ 3D WebGL Visualization

📜 Event Audit Trail

🔐 Session Identity

📂 Sub-Directory & Mono-Repo Support

📑 Spec-Driven Development (SDD)

🔌 Full MCP Specification Compliance

📁 Exposed Graph Resources

state-memory:///{project}/summary

state-memory:///{project}/blockers

state-memory:///{project}/decisions

state-memory:///{project}/events

state-memory:///{project}/sessions

💬 Reusable Prompts

session-start

plan-feature

triage-blockers

📚 Architecture & Complete Tool Reference

Complete Tool Definitions & Function Signatures

🚀 Session & Administration (8 Tools)

📋 Task & Node Mutations (11 Tools)

🔍 Graph Traversal & Cognitive Load (11 Tools)

📜 Audit Ledger & CA-MCP Reactors (11 Tools)

📸 Snapshots & Fine-Tuning Trajectories (14 Tools)

📑 Spec Compliance (4 Tools)

🗄️ Database Schema Reference

📁 Local Storage Architecture

📘 Formal MCP Tool API Reference

📦 Programmatic Library API

⚙️ Client & IDE Integrations

⚡ Recommended: 1-Step Auto-Scaffolding

👽 Google Antigravity

🤖 Claude Code & Desktop

🪄 Cursor & VS Code

🌊 Windsurf & Roo / Cline

🚀 Quickstart

1. Install @putervision/state-memory-mcp globally

2. Initialize inside your project repository

3. Display value metrics from CLI

4. Run environment & system health check