Memory Graph MCP Server

December 20, 2025 · View on GitHub

Note, this is somewhat superceded by Knowledge Graph - I hope you take a chance to check it out!

An MCP server that provides persistent memory capabilities through a local knowledge graph implementation. This server enables AI assistants to maintain context and information across chat sessions using a graph-based storage system.

Features

Domain-based memory organization for context isolation
Store and retrieve memories with content, tags, and metadata
Cross-domain memory references with relationship tracking
Memory domain transfer capability
Multiple storage backends (JSON, SQLite, and MariaDB)
Multiple transport protocols (STDIO and HTTP)
Full-text search capabilities with SQL-based storage backends
Advanced content search with fuzzy matching and regex support
Combine multiple search strategies (content, path, tags)
Flexible result sorting and relevance scoring
Graph traversal across domains and relationships
Mermaid graph visualization for memory connections
Docker and Docker Compose support

Documentation

Getting Started

Getting Started Guide - Quick setup and basic usage guide
Use Cases - Examples of how to use Memory Graph in real-world scenarios
Configuration - Comprehensive configuration options

Features

Storage Overview - Overview of storage backends
Transport Overview - Overview of transport types

Core Concepts

Memory Architecture - Domain-based memory system
Graph Model - Graph data model explanation

Reference

Memory Tools Reference - Comprehensive tool documentation
Database Schemas - Technical reference for database schemas

Developer Documentation

Architecture - System architecture and design patterns
Contributing - Contributing guidelines
Testing - Testing strategy

Installation

Local Installation

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Clean build directory
npm run clean

Docker Installation

The server is available as a Docker container from GitHub Container Registry:

# Pull the image
docker pull ghcr.io/aaronsb/memory-graph:latest

# Or build locally
./scripts/build-local.sh

Usage

Docker Usage

Run the container with your desired configuration:

# Using STDIO transport (default)
docker run -v /path/to/data:/app/data \
  -e MEMORY_DIR=/app/data \
  -e TRANSPORT_TYPE=STDIO \
  -e STORAGE_TYPE=sqlite \
  ghcr.io/aaronsb/memory-graph:latest

# Using HTTP transport
docker run -v /path/to/data:/app/data \
  -e MEMORY_DIR=/app/data \
  -e TRANSPORT_TYPE=HTTP \
  -e PORT=3000 \
  -e HOST=127.0.0.1 \
  -p 3000:3000 \
  ghcr.io/aaronsb/memory-graph:latest

# Using MariaDB storage
docker run -v /path/to/data:/app/data \
  --network=host \
  -e MEMORY_DIR=/app/data \
  -e STORAGE_TYPE=mariadb \
  -e MARIADB_HOST=localhost \
  -e MARIADB_PORT=3306 \
  -e MARIADB_USER=memory_user \
  -e MARIADB_PASSWORD=secure_password \
  -e MARIADB_DATABASE=memory_graph \
  ghcr.io/aaronsb/memory-graph:latest

Docker Compose

For convenience, a Docker Compose configuration is provided:

# Start with Docker Compose
docker-compose up -d

# Stop services
docker-compose down

Local Usage

# Start the server
npm start

# Run using custom configuration
MEMORY_DIR=/path/to/data STORAGE_TYPE=sqlite npm start

Configuration

The server can be configured using environment variables:

General Configuration

MEMORY_DIR: Directory to store memory files (default: ./data)
MEMORY_FILES: Comma-separated list of specific memory files to use
LOAD_ALL_FILES: Set to 'true' to load all JSON files in the storage directory
DEFAULT_PATH: Default path for storing memories
STRICT_MODE: Set to 'true' to ensure all logging goes to stderr, preventing interference with JSON-RPC communication on stdout

Storage Configuration

STORAGE_TYPE: Storage backend to use (json, sqlite, or mariadb, default: json)

MariaDB Configuration (when using `STORAGE_TYPE=mariadb`)

MARIADB_HOST: Database server hostname (default: localhost)
MARIADB_PORT: Database server port (default: 3306)
MARIADB_USER: Database username (default: root)
MARIADB_PASSWORD: Database password (default: empty)
MARIADB_DATABASE: Database name (default: memory_graph)
MARIADB_CONNECTION_LIMIT: Maximum number of connections in the pool (default: 10)

Transport Configuration

