Memory MCP Server (Go)

Memory MCP Server (Go)

A Model Context Protocol server that provides knowledge graph management capabilities. This server enables LLMs to create, read, update, and delete entities and relations in a persistent knowledge graph, helping AI assistants maintain memory across conversations. This is a Go implementation of the official TypeScript Memory MCP Server.

Features

• High-Performance Storage: SQLite backend with WAL mode, read/write connection separation for concurrent access
• Knowledge Graph Management: Persistent graph of entities, relationships, and observations
• Advanced Search: FTS5 full-text search with BM25 ranking, synonym expansion, and time-decay scoring
• Graph Traversal: Search results include 1-hop related entities for richer context
• Entity Management: Merge duplicate entities, update types, modify observations, detect conflicts
• Observation Metadata: Track source, confidence, and tags for each observation
• MCP Resources & Prompts: AI clients can passively load graph summaries and use guided memory workflows
• Flexible Transport: Supports stdio, SSE, and Streamable HTTP with optional Bearer or OAuth 2.1 authentication
• Seamless Migration: Automatic upgrade from JSONL to SQLite with zero intervention
• Cross-Platform: Pure Go SQLite (no CGO required), works on Linux, macOS, and Windows

Available Tools

Core CRUD

Tool	Description
create_entities	Create new entities with name, type, and observations
create_relations	Create relations between entities (active voice)
add_observations	Add observations to existing entities
delete_entities	Delete entities and their associated relations
delete_relations	Delete specific relations
delete_observations	Delete specific observations from entities

Query

Tool	Description
search_nodes	Search entities by keyword with FTS5, synonym expansion, and graph traversal. Returns lightweight results with snippets and related entities
open_nodes	Get full details of specific entities by exact name
read_graph	Get graph overview (summary mode) or full export (full mode)

Entity Management

Tool	Description
merge_entities	Merge two entities: migrate observations and relations from source to target, then delete source
update_entities	Change an entity's type
update_observations	Replace an observation's content
detect_conflicts	Find potential duplicates and contradictions within an entity's observations

MCP Resources

URI	Description
memory://graph/summary	Graph statistics and entity type distribution
memory://graph/recent	Recently accessed entities
memory://graph/types	All entity and relation type enumerations
memory://entities/{name}	Full details of a specific entity

MCP Prompts

Prompt	Description
memory-recall	Recall relevant memories by topic
memory-save	Analyze conversation text and suggest what to save
memory-review	Generate a comprehensive review of an entity's memories

Installation

Homebrew (macOS/Linux)

brew install okooo5km/tap/mms

