MemoryKG v0.6.0

Release Notes — v0.6.0

Released: 2026-07-09

This release makes Phase 2 embedding memory-bounded. A large-corpus build that previously peaked at 25–32 GB and stalled on MPS around 230k rows now completes with a flat ~4 GB footprint — same wall-clock, identical retrieval recall. If you have ever watched a big ingest balloon memory or hang mid-embed, this is the fix.

What changed

The memory fix. Transformer attention memory scales with batch × seq², and the encode batch defaulted to 1024 — so a single model.encode call on long chunks allocated 7–9 GB. Right-sizing the encode batch to 128 (throughput is flat above ~128 on both CPU and MPS, so this costs nothing) cuts peak RAM ~7×. Nodes are now streamed from SQLite rather than materialised in RAM, and SIMILAR_TO discovery uses a pre-allocated contiguous matrix instead of a Python list-of-lists.

Leaner, faster build loop. The embed path is now a straight stream — page → encode → buffer → write. A batch of GPU-oriented "drift" mitigations (adaptive/fixed embedder refresh, batch-shrink, per-window cache clearing) has been removed; they were compensating for the oversized batch and, on MPS, actively dragged throughput down by reloading the model every window.

Shared embedder + one device knob. The embedder is consolidated onto kg_utils.embedder (single source of truth for model loading and device handling), and device selection is unified on KG_EMBED_DEVICE (DOCKG_DEVICE is retired). Requires kgmodule-utils>=0.4.6, which carries the same 128 default so the dependency can't regress the fix.

Search recall preserved. search() remains an exact flat cosine scan — recall stays exact, which the benchmark suites depend on. Verified on LongMemEval: recall@30 1.000 / @10 0.992, unchanged.

Upgrading

No action required for existing graphs — the index is derived and can be rebuilt at any time. Rebuilds will simply use less memory. On Apple Silicon, embedding auto-selects MPS (~9× faster than CPU); pin the device with KG_EMBED_DEVICE=cpu|mps|cuda if you need to. If you were setting DOCKG_DEVICE, switch to KG_EMBED_DEVICE.

---

Full changelog: CHANGELOG.md

MemoryKG v0.5.3

Release Notes — v0.5.3

Released: 2026-07-09

A maintenance release covering CI and packaging hygiene, and the first release archived to Zenodo now that the GitHub–Zenodo integration is enabled. There are no functional code changes since v0.5.2.

What changed

CI badge repaired. The README status badge pointed at publish.yml, which was renamed to release.yml — so it 404'd and never rendered on GitHub. It now points at the real ci.yml workflow.

Runner deprecation cleared. Both workflows were bumped to actions/checkout@v5 and actions/setup-python@v6, moving off the deprecated Node 20 runtime onto Node 24.

Repository hygiene. The dist/ ignore (previously commented out) is now active, so built wheels and sdists — which the release workflow rebuilds and attaches to each GitHub Release — are no longer tracked in git.

Upgrading

Nothing to do. No API, dependency, or behavioural changes since v0.5.2; reinstall only if you want the refreshed metadata.

---

Full changelog: CHANGELOG.md

MemoryKG v0.5.2

Release Notes — v0.5.2

Released: 2026-07-09

This is the first tagged release since v0.4.1 and folds in everything from the untagged 0.5.0/0.5.1 line. The headline is a stability fix: memorykg build no longer crashes intermittently with a native segfault during the parse phase. Alongside it, this release lands a large benchmark suite, a toolchain modernization, and centralized embedding-model configuration shared across the KG ecosystem.

What changed

Build no longer segfaults. parse_corpus ran an 8-thread pool in which every worker shared a single SentenceTransformer/torch embedder. Under the default semantic chunking strategy those threads called encode() on that one model concurrently, corrupting the native heap (malloc: pointer being freed was not allocated → SIGSEGV) — nondeterministically, so some builds succeeded and others crashed. The parse now runs serially whenever a shared embedder is in use, matching the sister repo doc_kg. Threaded parsing is retained for the embedder-free strategies (fixed/heading/sentence_group), where the per-file work is pure Python and safe to parallelize.

