Skip to main content
Glama

@putervision/state-memory-mcp

npm version version npm downloads CI Node TypeScript Website License: MIT

@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-global

Related 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 TaskSlice extraction 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-mcp for 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-1KB compact_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

πŸ—οΈ Architecture & Codebase Distillation

High-signal architectural overview, module inventory, data flows, and design decisions.

πŸš€ v0.10 β†’ v1.0 Migration Guide

Step-by-step migration guide, legacy tool mapping table, and STATE_MEMORY_COMPAT mode.

πŸ’‘ Value Proposition & Theory

Cognitive Externalization, FSM Formalism, First-Hop Determinism & Benchmark metrics.

πŸ“‹ State Memory Concepts

Node Types (task, decision, blocker...), Status Values, Typed Edges & Seeding Guidelines.

βš™οΈ Configuration & IDE Setup

Auto-Initialization details, Environment Variables table, and Editor Configs (Cursor, VS Code, Claude, Antigravity, Windsurf).

πŸ› οΈ CLI Command Reference

CLI flags (init, run, view, inspect, metrics, audit, doctor, backup, restore, merge) & Git Scanner.

⏱️ Sessions, Snapshots & SDD

Session Lifecycle, Event Audit Trail, Snapshots, Trajectories, Sub-directory support & Spec-Driven Development.

🧰 Tools, Resources & Prompts

Complete reference for all 13 Consolidated MCP Tools, read-only state-memory:/// Resources, and Prompt templates.

πŸ“˜ 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 tools
get_analyticsA
Read-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_eventsA
Read-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_dataA
Destructive

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_databaseA
Destructive

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_edgesA
Destructive

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_nodesA
Destructive

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_snapshotsA
Destructive

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_graphA
Read-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_diagnosticsA
Destructive

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_blackboardA
Destructive

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

    A3.7/5.0

    Scored across 13 tools

    Disambiguation3/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      3
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP 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.
      9
      93
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP memory server that gives AI assistants durable project memory across coding sessions, storing context, changes, and decisions.
      1
      MIT