State Memory MCP

Name: State Memory MCP
Author: PuterVision

Local SQLite graph of tasks, decisions and blockers that coding assistants keep across sessions

By PuterVision TypeScript Local · stdio Knowledge and memory Productivity Developer tools

GitHub npm Website

38 popularity score ★ 41 ↓ 176/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server.

Or add it by command or config

FirstTerminal

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

Claude CodeTerminal

claude mcp add state-memory -- state-memory-mcp run

Claude Desktopclaude_desktop_config.json

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

Cursor~/.cursor/mcp.json

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

VS Code.vscode/mcp.json

{
  "servers": {
    "state-memory": {
      "type": "stdio",
      "command": "state-memory-mcp",
      "args": [
        "run"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.state-memory]
command = "state-memory-mcp"
args = ["run"]

Gemini CLITerminal

gemini mcp add --scope user state-memory state-memory-mcp -- run

Settings 11

`STATE_MEMORY_MCP_PROJECT`	Optional: Project slug to use; worked out from the project folder when unset.
`STATE_MEMORY_MCP_DIR`	Optional: Absolute path for the database files; defaults to .state-memory-mcp/ in the project.
`STATE_MEMORY_READ_ONLY`	Optional: true blocks all graph changes (same as --read-only).
`STATE_MEMORY_AUDIT_ONLY`	Optional: true allows only health and verification tools (same as --audit-only).
`STATE_MEMORY_ADMIN_MODE`	Optional: true enables privileged actions such as prune_events (same as --admin).
`STATE_MEMORY_ENCRYPTION_KEY`	Optional: Key for AES-256-GCM encryption of metadata at rest; plaintext when unset.
`STATE_MEMORY_MAX_DB_BYTES`	Optional: Database size at which writes are refused; 104857600 (100 MB) by default.
`STATE_MEMORY_WEBHOOK_URL`	Optional: Endpoint that receives an HTTP POST on each state change; off when unset.
`STATE_MEMORY_WEBHOOK_SECRET`	Optional: Sent as a Bearer token with webhook calls.
`STATE_MEMORY_COMPAT`	Optional: true accepts the old v0.10 tool names.
`STATE_MEMORY_LOG_LEVEL`	Optional: stderr log level: debug, info, warn or error; info by default.

What it does

State Memory MCP keeps a project's working state in a SQLite database inside the project folder (`.state-memory-mcp/` by default) so a coding assistant can pick up where it left off instead of rescanning files. The state is a graph: nodes such as tasks, decisions, plans, artifacts and blockers, joined by typed edges. The assistant can ask for the next unblocked task, trace what depends on what, record why a choice was made, and mark work done. No model is called for any of this; lookups are plain graph queries plus full-text (FTS5) and TF-IDF search.

Around that core sit snapshots with undo and revert, an append-only event log chained with SHA-256 hashes, analytics such as velocity, burndown and critical path, spec ingestion that turns a PRD or Gherkin file into tasks and acceptance criteria, a shared notice board for parallel agents, and export to JSON, DOT, Mermaid, HTML or GitHub/Jira issue JSON. The same package is also a CLI with a browser-based 3D graph viewer.

The 13 tools each take an `action` argument, so the real surface is much wider than the tool count: `manage_nodes` alone has nine actions. The `run` command, the default, accepts `--read-only`, `--audit-only` and `--admin` flags that match the `STATE_MEMORY_READ_ONLY`, `STATE_MEMORY_AUDIT_ONLY` and `STATE_MEMORY_ADMIN_MODE` settings (src/cli.ts at v1.4.1). The `raw` action of `query_graph` runs SQL on a read-only connection, accepts only a single SELECT or WITH statement over the server's own tables, and caps results at 500 rows by default (src/engine/query-raw.ts at v1.4.1).

What it needs

Runtime	Node.js 18+

Node.js 18.18.0 or later. The docs install the package globally with `npm install -g @putervision/state-memory-mcp`; running `state-memory-mcp init` in a project folder is optional and sets up the data folder and client configs. No account or API key. Git history is read by `init` when the folder is a git repository.

Limits

State lives per project in a local SQLite file; nothing syncs between machines except by backup, merge or committing the file yourself. Writes are refused once the database reaches `STATE_MEMORY_MAX_DB_BYTES` (100 MB by default). Pruning the event log (`run_diagnostics` action `prune_events`) works only with `STATE_MEMORY_ADMIN_MODE=true` or `--admin`. Raw SQL through `query_graph` is read-only and returns at most 500 rows unless a different limit is passed. Tool names changed in v1.0; older v0.10 names work only with `STATE_MEMORY_COMPAT=true`. The memory is task and decision state for a project, not free-form recall of facts about a user.

Who it suits

Suits developers who run long, multi-session work with Cursor, Claude Code, VS Code, Windsurf or similar and want the assistant to keep a structured task list, decision record and blocker list on their own disk, with no account and no outside service. It fits teams using spec-driven development or several agents in parallel, since specs, acceptance criteria and a shared notice board are built in. Pick something else if you want general memory of conversations or personal facts, or a hosted store shared across machines. Its maker also publishes Visual Memory MCP (@putervision/vision-memory-mcp), which its README names as a companion for caching visual state rather than a replacement.

Tools 13

manage_nodes: Create, update, fetch, list, delete and search graph nodes, in batches too, and attach notes
manage_edges: Add or remove typed links between nodes and link a node to visual state
manage_sessions: Start, end and list agent sessions and load starting context
manage_tasks: Return the next ready task, complete tasks, find blocked, stale or similar blockers, prune old tasks
manage_snapshots: Save checkpoints, compare them, view history, revert or undo changes
manage_specs: Scaffold or ingest specs, split features into tasks, verify criteria and report coverage
manage_database: Back up, restore, integrity-check and merge the database, and diff or merge state across git branches
manage_data: Export the graph, issues or trajectories and import graphs, issues or specs in bulk
query_graph: Fetch a neighbourhood, trace dependencies, run read-only SELECT queries or plain-language queries
get_analytics: Summaries, velocity, burndown, critical path, decision trails and contradiction checks
get_events: Read the event log, build a changelog or a session post-mortem
run_diagnostics: Validate the graph, check file references, verify the hash chain, compact, archive or prune
use_blackboard: Post and read expiring notices shared between agents

Popularity

38 popularity score, on our list (the bar is 36)

★ 41 ↓ 176/wk

GitHub stars	41	19.5 points
Stars in 30 days	+0	0 points
npm downloads, last week	176	18 points

Measured 2026-11-07. How the score works.

Where it is published

Code	putervision/state-memory-mcp ★ 41
npm	@putervision/state-memory-mcp 1.4.1, 2026-10-03

What it can reach

Runs	On your machine
Reaches	Files on your machine, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	MIT (npm)
Last code change	2026-10-03

Runs on your machine over stdio with no sign-in. It writes a SQLite database under .state-memory-mcp/ in the project unless STATE_MEMORY_MCP_DIR points elsewhere; metadata is stored in plaintext unless STATE_MEMORY_ENCRYPTION_KEY is set. Several actions take file paths from the assistant: spec ingest and import read a file, backup writes one, restore and merge replace or merge the database from one, and spec scaffolding creates files under .specs/. `init` also edits .gitignore and writes client config and agent-instruction files into the project. Network use is off by default: it posts state changes only when STATE_MEMORY_WEBHOOK_URL is set, and refuses private-network webhook targets unless STATE_MEMORY_ALLOW_PRIVATE_WEBHOOKS is true. --read-only and --audit-only narrow what tools may do.

Over time

GitHub stars 41 −70 (−63 %)

11139

8 Oct 20267 Nov 2026

npm downloads a week 176 −732 (−81 %)

14k77

3 Aug 20267 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 38 −19 (−34 %)

5619

8 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![State Memory MCP on EveryMCPServer](https://everymcpserver.com/badge/state-memory-mcp.svg)](https://everymcpserver.com/servers/state-memory-mcp)

Connect your client

Add in one click

Or add it by command or config

Settings 11

What it does

What it needs

Limits

Who it suits

Tools 13

Similar servers

vision-memory-mcp

codebase-memory-mcp

Engram

marm-memory

Signet

Memorix