# engrava

An MCP server that gives AI agents a persistent SQLite memory database. It enables hybrid retrieval, MindQL queries, and a thought graph over stdio.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 1
- Author: sovantica
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/sovantica/engrava-mcp
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/mcp/engrava

## What it does

The server exposes persistent agent memory backed by SQLite over stdio. A minimal start needs only `ENGRAVA_DB_PATH` pointing to a database file. In this setup, semantic vector search remains inactive because no embedding model is configured, though keyword search and graph queries function normally.

Activating vector retrieval requires `ENGRAVA_MCP_CONFIG` pointing to an `engrava.yaml` file. The server also supports `ENGRAVA_MCP_READ_ONLY` to disallow write tools. Even with write tools disabled, the process still requires filesystem write access at startup to create or upgrade the SQLite schema.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `ENGRAVA_DB_PATH`, `ENGRAVA_MCP_CONFIG`, `ENGRAVA_MCP_READ_ONLY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env ENGRAVA_DB_PATH=<ENGRAVA_DB_PATH> --env ENGRAVA_MCP_CONFIG=<ENGRAVA_MCP_CONFIG> --env ENGRAVA_MCP_READ_ONLY=<ENGRAVA_MCP_READ_ONLY> --transport stdio engrava -- uvx engrava-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from engrava-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add engrava --env ENGRAVA_DB_PATH=<ENGRAVA_DB_PATH> --env ENGRAVA_MCP_CONFIG=<ENGRAVA_MCP_CONFIG> --env ENGRAVA_MCP_READ_ONLY=<ENGRAVA_MCP_READ_ONLY> -- uvx engrava-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from engrava-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "engrava": {
            "command": "uvx",
            "args": [
                "engrava-mcp"
            ],
            "env": {
                "ENGRAVA_DB_PATH": "<ENGRAVA_DB_PATH>",
                "ENGRAVA_MCP_CONFIG": "<ENGRAVA_MCP_CONFIG>",
                "ENGRAVA_MCP_READ_ONLY": "<ENGRAVA_MCP_READ_ONLY>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from engrava-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "engrava": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "engrava-mcp"
            ],
            "env": {
                "ENGRAVA_DB_PATH": "<ENGRAVA_DB_PATH>",
                "ENGRAVA_MCP_CONFIG": "<ENGRAVA_MCP_CONFIG>",
                "ENGRAVA_MCP_READ_ONLY": "<ENGRAVA_MCP_READ_ONLY>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from engrava-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ENGRAVA_DB_PATH=<ENGRAVA_DB_PATH> -e ENGRAVA_MCP_CONFIG=<ENGRAVA_MCP_CONFIG> -e ENGRAVA_MCP_READ_ONLY=<ENGRAVA_MCP_READ_ONLY> engrava uvx engrava-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from engrava-mcp <command>

## When to use it
- persist agent thoughts across sessions in SQLite
- query past context using MindQL and text search
- link memory nodes inside a thought graph
- run the memory store in read-only mode to prevent edits

## Example prompts
- Save the current architectural decisions to the Engrava memory store
- Query memory using MindQL to find earlier database migration notes
- Inspect graph connections for the AuthController node

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119231
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47577
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43902

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md