state-memory-mcp
A local, deterministic SQLite-backed state memory MCP server for tracking and querying AI coding workflow state, tasks, decisions, artifacts, blockers, specs, and relationships.
Create, update, search, batch, and annotate graph nodes (tasks, decisions, artifacts, plans, milestones, blockers, specs, observations, etc.).
Link nodes with typed semantic edges (depends_on, blocks, produces, references, verifies, etc.) and visual-state relationships.
Manage task queues: next tasks, completion, blockers, stale tasks, similar blockers, and auto-pruning.
Track agent sessions, bootstrap context, and attribute changes to agents.
Author, ingest, export, verify, and decompose Spec-Driven Development specs and acceptance criteria.
Save, diff, revert, and time-travel through graph snapshots and node history.
Query graph topology: subgraphs, dependency traces, raw read-only SQL, natural language queries, and compact task slices.
Compute analytics: velocity, burndown, value metrics, cognitive load, critical path, decision trails, and contradictions.
Inspect the append-only event ledger, changelogs, and session post-mortems.
Run diagnostics, health checks, reference validation, audit-chain verification, and storage maintenance.
Back up, restore, audit, merge SQLite databases, and sync/diff/merge across Git branches.
Import/export graphs, issues, trajectories, synergy metrics, and specs.
Coordinate multi-agent work via shared blackboard topics, messages, and mutex leases.
Provides Git-aware state tracking by dynamically scoping project state to the current Git branch, and offers VCS branch sync and merge resolution tools for the state graph.
@putervision/state-memory-mcp
@putervision/state-memory-mcp is a zero-infrastructure, deterministic Model Context Protocol (MCP) server that provides AI coding assistants (such as Cursor, Claude Code, Gemini, or Copilot) with a structured, persistent SQLite graph for tracking workflow stateβtasks, decisions, artifacts, plans, blockers, and their semantic relationships.
π Official Documentation & Website: statememorymcp.com
β‘ Quick Start & Installation
Prerequisites: Node.js >= 18.18.0
# 1. Install globally
npm install -g @putervision/state-memory-mcp
# 2. Navigate to your project directory
cd your-project
# 3. Initialize state-memory-mcp
# Creates .state-memory-mcp/, updates .gitignore, registers project,
# and scaffolds IDE instructions and MCP configs for Cursor, Claude, VS Code, Windsurf, etc.
state-memory-mcp init
# Done! Restart your IDE or Agent Manager to activate.Alternative Options
# Run directly via binary (after global install)
state-memory-mcp run
# Re-initialize across all registered workspace projects
state-memory-mcp init-globalRelated MCP server: AIVectorMemory
π Key Highlights
π§ Deterministic State Memory & Compact TaskSlices: Zero LLM in the loop for memory operations; fast, deterministic SQLite graph traversals, and sub-1KB
TaskSliceextraction for System 1 fast path evaluation.β‘ 13 Production-Grade Consolidated MCP Tools: Full CRUD, relationship linking, DAG cycle checks, FTS5 search, TF-IDF RAG, time-travel history rollback, Spec-Driven Development, and auto-healing validation.
π Efficient Context Management & Decision Thresholding: Offloads context to a local SQLite database, filters sub-0.70 routine decisions to append-only event logs to prevent graph bloat, and preserves high-significance turns.
π 67%β74% Latency Reduction: Eliminates multi-step file scanning loops; agents retrieve unblocked tasks and blockers in milliseconds.
π€ Multi-Agent Blackboard: Shared Context Store allowing parallel subagents to publish decisions, tasks, and blocker updates safely.
π¨ Interactive 3D Visualizer: Browser-based dark-mode 3D WebGL force-directed graph visualizer (
state-memory-mcp view).π Dual-MCP Synergy: Pair with
@putervision/vision-memory-mcpfor visual state caching, perceptual hashing, and cryptographic multimodal evidence packs.π‘οΈ 100% Local & Private: Local-first architecture; all state stays inside
.state-memory-mcp/in your workspace.
π οΈ MCP Tool Suite
@putervision/state-memory-mcp provides 13 production-grade consolidated MCP tools organized across 5 core workflow domains:
Graph & Relationships:
manage_nodes(node CRUD, FTS5/TF-IDF vector search, atomic batch mutations, observation notes, thresholded fast decision logging),manage_edges(typed DAG links, multimodal visual state linking).Task Execution & Work Queue:
manage_tasks(topological dependency queue, blocker detection, task completion with artifacts, auto-prune),manage_sessions(agent attribution, turn tracking, context bootstrap).Spec-Driven Development (SDD):
manage_specs(PRD/RFC parsing, requirement-to-task decomposition, live acceptance criteria verification, compliance scoring).Analytics, Audit & Diagnostics:
get_analytics(velocity, burndown, token ROI, cognitive load, critical path),get_events(SHA-256 tamper-evident event ledger),run_diagnostics(DAG validation, health checks, AST reference integrity).Data, Snapshots & Multi-Agent:
manage_snapshots(checkpoints, time-travel undo),manage_database(backups, checksum audits, VCS branch merge),manage_data(bulk import/export, ML trajectories with interleaved fast decision events),query_graph(subgraphs, dependency tracing, raw SQL, sub-1KBcompact_slice),use_blackboard(multi-agent asynchronous topic board).
π For complete parameter specifications, return schemas, and example payloads, see the Tools Reference Guide and Formal API Reference.
π Architecture & State Graph Lifecycle
AI Agent Prompt / Task
β
βΌ
βββββββββββββββββββββββββββββββββββ
β Agent Session Attribution β βββΆ manage_sessions(action: "start")
ββββββββββββββββββ¬βββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββ
β Context & Task Prioritization β βββΆ get_analytics(action: "summary")
β β βββΆ manage_tasks(action: "next")
ββββββββββββββββββ¬βββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββ
β Deterministic Graph Mutation β βββΆ manage_nodes(action: "create"|"update")
β (Tasks, Decisions, Blockers) β βββΆ manage_edges(action: "add"|"link_visual")
ββββββββββββββββββ¬βββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββ
β Spec & Integrity Verification β βββΆ manage_specs(action: "compliance"|"verify")
β β βββΆ run_diagnostics(action: "validate")
ββββββββββββββββββ¬βββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββ
β Persistent SQLite Storage β βββΆ .state-memory-mcp/graph.db (WAL mode)
β Append-Only Event Ledger β βββΆ SHA-256 Cryptographic Audit Chain
βββββββββββββββββββββββββββββββββββπ Documentation Directory
Explore dedicated guides and deep dives in the docs/ directory:
Guide | Description |
High-signal architectural overview, module inventory, data flows, and design decisions. | |
Step-by-step migration guide, legacy tool mapping table, and | |
Cognitive Externalization, FSM Formalism, First-Hop Determinism & Benchmark metrics. | |
Node Types ( | |
βοΈ Configuration & IDE Setup | Auto-Initialization details, Environment Variables table, and Editor Configs (Cursor, VS Code, Claude, Antigravity, Windsurf). |
π οΈ CLI Command Reference | CLI flags ( |
β±οΈ Sessions, Snapshots & SDD | Session Lifecycle, Event Audit Trail, Snapshots, Trajectories, Sub-directory support & Spec-Driven Development. |
Complete reference for all 13 Consolidated MCP Tools, read-only | |
π Formal API Reference | Formal parameters, return schemas, and code signatures for all MCP endpoints. |
π¨ 3D Visualizer Guide | Viewing and exporting the interactive WebGL 3D Force-Directed Graph visualizer. |
ποΈ Database Schema | SQLite tables, columns, indexes, and schema migration history. |
π Agent Playbook: 5-Step Canonical Workflow
When an autonomous AI agent enters a repository with state-memory-mcp:
1. Orient & Bootstrap βββΆ manage_sessions(action: "start") + get_analytics(action: "summary")
2. Task Selection βββΆ manage_tasks(action: "next") + manage_tasks(action: "find_blockers")
3. Trace Context βββΆ query_graph(action: "trace") + manage_specs(action: "compliance")
4. Execute & Record βββΆ manage_nodes(action: "create", type: "decision") + manage_edges(action: "link_visual")
5. Validate & Close βββΆ run_diagnostics(action: "validate") + manage_tasks(action: "complete") + manage_sessions(action: "end")π§ͺ Testing
# Run full unit, integration, and performance benchmark test suite across all 113 test files (418 tests)
npm run testβοΈ License & Disclaimers
Developed and maintained by PuterVision. Released under the MIT License.
Local Storage Guarantee: All graph data, decision records, and event logs remain 100% local in your workspace. No telemetry or project data is ever transmitted.
Trademarks & Non-Affiliation: Product names (Cursor, Claude Code, Gemini, Windsurf, VS Code, GitHub, SQLite) are property of their respective owners and used solely for compatibility identification.
Available Tools
13 toolsget_analyticsARead-onlyIdempotent
Compute workflow metrics, velocity, burndown, cognitive load, decision lineages, and contradiction audits (actions: summary, velocity, burndown, value_metrics, cognitive_load, critical_path, context_snapshot, active_context, decision_trail, find_related_decisions, contradictions). Use get_analytics instead of query_graph when calculating high-level progress statistics, ROI metrics, or auditing decision conflicts.
Returns summary dashboard, velocity charts, burndown series, cognitive load metrics, critical path DAG, or contradiction reports.
Inputs: action (required), days, node_id, project, +3 more.
get_eventsARead-onlyIdempotent
Inspect the append-only event audit ledger, query structured changesets, and generate session post-mortems (actions: log, changelog, post_mortem). Use get_events instead of manage_snapshots when examining the granular chronological sequence of mutations rather than restoring state checkpoints.
Returns chronological event array, structured changeset diff, or session post-mortem markdown report.
Inputs: action (required), limit, since, until, +5 more.
manage_dataADestructive
Export and import graph structures, issue tracker items, fine-tuning trajectories, and multimodal synergy metrics (actions: export_graph, export_issues, export_trajectories, export_joint_trajectories, export_synergy_metrics, from_tick, import_graph, import_issues, import_spec). Use manage_data instead of query_graph when bulk-transferring graph data or generating AI training datasets.
Returns serialized graph payload, trajectory dataset, synergy metrics, or import statistics.
Inputs: action (required), edges, force, limit, +9 more.
manage_databaseADestructive
Physical SQLite database maintenance, backups, integrity checks, and Git VCS state sync (actions: backup, restore, audit, merge, branch_diff, branch_merge). Use manage_database instead of manage_snapshots when managing physical SQLite files, cross-branch merges, or database corruption audits.
Returns database backup path, foreign key integrity report, branch merge conflict report, or diff.
Inputs: action (required), force, project, backupPath, +5 more.
manage_edgesADestructive
Manage typed graph relationships between nodes (actions: add, remove, batch_add, link_visual). Use manage_edges instead of manage_nodes when creating or modifying relationships between existing entities rather than entity data itself.
Returns created edge record, batch count, or visual link confirmation.
Inputs: action (required), type, edges, project, +8 more.
manage_nodesADestructive
Manage graph nodes in the state graph (actions: create, update, get, remove, list, search, batch_create, batch_update, add_note). Use manage_nodes instead of manage_tasks when operating on general node types (decisions, artifacts, plans, milestones, blockers) rather than runnable task workflow states.
Returns node object, edge connections, batch results, or search matches.
Inputs: action (required), id, ids, tags, +17 more.
manage_sessionsA
Manage agent tracking sessions and multi-turn workflow attribution (actions: start, end, list, bootstrap). Use manage_sessions instead of manage_tasks when establishing agent session boundaries and tracking multi-turn workflows rather than individual work items.
Returns session record, bootstrap context snapshot, or active session listing.
Inputs: action (required), limit, project, agent_id, +4 more.
manage_snapshotsADestructive
State checkpointing, time travel, diffing, and undo operations (actions: save, list, diff, get_state, revert, undo, get_history). Use manage_snapshots instead of manage_database when reverting state graph mutations or comparing checkpoints rather than physical database file maintenance.
Returns snapshot record, state graph diff, historical graph state, or node audit history.
Inputs: action (required), force, limit, node_id, +5 more.
manage_specsA
Spec-Driven Development (SDD) lifecycle and workflow template generation (actions: scaffold, ingest, export, compliance, verify, decompose_feature, template). Use manage_specs instead of manage_nodes when authoring, ingesting, or verifying formal SDD specifications against acceptance criteria.
Returns specification AST, compliance matrix, verification verdict, or decomposed feature plan.
Inputs: action (required), name, title, format, +9 more.
manage_tasksA
Task prioritization, workflow execution, blockers, and stale task management (actions: next, complete, find_blocked, find_stale, find_blockers, find_similar_blockers, auto_prune). Use manage_tasks instead of query_graph when querying runnable tasks by priority order or resolving execution blockers.
Returns prioritized runnable tasks, blocker hierarchy, similar resolved blockers, or completion confirmation.
Inputs: action (required), type, limit, query, +16 more.
query_graphARead-onlyIdempotent
Query graph topology, neighborhoods, dependency paths, safe read-only SQL queries, and compact System One task slices (actions: subgraph, trace, raw, natural_language, compact_slice). Use query_graph instead of get_analytics when exploring graph topology and path traversals rather than aggregated numerical metrics.
Returns subgraph nodes and edges, upstream/downstream trace path, raw SQL rows, or compact task slice.
Inputs: action (required), sql, depth, query, +7 more.
run_diagnosticsADestructive
Run graph sanity checks, health diagnostics, reference validation, audit chain verification, and storage maintenance (actions: validate, doctor, check_refs, audit_chain, compact, archive, prune_events, version, dedupe). Use run_diagnostics instead of get_analytics when performing database repair, AST reference auto-healing, or verifying SHA-256 event hash chains.
Returns validation diagnostics, health report, broken reference repair log, Merkle chain audit, or maintenance stats.
Inputs: action (required), apply, checks, dry_run, +6 more.
use_blackboardADestructive
Multi-agent shared blackboard for asynchronous coordination and mutex leases (actions: get, set, delete, lease, list, post, read). Use use_blackboard instead of manage_nodes when exchanging transient inter-agent messages or mutex resource leases rather than recording persistent graph knowledge.
Returns blackboard message payload, lease acquisition status, active topic list, or deletion confirmation.
Inputs: action (required), id, mode, limit, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 13 tools
The descriptions are unusually thorough with explicit 'use X instead of Y' guidance, which genuinely helps separate tools like manage_nodes vs manage_edges vs use_blackboard and manage_snapshots vs manage_database vs get_events. However, the underlying domain heavily overlaps: nodes/edges/specs/blackboard all manipulate graph-like entities, and query_graph/get_analytics/run_diagnostics all operate on the same graph for read, aggregate, and maintenance purposes. Boundaries are clarified by prose rather than being intrinsically clean.
Most tools use a manage_* pattern (manage_data, manage_nodes, manage_edges, manage_sessions, manage_tasks, manage_snapshots, manage_specs, manage_database), which is consistent. But the remaining tools break the pattern with distinct verbs (query_graph, get_analytics, get_events, run_diagnostics, use_blackboard), producing mixed conventions. It remains readable, but there is no single predictable verb_noun scheme.
13 tools is within the well-scoped range and appropriate for a state/memory graph server covering graph, tasks, sessions, specs, analytics, events, and diagnostics. The design consolidates many operations as actions within each tool rather than exploding the tool count, keeping the surface manageable. Slightly heavy given the breadth, but reasonable.
Coverage is broad: node/edge CRUD, task workflow, sessions, snapshots/time-travel, specs, database maintenance, graph queries, analytics, event ledger, diagnostics, and multi-agent blackboard. Most lifecycle operations (create, update, get, list, remove, batch) appear across the mutation tools. Minor gaps exist, such as bulk-delete actions being less explicit than bulk-create.
Maintenance
Related MCP Connectors
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Cross-tool persistent memory and context for AI assistants over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA self-hosted MCP server that provides AI assistants with a shared, persistent SQLite-backed memory for storing and retrieving project context, decisions, and discoveries. It enables cross-session continuity and team-wide knowledge sharing to keep AI coding tools aligned and informed.3MIT
- AlicenseBqualityDmaintenanceMCP server that provides cross-session persistent memory for AI coding assistants using local vector database and semantic search, enabling automatic recall of project context, issues, and tasks.993Apache 2.0
- FlicenseNot gradedqualityDmaintenanceA persistent, conflict-aware memory MCP server for AI coding assistants (Cursor, Claude Code).-
- AlicenseNot gradedqualityDmaintenanceA local MCP memory server that gives AI assistants durable project memory across coding sessions, storing context, changes, and decisions.1MIT