Migration Guide

This guide covers the public upgrade path from Zaxy 0.4 through 2.x. Eventloom logs are append-only; migrations should add events, projection metadata, indexes, docs, or compatibility shims instead of rewriting historical records.

Upgrade Checklist

Before and after each upgrade:

1. Back up .eventloom/, projection directories, and any sidecar database.
2. Run zaxy memory status --graph to verify Eventloom integrity and graph projection lag before changing code.
3. Run zaxy doctor --beta-readiness from the target checkout.
4. Rebuild or refresh projections with zaxy refresh-context or zaxy reproject when the release notes mention projection changes.
5. Re-run the documented examples or mission smoke that your integration uses.
6. Capture the final command evidence in Eventloom with verification.recorded or your normal lifecycle capture path.

From 0.4 to 0.5

0.5 reframed the public path around Coordinator Memory for Agent Teams. The memory substrate remains compatible with 0.4 Eventloom logs, but docs and examples now expect the first-run flow to prove install, init, bootstrap, checkout, doctor, and example timing.

Required actions:

• Read the updated getting-started and MCP quickstart docs before changing client configuration.
• Keep existing Eventloom files in place; do not flatten them into markdown or vector-only stores.
• Run zaxy init or the appropriate preset only after confirming it will not overwrite local MCP config unexpectedly.
• Validate public examples with the release smoke path if you package Zaxy for other users.

From 0.5 to 0.6

0.6 introduced the shared native integration contract and stronger MCP response shape checks. Existing MCP clients should keep working, but code that parses checkout metadata should expect the zaxy.native.v0.6 contract in native adapter responses.

Required actions:

• Update LangGraph or CrewAI adapters to read the zaxy.native.v0.6 metadata envelope instead of relying on ad hoc keys.
• Prefer memory_bootstrap, memory_checkout, and context_assemble for model-facing state instead of assembling prompt memory manually.
• Check docs/examples/mcp-tool-contract.json and docs/examples/mcp-response-snapshots.json when updating client tests.
• Run the MCP and native example smoke tests after changing integration code.

From 0.6 to 0.7

0.7 added Zaxy Coordinate mission workflows. This is additive for single-agent memory users, but multi-agent clients should move from informal transcript-only coordination to explicit mission, worker, assignment, finding, review, promotion, approval, checkout, and handoff events.

Required actions:

• Use Coordinate APIs or MCP tools for team state instead of storing accepted findings as unstructured transcript text.
• Inspect migrated mission state with zaxy coordinate inspect.
• Preserve finding evidence and review decisions so promoted memory remains auditable.
• If you use benchmark claims, regenerate CoordinationBench reports from tracked workloads instead of local scratch files.

From 0.7 to 0.8

0.8 added outside-MCP model-call wrappers and provider-neutral trace export. These paths are optional; MCP remains the framework-neutral integration route.

Required actions:

• Use the OpenAI-compatible or Claude-compatible adapters only when model calls happen directly in application code and you want checkout injection there.
• Keep model-call capture opt-in and bounded. Do not record raw provider secrets or full private request bodies in Eventloom.
• Use zaxy trace export when a run needs replay-derived mission, checkout, model-call, tool-call, review, promotion, or handoff correlation without a tracing vendor.
• Use zaxy replay --from-seq and --to-seq for bounded inspection of long sessions rather than splitting or rewriting logs.

From 1.0 to 1.1

1.1 adds StateRecoveryBench and replay-derived Coordinate accepted-state resolution. This is additive for existing memory users, but Coordinate clients should treat parent-promoted accepted state as the only answerable mission state by default.

Required actions:

• Use zaxy state-recovery-benchmark for accepted-state recovery claims. zaxy experimental state-recovery remains a research/debug command.
• Keep benchmark claims scoped to the production memory_fabric_checkout baseline. Associative projection rows are diagnostic only.
• If a client consumes Coordinate proof packets, expect accepted_finding_ids, review refs, promotion refs, worker source refs, and non-authoritative row labels to come from one replay-derived resolver.
• Preserve review and promotion events in the parent mission session; worker findings alone are diagnostic until promoted.

From 0.8 to 0.9

0.9 was the API freeze candidate. The main migration task is to compare your client usage with docs/api-inventory.md and remove dependencies on surfaces marked Internal. Surfaces marked Experimental can remain in prototypes, but they should not be required for a production 1.0 rollout.

