xgmem

xgmem MCP Memory Server

xgmem is a TypeScript-based Model Context Protocol (MCP) server for enabling project-specific and knowledge graph-based memory for Claude, LLM agents, and other tools. It supports storing, retrieving, and managing entities, relations, and observations per project, with a focus on flexibility and cross-project knowledge sharing.

Features

• Knowledge graph storage for entities, relations, and observations
• CRUD operations via MCP tools
• Persistence to disk (memory.json)
• Docker and TypeScript support

Use Case

xgmem is ideal for:

• Agents and LLMs that need to store and retrieve structured memory (entities, relations, observations) per project.
• Cross-project knowledge sharing and migration.
• Scalable, disk-persistent, and queryable memory for agent ecosystems.

Usage

MCP Config Example

Add to your MCP config (e.g., for windsurf):

"mcpServers": {
    "xgmem": {
      "command": "npx",
      "args": ["-y", "xgmem@latest"]
    }
  }

Install dependencies

npm install

Build

npm run build

Run (development)

npx ts-node index.ts

Run (production)

npm start

Docker

docker build -t xgmem-mcp-server .
docker run -v $(pwd)/memories:/app/memories xgmem-mcp-server

This will persist all project memory files in the memories directory on your host.

How to Save Memory (MCP API)

To save observations (memory) for a project, call the save_project_observations tool via the MCP API:

Example JSON:

{
  "name": "save_project_observations",
  "args": {
    "projectId": "demo-project",
    "observations": [
      {
        "entityName": "Alice",
        "contents": [
          "Alice joined Acme Corp in 2021.",
          "Alice is a software engineer."
        ]
      },
      {
        "entityName": "Bob",
        "contents": [
          "Bob joined Acme Corp in 2022.",
          "Bob is a product manager."
        ]
      }
    ]
  }
}

You can use any compatible MCP client, or send this JSON via stdin if running the server directly.

Tooling and API

xgmem exposes the following tools:

• save_project_observations
• get_project_observations
• add_graph_observations
• create_entities
• create_relations
• delete_entities
• delete_observations
• delete_relations
• read_graph
• search_nodes
• search_all_projects
• open_nodes
• copy_memory

See the get_help tool (if enabled) for documentation and usage examples via the MCP API.

Configuration

• Set MEMORY_DIR_PATH env variable to change the memory storage directory (default: /app/memories).

License

MIT