A full benchmark program. New harnesses and academic writeups for MemBench (87.7% recall@k20), ConvoMem (corrected 96.3% tier-1 recall, +3.4 pp over MemPal), and a MemoryKG-native LoCoMo benchmark (98.1% session recall). A prior ConvoMem scoring bug that inflated recall to 100% — an empty node_text counted as a substring match — was fixed, and the results and articles were regenerated with honest numbers.

Toolchain modernization. The type checker migrated from mypy to Astral's ty, pylint was dropped in favour of ruff (which already enforces the equivalent PLE/PLW rules), and snapshotting moved off the deprecated kg_snapshot package onto kg_utils.snapshots. Embedding-model configuration (DEFAULT_MODEL, model-path resolution) is now centralized in kg_utils.embed, and the default model is BAAI/bge-small-en-v1.5 (384-d) across both the core build and the pipeline.

Packaging. The cross-KG siblings (pycode-kg, doc-kg) are now optional manual installs rather than a resolved extra — pinning them forced Poetry to reconcile their newer transformers requirement against this project's cap and left the lock unbuildable. The transformers constraint was relaxed to >=4.40.0,<4.57, and --version now reports the correct memory-kg distribution name.

Upgrading

No API changes and no migration required. Reinstall to pick up the fix and the relaxed dependency bounds:

pip install -e ".[dev]"     # or: poetry install --all-extras

The cross-KG sibling integrations are no longer installed automatically — add them explicitly if you use them (pip install pycode-kg doc-kg). Existing .memorykg/ indices remain compatible; rebuild with memorykg build --wipe only if you want to regenerate from scratch.

---

Full changelog: CHANGELOG.md

v0.4.1 — ConvoMem 100% retrieval recall

MemoryKG v0.4.1

Released: 2026-04-25

This is the first release of MemoryKG that consolidates two independent benchmark wins, polished documentation, and a competitive narrative.

Headline result: ConvoMem 100% retrieval recall

MemoryKG achieves 100% retrieval recall on the ConvoMem benchmark — every evidence message found, on every question, across 17,463 items spanning all six evidence categories (User Facts, Assistant Facts, Abstention, Implicit Connections, Preferences, Changing Facts) and all four evaluated tiers (1–4 messages).

This is the largest non-LLM evaluation on ConvoMem reported. It outperforms the closest verbatim-storage baseline (MemPal at 92.9% overall) by +7.1 pp, with the largest gains on the categories where vocabulary mismatch is hardest: Preferences (+14.0 pp), Implicit Connections (+10.7 pp), and Abstention (+9.0 pp).

A full academic write-up ships in this release: benchmarks/convomem/convomem_article.pdf.

Standing result: tied for top LLM-free on LongMemEval-S

On LongMemEval-S, MemoryKG is tied for the top LLM-free score at 98.4% Recall@5 / 99.4% Recall@10 / 0.943 NDCG@10. With the sibling boost enabled, recall_all@10 reaches 98.6% — every required session retrieved for 493 of 500 questions, with no LLM at any stage.

Compatibility

No API or schema changes. Drop-in replacement for v0.4.0.

Reproducing the headline result

poetry run python3 benchmarks/convomem/convomem_bench.py --limit 1000 --tier 1
poetry run python3 benchmarks/convomem/convomem_bench.py --limit 1000 --tier 2
poetry run python3 benchmarks/convomem/convomem_bench.py --limit 1000 --tier 3
poetry run python3 benchmarks/convomem/convomem_bench.py --limit 1000 --tier 4
# Expected: 100% retrieval recall on every category × tier (17,463 items, ~20 min on Apple Silicon)

---

Full file-by-file changes: CHANGELOG.md