Required actions:

• Compare MCP tools, Python imports, CLI commands, Eventloom event types, projection backend usage, and benchmark artifacts against docs/api-inventory.md.
• For Stable or Beta surfaces, add compatibility tests before changing payload keys, command options, event names, or report schemas.
• Treat pgGraph and LatticeDB backend use as experimental unless the current release gate explicitly promotes them.
• Do not make public benchmark claims from untracked Eventloom, query, or diagnostics files.

From 0.9 to 2.0

The frozen v0.9 surfaces carry forward; 1.x and 2.0 changes are additive or follow the freeze policy in docs/api-inventory.md. Notable upgrade items:

• The PyPI distribution is zaxy-memory; the import package and console command remain zaxy.
• 1.1.x adopted Eventloom v1 JSONL envelopes while preserving legacy log replay; see the changelog for envelope details.
• 2.0 added causal memory contracts, review-gated consolidation, and reasoning-loop primitives as new (additive) surfaces.
• Benchmark and evaluation modules moved out of the runtime package into zaxy_benchmarks; production imports of zaxy.*benchmark* modules should be removed (they were Internal/Experimental surfaces).

From 2.0 to 2.1+

The 2.1–2.3 agent-experience and cognitive-memory surfaces are entirely additive — no Eventloom envelope changes, no projection migrations, no removed or renamed tools — but 2.1.0 flips two defaults, each promoted by its measurement lane per the roadmap:

1. MCP_TOOL_PROFILE defaults to core (was full). The internal tool-adoption lane measured the listed tool surface at 8,165 → 1,344 estimated tokens (an 83.5% reduction) with memory_checkout listed first. Profiles change listing only; dispatch is never filtered, so every tool stays callable by name. Opt out: MCP_TOOL_PROFILE=full (or zaxy serve --profile full). Affected: clients that snapshot tool listings or pin the listed-tool count — refresh snapshots or pin full.
2. RETRIEVAL_PROFILE defaults to cognitive (was local_fast). The internal forgetting lane measured exact cold-start parity (zero-reinforcement corpora rank byte-identically to plain), no-recall-loss 1.0 (attenuated memories stay reachable by explicit query, labeled in diagnostics), pin/authority exemptions 1.0, and ranking lift 1.0 vs 0.0. The cognitive profile composes the same local retrieval stack as local_fast plus the salience-ranking, cue-blending, and graph-walk flags. Opt out: RETRIEVAL_PROFILE=local_fast for the previous plain default. Affected: users with reinforcement history or graph structure the walk can traverse may see ranking shifts; cold-start users (no reinforcement events) see identical ranking. Settings that leave the profile unset but explicitly customize embedding/reranker/scoring knobs keep resolving to the custom profile exactly as before the flip.

Unchanged defaults: the write-time encoding gate stays off (ENCODING_GATE_ENABLED=false, unmeasured) and vector quantization stays none. One default moved defensively: VECTOR_ANN_THRESHOLD rose from 50000 to 1000000 because the internal vector-scale lane measured the HNSW path below exact search on both recall and latency at 10^5 vectors — the raise prevents auto-engaging a measured-worse path; lower it explicitly to opt in. The feeling-of-knowing surface remains experimental (its calibration lane Brier margin over the base-rate predictor is +0.001–0.006 — too thin for promotion). Beyond the two flips above, existing clients upgrade without action; everything below is opt-in.

New settings (all documented in configuration.md):

• MCP_TOOL_PROFILE (core default since 2.1.0, or full): MCP tool listing profile. core lists only the front-door verb set; profiles change listing, never capability — every tool stays callable by name.
• SALIENCE_HALF_LIFE_DAYS (default 30.0): recency-decay half-life for the salience reinforcement ledger.
• SALIENCE_FLOOR (default 0.15): attenuation floor under the cognitive retrieval profile; below-floor memories leave default checkout ranking but remain reachable by explicit query.
• ENCODING_GATE_ENABLED (default false): tag appends as novel/reinforcing/redundant; events are always appended and hash-chained regardless.
• VECTOR_ANN_THRESHOLD (default 1000000 in 2.1.0, lowered to 100000 in 2.2 — see the 2.2 subsection below): per-scope vector count at which the embedded backend uses an engine-native HNSW index; results from the approximate path report exact: false.
• VECTOR_QUANTIZATION (none default, or int8): opt-in quantized vector storage with exact float rerank of oversampled candidates.

