MemKraft 3.1.0

MemKraft 3.1.0

MemKraft 3.1.0 is a minor release focused on canonical truth performance. Reading
compiled truth for a subject no longer rescans the full canonical event log once
per compiled row, so current_truth() stays usable as an event store grows. No
public API, storage format, or read semantic changes.

What changed

• current_truth() now builds one per-call event signature index and looks
  each compiled truth row up in it, instead of rescanning all events for every
  row. This reduces the dominant path from quadratic toward linear in the number
  of canonical events.
• The signature covers exactly the fields the previous equality scan compared
  (key, value, source, valid_from, provenance), canonicalising nested
  lists and dicts so dict key order does not affect matching.
• The legacy equality scan is preserved as a fallback. If any compared value
  resists canonicalisation (unhashable or otherwise unsupported), the read falls
  back to the original literal scan for that read, so behaviour is unchanged
  rather than approximated.
• compile_truth() reads deny policies once per call instead of re-reading
  them for every candidate event.

Tombstone resolution, deny-policy enforcement, and fail-closed handling of
corrupt snapshots are unchanged.

Benchmark methodology

Local, deterministic, single-process measurement of the derived-view read path.

• Workload: one subject with N unique-key canonical events, compiled once.
• Cold: first current_truth() read from a freshly constructed instance
  (snapshot caches empty).
• Warm: immediate second current_truth() read on the same instance.
• Comparison: identical workload and machine, before vs. after the change;
  the only variable is the derived_views implementation.
• Shape: matches the in-repo cold/warm harness benchmarks/derived_views_bench.py,
  which reports cold_current_truth_ms and warm_current_truth_ms per size.

No model provider, network call, or API key is involved: this path is
deterministic local computation over on-disk JSONL.

Results

3,000 events:

read	before	after	speedup	latency reduction
cold	429.7 ms	12.8 ms	33.5×	97.0%
warm	422.6 ms	5.4 ms	78.4×	98.7%

8,000 events (confirmed final run):

read	before	after	speedup	latency reduction
cold	3520.191 ms	38.021 ms	92.6×	98.9%
warm	2961.463 ms	17.471 ms	169.5×	99.4%

The gap between the two sizes is the expected signature of the complexity
change: the larger store benefits more.

Safety and compatibility

• No destructive migration. Existing .memkraft/ directories are read as-is.
• Existing public APIs, on-disk storage layout, and read behaviour remain
  compatible.
• Deny policies still suppress denied keys; partial tombstones still keep a
  duplicate-backed row visible; full tombstones still hide it.
• Corrupt event, policy, or compiled snapshots still fail closed.
• Search ranking and recall were not changed by this release.

Validation

• Full local suite: 2,256 passed / 3 skipped, with 258 pre-existing warnings.
• Focused compatibility tests cover duplicate identical events, partial and full
  tombstones, deny policies, compiled rows whose source event is missing, corrupt
  event/policy/compiled snapshots, nested list and dict values with
  order-independent dict equality, and Python scalar equality such as
  False == 0 and 1 == 1.0.
• A scan-counting test asserts current_truth() does not rescan the event
  snapshot per compiled row, and a second test asserts compile_truth() reads
  deny policies once per call.
• Opus 5 release audit: implementation and compatibility coverage confirmed; its
  only pre-release blocker was resolved by including this release-note file in
  the release commit.

Upgrade

pipx upgrade memkraft    # or: pip install --upgrade memkraft
memkraft --version       # expect 3.1.0

No migration command, re-compilation, or data rewrite is required. Existing
compiled truth files remain valid.

Limitations

• The measurements above are local workload evidence from one machine and one
  synthetic single-subject shape. They are not universal latency claims:
  absolute timings depend on hardware, filesystem, store shape, subject count,
  and value size.
• No external LLM/provider benchmark applies to this release. The change is
  deterministic local derived-view computation with no model in the path, so
  provider accuracy or p95 tables would not measure it.
• Recall and ranking quality are untouched here; this release makes no new
  accuracy claim, and prior benchmark results are neither re-run nor restated as
  validation of this change.
• Stores containing values that resist canonicalisation fall back to the legacy
  scan and will not see the speedup for the affected reads.
• The optimisation targets the compiled-truth read path. Write, compaction, and
  search paths are unchanged.