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.
- 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
| 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 |
| 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) |
| 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 |
| URI | Description |
|---|---|
memory://graph/summary |
Graph statistics and entity type distribution |
memory://graph/types |
All entity and relation type enumerations |
memory://entities/{name} |
Full details of a specific entity |
| 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 |
brew install okooo5km/tap/mmscurl -fsSL https://raw.githubusercontent.com/okooo5km/memory-mcp-server-go/main/scripts/install.sh | bashOptions: -v v0.2.3 for a specific version, -d /usr/local/bin for a custom directory.
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/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.
mms [options]
-t, --transport string Transport: stdio, http (alias streamable-http) or sse
(env: MMS_TRANSPORT; default stdio, or http when a public URL is set)
-m, --memory string Memory file path (auto-detected if not specified)
-p, --port int Port for http/sse transports (env: MMS_PORT, default 8080)
--host string Host/IP to bind for http/sse (env: MMS_HOST; default all interfaces,
or 127.0.0.1 when a public URL is set)
-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
Deployment:
--public-url string Public base URL, e.g. https://mcp.example.com (env: MMS_PUBLIC_URL).
Becomes the OAuth issuer/resource and the only accepted Host (besides
loopback). When set, defaults to: http transport, host 127.0.0.1 and the
OAuth store at oauth.db next to the memory database
Streamable HTTP:
--http-endpoint string HTTP endpoint path (env: MMS_HTTP_ENDPOINT, default "/mcp")
--http-heartbeat string Server-to-client keepalive ping interval, e.g. 30s; 0 disables (default "0")
--http-stateless Stateless HTTP mode
Auth:
--auth-bearer string Require Bearer token for http/sse (env: MMS_AUTH_BEARER)
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; prefer the env var, argv is visible)
--oauth-issuer string Legacy: set only the OAuth issuer, with no other --public-url effects (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)
Reverse proxy:
--trusted-proxies string Comma-separated CIDRs or IPs of reverse proxies whose X-Real-IP header is
trusted for login rate limiting (env: MMS_TRUSTED_PROXIES). Loopback is
always trusted. Needed when the proxy is in another container or host
CORS:
--cors-origin string Allowed CORS origins: '*' for all, or comma-separated list (env: MMS_CORS_ORIGIN, default "*")
Flags win over environment variables. The server also serves GET /healthz (returns ok, no auth) on the http and sse transports.
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 (endpoint /sse)
mms --transport http --auth-bearer mytoken # Streamable HTTP with Bearer auth
MMS_PUBLIC_URL=https://mcp.example.com OAUTH_USER=admin OAUTH_PASS='a-long-password' mms # OAuth 2.1 behind a reverse proxy
mms --transport http --cors-origin "https://app.example.com,https://admin.example.com" # CORS whitelist"mcpServers": {
"memory": {
"command": "mms",
"env": {
"MEMORY_FILE_PATH": "/path/to/memory.json"
}
}
}For remote deployment with OAuth 2.1 authentication, compatible with Claude Desktop's Custom Connectors:
# Behind a reverse proxy: the public URL implies --transport http --host 127.0.0.1 and an OAuth store next to the memory database
MMS_PUBLIC_URL=https://mcp.example.com MMS_PORT=8080
OAUTH_USER=admin OAUTH_PASS='a-long-password' MEMORY_FILE_PATH=/var/lib/mms/memory.db
mms
# Local trial without TLS
mms --transport http --host 127.0.0.1 --oauth-user admin --oauth-pass secret --oauth-store ./oauth.dbThen 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.
Add to Cursor Settings > mcp.json:
{
"mcpServers": {
"memory": {
"command": "mms",
"env": {
"MEMORY_FILE_PATH": "/path/to/memory.json"
}
}
}
}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.
The Streamable HTTP endpoint is served by the official MCP Go SDK. It 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.
With --transport sse the legacy HTTP+SSE transport is served instead: connect
to GET /sse; the server announces a session-specific message URL
(/sse?sessionid=...) to POST to. The separate /message path of earlier
releases no longer exists.
# 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>'For AI agents: to deploy without the script (Docker, Caddy, Traefik, an existing nginx, Cloudflare Tunnel, bearer-only), follow doc/deploy-custom.md: runtime contract, recipes and an acceptance script (scripts/verify-deploy.sh).
One-line VPS deployment (nginx + Let's Encrypt + systemd, OAuth 2.1 login); see doc/deploy.md:
curl -fsSL https://raw.githubusercontent.com/okooo5km/memory-mcp-server-go/main/scripts/deploy-vps.sh | sudo bash -s -- --domain mcp.example.com --email me@example.com- Deploy behind TLS (Nginx/Caddy/Traefik), bind server to localhost
- Public URL: set
--public-url/MMS_PUBLIC_URL(for examplehttps://mcp.example.com) when behind a proxy. It selects the http transport on127.0.0.1, becomes the OAuth issuer and resource, and restricts/mcp,/sseand the OAuth routes to thatHost(plus loopback); other hosts get403.GET /healthzis exempt. Keepproxy_set_header Host $hostin the proxy - DNS-rebinding protection: on a loopback listener without auth and without a public URL, requests with a non-loopback
Hostare rejected with403; it is relaxed only when a token is required or a public URL is configured - Simple auth: Use
--auth-bearer $(openssl rand -hex 32)(orMMS_AUTH_BEARER) for programmatic clients; the token is compared in constant time - OAuth 2.1: Use
OAUTH_USER/OAUTH_PASS(preferred over--oauth-pass, argv is visible in the process list) for browser-based login (Claude Desktop Connectors). With a public URL the OAuth store defaults tooauth.dbnext to the memory database; otherwise set--oauth-storeso registered clients and tokens survive restarts, and run the service with a restrictive umask such as systemdUMask=0077to protect SQLite WAL/SHM files. Supports PKCE (S256, required), resource indicators, dynamic client registration and Client ID Metadata Documents, durable token storage, token revocation, and refresh token rotation with a replay grace window for concurrent or multi-worker clients. See doc/oauth.md - Proxy in another container or host: the login rate limiter keys on the client address. It believes
X-Real-IPonly from loopback and from peers listed in--trusted-proxies/MMS_TRUSTED_PROXIES(CIDRs or IPs, e.g.172.20.0.0/16); otherwise every user shares the proxy's address and five bad logins lock everybody out.X-Forwarded-Foris never used. An invalid value is a startup error - Run as non-root, open only required ports, enable rate limiting for untrusted clients
| 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 |
# 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- 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
{
"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"]
}
]
}{
"relations": [
{ "from": "John Smith", "to": "Acme Corp", "relationType": "works at" }
]
}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")
{
"sourceName": "React.js",
"targetName": "React"
}Merges all observations and relations from "React.js" into "React", then deletes "React.js".
{
"entityName": "John Smith"
}Returns potential duplicates (>60% prefix overlap) and contradictions (antonym keyword pairs like "likes/dislikes").
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- Go 1.25+
- github.com/modelcontextprotocol/go-sdk v1.8.0 (official MCP Go SDK)
- modernc.org/sqlite (pure Go SQLite, no CGO)
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".
MIT License. See LICENSE for details.