MemKraft 3.2.0

MemKraft 3.2.0

MemKraft 3.2.0 strengthens local-first synchronization without changing what is authoritative. Markdown remains canonical; BM25 remains the default retriever; embeddings remain optional; every new sidecar is derived and disposable.

What changed

• watch now sends create, modify, delete, and move events through explicit path-aware invalidation instead of issuing a dummy search. Moves invalidate both source and destination.
• Each accepted Markdown change appends a compact memkraft.live_sync.change_event/1 envelope and links its event id to provenance. File content is never copied into the event or provenance record.
• live_sync_freshness() and memkraft freshness compare canonical Markdown with in-memory BM25 and any existing optional embedding index. --repair rebuilds derived state from Markdown.
• Existing embedding indexes can update one changed path at a time. Deletes, moves out of the canonical corpus, and files that become empty remove stale vectors. Running watch never creates an embedding index or installs/loads a model unless the optional index already exists.
• The implementation adds no mandatory dependency. watchdog remains behind the existing watch extra and sentence-transformers remains behind the existing embedding extra.

Compatibility and recovery

• No migration command or Markdown rewrite is required.
• .memkraft/live-sync/events.jsonl is lazy-created derived audit state.
• .memkraft/embeddings/index.jsonl remains derived state.
• Deleting .memkraft/ and running memkraft freshness --repair reconstructs supported derived indexes from Markdown. The event history itself is disposable and is not reconstructed.
• Default search and ranking semantics are unchanged.

Validation

• Full local suite: 2,295 passed, 6 skipped after the final concurrency, recovery, path-alias, and release metadata changes.
• Memory Gym: 45 passed. Python 3.9 core validation: 376 passed, 3 skipped.
• Focused live-sync suite: 39 passed, 3 skipped, including create/modify/delete/move, Markdown-to-non-Markdown moves, moves into derived state, corrupt and absent embedding indexes, empty/deleted corpus repair, and incremental/full rebuild equivalence.
• A deterministic 200-document structural benchmark measured one Markdown change as 200 to 1 files read for BM25 and 200 to 1 files encoded for the optional embedding index. On the same local run, indicative wall times were 6.075 ms to 2.005 ms for BM25 and 6.597 ms to 4.470 ms for the fake embedding encoder.

Benchmark limits

The 200-to-1 figures are exact structural work counts for this synthetic one-file-change workload, not universal latency claims. Both paths still stat() the corpus to fingerprint it. Embedding wall time uses a deterministic fake encoder and excludes real model inference. Search quality and recall were not changed, so this release makes no new accuracy claim.

Upgrade

pipx upgrade memkraft    # or: pip install --upgrade memkraft
memkraft --version       # expect 3.2.0
memkraft freshness --json

Rollback is reinstalling 3.1.0. New live-sync and embedding sidecars can be deleted; user Markdown is unchanged.