New MCP tools (additive; no existing tool was removed or renamed):

• memory_feeling_of_knowing: experimental metamemory pre-check, listed in the core profile; each call appends a non-authoritative metacognition.fok.predicted calibration marker.
• memory_consolidation(operation, ...) and memory_confidence(operation, ...): umbrella tools over the existing consolidation and confidence/metacognition handlers; the single-purpose tool names remain available per the stability commitment.

Both profiles now list memory_checkout first, and every core-profile tool description names checkout as the front door. Clients that snapshot tool listings or descriptions should refresh against docs/examples/mcp-tool-contract.json.

New CLI surfaces:

• zaxy serve --profile core|full overrides MCP_TOOL_PROFILE per process.
• zaxy memory checkout --max-tokens N (and the max_tokens argument on the memory_checkout and context_assemble MCP tools) applies a token budget with greedy packing; diagnostics report budget_requested, budget_used, and elided, plus stable_prefix_chars for the cache-stable consolidated prefix.
• zaxy memory mine-procedures mines recurring successful tool sequences into review-pending procedure candidates; nothing becomes authoritative without consolidation review.
• zaxy memory re-embed batch-migrates projected vectors to the active embedding provider version tag; Eventloom events are never rewritten.
• zaxy hook-event session-resumed records hook.session_resumed and prints a cited compaction-recovery packet; see hooks.md.
• zaxy agent-experience-lanes runs the internal tool-adoption, budget, and cache lanes (internal validation labels only; not public claims).

New event kinds and payload conventions (additive Eventloom payloads):

• memory.reinforcement with kind: surfaced | confirmed | promoted | invalidated, batched target event refs, and a source id; salience is fully rebuildable by replaying these events.
• metacognition.fok.predicted: non-authoritative feeling-of-knowing calibration markers.
• hook.session_resumed: post-compaction resume lifecycle events.
• Payload conventions: an optional cues mapping (mission, workspace, tool, phase) for encoding-specificity blending, an encoding tag written only when the gate is enabled, and "pinned": true to exempt a memory from the attenuation floor.

The cognitive retrieval profile (the default since 2.1.0) enables salience-blended ranking, cue-overlap blending, and personalized-PageRank graph-walk retrieval over the unchanged immutable log. Attenuation is projection policy only — labeled in diagnostics.attenuation, exempting pinned and authority-bearing memories, and reversible by switching to RETRIEVAL_PROFILE=local_fast. See retrieval.md. The lean core tool listing is likewise the default since 2.1.0; restore the full listing with MCP_TOOL_PROFILE=full or zaxy serve --profile full; memory_capabilities reports the active profile and the available-but-unlisted tools.

2.2: ANN engagement defaults

2.2 changes when the embedded backend's HNSW vector path engages — nothing else in the upgrade path changes. VECTOR_ANN_THRESHOLD drops from 1000000 to 100000, gated by a new dimension ceiling VECTOR_ANN_MAX_DIMENSION (default 64), and engagement gains a second clause: within the ceiling, a (session, version) vector scope also engages ANN when its exact float64 matrix (count × dimension × 8 bytes) would exceed the 256 MiB vector index cache byte budget — above 524,288 rows at dimension 64. The lowered count default is backed by two consecutive vector-scale lane passes at exactly 10^5 vectors (dimension 64) with recall@10 of 1.0 on both the strict and tie-aware metrics, ANN p50 at-or-better than exact in-run, and resident bytes improved (docs/research/artifacts/ann-2026-06/ann3-d64-100k-r1.json/-r2.json); the ceiling is that evidence's measured envelope — at dimension 1536/50k gaussian the lane measured HNSW recall@10 of 0.6 against exact at 22ms p50 (ann3-d1536-50k-gauss-crossover.json; 0.6344 on a rerun, and 0.8438 at efs 800 with worse-than-exact latency), so higher-dimensional scopes stay on exact (or opted-in int8) search regardless of size. Opt out: VECTOR_ANN_THRESHOLD=1000000 restores the 2.1 count behavior, and VECTOR_ANN_BYTE_BUDGET_ENGAGEMENT=false disables the byte clause; a single over-budget exact matrix stays resident as a cache of one (the budget bounds multi-scope cache totals). An explicit VECTOR_QUANTIZATION=int8 opt-in keeps its precedence below the count threshold and is exempt from the byte clause. memory_capabilities reports the effective rule under vector_search.

