state-memory-mcp

# @putervision/state-memory-mcp

[![npm version](https://img.shields.io/npm/v/@putervision/state-memory-mcp.svg)](https://www.npmjs.com/package/@putervision/state-memory-mcp)
[![Website](https://img.shields.io/badge/Website-statememorymcp.com-6366f1.svg)](https://statememorymcp.com)
[![License](https://img.shields.io/npm/l/@putervision/state-memory-mcp.svg)](https://github.com/putervision/state-memory-mcp/blob/main/LICENSE)

`@putervision/state-memory-mcp` is a zero-infrastructure, deterministic Model Context Protocol (MCP) server that provides AI agents with a structured, persistent graph for tracking workflow state—tasks, decisions, artifacts, plans, blockers, and their semantic relationships. Official Documentation & Interactive Demos: [statememorymcp.com](https://statememorymcp.com)

By using `@putervision/state-memory-mcp`, your AI coding assistant (such as Cursor, Claude Code, Gemini, or Copilot) maintains long-term project coherence, manages complex dependencies, and audits architectural decisions across sessions.

---

## ⚡ Quick Start & Installation

> **Prerequisites**: Node.js **>= 18.0.0**

```bash
# Install globally
npm install -g @putervision/state-memory-mcp

# Navigate to your project directory
cd your-project

# Initialize — creates .state-memory-mcp/, updates .gitignore,
# scaffolds IDE instructions and MCP configs for Cursor, Claude, Windsurf, etc.
state-memory-mcp init

# Done! Restart your IDE or Agent Manager (Cursor, VS Code, Antigravity, Claude) to activate.
```

### Alternative Installation Options

```bash
# Run directly via binary (after global install)
state-memory-mcp run

# Or install as a project dev dependency
npm install --save-dev @putervision/state-memory-mcp
```

---

## Key Features

1. **Deterministic State Memory**: No LLM in the loop; all operations are structured, deterministic, and fast.
2. **SQLite Storage**: Zero-infrastructure database persisted project-locally (under `.state-memory-mcp/`) or globally.
3. **80 Core MCP Tools**: Covers Node CRUD, relationship linking, circular dependency rejection, full-text search (FTS5), dependency path tracing, blocker analysis, natural language text-to-graph querying (`natural_language_query`), multi-agent optimistic CAS concurrency & blackboard store (`post_blackboard`, `read_blackboard`), atomic compound feature decomposition (`plan_and_decompose_feature`, `post_mortem_from_session`), time-travel history recovery (`get_state_at_timestamp`, `revert_to_timestamp`), cross-memory validation & auto-healing (`validate_memory_references`), velocity & burndown time-series analytics (`velocity_analytics`, `burndown_chart`), bidirectional issue sync (`export_issues`, `import_issues`), VCS branch sync & merge resolution (`vcs_branch_sync`, `vcs_merge_resolution`), automated compaction & historical archiving (`compact_graph`, `archive_completed_nodes`), health doctor & watcher (`doctor_report`, `watch_graph_changes`), value analytics, database administration utilities, template scaffolding, agent QoL context tools, session lifecycle tracking, event logging, cryptographic SHA-256 session audit verification (`verify_audit_chain`), state rollback/undo, compound workflow tools (`bootstrap_session`, `complete_task`, `batch_create_nodes`, `batch_add_edges`), selective field projections (`fields`), self-healing graph repair (`auto_fix`), dynamic resources, and workflow prompts.
4. **Interactive 3D HTML Visualizer**: Easily export or view your project state graph in your browser using an interactive, dark-themed WebGL 3D Force-Directed Graph visualizer built with `3d-force-graph` / Three.js.
5. **Safe SQL Querying**: Safe read-only SELECT querying against the database for advanced analytics.
6. **Git Branch Awareness**: Dynamically tracks and filters states based on the checkout workspace Git branch.
7. **One-Command Setup**: `state-memory-mcp init` scaffolds the data directory, `.gitignore`, IDE instruction files, and MCP configs for all major editors.
8. **Event-Sourced Audit Trail**: Every node and edge mutation is logged to an append-only events table with before/after state snapshots, session attribution, and timestamps.
9. **Session & Agent Tracking**: First-class session lifecycle with agent identity, enabling multi-agent collaboration and full provenance of who changed what.
10. **Persistent Context Snapshots**: Save, list, and diff context snapshots across sessions to detect drift and answer "what changed since last time?"
11. **Dual MCP Synergy**: Deep integration with `vision-memory-mcp` for unified text+visual trajectory tracking, automatic visual cache grounding, and visual state verification for UI tasks.

---

## Why State Memory MCP? (Agent Value Proposition)

AI coding agents (like Cursor, Gemini, Claude, and Copilot) operate within strict context window and performance limits. Storing your project's workflow state in the chat history or forcing agents to search files repeatedly is inefficient. `state-memory-mcp` solves this by introducing a structured, external state engine:

* **🧠 Cognitive Externalization**: Grounded in Cognitive Load Theory, this offloads the agent's extraneous load ($CL_E$). By relocating state from the model's weights and active context window into SQLite, it converts complex recall tasks into simple recognition tasks. Only the active node's schema and target variables are paged into context, preserving attention budget.
* **🚀 Faster Agent Executions**: Instead of running expensive, multi-step text search loops or file scans to figure out what to do next, agents can query `get_project_summary` or `find_blockers` in milliseconds. They immediately understand current blockers, goals, and outstanding tasks, reducing end-to-end execution latency by **67% to 74%** in multi-agent workflows.
* **📉 Massive Token Savings**: Storing logs, decisions, and task statuses in chat prompts wastes tokens on every turn. With `state-memory-mcp`, agents keep this state offloaded in a local SQLite database, fetching only relevant subgraphs when needed. This reduces context bloat and API costs by **128× to 462×** when utilizing compiled trajectory models.
* **🎯 Increased Quality of Responses**: Hallucinations and duplicate work happen when agents forget past context. A branch-aware state graph provides agents with a single, clear source of truth for all architectural decisions, milestones, and task requirements. Agents write better code because they always know *why* a decision was made.
* **🔒 First-Hop Determinism**: Unlike probabilistic vector RAG (cosine similarity), `state-memory-mcp` graph queries use deterministic SQL/CTE traversals. This eliminates the "first-hop" retrieval error that propagates cascading hallucinations down multi-agent execution pipelines.
* **🔗 Simplified Relationship Modeling**: Relationships are explicitly mapped with typed links (e.g. `blocks`, `produces`, `depends_on`). The server automatically validates dependencies and rejects circular reference loops, maintaining a clean, easily-navigable project structure.
* **🤝 Supercharged Multi-Agent Collaboration**: When deploying parallel subagents (e.g., one writing code, one running tests, one scanning logs), they lack a shared memory pool. `state-memory-mcp` acts as a local blackboard (Shared Context Store) where all subagents publish decisions, tasks, and blocker updates, ensuring coordination-level alignment without passing massive chat histories. This limits central LLM invocations to a constant $O(1)$ (Plan + Summarize) instead of scaling linearly $O(N)$ with task steps.
* **📈 Compounding Memory Flywheel**: As you log more tasks, architectural decisions, and observations, the state memory transitions from a simple checklist into a rich repository of project intelligence. Future agents can trace the `decision_trail`, reuse established subgraphs, avoid repeating past failures (recorded as blockers/observations), and instantly query context snapshots to understand code rationale. The more context is recorded, the less onboarding/discovery overhead is required for new agents, creating a compounding productivity flywheel.

> *\*Disclaimer: Latency reduction percentages and token savings ratios cited above are illustrative metrics derived from controlled context-store research models. Actual performance improvements, token savings, and cost reductions vary depending on model provider choice, prompt frequency, and individual workflow complexity.*

---

## State Memory Concepts

`state-memory-mcp` models your development workspace as a directed acyclic graph (DAG) where nodes represent development objects and edges represent their semantic relationships.

### 📋 Node Types & Valid Status Values

1. **`task`**: Incremental items of work or coding TODOs (Status: `pending`, `in_progress`, `done`, `blocked`, `cancelled`).
2. **`decision`**: Architectural choices, pattern selections, and rationale (Status: `active`, `accepted`, `deprecated`, `rejected`).
3. **`artifact`**: Coding output, documentation, or schemas generated (Status: `current`, `draft`, `deprecated`).
4. **`plan`**: High-level development specifications and roadmaps containing milestones (Status: `active`, `draft`, `completed`, `archived`).
5. **`milestone`**: Progress checkpoints representing a grouped set of related tasks (Status: `upcoming`, `in_progress`, `done`, `delayed`).
6. **`blocker`**: Impediments or bugs preventing tasks from being completed (Status: `active`, `resolved`, `mitigated`).
7. **`observation`**: Contextual findings, codebase notes, or runtime constraints recorded by the agent (Status: `active`, `archived`).
8. **`visual_state`**: Represents a visual UI screenshot checkpoint via Dual MCP Synergy (Status: `active`, `archived`, `invalidated`).

### 🔗 Edge Relationships

Nodes are linked together to represent workflow connections:
* `depends_on`: Declares that a task or milestone depends on another.
* `blocks`: Connects a blocker to the task/milestone it stalls.
* `produc