Upgrade from 0.4 to 0.5

For most applications, upgrading the engrava library itself is a normal package upgrade:

pip install --upgrade engrava

Existing databases are migrated on the first ensure_schema() call. If your application opens the store through SqliteEngravaCore.from_config(), that call is made for you and the schema check runs during startup. The direct constructor, SqliteEngravaCore(conn, ...), does not make it — on that path, await store.ensure_schema() yourself, or run the migration explicitly:

engrava --db my-data.db migrate

Before upgrading

Back up the SQLite database before a minor-version upgrade, especially if several processes share the same store.

sqlite3 my-data.db "PRAGMA wal_checkpoint(TRUNCATE);"
cp my-data.db my-data.db.bak

If the database is in WAL mode and you do not checkpoint first, copy the database together with its -wal and -shm files. For multi-worker deployments, stop old-version writers, let one new-version process run the migration, then start the rest of the new-version workers.

The full OSS upgrade guide has the longer backup and recovery notes: Upgrade Guide.

What changes in 0.5

The core schema changes are additive: 0.5 advances the database schema from user_version = 14 to 18, in four migrations applied on first open. They do not rewrite thoughts, edges, or embeddings.

Step	Adds
14 → 15	the composite `(edge_type, to_thought_id)` edge index
15 → 16	the action-outcome aggregate column and its seek index
16 → 17	the opt-in provenance column and its identity indexes
17 → 18	the Memory Hygiene forgetting-loop columns

The breaking change is limited to MCP-server users: the MCP server no longer ships inside engrava. It now lives in the standalone engrava-mcp package.

Removed from engrava in 0.5:

the engrava[mcp] optional dependency extra
the engrava-mcp console command installed by the engrava package

Migrating MCP setups

If you used the MCP server in 0.4, update the server dependency and client command.

Before 0.5	After 0.5
`pip install "engrava[mcp]"`	`pip install engrava-mcp`
`engrava-mcp` installed by `engrava`	`engrava-mcp` installed by `engrava-mcp`
client command: `engrava-mcp` from the old environment	client command: `uvx engrava-mcp`, or the `engrava-mcp` executable from the new package

Using uvx is the simplest client configuration because it makes the package boundary explicit:

{
  "mcpServers": {
    "engrava": {
      "command": "uvx",
      "args": ["engrava-mcp"],
      "env": {
        "ENGRAVA_MCP_CONFIG": "/absolute/path/to/engrava.yaml"
      }
    }
  }
}

If you prefer a pinned environment, install engrava-mcp there and point the client at that executable:

pip install engrava-mcp
which engrava-mcp

Then use that absolute path as the client command if the client cannot find it on PATH.

MCP configuration stays the same

The store configuration environment variables are unchanged:

Variable	Purpose
`ENGRAVA_MCP_CONFIG`	Path to an `engrava.yaml`; use this for configured embeddings, vector backend, journal, TTL, and other store settings.
`ENGRAVA_DB_PATH`	Path to a bare SQLite database file; useful for simple lexical-only access.
`ENGRAVA_MCP_READ_ONLY`	Set to `true`, `1`, or `yes` to hide write tools.

ENGRAVA_MCP_CONFIG still takes precedence over ENGRAVA_DB_PATH.

Cutover checklist

Back up the database.
Upgrade application dependencies to engrava>=0.5.
Replace engrava[mcp] requirements with engrava-mcp.
Update MCP client config to run uvx engrava-mcp or the new package’s executable.
Keep the same ENGRAVA_MCP_CONFIG or ENGRAVA_DB_PATH.
Start one new-version process first so the schema migration completes.
Do not run the old in-engrava MCP server and the new engrava-mcp package against the same store during the cutover.

For the full server setup after migration, see MCP Server.