Skip to content
Back to search

memory-mcp-server-go

A Model Context Protocol server that provides knowledge graph management capabilities.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/okooo5km--memory-mcp-server-go/badge.svg)](/listings/okooo5km--memory-mcp-server-go)

HTML

<a href="/listings/okooo5km--memory-mcp-server-go"><img src="/api/listings/okooo5km--memory-mcp-server-go/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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](https://github.com/okooo5km/memory-mcp-server-go/releases/latest). 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`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 410 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Memory MCP Server (Go)
  2. > 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](https://github.com/modelcontextprotocol/servers/tree/main/src/memory).
  3. ![Go Platform](https://img.shields.io/badge/platform-cross--platform-lightgrey)
  4. ![License](https://img.shields.io/badge/license-MIT-blue)
  5. ## Features
  6. * **High-Performance Storage**: SQLite backend with WAL mode, read/write connection separation for concurrent access
  7. * **Knowledge Graph Management**: Persistent graph of entities, relationships, and observations
  8. * **Advanced Search**: FTS5 full-text search with BM25 ranking, synonym expansion, and time-decay scoring
  9. * **Graph Traversal**: Search results include 1-hop related entities for richer context
  10. * **Entity Management**: Merge duplicate entities, update types, modify observations, detect conflicts
  11. * **Observation Metadata**: Track source, confidence, and tags for each observation
  12. * **MCP Resources & Prompts**: AI clients can passively load graph summaries and use guided memory workflows
  13. * **Flexible Transport**: Supports stdio, SSE, and Streamable HTTP with optional Bearer or OAuth 2.1 authentication
  14. * **Seamless Migration**: Automatic upgrade from JSONL to SQLite with zero intervention
  15. * **Cross-Platform**: Pure Go SQLite (no CGO required), works on Linux, macOS, and Windows
  16. ## Available Tools
  17. ### Core CRUD
  18. | Tool | Description |
  19. |------|-------------|
  20. | `create_entities` | Create new entities with name, type, and observations |
  21. | `create_relations` | Create relations between entities (active voice) |
  22. | `add_observations` | Add observations to existing entities |
  23. | `delete_entities` | Delete entities and their associated relations |
  24. | `delete_relations` | Delete specific relations |
  25. | `delete_observations` | Delete specific observations from entities |
  26. ### Query
  27. | Tool | Description |
  28. |------|-------------|
  29. | `search_nodes` | Search entities by keyword with FTS5, synonym expansion, and graph traversal. Returns lightweight results with snippets and related entities |
  30. | `open_nodes` | Get full details of specific entities by exact name |
  31. | `read_graph` | Get graph overview (`summary` mode) or full export (`full` mode) |
  32. ### Entity Management
  33. | Tool | Description |
  34. |------|-------------|
  35. | `merge_entities` | Merge two entities: migrate observations and relations from source to target, then delete source |
  36. | `update_entities` | Change an entity's type |
  37. | `update_observations` | Replace an observation's content |
  38. | `detect_conflicts` | Find potential duplicates and contradictions within an entity's observations |
  39. ### MCP Resources
  40. | URI | Description |
  41. |-----|-------------|
  42. | `memory://graph/summary` | Graph statistics and entity type distribution |
  43. | `memory://graph/types` | All entity and relation type enumerations |
  44. | `memory://entities/{name}` | Full details of a specific entity |
  45. ### MCP Prompts
  46. | Prompt | Description |
  47. |--------|-------------|
  48. | `memory-recall` | Recall relevant memories by topic |
  49. | `memory-save` | Analyze conversation text and suggest what to save |
  50. | `memory-review` | Generate a comprehensive review of an entity's memories |
  51. ## Installation
  52. ### Homebrew (macOS/Linux)
  53. ```bash
  54. brew install okooo5km/tap/mms
  55. ```
  56. ### Quick Install Script (macOS/Linux)
  57. ```bash
  58. curl -fsSL https://raw.githubusercontent.com/okooo5km/memory-mcp-server-go/main/scripts/install.sh | bash
  59. ```
  60. Options: `-v v0.2.3` for a specific version, `-d /usr/local/bin` for a custom directory.
  61. ### Pre-built Binaries
  62. Download from [GitHub Releases](https://github.com/okooo5km/memory-mcp-server-go/releases/latest). Available for macOS (arm64/amd64), Linux (arm64/amd64), and Windows (arm64/amd64).
  63. ```bash
  64. # Example: macOS Apple Silicon
  65. curl -L https://github.com/okooo5km/memory-mcp-server-go/releases/latest/download/mms_VERSION_darwin_arm64.tar.gz | tar xz
  66. chmod +x mms && mv mms ~/.local/bin/
  67. ```
  68. ### Build from Source
  69. ```bash
  70. git clone https://github.com/okooo5km/memory-mcp-server-go.git
  71. cd memory-mcp-server-go
  72. make build # binary in .build/
  73. ```
  74. Make sure `~/.local/bin` (or your chosen directory) is in your `PATH`.
  75. ## Command Line Arguments
  76. ```
  77. mms [options]
  78. -t, --transport string Transport: stdio, http (alias streamable-http) or sse
  79. (env: MMS_TRANSPORT; default stdio, or http when a public URL is set)
  80. -m, --memory string Memory file path (auto-detected if not specified)
  81. -p, --port int Port for http/sse transports (env: MMS_PORT, default 8080)
  82. --host string Host/IP to bind for http/sse (env: MMS_HOST; default all interfaces,
  83. or 127.0.0.1 when a public URL is set)
  84. -v, --version Show version
  85. Storage:
  86. --storage string Force storage type: sqlite or jsonl (auto-detected)
  87. --auto-migrate Auto-migrate JSONL to SQLite (default true)
  88. Migration:
  89. --migrate string Source JSONL file for manual migration
  90. --migrate-to string Destination SQLite file
  91. --dry-run Dry run migration
  92. --force Overwrite destination
  93. Deployment:
  94. --public-url string Public base URL, e.g. https://mcp.example.com (env: MMS_PUBLIC_URL).
  95. Becomes the OAuth issuer/resource and the only accepted Host (besides
  96. loopback). When set, defaults to: http transport, host 127.0.0.1 and the
  97. OAuth store at oauth.db next to the memory database
  98. Streamable HTTP:
  99. --http-endpoint string HTTP endpoint path (env: MMS_HTTP_ENDPOINT, default "/mcp")
  100. --http-heartbeat string Server-to-client keepalive ping interval, e.g. 30s; 0 disables (default "0")
  101. --http-stateless Stateless HTTP mode
  102. Auth:
  103. --auth-bearer string Require Bearer token for http/sse (env: MMS_AUTH_BEARER)
  104. OAuth 2.1 (mutually exclusive with --auth-bearer):
  105. --oauth-user string OAuth login username (env: OAUTH_USER)
  106. --oauth-pass string OAuth login password (env: OAUTH_PASS; prefer the env var, argv is visible)
  107. --oauth-issuer string Legacy: set only the OAuth issuer, with no other --public-url effects (env: OAUTH_ISSUER)
  108. --oauth-store string SQLite path for durable OAuth clients and tokens (env: OAUTH_STORE_PATH)
  109. --oauth-refresh-replay-grace string
  110. Duration to accept replay of a rotated refresh token (env: OAUTH_REFRESH_REPLAY_GRACE, default 75m)
  111. Reverse proxy:
  112. --trusted-proxies string Comma-separated CIDRs or IPs of reverse proxies whose X-Real-IP header is
  113. trusted for login rate limiting (env: MMS_TRUSTED_PROXIES). Loopback is
  114. always trusted. Needed when the proxy is in another container or host
  115. CORS:
  116. --cors-origin string Allowed CORS origins: '*' for all, or comma-separated list (env: MMS_CORS_ORIGIN, default "*")
  117. ```
  118. Flags win over environment variables. The server also serves `GET /healthz` (returns `ok`, no auth) on the http and sse transports.
  119. Examples:
  120. ```bash
  121. mms # stdio, auto-detect storage
  122. mms --memory /path/to/memory.json # custom path, auto-migrates to SQLite
  123. mms --transport sse --port 9000 # SSE transport (endpoint /sse)
  124. mms --transport http --auth-bearer mytoken # Streamable HTTP with Bearer auth
  125. MMS_PUBLIC_URL=https://mcp.example.com OAUTH_USER=admin OAUTH_PASS='a-long-password' mms # OAuth 2.1 behind a reverse proxy
  126. mms --transport http --cors-origin "https://app.example.com,https://admin.example.com" # CORS whitelist
  127. ```
  128. ## Configuration
  129. ### Claude Desktop / Claude.app
  130. ```json
  131. "mcpServers": {
  132. "memory": {
  133. "command": "mms",
  134. "env": {
  135. "MEMORY_FILE_PATH": "/path/to/memory.json"
  136. }
  137. }
  138. }
  139. ```
  140. ### Claude Desktop Connectors (OAuth)
  141. For remote deployment with OAuth 2.1 authentication, compatible with Claude Desktop's Custom Connectors:
  142. ```bash
  143. # Behind a reverse proxy: the public URL implies --transport http --host 127.0.0.1 and an OAuth store next to the memory database
  144. MMS_PUBLIC_URL=https://mcp.example.com MMS_PORT=8080
  145. OAUTH_USER=admin OAUTH_PASS='a-long-password' MEMORY_FILE_PATH=/var/lib/mms/memory.db
  146. mms
  147. # Local trial without TLS
  148. mms --transport http --host 127.0.0.1 --oauth-user admin --oauth-pass secret --oauth-store ./oauth.db
  149. ```
  150. 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.
  151. ### Cursor
  152. Add to Cursor Settings > mcp.json:
  153. ```json
  154. {
  155. "mcpServers": {
  156. "memory": {
  157. "command": "mms",
  158. "env": {
  159. "MEMORY_FILE_PATH": "/path/to/memory.json"
  160. }
  161. }
  162. }
  163. }
  164. ```
  165. ### Example System Prompt
  166. ```text
  167. You have access to a Knowledge Graph memory system that persists across conversations.
  168. Saving memories:
  169. - create_entities: Add new people, places, concepts (check search_nodes first to avoid duplicates)
  170. - create_relations: Record how entities relate to each other
  171. - add_observations: Add facts to existing entities
  172. Retrieving memories:
  173. - search_nodes: Find relevant entities by keyword (supports synonyms like JS→JavaScript)
  174. - open_nodes: Get full details of specific entities
  175. - read_graph: Get an overview of all stored knowledge (use "summary" mode first)
  176. Managing memories:
  177. - merge_entities: Combine duplicate entities
  178. - detect_conflicts: Find contradictory observations
  179. - update_entities / update_observations: Fix incorrect data
  180. Always check your memory before answering questions that might require past context.
  181. ```
  182. ## Streamable HTTP Usage
  183. The Streamable HTTP endpoint is served by the official MCP Go SDK. It accepts
  184. JSON-RPC requests, notifications, and responses; client responses such as
  185. replies to server `ping` messages are acknowledged with `202 Accepted` and no
  186. body, per the MCP transport spec.
  187. With `--transport sse` the legacy HTTP+SSE transport is served instead: connect
  188. to `GET /sse`; the server announces a session-specific message URL
  189. (`/sse?sessionid=...`) to POST to. The separate `/message` path of earlier
  190. releases no longer exists.
  191. ```bash
  192. # 1. Initialize session
  193. curl -i -X POST http://localhost:8080/mcp \
  194. -H 'Content-Type: application/json' \
  195. -H 'Authorization: Bearer mytoken' \
  196. -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'
  197. # 2. Listen for server messages
  198. curl -N http://localhost:8080/mcp \
  199. -H 'Authorization: Bearer mytoken' \
  200. -H 'Mcp-Session-Id: <session-id>'
  201. # 3. Call a tool
  202. curl -s http://localhost:8080/mcp \
  203. -H 'Content-Type: application/json' \
  204. -H 'Authorization: Bearer mytoken' \
  205. -H 'Mcp-Session-Id: <session-id>' \
  206. -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_nodes","arguments":{"query":"idea"}}}'
  207. # 4. Terminate session
  208. curl -X DELETE http://localhost:8080/mcp \
  209. -H 'Authorization: Bearer mytoken' \
  210. -H 'Mcp-Session-Id: <session-id>'
  211. ```
  212. ## Security & Deployment
  213. **For AI agents:** to deploy without the script (Docker, Caddy, Traefik, an existing nginx, Cloudflare Tunnel, bearer-only), follow [doc/deploy-custom.md](doc/deploy-custom.md): runtime contract, recipes and an acceptance script (`scripts/verify-deploy.sh`).
  214. One-line VPS deployment (nginx + Let's Encrypt + systemd, OAuth 2.1 login); see [doc/deploy.md](doc/deploy.md):
  215. ```bash
  216. 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
  217. ```
  218. - Deploy behind TLS (Nginx/Caddy/Traefik), bind server to localhost
  219. - **Public URL**: set `--public-url` / `MMS_PUBLIC_URL` (for example `https://mcp.example.com`) when behind a proxy. It selects the http transport on `127.0.0.1`, becomes the OAuth issuer and resource, and restricts `/mcp`, `/sse` and the OAuth routes to that `Host` (plus loopback); other hosts get `403`. `GET /healthz` is exempt. Keep `proxy_set_header Host $host` in the proxy
  220. - DNS-rebinding protection: on a loopback listener without auth and without a public URL, requests with a non-loopback `Host` are rejected with `403`; it is relaxed only when a token is required or a public URL is configured
  221. - **Simple auth**: Use `--auth-bearer $(openssl rand -hex 32)` (or `MMS_AUTH_BEARER`) for programmatic clients; the token is compared in constant time
  222. - **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 to `oauth.db` next to the memory database; otherwise set `--oauth-store` 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, 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](doc/oauth.md)
  223. - **Proxy in another container or host**: the login rate limiter keys on the client address. It believes `X-Real-IP` only 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-For` is never used. An invalid value is a startup error
  224. - Run as non-root, open only required ports, enable rate limiting for untrusted clients
  225. ## Storage System
  226. ### Storage Types
  227. | | SQLite (Recommended) | JSONL (Legacy) |
  228. |---|---|---|
  229. | **Read/Search** | 1.9x faster | Baseline |
  230. | **Memory** | 1.9x more efficient | Baseline |
  231. | **File Size** | Larger | 3x smaller |
  232. | **Startup** | Slower | 55x faster |
  233. | **Features** | FTS5, ACID, WAL, concurrent reads | Human-readable |
  234. | **Best For** | >100 entities | <50 entities |
  235. ### Migration
  236. ```bash
  237. # Automatic (default): just use your existing JSONL path
  238. mms --memory /path/to/memory.json # auto-migrates to .db
  239. # Manual migration
  240. mms --migrate /path/to/memory.json --migrate-to /path/to/memory.db
  241. # Dry run
  242. mms --migrate /path/to/memory.json --dry-run
  243. ```
  244. ## Knowledge Graph Structure
  245. * **Entities**: Nodes with a name, type, and list of observations (each with optional metadata: source, confidence, tags)
  246. * **Relations**: Directed edges between entities with a relation type in active voice
  247. * **Observations**: Atomic facts associated with entities, supporting time-decay ranking based on access patterns
  248. ## Usage Examples
  249. ### Creating Entities
  250. ```json
  251. {
  252. "entities": [
  253. {
  254. "name": "John Smith",
  255. "entityType": "person",
  256. "observations": ["Software engineer", "Lives in San Francisco", "Enjoys hiking"]
  257. },
  258. {
  259. "name": "Acme Corp",
  260. "entityType": "company",
  261. "observations": ["Founded in 2010", "Tech startup"]
  262. }
  263. ]
  264. }
  265. ```
  266. ### Creating Relations
  267. ```json
  268. {
  269. "relations": [
  270. { "from": "John Smith", "to": "Acme Corp", "relationType": "works at" }
  271. ]
  272. }
  273. ```
  274. ### Searching with Graph Traversal
  275. Search for "John" returns:
  276. - **Direct hits**: Entities matching "John" with observation snippets
  277. - **Related entities**: Entities connected to "John" via relations (e.g., "Acme Corp" via "works at")
  278. ### Merging Duplicate Entities
  279. ```json
  280. {
  281. "sourceName": "React.js",
  282. "targetName": "React"
  283. }
  284. ```
  285. Merges all observations and relations from "React.js" into "React", then deletes "React.js".
  286. ### Detecting Conflicts
  287. ```json
  288. {
  289. "entityName": "John Smith"
  290. }
  291. ```
  292. Returns potential duplicates (>60% prefix overlap) and contradictions (antonym keyword pairs like "likes/dislikes").
  293. ## Development
  294. ```bash
  295. make fmt # Format code
  296. make check # Static analysis (gofmt + go vet)
  297. go test ./... # Run tests
  298. make build # Build binary
  299. # Full verification
  300. make fmt && make check && go test ./... && make build
  301. ```
  302. ### Requirements
  303. * Go 1.25+
  304. * github.com/modelcontextprotocol/go-sdk v1.8.0 (official MCP Go SDK)
  305. * modernc.org/sqlite (pure Go SQLite, no CGO)
  306. ### Versioning
  307. 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"`.
  308. ## License
  309. MIT License. See [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.