Quick Install Script (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/okooo5km/memory-mcp-server-go/main/scripts/install.sh | bash

Options: -v v0.2.3 for a specific version, -d /usr/local/bin for a custom directory.

Pre-built Binaries

Download from GitHub Releases. Available for macOS (arm64/amd64), Linux (arm64/amd64), and Windows (arm64/amd64).

# Example: macOS Apple Silicon
curl -L https://github.com/okooo5km/memory-mcp-server-go/releases/latest/download/mms_VERSION_darwin_arm64.tar.gz | tar xz
chmod +x mms && mv mms ~/.local/bin/

Build from Source

git clone https://github.com/okooo5km/memory-mcp-server-go.git
cd memory-mcp-server-go
make build        # binary in .build/

Make sure ~/.local/bin (or your chosen directory) is in your PATH.

Command Line Arguments

mms [options]
  -t, --transport string   Transport type: stdio, sse, or http (default "stdio")
  -m, --memory string      Memory file path (auto-detected if not specified)
  -p, --port int           Port for SSE/HTTP transport (default 8080)
  --host string            Host/IP to bind for SSE/HTTP transports (env: MMS_HOST, default all interfaces)
  -v, --version            Show version

  Storage:
  --storage string         Force storage type: sqlite or jsonl (auto-detected)
  --auto-migrate           Auto-migrate JSONL to SQLite (default true)

  Migration:
  --migrate string         Source JSONL file for manual migration
  --migrate-to string      Destination SQLite file
  --dry-run                Dry run migration
  --force                  Overwrite destination

  Streamable HTTP:
  --http-endpoint string   HTTP endpoint path (default "/mcp")
  --http-heartbeat string  Heartbeat interval (default "30s")
  --http-stateless         Stateless HTTP mode

  Auth:
  --auth-bearer string     Require Bearer token for SSE/HTTP

  OAuth 2.1 (mutually exclusive with --auth-bearer):
  --oauth-user string      OAuth login username (env: OAUTH_USER)
  --oauth-pass string      OAuth login password (env: OAUTH_PASS)
  --oauth-issuer string    OAuth issuer URL (auto-detect if empty, env: OAUTH_ISSUER)
  --oauth-store string     SQLite path for durable OAuth clients and tokens (env: OAUTH_STORE_PATH)
  --oauth-refresh-replay-grace string
                           Duration to accept replay of a rotated refresh token (env: OAUTH_REFRESH_REPLAY_GRACE, default 75m)

  CORS:
  --cors-origin string     Allowed CORS origins: '*' for all, or comma-separated list (default "*")

Examples:

mms                                          # stdio, auto-detect storage
mms --memory /path/to/memory.json            # custom path, auto-migrates to SQLite
mms --transport sse --port 9000              # SSE transport
mms --transport http --auth-bearer mytoken   # Streamable HTTP with Bearer auth
mms --transport http --host 127.0.0.1 --oauth-user admin --oauth-pass secret --oauth-store /var/lib/mms/oauth.db  # OAuth 2.1 auth
mms --transport http --cors-origin "https://app.example.com,https://admin.example.com"  # CORS whitelist

Configuration

Claude Desktop / Claude.app

"mcpServers": {
  "memory": {
    "command": "mms",
    "env": {
      "MEMORY_FILE_PATH": "/path/to/memory.json"
    }
  }
}

Claude Desktop Connectors (OAuth)

For remote deployment with OAuth 2.1 authentication, compatible with Claude Desktop's Custom Connectors:

# Start server with OAuth
mms --transport http --host 127.0.0.1 --oauth-user admin --oauth-pass secret --oauth-store /var/lib/mms/oauth.db --port 8080

# Or with environment variables and explicit issuer
OAUTH_USER=admin OAUTH_PASS=secret OAUTH_STORE_PATH=/var/lib/mms/oauth.db \
  OAUTH_REFRESH_REPLAY_GRACE=24h \
  mms --transport http --oauth-issuer https://mcp.example.com

Then in Claude Desktop: Settings → Connectors → Add Custom Connector → enter your server URL (e.g., https://mcp.example.com/mcp). Claude will automatically discover the OAuth endpoints and prompt you to log in.

Cursor

Add to Cursor Settings > mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "mms",
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.json"
      }
    }
  }
}

Example System Prompt

You have access to a Knowledge Graph memory system that persists across conversations.

Saving memories:
- create_entities: Add new people, places, concepts (check search_nodes first to avoid duplicates)
- create_relations: Record how entities relate to each other
- add_observations: Add facts to existing entities

Retrieving memories:
- search_nodes: Find relevant entities by keyword (supports synonyms like JS→JavaScript)
- open_nodes: Get full details of specific entities
- read_graph: Get an overview of all stored knowledge (use "summary" mode first)

Managing memories:
- merge_entities: Combine duplicate entities
- detect_conflicts: Find contradictory observations
- update_entities / update_observations: Fix incorrect data

Always check your memory before answering questions that might require past context.

Streamable HTTP Usage

The Streamable HTTP endpoint accepts JSON-RPC requests, notifications, and responses. Client responses such as replies to server ping messages are acknowledged with 202 Accepted and no body, per the MCP transport spec.

# 1. Initialize session
curl -i -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mytoken' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'

