Knowledge Graph Memory Server (Go)

A Go implementation of the Memory MCP server that mirrors the existing TypeScript version. Supports both stdio and Streamable HTTP transports and optional Basic Auth for HTTP. Stores data in SQLite with a BoltDB-backed token index for fast search.

Features

• Transports: stdio, Streamable HTTP
• Auth: Optional Basic Auth for HTTP via env or file-based secrets
• Storage: SQLite database for entities/relations/observations, BoltDB for token index
• Parity: Same tool surface as the TS server

Core Concepts

Entities

Entities are the primary nodes in the knowledge graph. Each entity has a unique name, an entityType, and a list of observations.

Example:

{
  "name": "John_Smith",
  "entityType": "person",
  "observations": ["Speaks fluent Spanish"]
}

Relations

Directed connections between entities, stored in active voice.

Example:

{
  "from": "John_Smith",
  "to": "Anthropic",
  "relationType": "works_at"
}

Observations

Atomic facts attached to entities.

Example:

{
  "entityName": "John_Smith",
  "observations": [
    "Speaks fluent Spanish",
    "Graduated in 2019",
    "Prefers morning meetings"
  ]
}

Requirements

• Go 1.25+ for local build/testing
• Docker (optional) for containerized build/run

Build and Test (Local)

# Pull dependencies and run tests
go mod tidy
go test ./...

# Build binary
go build -o mcp-memory ./

Usage with Claude Desktop

Setup

Add this to your claude_desktop_config.json.

Docker

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "claude-memory:/app",
        "ghcr.io/viktorprogger/mcp-memory:latest"
      ]
    }
  }
}

This mounts a named volume claude-memory at /app so the default SQLite/Bolt files (/app/memory.db, /app/memory.db.bolt) persist across runs.

Local (go run)

{
  "mcpServers": {
    "memory": {
      "command": "bash",
      "args": [
        "-lc",
        "cd /absolute/path/to/mcp-memory && go run ."
      ]
    }
  }
}

For custom settings (HTTP mode, custom DB paths, Basic Auth), see the Configuration section below.

Configuration

Environment variables

• TRANSPORT: stdio (default) or http
• HTTP_ADDR: HTTP listen address (default :8080)
• HTTP_PATH: HTTP endpoint path (default /mcp)
• MEMORY_FILE_PATH: path to the SQLite database file (default memory.db next to the binary)
• BOLT_DB_PATH: path to the BoltDB token index file (default <MEMORY_FILE_PATH>.bolt)
• BASIC_AUTH_USER / BASIC_AUTH_PASSWORD: credentials for Basic Auth
• BASIC_AUTH_USER_FILE / BASIC_AUTH_PASSWORD_FILE: file-based credentials (take precedence over env vars)

Notes:

• If either BASIC_AUTH_USER or BASIC_AUTH_PASSWORD (or the *_FILE variants) is set, Basic Auth is enforced. By default (no values set) HTTP runs without auth.

Using with MCP Clients

• MCP Inspector
  • Install: npx @modelcontextprotocol/inspector
  • Connect: http://localhost:8080/mcp
• Claude Code / VS Code / Cursor
  • Add as HTTP MCP server with URL http://localhost:8080/mcp
  • If Basic Auth enabled, include Authorization: Basic <base64(user:pass)> header per client configuration
• STDIO
  • Use as a local spawned process transport where the host MCP client manages stdio

Built-in Tools

• create_entities

  • Create multiple new entities in the knowledge graph
  • Input: entities (array of objects)
    • Each contains name (string), entityType (string), observations (string[])
  • Ignores entities with existing names

• create_relations

  • Create multiple new relations between entities
  • Input: relations (array of objects)
    • Each contains from (string), to (string), relationType (string)
  • Skips duplicate relations

• add_observations

  • Add new observations to existing entities
  • Input: observations (array of objects)
    • Each contains entityName (string), contents (string[])
  • Returns added observations per entity; fails if entity doesn't exist

• delete_entities

  • Remove entities and their relations
  • Input: entityNames (string[])
  • Cascading deletion of associated relations; silent if entity doesn't exist

• delete_observations

  • Remove specific observations from entities
  • Input: deletions (array of objects)
    • Each contains entityName (string), observations (string[])
  • Silent if observation doesn't exist

• delete_relations

  • Remove specific relations from the graph
  • Input: relations (array of objects)
    • Each contains from (string), to (string), relationType (string)
  • Silent if relation doesn't exist

• read_graph

  • Read the entire knowledge graph
  • No input; returns all entities and relations

• search_nodes

  • Search for nodes based on a query string
  • Input: query (string); searches names, types, observation content
  • Returns matching entities and their relations

• open_nodes

  • Retrieve specific nodes by name
  • Input: names (string[])
  • Returns requested entities and relations between them

Data Model

• Stored in SQLite tables for entities, observations, and relations.
• A BoltDB-based token index is maintained for efficient search.

Notes on Spec/SDK Versions

• MCP Spec: 2025-06-18
• TS SDK (@modelcontextprotocol/sdk) latest: see npm; project previously used 1.0.1
• Go SDK: github.com/modelcontextprotocol/go-sdk v1.0.0

License

MIT