memory-mcp

mhv2109/memory-mcp

3.2

If you are the rightful owner of memory-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server implementation in Go with persistent knowledge graph storage.

Tools
11
Resources
0
Prompts
0

memory-mcp

A Model Context Protocol (MCP) server implementation in Go with persistent knowledge graph storage.

Overview

memory-mcp is an MCP server that exposes tools and resources to MCP clients like Claude. The server communicates using JSON-RPC 2.0 over stdio, following the MCP protocol specification. It includes a SQLite-backed knowledge graph for persistent memory storage. It is based on the Knowledge Graph Memory Server.

I built this project to better familiarize myself with MCP by developing a server with mark3labs/mcp-go using tools like Claude Code and Serena.

Features

MCP Tools

The server provides 11 tools for managing a knowledge graph with structured input schemas and type validation:

  • create_entities: Create multiple new entities in the knowledge graph
  • create_relations: Create multiple new relations between entities in the knowledge graph
  • add_observations: Add new observations to existing entities in the knowledge graph
  • delete_entities: Delete multiple entities and their associated relations from the knowledge graph
  • delete_observations: Delete specific observations from an entity in the knowledge graph
  • delete_relations: Delete multiple relations from the knowledge graph
  • read_graph: Read the entire knowledge graph including all entities, their observations, and relations
  • search_entities_by_observation: Search for entities in the knowledge graph by observation based on a query string, retrieving their details and direct relations
  • get_entities: Open specific entities by their names, retrieving their details and direct relations
  • list_entity_names: List the names of all entities in the knowledge graph
  • list_entity_types: List all unique entity types in the knowledge graph

Requirements

  • Go 1.25.1 or later
  • golangci-lint for code quality checks.
  • goreleaser for building and releasing.
  • sqlc for generating Go from SQL queries.
  • goose for managing SQL schema.

Installation

go mod download

Usage

Run the MCP server:

go run .

Or specify a custom database path:

go run . -memory-file-path=/path/to/database.db

The server will:

  1. Initialize the SQLite database at the specified path (default: memory.db)
  2. Run database migrations to create the knowledge graph schema
  3. Start the MCP server on stdio

Note: Now uses the modernc.org/sqlite pure Go driver, eliminating the need for CGO and FTS5 build tags.

Troubleshooting and Testing with MCP Inspector

The MCP Inspector is an interactive developer tool for testing MCP servers. It provides a web-based UI to explore tools, test tool calls, and debug server responses.

Run the server with MCP Inspector:

npx @modelcontextprotocol/inspector go run . -memory-file-path=":memory:"

This will:

  1. Start the MCP Inspector web interface (usually at http://localhost:5173)
  2. Launch your MCP server with an in-memory database (no persistence)
  3. Allow you to interactively test all 11 knowledge graph tools
  4. View JSON-RPC messages, responses, and errors in real-time

Debug Mode with Traffic Logging

For advanced debugging and protocol analysis, use the debug_stdio.sh script to capture all MCP traffic:

./debug_stdio.sh

What it does:

  • Captures all communication: Logs both client→server and server→client JSON-RPC messages
  • Preserves stderr: Captures server logs separately for debugging
  • Uses in-memory database: Runs with :memory: for fast, ephemeral testing
  • Timestamped logs: Creates unique log files with timestamps to avoid conflicts

Generated log files:

  • /tmp/client_to_server_YYYYMMDD_HHMMSS.log - Messages sent to the server
  • /tmp/server_to_client_YYYYMMDD_HHMMSS.log - Responses from the server
  • /tmp/mcp_stderr_YYYYMMDD_HHMMSS.log - Server error output and logs

Use cases:

  • Protocol debugging: Examine raw JSON-RPC message flow
  • Performance analysis: Measure response times and message sizes
  • Error investigation: Correlate client requests with server errors
  • Development: Understand exactly what data is being exchanged

Example workflow:

  1. Run ./debug_stdio.sh in one terminal
  2. In another terminal, use an MCP client (like Claude or MCP Inspector) to connect
  3. Perform the operations you want to debug
  4. Exit the debug session (Ctrl+C) to see log file locations
  5. Examine the captured traffic to debug issues

The script automatically cleans up temporary pipes and reports log file locations when you exit.

Development

Building

Local Development Build

Build the project:

go build

Then run:

./memory-mcp
Releasing Cross-platform Builds with GoReleaser

This project uses GoReleaser for cross-platform builds and releases.

Prerequisites:

Local testing:

# Validate configuration
goreleaser check

# Build for all platforms (snapshot)
goreleaser build --snapshot --clean

# Test built binaries
./dist/memory-mcp_linux_amd64_v1/memory-mcp -help
./dist/memory-mcp_darwin_arm64_v8.0/memory-mcp -help
./dist/memory-mcp_windows_amd64_v1/memory-mcp.exe -help

Creating releases:

# Tag a release (use Conventional Commits format)
git tag v1.0.0
git push origin v1.0.0

# Build and publish release (requires GITHUB_TOKEN)
export GITHUB_TOKEN="your-token"
goreleaser release --clean

Commit Message Format: Use Conventional Commits for all commit messages:

  • feat: add new feature (triggers MINOR version bump)
  • fix: resolve bug (triggers PATCH version bump)
  • feat!: breaking change or BREAKING CHANGE: footer (triggers MAJOR version bump)
  • Other types: docs:, test:, refactor:, chore:, ci:, build:, perf:

Examples:

git commit -m "feat: add search_entities_by_observation tool"
git commit -m "fix: resolve database connection leak"
git commit -m "docs: update README with conventional commits guidance"
git commit -m "feat!: change tool parameter names

BREAKING CHANGE: tool parameter 'query' renamed to 'searchQuery'"

Testing

Run all tests (including integration tests):

go test -v ./...

Run only unit tests (skip integration tests):

go test -short -v ./...

Code Quality

Format code:

go fmt ./...

Lint code:

golangci-lint run

Working with SQL

This project uses sqlc for type-safe SQL query generation. SQL queries are defined in sql/queries/ and the database schema is defined by Goose migrations in sql/migrations/.

Generate Go code from SQL queries:

go run github.com/sqlc-dev/sqlc/cmd/sqlc@latest generate

After modifying SQL queries or migrations, regenerate the code and run tests to ensure everything still works.

Dependency Management

Tidy dependencies:

go mod tidy

Project Structure

memory-mcp/
├── main.go                    # MCP server implementation
├── sql.go                     # Repository struct and database migrations
├── tools.go                   # Service struct with MCP tool handlers
├── tools_test.go              # Unit tests for all MCP tools
├── migrations_test.go         # Database migration tests
├── integration_test.go        # Integration tests (subprocess-based)
├── sql/                       # SQL files
│   ├── migrations/            # Goose migration files
│   │   └── 00001_initial_schema.sql
│   └── queries/               # sqlc query files
│       ├── entities.sql       # Entity queries
│       ├── observations.sql   # Observation queries
│       └── relations.sql      # Relation queries
├── internal/
│   └── dbstore/               # Generated sqlc code (do not edit)
├── sqlc.yaml                  # sqlc configuration
├── go.mod                     # Go module definition
├── go.sum                     # Dependency checksums
├── tmp/                       # Temporary files (schema reference)
│   └── schema.sql             # SQLite schema documentation
├── CLAUDE.md                  # Documentation for Claude Code
└── README.md                  # This file

License

[Add your license here]