utenadev/memory-mcp-server

Memory MCP Server

A Go implementation of a Model Context Protocol (MCP) server that provides persistent memory storage for AI applications.

Overview

This MCP server enables AI applications to save, retrieve, update, and delete memory entries in a persistent storage system (JSON or SQLite). It is designed based on clean architecture principles and follows Go best practices.

Features

• Persistent Memory Storage: Persists memory using either JSON files or a SQLite database.
• Dynamic Storage Selection: Automatically selects the storage backend (JSON/SQLite) based on the file extension of the path provided at startup.
• Full CRUD Operations: Create, read, update, and delete memory entries.
• Thread-Safe: Protects concurrent access using mutexes.
• Clean Architecture: Modular design with separation of concerns.
• MCP Compliant: Implements the Model Context Protocol specification.
• Cross-Platform: Supports builds for Windows, Linux, and macOS.

Architecture

The project follows a clean and modular architecture:

memory-mcp/
├── cmd/
│   └── memory-mcp/
│       └── main.go           # Application entry point
├── internal/
│   ├── handler/
│   │   └── memory_handler.go # MCP request handler
│   └── storage/
│       ├── store.go          # Storage interface
│       ├── json_store.go     # JSON storage implementation
│       └── sqlite_store.go   # SQLite storage implementation
├── go.mod
├── go.sum
└── memory.json              # Storage file (default, auto-generated)

Installation

Prerequisites

• Go 1.21 or later
• Git
• C compiler (if using SQLite)

Building from Source

# Clone the repository
git clone <repository-url>
cd memory-mcp

# Download dependencies
go mod tidy

# Build the server (dynamically linked)
go build -o memory-mcp-server ./cmd/memory-mcp

# Build the server (statically linked for cross-platform)
CGO_ENABLED=0 go build -o memory-mcp-server -ldflags="-s -w" -trimpath ./cmd/memory-mcp

# For Windows
# Static build
CGO_ENABLED=0 go build -o memory-mcp-server.exe -ldflags="-s -w" -trimpath ./cmd/memory-mcp

Usage

Running the Server

By default, the server starts in stdio mode using memory.json.

# Run the server with the default JSON store
./memory-mcp-server

# For Windows
./memory-mcp-server.exe

You can specify the location and type of storage file using the --storage-path flag.

# Run the server using SQLite
./memory-mcp-server --storage-path /path/to/memory.db

# Specify a JSON file in a different location
./memory-mcp-server --storage-path /data/memory_store.json

The server will start in stdio mode and wait for an MCP client connection.

Available Tools

The server provides the following MCP tools:

list_memory

Lists all saved memories.

Parameters: None

Example Response:

{
  "1234567890": "This is a sample memory",
  "1234567891": "Another memory entry"
}

create_memory

Creates a new memory entry.

Parameters:

• content (string, required): The information to remember.

Returns: The memory ID of the created entry.

read_memory

Retrieves a specific memory by its ID.

Parameters:

• id (string, required): The ID of the memory to retrieve.

Returns: The content of the memory.

update_memory

Updates an existing memory entry.

Parameters:

• id (string, required): The ID of the memory to update.
• content (string, required): The new content for the memory.

Returns: A confirmation message.

delete_memory

Deletes a memory entry by its ID.

Parameters:

• id (string, required): The ID of the memory to delete.

Returns: A confirmation message.

Configuration

The server's behavior can be configured through command-line flags.

• --storage-path: Specifies the path to the storage file.
  • Default: memory.json
  • Behavior:
    • If the path ends with .db, .sqlite, or .sqlite3, the SQLite store will be used.
    • If the path ends with .json or has any other extension, the JSON store will be used.
  • Examples:
    • memory.db -> SQLite
    • data.json -> JSON
    • archive.dat -> JSON (default)

If the directory for the specified path does not exist, it will be created automatically.

Development

Project Structure

• cmd/memory-mcp/main.go: Application entry point and MCP server setup.
• internal/handler/: MCP request handlers and business logic.
• internal/storage/: Storage interface and implementations.
• internal/storage/store.go: Defines the Store interface.
• internal/storage/json_store.go: JSON file storage implementation.
• internal/storage/sqlite_store.go: SQLite database storage implementation.

Adding a New Storage Backend

To add a new storage backend:

1. Implement the storage.Store interface.
2. Update the initializeStore function in cmd/memory-mcp/main.go to instantiate the new implementation under the appropriate conditions.
3. The interface provides:
   • Get(id string) (string, error)
   • Set(id, content string) error
   • Delete(id string) error
   • GetAll() (map[string]string, error)
   • Close() error

Testing

# Run tests
go test ./...

# Run tests with coverage
go test -cover ./...

Dependencies

• mcp-go v0.36.0 - Go implementation of the Model Context Protocol.

License

This project is open source. See the LICENSE file for details.

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Implement your changes.
4. Add tests where applicable.
5. Submit a pull request.

Troubleshooting

Common Issues

1. Build fails with "ar archive" error:

   • Ensure cmd/memory-mcp/main.go contains the correct main package code.
   • Check that the file has not been accidentally replaced with other content.

2. Permission denied on execution:

   • Make sure the executable has the proper permissions: chmod +x memory-mcp-server.

3. Memory file access errors:

   • Ensure the directory is writable.
   • Check the file permissions of memory.json.

Debug Mode

For debugging, you can add more detailed logging by changing the log level in the source code.

Support

For issues or questions:

1. Review the troubleshooting section above.
2. Check the MCP specification.
3. Consult the mcp-go documentation.
4. Create an issue in the repository.