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

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

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

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

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

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

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

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

# 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

{
  "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.