Memory MCP Server

Memory MCP

A SQLite-backed MCP server for persistent memory storage, full-text retrieval, and relationship graph traversal.

Overview

Memory MCP provides a local, persistent memory layer for MCP-enabled assistants. It stores SHA-256-addressed memory items in SQLite with FTS5-powered full-text search, a directed relationship graph, BFS recall traversal, and token-budget-aware context retrieval — all accessible over stdio transport with no external dependencies.

Key Features

• 13 MCP tools for CRUD, batch operations, FTS5 search, BFS graph recall, token-budget context retrieval, relationships, and stats.
• Full-text search over content and tags via SQLite FTS5 with importance and type filters.
• Graph recall with BFS traversal, bounded frontier, and MCP progress notifications per hop.
• Token-budget retrieval (retrieve_context) selects memories that fit a caller-specified token budget — no manual pagination needed.
• Strict Zod input validation with typed output envelopes and SHA-256 hash addressing.
• Resource support with internal://instructions (Markdown guide) and memory://memories/{hash} URI template with hash auto-completion.
• stdio transport with clean shutdown handling (SIGINT, SIGTERM) and no HTTP endpoints. |

Requirements

• Node.js >=24.
• SQLite with FTS5 support (verified at startup).
• Any MCP client that supports stdio command servers.

Quick Start

Use the npm package directly with npx — no installation required:

{

"mcpServers": { "memory-mcp": { "command": "npx", "args": ["-y", "@j0hanz/memory-mcp@latest"] } } }

[!TIP]

The server uses stdio transport only; no HTTP endpoint is exposed. Stdout must not be polluted by custom logging.

Or run with Docker:

docker run --rm -i ghcr.io/j0hanz/memory-mcp:latest

Client Configuration

Install in VS Code

Workspace file .vscode/mcp.json:

{

"servers": { "memory-mcp": { "command": "npx", "args": ["-y", "@j0hanz/memory-mcp@latest"] } } }

CLI:

code --add-mcp '{"name":"memory-mcp","command":"npx","args":["-y","@j0hanz/memory-mcp@latest"]}'

Install in VS Code Insiders

CLI:

code-insiders --add-mcp '{"name":"memory-mcp","command":"npx","args":["-y","@j0hanz/memory-mcp@latest"]}'

Install in Cursor

~/.cursor/mcp.json:

{

"mcpServers": { "memory-mcp": { "command": "npx", "args": ["-y", "@j0hanz/memory-mcp@latest"] } } }

Install in Claude Desktop / Claude Code

claude_desktop_config.json:

{

"mcpServers": { "memory-mcp": { "command": "npx", "args": ["-y", "@j0hanz/memory-mcp@latest"] } } }

CLI:

claude mcp add memory-mcp -- npx -y @j0hanz/memory-mcp@latest

Install in Windsurf

MCP config:

{

"mcpServers": { "memory-mcp": { "command": "npx", "args": ["-y", "@j0hanz/memory-mcp@latest"] } } }

Run with Docker

# Pull and run (stdio mode)

docker run --rm -i \ -e MEMORY_DB_PATH=/data/memory.db \ -v memory-data:/data \ ghcr.io/j0hanz/memory-mcp:latest

MCP client config:

{

"mcpServers": { "memory-mcp": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "MEMORY_DB_PATH=/data/memory.db", "-v", "memory-data:/data", "ghcr.io/j0hanz/memory-mcp:latest" ] } } }

Documentation Maintenance

• Owner: maintainers updating MCP behavior in src/ must update README.md and affected mcp/ mirror pages in the same PR.
• Link/version policy: use pinned https://modelcontextprotocol.io/specification/2025-11-25/... links for protocol references; avoid latest and mixed legacy targets.
• Drift-check checklist:
• Re-verify capability declarations in src/server.ts.
• Reconcile tool/resource/prompt docs with src/tools/index.ts, src/resources/index.ts, and src/prompts/index.ts.
• Confirm limitations/gotchas in src/instructions.md match runtime behavior.
• Validation commands: npm run type-check, npm run test:fast, npm run build.

MCP Surface

Tools Summary

---

store_memory

Store a new memory with content, tags, and optional type/importance. Idempotent — storing the same content+tags returns the existing hash with created: false.

Returns: { hash, created }

---

store_memories

Store multiple memories in one transaction (max 50 items).

Returns: { items, succeeded, failed }

---

get_memory

Retrieve one memory by its SHA-256 hash.

Returns: Memory or { ok: false, error } on E_NOT_FOUND.

---

update_memory

Update content and optionally tags for an existing memory. Returns both hashes.

Returns: { old_hash, new_hash }

---

delete_memory

Delete one memory by hash. Cascades to related relationship rows.

Returns: { hash, deleted }

---

delete_memories

Delete multiple memories by hash in one transaction.

Returns: { items, succeeded, failed }

---

search_memories

Full-text search over memory content and tags using FTS5. Supports importance and type filters with cursor pagination.

| min_importance | integer | No | — | Only return memories