TRANSPORT_TYPE: Communication transport to use (STDIO or HTTP, default: STDIO)
PORT: Port number for HTTP transport (required when TRANSPORT_TYPE=HTTP)
HOST: Host address for HTTP transport (default: 127.0.0.1, only used when TRANSPORT_TYPE=HTTP)

MCP Configuration

To use this server with an AI assistant via MCP, add it to your MCP configuration file:

STDIO Transport (Default)

{
  "mcpServers": {
    "memory-graph": {
      "command": "node",
      "args": ["/path/to/memory-graph/build/index.js"],
      "env": {
        "MEMORY_DIR": "/path/to/memory/storage",
        "STORAGE_TYPE": "sqlite",
        "STRICT_MODE": "true"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

HTTP Transport

{
  "mcpServers": {
    "memory-graph": {
      "command": "node",
      "args": ["/path/to/memory-graph/build/index.js"],
      "env": {
        "MEMORY_DIR": "/path/to/memory/storage",
        "STORAGE_TYPE": "sqlite",
        "TRANSPORT_TYPE": "HTTP",
        "PORT": "3000",
        "STRICT_MODE": "true"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Docker with MariaDB

{
  "mcpServers": {
    "memory-graph": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=host",
        "-v", "/path/to/data:/app/data",
        "-e", "MEMORY_DIR=/app/data",
        "-e", "STORAGE_TYPE=mariadb",
        "-e", "MARIADB_HOST=localhost",
        "-e", "MARIADB_PORT=3306",
        "-e", "MARIADB_USER=memory_user",
        "-e", "MARIADB_PASSWORD=secure_password",
        "-e", "MARIADB_DATABASE=memory_graph",
        "-e", "STRICT_MODE=true",
        "ghcr.io/aaronsb/memory-graph:latest"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Storage Options

The Memory Graph MCP supports three storage backends:

JSON: Simple file-based storage (default)
- One JSON file per domain in the memories/ directory
- Good for smaller datasets and simple deployments
- Easy to inspect and manually edit if needed
SQLite: Database storage with improved performance
- Single SQLite database file for all domains
- Better performance for large datasets
- Full-text search capabilities
- More efficient memory usage
- Good for local deployments
MariaDB: Production-ready database storage
- Uses a MariaDB/MySQL database server
- Ideal for large-scale deployments
- Full-text search capabilities
- Better scalability and concurrency support
- Suitable for deployments with high load or multiple concurrent users

To switch between storage types, set the STORAGE_TYPE environment variable to json, sqlite, or mariadb.

For detailed information about storage options, including how to convert between formats, see Storage Overview and Converting Between Storage Types.

Available Memory Tools

The Memory Graph MCP provides the following tools:

Domain Management

select_domain: Switch to a different memory domain
list_domains: List all available memory domains
create_domain: Create a new memory domain

Memory Operations

store_memory: Store new information in the memory graph
recall_memories: Retrieve memories using various strategies
edit_memory: Edit an existing memory or move it to another domain
forget_memory: Remove a memory from the graph

Visualization

generate_mermaid_graph: Generate a visual representation of memory relationships

Search

search_memory_content: Full-text search capabilities (with SQLite and MariaDB backends)
traverse_memories: Explore connections between memories across domains

For detailed information about all tools and their parameters, see the Memory Tools Reference.

Project Structure

memory-graph/
├── src/
│   ├── graph/           # Knowledge graph implementation
│   ├── storage/         # Storage backends (JSON, SQLite, MariaDB)
│   ├── tools/           # MCP tool implementations
│   ├── types/           # TypeScript type definitions
│   └── index.ts         # Main server entry
├── data/                # Memory storage (created at runtime)
└── docs/                # Project documentation

Development

Building

# Build the TypeScript code
npm run build

# Build local Docker image
./scripts/build-local.sh

Testing

# Run all tests
npm test

# Run tests in watch mode
npm test:watch

Converting Between Storage Types

# Convert from JSON to SQLite
npx ts-node scripts/convert-storage.ts json2sqlite /path/to/json/data /path/to/sqlite/file.db

# Convert from SQLite to JSON
npx ts-node scripts/convert-storage.ts sqlite2json /path/to/sqlite/file.db /path/to/json/data

# Convert from JSON to MariaDB
npx ts-node scripts/convert-storage.ts json2mariadb /path/to/json/data "mariadb://user:password@localhost:3306/memory_graph"

License

MIT