engrava — Claude Code MCP server: what it does, how to install
An MCP server that gives AI agents a persistent SQLite memory database. It enables hybrid retrieval, MindQL queries, and a thought graph over stdio.
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-mcpWhat engrava 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.
What it helps with
- 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 for the agent
- 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
How to install engrava
Platform CLI
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-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from engrava-mcp <command>
Platform CLI
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-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from engrava-mcp <command>
Config file
{
"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>
Config file
{
"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>
Platform CLI
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-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from engrava-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about engrava
How to install engrava in Claude Code?
Run claude mcp add engrava -e ENGRAVA_DB_PATH=<ENGRAVA_DB_PATH> -- uvx engrava-mcp in your terminal. To provide an embedding configuration, pass ENGRAVA_MCP_CONFIG pointing to your YAML file as well.
What does engrava do?
It runs an MCP server that exposes Engrava's persistent agent memory. Agents can store thoughts, query them via MindQL, and navigate contextual graph edges.
Why is semantic search inactive with just ENGRAVA_DB_PATH?
A bare database path does not declare an embedding provider. Vector scoring requires an engrava.yaml supplied through the ENGRAVA_MCP_CONFIG environment variable.
