# Semurg agent memory

> Semurg agent memory is a free MCP server for knowledge and memory. Self-hosted persistent memory for agents: knowledge graph, vectors and cited recall. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** self-hosted, Linux, Windows
- **Website:** https://one.semurg.io/blog/semurg-agent-memory-over-mcp
- **Repository:** https://github.com/one-semurg/semurg-mcp
- **MCP Registry name:** io.semurg/agent-memory
- **Categories:** knowledge and memory, AI models and LLM tooling
- **Listing updated:** 2026-11-14

## About

Semurg gives an agent a memory that survives the end of a session, running on your own machine on a single engine the authors wrote from scratch. The node sends nothing to a hosted service, and one node is free with no licence key. It runs on x86_64 hardware: Ubuntu 24.04, Windows through WSL2, or Docker.

Recall is built around citations. Each returned item says which document it came from and when it was stored, and for passages and facts read from text it carries the quoted sentence, checked against the stored text before it is served; if a quote cannot be verified the span is left empty and the reply says why. Facts an agent sent without text are labelled as asserted. When nothing matches, the reply says nothing_stored.

Memories are separated by scope, and an app can give each end user their own with user_id, pinned by a header. Forgetting an entity hides it and its linked facts and passages immediately. Semantic search works once a local embedding model is installed.

## Features

- **Knowledge graph:** Entities and relationships recorded without a schema to write.
- **Cited answers:** Items cite their source document, with quotes checked against stored text.
- **Question-based context:** memory_context walks relationships around names found in a question.
- **Scoped memories:** Share or separate memory by scope and per-user ids.
- **Immediate forget:** Forgetting hides an entity and its linked passages at once.
- **Local semantic search:** Meaning-based search runs on your node once an embedding model is installed.

## Good for

- Give a coding agent memory across sessions
- Keep per-user memory in an app
- Export and import a memory scope
- Answer questions with citations to stored sources
- Keep agent memory off hosted services

## Install

### Claude Code (Terminal)

```sh
claude mcp add agent-memory --env SEMURG_API_TOKEN='<SEMURG_API_TOKEN>' -- uvx semurg
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "agent-memory": {
      "command": "uvx",
      "args": [
        "semurg"
      ],
      "env": {
        "SEMURG_API_TOKEN": "<SEMURG_API_TOKEN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "agent-memory": {
      "command": "uvx",
      "args": [
        "semurg"
      ],
      "env": {
        "SEMURG_API_TOKEN": "<SEMURG_API_TOKEN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "agent-memory": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "semurg"
      ],
      "env": {
        "SEMURG_API_TOKEN": "<SEMURG_API_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "agent-memory": {
      "command": "uvx",
      "args": [
        "semurg"
      ],
      "env": {
        "SEMURG_API_TOKEN": "<SEMURG_API_TOKEN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "agent-memory": {
      "command": "uvx",
      "args": [
        "semurg"
      ],
      "env": {
        "SEMURG_API_TOKEN": "<SEMURG_API_TOKEN>"
      }
    }
  }
}
```

## Tools

- `memory_status`: Reports memory status.
- `memory_remember`: Stores what the agent learns.
- `memory_recall`: Finds stored items again.
- `memory_relate`: Creates relationships between entities.
- `memory_forget`: Hides an entity, its facts and linked passages.
- `memory_context`: Starts from names in a question and returns related facts and passages.
- `memory_document`: Works with documents.
- `memory_export`: Reads everything a scope holds, a page at a time.
- `memory_import`: Stores records back into any scope.

## FAQ

### Does data leave my machine?

The post says the node sends nothing to a hosted service.

### What does it cost?

One node is free, with no licence key.

### What hardware is needed?

x86_64: Ubuntu 24.04, Windows via WSL2 with Ubuntu 24.04, or Docker on an x86_64 host.

### What happens when nothing matches?

The reply says nothing_stored.

### Is Semurg agent memory free?

Yes. Semurg agent memory is free to use.

### How do I add Semurg agent memory to Claude Code?

Run this command in your terminal: claude mcp add agent-memory --env SEMURG_API_TOKEN='<SEMURG_API_TOKEN>' -- uvx semurg

### What are the best alternatives to Semurg agent memory?

The closest alternatives to Semurg agent memory are Codebase Memory, XERJ, Claude Code Ultimate Guide, Nautilus Compass Memory and note1.

## Alternatives

- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [MedXpert 图书馆连接器（通用版）](https://ai-powered.com/mcp/medxpert): MedXpert 图书馆连接器（通用版） is an open-source MCP server for knowledge and memory.
- [Context Nest](https://ai-powered.com/mcp/context-nest): Context Nest is a freemium MCP server for knowledge and memory.
- [Tulsa Ecosystem Map](https://ai-powered.com/mcp/tulsa-ecosystem-map): Tulsa Ecosystem Map is a free MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/semurg-agent-memory