# 2. Listen for server messages
curl -N http://localhost:8080/mcp \
  -H 'Authorization: Bearer mytoken' \
  -H 'Mcp-Session-Id: <session-id>'

# 3. Call a tool
curl -s http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mytoken' \
  -H 'Mcp-Session-Id: <session-id>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_nodes","arguments":{"query":"idea"}}}'

# 4. Terminate session
curl -X DELETE http://localhost:8080/mcp \
  -H 'Authorization: Bearer mytoken' \
  -H 'Mcp-Session-Id: <session-id>'

Security & Deployment

• Deploy behind TLS (Nginx/Caddy/Traefik), bind server to localhost
• Simple auth: Use --auth-bearer $(openssl rand -hex 32) for programmatic clients
• OAuth 2.1: Use --oauth-user/--oauth-pass for browser-based login (Claude Desktop Connectors). Set --oauth-store in production so registered clients and tokens survive restarts, and run the service with a restrictive umask such as systemd UMask=0077 to protect SQLite WAL/SHM files. Supports PKCE (S256), dynamic client registration, durable token storage, and refresh token rotation with a replay grace window for concurrent or multi-worker clients. Use --oauth-refresh-replay-grace for clients that keep stale refresh tokens in multiple processes
• Forward Authorization header from reverse proxy to backend; set --oauth-issuer to the public URL when behind a proxy
• Run as non-root, open only required ports, enable rate limiting for untrusted clients

Storage System

Storage Types

	SQLite (Recommended)	JSONL (Legacy)
Read/Search	1.9x faster	Baseline
Memory	1.9x more efficient	Baseline
File Size	Larger	3x smaller
Startup	Slower	55x faster
Features	FTS5, ACID, WAL, concurrent reads	Human-readable
Best For	>100 entities	<50 entities

Migration

# Automatic (default): just use your existing JSONL path
mms --memory /path/to/memory.json  # auto-migrates to .db

# Manual migration
mms --migrate /path/to/memory.json --migrate-to /path/to/memory.db

# Dry run
mms --migrate /path/to/memory.json --dry-run

Knowledge Graph Structure

• Entities: Nodes with a name, type, and list of observations (each with optional metadata: source, confidence, tags)
• Relations: Directed edges between entities with a relation type in active voice
• Observations: Atomic facts associated with entities, supporting time-decay ranking based on access patterns

Usage Examples

Creating Entities

{
  "entities": [
    {
      "name": "John Smith",
      "entityType": "person",
      "observations": ["Software engineer", "Lives in San Francisco", "Enjoys hiking"]
    },
    {
      "name": "Acme Corp",
      "entityType": "company",
      "observations": ["Founded in 2010", "Tech startup"]
    }
  ]
}

Creating Relations

{
  "relations": [
    { "from": "John Smith", "to": "Acme Corp", "relationType": "works at" }
  ]
}

Searching with Graph Traversal

Search for "John" returns:

• Direct hits: Entities matching "John" with observation snippets
• Related entities: Entities connected to "John" via relations (e.g., "Acme Corp" via "works at")

Merging Duplicate Entities

{
  "sourceName": "React.js",
  "targetName": "React"
}

Merges all observations and relations from "React.js" into "React", then deletes "React.js".

Detecting Conflicts

{
  "entityName": "John Smith"
}

Returns potential duplicates (>60% prefix overlap) and contradictions (antonym keyword pairs like "likes/dislikes").

Development

make fmt          # Format code
make check        # Static analysis (gofmt + go vet)
go test ./...     # Run tests
make build        # Build binary

# Full verification
make fmt && make check && go test ./... && make build

Requirements

• Go 1.24+
• github.com/mark3labs/mcp-go v0.19.0+
• modernc.org/sqlite (pure Go SQLite, no CGO)

Versioning

Version is managed via the VERSION file. Override with make build VERSION=1.2.3 or go build -ldflags "-X main.version=1.2.3".

License

MIT License. See LICENSE for details.