xgmem

xgmem is a TypeScript-based MCP server that provides a disk-persistent memory store for projects, implemented as a knowledge graph of entities, relations, and observations. It exposes MCP tools to create, read, update, and delete memory components, enabling agents and LLMs to store and retrieve structured memory per project and even share or migrate memory across projects. You can interact with the server using the built-in tools such as save_project_observations, get_project_observations, create_entities, read_graph, and more, via the MCP API or directly through the provided CLI example. The memory is persisted to disk (memory.json by default) and can be run locally via npm scripts or Docker for easier deployment.

Prerequisites:

• Node.js and npm installed on your system
• Basic familiarity with MCP tooling

1. Install dependencies and build

npm install

2. Build the TypeScript project (if required by the repository)

npm run build

3. Run in development mode (example using ts-node)

npx ts-node index.ts

4. Run in production mode

npm start

5. If you prefer Docker, you can build and run the container:

# Build the Docker image
docker build -t xgmem-mcp-server .

# Run the container and mount a host memories directory for persistence
docker run -v $(pwd)/memories:/app/memories xgmem-mcp-server

6. Update MCP config (example)

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

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

Environment and storage:

• MEMORY_DIR_PATH can be set to customize where memory files are stored on disk. The default is /app/memories inside the container or project root when running locally.
• The server exposes a set of MCP tools for memory management, such as 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, and copy_memory. Use get_help if available for usage details.
• If running with Docker, ensure the mounted memories directory is writable by the container. Correct permissions on the host path are important to avoid write errors.
• For production, consider using a process manager and proper logging configuration to monitor the MCP server.