From 2.2 to 2.3: embedded engine moves to LadybugDB

2.3 replaces the embedded projection engine. The Kuzu project was archived upstream in October 2025 with 0.11.3 as its final release: it already ships no macOS or Windows wheels for Python 3.14, and no Python 3.15 wheels will ever exist (3.15 lands ~October 2026), so staying was a countdown, not an option — there is no opt-out. Zaxy now exact-pins LadybugDB (ladybug==0.17.1), the actively maintained fork of the same engine. The adoption was gated on re-running Zaxy's own defect reproductions and the full vector-scale and graph-walk lanes against the fork.

What changes for you:

• Storage format. LadybugDB cannot read a projection file written by the pre-fork engine. On first open of an old embedded.kuzu, Zaxy automatically moves it (and its .wal) aside to <path>.pre-ladybug.bak — no data is deleted — opens a fresh store at the same path, and logs the rebuild instructions. Projections are derived state: replay full history with zaxy reproject <eventloom log>, or let new checkins project incrementally. zaxy doctor reports a leftover .pre-ladybug.bak with a remediation line; it is safe to delete once the rebuilt projection is verified. Eventloom logs — the source of truth — are untouched.
• Paths stay put. The default projection path remains .eventloom/projections/embedded.kuzu; the extension is cosmetic and changing the default would orphan configured paths.
• Dependency. pip install "zaxy-memory" now pulls ladybug==0.17.1 instead of kuzu. The pin is exact on purpose (single-maintainer fork; every defect verdict was verified against this version) — and pins the ladybug PyPI name, not the stale pre-rename real-ladybug.
• Behavior. Query semantics, schema, retrieval results, and the ANN engagement defaults are unchanged; the vector index code is unchanged since the fork, and the 2.3 lane reruns reproduced the 2.2 deterministic blocks (identical corpus hashes and recall). Superseded ANN shadow generations are now dropped instead of emptied (full space reclaim, enabled by an upstream fix verified through Zaxy's own rebuild cycle).
• Vector extension fetch (local-first, one-time). Kuzu 0.11.3 bundled the vector index; LadybugDB ships it as an official vector extension fetched on first use (a small one-time download cached under ~/.lbdb), much like installing the package itself. Zaxy fetches it automatically the first time the ANN path engages, then it runs entirely on-box. Air-gapped deployments that want ANN run INSTALL vector once on a networked host and ship the ~/.lbdb cache; with no network and no cache, approximate (HNSW) search is simply unavailable and retrieval falls back to exact float search — correct results, no error, fully on-box. The default exact path is pure NumPy and needs nothing fetched.

Compatibility Tests

The compatibility suite should prove that old public behavior still works or that a migration path is documented:

• MCP schema tests compare advertised tool names and input schemas.
• Response snapshot tests cover memory_bootstrap, memory_checkout, memory_query, memory_verbatim, context_assemble, memory_feedback, and coordination checkout outputs.
• Event and graph tests cover hash-chain replay, projection provenance, invalidation, temporal versions, inferred-edge metadata, and source citations.
• CLI tests cover release smoke, beta readiness, replay windows, trace export, Coordinate inspection, and schema migration planning.
• Benchmark guardrail tests reject reports without tracked inputs, query diagnostics, citation coverage, latency budgets, and fingerprint validation.

When a compatibility break is intentional, update this guide, the changelog, the API inventory, and the narrow test that proves the old behavior is rejected or migrated. For stable or beta surfaces listed in docs/examples/v1-schema-freeze.json, record the change with schema.migration.proposed before implementation and schema.migration.applied after verification.

Rollback Policy

Rollback should restore code and projections without rewriting Eventloom:

• Revert the application code or package version.
• Restore projection directories or sidecar database snapshots if projection schema changed.
• Keep new Eventloom records as audit history. If a fact is no longer valid, append memory_invalidate or a superseding typed event.
• Run zaxy memory status --graph after rollback to confirm the log and graph agree.
• Record rollback verification with verification.recorded so future checkout can cite the operational decision.

Related references: api-inventory.md, testing.md, runbook.md, and README.md.