# State Memory MCP

> State Memory MCP is an open-source MCP server for knowledge and memory. Local SQLite task and decision graph that gives coding agents persistent memory. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, macOS, Windows, Linux
- **Website:** https://statememorymcp.com
- **Repository:** https://github.com/putervision/state-memory-mcp
- **MCP Registry name:** io.github.putervision/state-memory-mcp
- **Categories:** knowledge and memory, developer tools
- **Listing updated:** 2026-11-16

## About

Instead of keeping project history in the chat window, this server stores tasks, design decisions, blockers and artifacts as nodes and typed edges in a SQLite file inside the workspace (`.state-memory-mcp/graph.db`). Links such as depends_on, blocks, produces and satisfies are checked for cycles, and an agent can ask for the next unblocked task or a small scoped slice of context rather than rereading old conversation.

The README describes 13 consolidated tools covering node and edge management, a dependency-ordered work queue, session tracking, spec ingestion from Markdown PRDs, OpenSpec and Gherkin files, analytics, a SHA-256 hash-chained event ledger and diagnostics with auto-repair. A `view` command opens a browser-based 3D graph of the project.

It is run locally over stdio after an npm install, and `init` scaffolds MCP configuration and instructions for editors such as Cursor, Claude Code, VS Code and Windsurf. The README states that all state stays in the project folder and that no LLM is involved in memory operations. Latency figures quoted on the site (67 to 74 percent) are the vendor's own claims.

## Features

- **Persistent task graph:** Tracks tasks, decisions, artifacts and blockers as linked nodes in a project-local SQLite database.
- **Dependency work queue:** Returns unblocked tasks in topological order and rejects cyclic links.
- **Spec ingestion:** Parses Markdown PRDs, OpenSpec and Gherkin feature files and checks for drift against them.
- **Tamper-evident ledger:** Hash-chains every mutation so the event history can be verified.
- **Full-text search:** Finds nodes with FTS5 and TF-IDF search rather than vector embeddings.
- **3D graph viewer:** Opens a WebGL force-directed view of the project graph in the browser.
- **Branch awareness:** Keeps state aware of the current Git branch.

## Good for

- Keep a coding agent on track across many sessions on one codebase
- Record architectural decisions so later sessions do not repeat them
- Break a PRD into tasks and verify acceptance criteria as work finishes
- Let parallel subagents share task and blocker state
- Audit what an agent changed and when

## Install

### Claude Code (Terminal)

```sh
claude mcp add state-memory-mcp -- npx -y @putervision/state-memory-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "state-memory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@putervision/state-memory-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "state-memory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@putervision/state-memory-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "state-memory-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@putervision/state-memory-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "state-memory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@putervision/state-memory-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "state-memory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@putervision/state-memory-mcp"
      ]
    }
  }
}
```

## Tools

- `manage_nodes`: Node CRUD, full-text and TF-IDF search, batch mutations, observation notes and decision logging.
- `manage_edges`: Typed dependency links between nodes, including visual state linking.
- `manage_tasks`: Dependency-ordered work queue with blocker detection and task completion.
- `manage_sessions`: Agent attribution, turn tracking and context bootstrap.
- `manage_specs`: PRD and RFC parsing, requirement decomposition and acceptance verification.
- `get_analytics`: Velocity, burndown, token ROI, cognitive load and critical path.
- `get_events`: Reads the SHA-256 tamper-evident event ledger.
- `run_diagnostics`: DAG validation, health checks and reference integrity checks.

## FAQ

### How is state stored?

In a SQLite database at .state-memory-mcp/graph.db inside your project; the README says nothing leaves your machine.

### How do I install it?

Run npm install -g @putervision/state-memory-mcp, then state-memory-mcp init in your project and restart your editor. Node.js 18.18 or newer is required.

### Does it use an LLM or vector database?

The README says memory operations run with no LLM in the loop, using SQL graph traversal plus FTS5 and TF-IDF search.

### Which editors does it support?

The init command scaffolds configuration for Cursor, Claude Code, VS Code and Windsurf, and the docs also mention Gemini and Copilot.

### Is State Memory MCP free?

Yes. State Memory MCP is open source, so you can use and self-host it for free.

### How do I add State Memory MCP to Claude Code?

Run this command in your terminal: claude mcp add state-memory-mcp -- npx -y @putervision/state-memory-mcp

### What are the best alternatives to State Memory MCP?

The closest alternatives to State Memory MCP are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/state-memory-mcp
