# Vayl

> Vayl is an open-source MCP server for knowledge and memory. Agent memory that replaces outdated facts, keeps history and can hold changes for approval. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Website:** https://vayl.gitbook.io/vayl-docs
- **Repository:** https://github.com/ac12644/vayl
- **MCP Registry name:** io.github.ac12644/vayl
- **Categories:** knowledge and memory
- **Listing updated:** 2026-11-14

## About

Facts are written so a new value supersedes the old one and a removal retracts it, so a retired fact is never returned as current, while the history stays queryable. Ambiguous inputs are flagged rather than guessed, and high-stakes changes can wait for human approval.

It targets agents where a wrong stored fact causes harm, such as medication lists or account status. The docs demo shows a warfarin to apixaban change held until confirm_change. Locally it runs over stdio with one SQLite file, and a team server is available. It needs an OpenAI key or a local Ollama model, and the license is Apache-2.0.

The docs mention encryption at rest, a tamper-evident audit chain and GDPR building blocks.

## Features

- **Reconciles on write:** New values supersede old ones.
- **History:** Ask what was true before.
- **Approval hold:** Pending changes wait for confirmation.
- **Audit chain:** Signed, tamper-evident log.
- **Local first:** SQLite file with optional team server.

## Good for

- Keep a medication list current
- Track account status for a support agent
- Audit how a stored fact changed
- Gate risky memory changes on approval

## Install

### Claude Code (Terminal)

```sh
claude mcp add vayl --env OPENAI_API_KEY='<OPENAI_API_KEY>' -- uvx vayl-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "vayl": {
      "command": "uvx",
      "args": [
        "vayl-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>"
      }
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "vayl": {
      "command": "uvx",
      "args": [
        "vayl-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>"
      }
    }
  }
}
```

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

```json
{
  "servers": {
    "vayl": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "vayl-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>"
      }
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "vayl": {
      "command": "uvx",
      "args": [
        "vayl-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>"
      }
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "vayl": {
      "command": "uvx",
      "args": [
        "vayl-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>"
      }
    }
  }
}
```

## Tools

- `remember`: Stores a fact and reconciles it against existing ones.
- `recall`: Answers from current memory.
- `confirm_change`: Approves a held change.
- `pending_changes`: Lists changes awaiting approval.
- `check_before_act`: Checks memory before an action.

## FAQ

### What license?

Apache-2.0.

### Which models does it need?

An OpenAI key, or a local Ollama model.

### Where is data stored?

In a SQLite file at VAYL_DB.

### Which tools exist?

Includes remember, recall, confirm_change, pending_changes and check_before_act.

### Is Vayl free?

Yes. Vayl is open source, so you can use and self-host it for free.

### How do I add Vayl to Claude Code?

Run this command in your terminal: claude mcp add vayl --env OPENAI_API_KEY='<OPENAI_API_KEY>' -- uvx vayl-mcp

### What are the best alternatives to Vayl?

The closest alternatives to Vayl 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/vayl
