MESA Core · v0.9.3

Upgrade to v0.9.3

v0.9.3 source: docs/RUNBOOK.md

This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.

Purpose and boundaries#

Back up offline before a forward migration. V4 requires an explicit combined owner and optional model processing; V3 uses a separate root. Old graph/vector/temporal capability names have narrower replacements. Restore the retained backup into a new empty target for rollback; do not downgrade an in-place migrated root.

Continue with the maintained contracts#

Use the pinned source reference below for complete tables and operator details. Related guides: architecture, API, operations and release limits.

Back up the old root, record its schema/embedding identity and use the v0.9.3 locked environment. The retained source appendix describes the earlier v0.8.0 upgrade; it is historical migration guidance. Review local credentials, optional model/graph flags and whole-document revision semantics before upgrading.

Existing v0.9.1 ingestion indexes#

Normal startup applies migration e6f7a8b9c0d1. Stop the single storage owner and take a complete offline backup before upgrading. Follow backup and restore and single-owner recovery. Upgrade with the verified PyPI package using pip install --upgrade mesa-memory==0.9.3; see installation. Set MESA_CHUNKING=plain and MESA_RRF_VECTOR_WEIGHT=1 for previous chunk planning on new revisions and previous vector weighting. Existing ACTIVE revisions are unchanged.

bash
pip install --upgrade mesa-memory==0.9.3

Review changed defaults on upgrade#

MESA_EXTRACTION_ENABLED now defaults to false independently of models. Set it explicitly to true to retain open-ended model-based SPO extraction. Legal rules default to true; MESA_LEGAL_RULES_ENABLED=false disables new legal enrichment and legal search overlays without deleting stored identities/snapshots. Existing ACTIVE revisions are not re-extracted by a settings change. Review the configuration and release limits before restarting the single storage owner.

v0.9.3 embedding identity and startup#

The default is MESA_EMBEDDING_MODEL=local:BAAI/bge-m3, MESA_EMBEDDING_DIMENSION=1024, normalized. Models remain off by default. Download the local model before enabling it. For an older store created with the previous default, keep both settings below, or rebuild before changing identity:

bash
MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m
MESA_EMBEDDING_DIMENSION=768

Startup rejects MESA_TIER3_MODE=1/2 without an active consolidation loop; extraction must be enabled. Bootstrap MESA_API_KEY values containing . are rejected at startup.

Verified sources
Source reference for this page

The sections of the upstream file that back this page, translated to English where the original mixes in Turkish. The GitHub link shows the exact original.

Upgrading to v0.8.0#

The pinned source describes package metadata 0.9.3 before its publication. The v0.8.1 publication was owner-approved with the limitations in

the release notes; it does not certify production

readiness. Confirm actual tags in GitHub Releases. This guide describes changes

since v0.7.1, not a completed production migration.

v0.8.1 retains the v0.8.0 schema head below. It adds storage/retrieval hardening

and developer-experience fixes; it introduces no new schema migration. The

existing embedding identity, offline upgrade and backup requirements still apply.

Preconditions and changed contracts#

Use a stopped, backed-up storage root and rehearse on a new disposable root.

Record source commit, lockfile, provider/model/revision/dimension/normalization,

Alembic head, artifacts and rollback path. RBAC has its own schema version.

Since v0.7.1, the tree includes immutable revision manifest activation, opaque

physical catalog identity, declared/manifest/chunk hash separation, durable

rebuild operations/generations, provider identity, assertion FTS/representation

and typed legal identity migrations. Current source expects Alembic head

d5e6f7a8b9c0. Do not assume an old database is compatible just because the

package version stayed 0.7.1 throughout the development branch.

New insertion/reprojection uses assertion-semantic-v1; migrated old vectors

are legacy-v0 and cannot contribute as current semantic evidence. Reindex via

the supported full offline rebuild. Unknown legacy provider

identity can be adopted only with external proof and a fresh unclaimed pending

operation. Matching dimensions alone do not prove matching embedding spaces.

Search/context carry temporal and jurisdiction filters; graph ON/OFF ablation

and bounded diagnostics are available. Context has atomic proof packing and an

opt-in adaptive mode. HTTP insert supports typed legal identity, while SDK

insert does not currently expose it. Invalid/frozen/idempotency-conflicting

source identity fails rather than silently overwriting. Semantic REJECTED

replay returns 409 NON_REPLAYABLE.

Migration configuration#

mesa_storage/alembic.ini owns the migration database URL.

MESA_STORAGE_ROOT alone does not change that URL. With all writers stopped,

prepare a reviewed copy of the Alembic configuration with an absolute staging

SQLite URL and absolute script_location pointing to this release's migrations:

bash
.venv/bin/alembic -c /srv/mesa/reviewed-staging-alembic.ini upgrade head

The path is an operator example, not a configuration supplied by the repository.

Use a verified restored staging root and the matching release environment.

This migrates canonical V4 schema; the projection runner

rebuilds its derived stores. Neither procedure is a general V3 content converter.

V3 content needs explicit source/catalog mapping and V4 ingestion into a separate root.

Upgrade and rollback sequence#

  1. Drain work, stop writers and take a checksummed backup under the writer-lock boundary.
  2. Validate the backup and restore to a new empty staging root.
  3. Apply forward migrations offline with the supported release environment.
  4. Rebuild derived projections where required; check scope, provenance and parity.
  5. Rehearse start, insert, poll, search, restart and negative authorization.
  6. Cut over only with full release evidence and retain previous roots/generations.

Alembic downgrade is not the rollback strategy. Restore a verified prior backup

into a new empty root using the matching prior code/config, then validate before

switching traffic. V3 and V4 never share writable physical storage. Do not alter

official certification evidence as part of upgrade verification.