MESA Core · v0.9.3
Upgrade to v0.9.3
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.
pip install --upgrade mesa-memory==0.9.3Review 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:
MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m
MESA_EMBEDDING_DIMENSION=768Startup 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.
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:
.venv/bin/alembic -c /srv/mesa/reviewed-staging-alembic.ini upgrade headThe 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#
- Drain work, stop writers and take a checksummed backup under the writer-lock boundary.
- Validate the backup and restore to a new empty staging root.
- Apply forward migrations offline with the supported release environment.
- Rebuild derived projections where required; check scope, provenance and parity.
- Rehearse start, insert, poll, search, restart and negative authorization.
- 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.
