wavemind 2.2.7__tar.gz → 2.2.8__tar.gz

{wavemind-2.2.7 → wavemind-2.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavemind
-Version: 2.2.7
+Version: 2.2.8
 Summary: Local-first dynamic memory field with vector search and wave-field re-ranking
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/CaspianG/wavemind
@@ -543,10 +543,10 @@ Checked-in result:
 |---|---:|
 | Cluster planner | 4096 namespaces, 4 nodes, replication factor 2, node-loss availability `1.000`, zone-loss availability `1.000`, write quorum `2`. |
 | Hot cache | 2000 lookups, hit rate `0.920`, p99 lookup `0.003 ms`. |
-| Replicated runtime | 3 physical WaveMind stores, replication factor 3, write quorum 2, node-loss recall `true`, repair copied `1` missing record, tombstone repair deleted `1` stale record, p99 query-after-loss `1.29 ms`. |
-| Active-active delta sync | 2 regions, bidirectional convergence `true`, stale import suppressed after delete `true`, tombstone convergence `true`, sync `112.50 ms`. |
-| Replicated snapshot | 3 replica files, manifest checksum validation `true`, restore `11.42 ms`, recall after restored-primary loss `true`. |
-| Structured payloads | image/audio/table/event retrieval, precision@1 `1.000`, p99 `0.67 ms`. |
+| Replicated runtime | 3 physical WaveMind stores, replication factor 3, write quorum 2, node-loss recall `true`, repair copied `1` missing record, tombstone repair deleted `1` stale record, p99 query-after-loss `1.35 ms`. |
+| Active-active delta sync | 2 regions, bidirectional convergence `true`, stale import suppressed after delete `true`, tombstone convergence `true`, sync `103.42 ms`. |
+| Replicated snapshot job | 3 replica files, manifest checksum validation `true`, offsite mirror validation `true`, restore `7.10 ms`, recall after restored-primary loss `true`. |
+| Structured payloads | image/audio/table/event retrieval, precision@1 `1.000`, p99 `0.59 ms`. |
 
 This profile validates routing, quorum-replicated runtime behavior, cache
 behavior, active-active namespace delta sync, replicated snapshot/restore, and
@@ -575,16 +575,18 @@ should still use a production database or service layer.
 
 The same planner is available over HTTP as `POST /cluster-plan`.
 
-Maintenance worker:
+Maintenance workers:
 
 ```sh
 wavemind maintenance --namespace user:42 --consolidate-steps 10 --consolidate-concepts --json
+wavemind replicated-snapshot --root ./state/replicas --node node-a --node node-b --node node-c --out ./backups/replicated --offsite ./offsite/replicated --keep-last 7 --json
 ```
 
-This runs one deterministic maintenance pass: expired-memory purge, optional
-field/concept consolidation, and index-health repair. Production deployments can
-call the same command from cron, systemd, Kubernetes CronJobs, Celery, RQ, or
-Temporal.
+The first command runs one deterministic memory pass: expired-memory purge,
+optional field/concept consolidation, and index-health repair. The second
+command creates a verified replicated snapshot, mirrors it to an offsite path,
+and applies retention. Production deployments can call these commands from
+cron, systemd, Kubernetes CronJobs, Celery, RQ, or Temporal.
 
 Hot-cache options:
 
@@ -674,7 +676,7 @@ backup command.
 Replicated runtime snapshot/restore:
 
 ```python
-from wavemind import HashingTextEncoder, ReplicatedWaveMind
+from wavemind import HashingTextEncoder, ReplicatedSnapshotWorker, ReplicatedWaveMind
 
 memory = ReplicatedWaveMind(
     root_path="./state/replicas",
@@ -684,20 +686,43 @@ memory = ReplicatedWaveMind(
 )
 memory.remember("Tenant A prefers short support replies.", namespace="tenant:a")
 
-snapshot = memory.snapshot("./backups/replicated")
-assert ReplicatedWaveMind.verify_snapshot(snapshot.snapshot_path)["healthy"]
+snapshot_job = ReplicatedSnapshotWorker(memory).run_once(
+    destination="./backups/replicated",
+    offsite_destination="./offsite/replicated",
+    keep_last=7,
+)
+assert snapshot_job.ok
 
 restored, report = ReplicatedWaveMind.restore_snapshot(
-    snapshot.snapshot_path,
+    snapshot_job.offsite_path,
     "./state/restored-replicas",
     encoder=HashingTextEncoder(vector_dim=64),
 )
 ```
 
-The replicated snapshot writes one SQLite backup per replica plus
+The replicated snapshot job writes one SQLite backup per replica plus
 `manifest.json` with SHA-256 checksums, replica metadata, quorum settings, and
-node definitions. Restore refuses to overwrite a non-empty root unless
-`overwrite=True` is passed.
+node definitions. It can mirror the snapshot to a second path for offsite
+backup and applies `keep_last` retention locally and offsite. Restore refuses to
+overwrite a non-empty root unless `overwrite=True` is passed.
+
+Equivalent CLI:
+
+```sh
+wavemind replicated-snapshot \
+  --root ./state/replicas \
+  --node node-a --node node-b --node node-c \
+  --out ./backups/replicated \
+  --offsite ./offsite/replicated \
+  --keep-last 7 \
+  --json
+
+wavemind replicated-restore \
+  --from ./offsite/replicated/wavemind-replicated-20260705-120000 \
+  --to ./state/restored-replicas \
+  --overwrite \
+  --json
+```
 
 ## HTTP API
 
@@ -1072,7 +1097,7 @@ Current read:
 | LongMemEval 50-query smoke | On the first 50 non-abstention LongMemEval-S questions, WaveMind reaches `evidence_recall@5 0.920`, `precision@1 0.760`, and `MRR@5 0.827`; Chroma/Qdrant static reach `0.600`, `0.260`, and `0.385`. | This is the fast regression profile for checking current changes before rerunning the full LongMemEval profile. WaveMind wins on quality; latency still needs work. |
 | ANN/index curve | At 50000 generated 128-d vectors, NumPy exact keeps `recall@10 1.000` at `6.49 ms`; quantized int8 keeps `0.934` at `24.92 ms`; Annoy is faster at `4.92 ms` but drops to `0.730` recall; Qdrant local keeps `1.000` recall at `43.49 ms`. | Current local scale boundary is clear: quantized search needs kernel work, Annoy needs tuning/FAISS, and Qdrant should be tested in service mode for a fair production comparison. |
 | Production load | At 100000 generated 128-d vectors, service-mode Qdrant reaches `recall@10 1.000`, avg `10.28 ms`, p99 `21.26 ms`. At 1M, tuned Qdrant reaches `recall@10 0.984`, avg `116.80 ms`, p99 `209.28 ms`; an EF sweep finds `recall@10 0.977`, avg `64.76 ms`, p99 `103.77 ms` at `hnsw_ef=2048` on 30 queries. | 100k is production-grade on the tested machine. 1M recall is now strong, but p99 still needs tuning before claiming a stable sub-100 ms SLO. |
-| Scale readiness | Deterministic 1M-memory simulation validates 4096 namespace placements over 4 nodes with replication factor 2, node-loss availability `1.000`, zone-loss availability `1.000`, hot-cache hit rate `0.920`, quorum-replicated runtime recall after node loss, missing-record repair, tombstone repair, active-active delta sync, checksummed replicated snapshot/restore, and structured payload precision@1 `1.000`. | This proves routing, cache, payload, replicated-runtime, namespace-delta, and restore-drill foundations. It is not a 10M-vector latency claim; real 10M latency still needs service-backed load tests on larger hardware. |
+| Scale readiness | Deterministic 1M-memory simulation validates 4096 namespace placements over 4 nodes with replication factor 2, node-loss availability `1.000`, zone-loss availability `1.000`, hot-cache hit rate `0.920`, quorum-replicated runtime recall after node loss, missing-record repair, tombstone repair, active-active delta sync, checksummed replicated snapshot/restore, offsite snapshot verification, and structured payload precision@1 `1.000`. | This proves routing, cache, payload, replicated-runtime, namespace-delta, offsite backup, and restore-drill foundations. It is not a 10M-vector latency claim; real 10M latency still needs service-backed load tests on larger hardware. |
 | Memory competitor adapters | WaveMind reaches `precision@1 0.80`, `precision@3 1.00`, stale suppression `1.00` on the small adapter profile. Mem0, Zep, and LangGraph are listed as skipped unless their real packages/services are configured. | This prevents fake competitor claims. The adapter harness is ready; real Mem0/Zep/LangGraph results still need configured installs. |
 | LongMemEval local answer generation | With the same local Ollama `qwen2.5:1.5b`, WaveMind reaches `exact_match 0.240`, `contains_answer 0.380`, `token_f1 0.333`, and `evidence_recall@5 0.920`; Chroma and Qdrant static both reach `0.120`, `0.160`, `0.170`, and `0.600`. | This is the first checked-in end-to-end answer benchmark against Chroma/Qdrant. It is still a 50-question lightweight smoke run, not a full LongMemEval leaderboard score. |
 
@@ -1091,7 +1116,7 @@ Current read:
 | Production index profile | Docker-backed 50000-vector profile for persisted FAISS, Qdrant service, and PostgreSQL/pgvector HNSW. | implemented | FAISS / Qdrant service / pgvector | Keep service-mode candidate generation above `0.95` recall@10 and below 10 ms average query latency at 50000 vectors. |
 | Production load profile | 100k and 1M service-backed candidate-index checks with p95/p99 latency. | implemented | Qdrant service / pgvector HNSW / FAISS persisted | Keep 100k at recall@10 `1.000`; push 1M p99 below 100 ms with recall@10 >= 0.95. |
 | Qdrant 1M HNSW ef sweep | One 1M Qdrant collection queried with multiple `hnsw_ef` values. | implemented | Qdrant service | Repeat with 100+ queries and collection-level HNSW build parameters before claiming a stable 1M SLO. |
-| Scale readiness profile | Cluster placement, node/zone-loss simulation, quorum report, replicated runtime, active-active delta sync, replicated snapshot/restore, hot-cache behavior, and structured/multimodal payload retrieval. | implemented | Mem0 / Zep / LangGraph persistent memory / GraphRAG target adapters | Keep quorum replication, namespace-delta sync, repair, and restore drills green while adding larger service-backed 10M load tests. |
+| Scale readiness profile | Cluster placement, node/zone-loss simulation, quorum report, replicated runtime, active-active delta sync, replicated snapshot/restore with offsite verification, hot-cache behavior, and structured/multimodal payload retrieval. | implemented | Mem0 / Zep / LangGraph persistent memory / GraphRAG target adapters | Keep quorum replication, namespace-delta sync, repair, offsite backup, and restore drills green while adding larger service-backed 10M load tests. |
 | Memory competitor adapter profile | Dynamic-memory scenario wired for external memory frameworks. | implemented | Mem0 / Zep / LangGraph persistent memory | Report real competitor results only when their packages/services are explicitly configured. |
 | [BEIR](https://github.com/beir-cellar/beir) | Standard zero-shot information retrieval quality. | planned | Chroma / Qdrant / FAISS | Stay within 0.02 `nDCG@10` on identical embeddings. |
 | [MTEB Retrieval](https://github.com/embeddings-benchmark/mteb) | Separates encoder quality from retrieval-store quality. | planned | Chroma / Qdrant / FAISS | Prove WaveMind does not reduce same-embedding retrieval quality. |
@@ -1224,7 +1249,7 @@ For HA-style local or service-mode deployments, `ReplicatedWaveMind` writes each
 namespace to a deterministic replica set and enforces read/write quorum:
 
 ```python
-from wavemind import ReplicatedWaveMind
+from wavemind import ReplicatedSnapshotWorker, ReplicatedWaveMind
 
 memory = ReplicatedWaveMind(
     root_path="./state/wavemind-replicas",
@@ -1265,21 +1290,26 @@ region_b.import_namespace_delta(region_a.export_namespace_delta("tenant:a"))
 The delta contains active records plus tombstones. Import is idempotent and
 tombstone-aware, so a stale region export cannot resurrect a deleted memory.
 
-For operational recovery, `snapshot()` creates a checksummed replicated snapshot
-and `restore_snapshot()` restores it into a fresh replica root:
+For operational recovery, `ReplicatedSnapshotWorker` creates a checksummed
+replicated snapshot, verifies an optional offsite mirror, and
+`restore_snapshot()` restores it into a fresh replica root:
 
 ```python
-snapshot = memory.snapshot("./backups/replicated")
-health = ReplicatedWaveMind.verify_snapshot(snapshot.snapshot_path)
+job = ReplicatedSnapshotWorker(memory).run_once(
+    destination="./backups/replicated",
+    offsite_destination="./offsite/replicated",
+    keep_last=7,
+)
 restored, report = ReplicatedWaveMind.restore_snapshot(
-    snapshot.snapshot_path,
+    job.offsite_path,
     "./state/restored-replicas",
 )
 ```
 
-The checked-in scale-readiness profile verifies manifest checksums, restores
-three replica files, then disables the restored primary and confirms the memory
-is still recalled from the remaining replicas.
+The checked-in scale-readiness profile verifies manifest checksums, verifies the
+offsite mirror, restores three replica files from that offsite mirror, then
+disables the restored primary and confirms the memory is still recalled from the
+remaining replicas.
 
 Checked-in official LoCoMo retrieval result:
 
@@ -1669,9 +1699,10 @@ Near-term priorities:
   OpenClaw, and HTTP-only sidecar use.
 - Faster dynamic re-ranking through smaller candidate windows, caching, and
   background updates.
-- Better production operations: OpenTelemetry is optional and implemented;
-  richer latency histograms, index-health metrics, alerting examples, scheduled
-  offsite snapshots, and Postgres PITR runbooks are next.
+- Better production operations: OpenTelemetry and replicated offsite snapshot
+  jobs are implemented; richer latency histograms, index-health metrics,
+  alerting examples, object-store upload adapters, and Postgres PITR runbooks
+  are next.
 
 Longer-term direction:
 

{wavemind-2.2.7 → wavemind-2.2.8}/README.md

@@ -490,10 +490,10 @@ Checked-in result:
 |---|---:|
 | Cluster planner | 4096 namespaces, 4 nodes, replication factor 2, node-loss availability `1.000`, zone-loss availability `1.000`, write quorum `2`. |
 | Hot cache | 2000 lookups, hit rate `0.920`, p99 lookup `0.003 ms`. |
-| Replicated runtime | 3 physical WaveMind stores, replication factor 3, write quorum 2, node-loss recall `true`, repair copied `1` missing record, tombstone repair deleted `1` stale record, p99 query-after-loss `1.29 ms`. |
-| Active-active delta sync | 2 regions, bidirectional convergence `true`, stale import suppressed after delete `true`, tombstone convergence `true`, sync `112.50 ms`. |
-| Replicated snapshot | 3 replica files, manifest checksum validation `true`, restore `11.42 ms`, recall after restored-primary loss `true`. |
-| Structured payloads | image/audio/table/event retrieval, precision@1 `1.000`, p99 `0.67 ms`. |
+| Replicated runtime | 3 physical WaveMind stores, replication factor 3, write quorum 2, node-loss recall `true`, repair copied `1` missing record, tombstone repair deleted `1` stale record, p99 query-after-loss `1.35 ms`. |
+| Active-active delta sync | 2 regions, bidirectional convergence `true`, stale import suppressed after delete `true`, tombstone convergence `true`, sync `103.42 ms`. |
+| Replicated snapshot job | 3 replica files, manifest checksum validation `true`, offsite mirror validation `true`, restore `7.10 ms`, recall after restored-primary loss `true`. |
+| Structured payloads | image/audio/table/event retrieval, precision@1 `1.000`, p99 `0.59 ms`. |
 
 This profile validates routing, quorum-replicated runtime behavior, cache
 behavior, active-active namespace delta sync, replicated snapshot/restore, and
@@ -522,16 +522,18 @@ should still use a production database or service layer.
 
 The same planner is available over HTTP as `POST /cluster-plan`.
 
-Maintenance worker:
+Maintenance workers:
 
 ```sh
 wavemind maintenance --namespace user:42 --consolidate-steps 10 --consolidate-concepts --json
+wavemind replicated-snapshot --root ./state/replicas --node node-a --node node-b --node node-c --out ./backups/replicated --offsite ./offsite/replicated --keep-last 7 --json
 ```
 
-This runs one deterministic maintenance pass: expired-memory purge, optional
-field/concept consolidation, and index-health repair. Production deployments can
-call the same command from cron, systemd, Kubernetes CronJobs, Celery, RQ, or
-Temporal.
+The first command runs one deterministic memory pass: expired-memory purge,
+optional field/concept consolidation, and index-health repair. The second
+command creates a verified replicated snapshot, mirrors it to an offsite path,
+and applies retention. Production deployments can call these commands from
+cron, systemd, Kubernetes CronJobs, Celery, RQ, or Temporal.
 
 Hot-cache options:
 
@@ -621,7 +623,7 @@ backup command.
 Replicated runtime snapshot/restore:
 
 ```python
-from wavemind import HashingTextEncoder, ReplicatedWaveMind
+from wavemind import HashingTextEncoder, ReplicatedSnapshotWorker, ReplicatedWaveMind
 
 memory = ReplicatedWaveMind(
     root_path="./state/replicas",
@@ -631,20 +633,43 @@ memory = ReplicatedWaveMind(
 )
 memory.remember("Tenant A prefers short support replies.", namespace="tenant:a")
 
-snapshot = memory.snapshot("./backups/replicated")
-assert ReplicatedWaveMind.verify_snapshot(snapshot.snapshot_path)["healthy"]
+snapshot_job = ReplicatedSnapshotWorker(memory).run_once(
+    destination="./backups/replicated",
+    offsite_destination="./offsite/replicated",
+    keep_last=7,
+)
+assert snapshot_job.ok
 
 restored, report = ReplicatedWaveMind.restore_snapshot(
-    snapshot.snapshot_path,
+    snapshot_job.offsite_path,
     "./state/restored-replicas",
     encoder=HashingTextEncoder(vector_dim=64),
 )
 ```
 
-The replicated snapshot writes one SQLite backup per replica plus
+The replicated snapshot job writes one SQLite backup per replica plus
 `manifest.json` with SHA-256 checksums, replica metadata, quorum settings, and
-node definitions. Restore refuses to overwrite a non-empty root unless
-`overwrite=True` is passed.
+node definitions. It can mirror the snapshot to a second path for offsite
+backup and applies `keep_last` retention locally and offsite. Restore refuses to
+overwrite a non-empty root unless `overwrite=True` is passed.
+
+Equivalent CLI:
+
+```sh
+wavemind replicated-snapshot \
+  --root ./state/replicas \
+  --node node-a --node node-b --node node-c \
+  --out ./backups/replicated \
+  --offsite ./offsite/replicated \
+  --keep-last 7 \
+  --json
+
+wavemind replicated-restore \
+  --from ./offsite/replicated/wavemind-replicated-20260705-120000 \
+  --to ./state/restored-replicas \
+  --overwrite \
+  --json
+```
 
 ## HTTP API
 
@@ -1019,7 +1044,7 @@ Current read:
 | LongMemEval 50-query smoke | On the first 50 non-abstention LongMemEval-S questions, WaveMind reaches `evidence_recall@5 0.920`, `precision@1 0.760`, and `MRR@5 0.827`; Chroma/Qdrant static reach `0.600`, `0.260`, and `0.385`. | This is the fast regression profile for checking current changes before rerunning the full LongMemEval profile. WaveMind wins on quality; latency still needs work. |
 | ANN/index curve | At 50000 generated 128-d vectors, NumPy exact keeps `recall@10 1.000` at `6.49 ms`; quantized int8 keeps `0.934` at `24.92 ms`; Annoy is faster at `4.92 ms` but drops to `0.730` recall; Qdrant local keeps `1.000` recall at `43.49 ms`. | Current local scale boundary is clear: quantized search needs kernel work, Annoy needs tuning/FAISS, and Qdrant should be tested in service mode for a fair production comparison. |
 | Production load | At 100000 generated 128-d vectors, service-mode Qdrant reaches `recall@10 1.000`, avg `10.28 ms`, p99 `21.26 ms`. At 1M, tuned Qdrant reaches `recall@10 0.984`, avg `116.80 ms`, p99 `209.28 ms`; an EF sweep finds `recall@10 0.977`, avg `64.76 ms`, p99 `103.77 ms` at `hnsw_ef=2048` on 30 queries. | 100k is production-grade on the tested machine. 1M recall is now strong, but p99 still needs tuning before claiming a stable sub-100 ms SLO. |
-| Scale readiness | Deterministic 1M-memory simulation validates 4096 namespace placements over 4 nodes with replication factor 2, node-loss availability `1.000`, zone-loss availability `1.000`, hot-cache hit rate `0.920`, quorum-replicated runtime recall after node loss, missing-record repair, tombstone repair, active-active delta sync, checksummed replicated snapshot/restore, and structured payload precision@1 `1.000`. | This proves routing, cache, payload, replicated-runtime, namespace-delta, and restore-drill foundations. It is not a 10M-vector latency claim; real 10M latency still needs service-backed load tests on larger hardware. |
+| Scale readiness | Deterministic 1M-memory simulation validates 4096 namespace placements over 4 nodes with replication factor 2, node-loss availability `1.000`, zone-loss availability `1.000`, hot-cache hit rate `0.920`, quorum-replicated runtime recall after node loss, missing-record repair, tombstone repair, active-active delta sync, checksummed replicated snapshot/restore, offsite snapshot verification, and structured payload precision@1 `1.000`. | This proves routing, cache, payload, replicated-runtime, namespace-delta, offsite backup, and restore-drill foundations. It is not a 10M-vector latency claim; real 10M latency still needs service-backed load tests on larger hardware. |
 | Memory competitor adapters | WaveMind reaches `precision@1 0.80`, `precision@3 1.00`, stale suppression `1.00` on the small adapter profile. Mem0, Zep, and LangGraph are listed as skipped unless their real packages/services are configured. | This prevents fake competitor claims. The adapter harness is ready; real Mem0/Zep/LangGraph results still need configured installs. |
 | LongMemEval local answer generation | With the same local Ollama `qwen2.5:1.5b`, WaveMind reaches `exact_match 0.240`, `contains_answer 0.380`, `token_f1 0.333`, and `evidence_recall@5 0.920`; Chroma and Qdrant static both reach `0.120`, `0.160`, `0.170`, and `0.600`. | This is the first checked-in end-to-end answer benchmark against Chroma/Qdrant. It is still a 50-question lightweight smoke run, not a full LongMemEval leaderboard score. |
 
@@ -1038,7 +1063,7 @@ Current read:
 | Production index profile | Docker-backed 50000-vector profile for persisted FAISS, Qdrant service, and PostgreSQL/pgvector HNSW. | implemented | FAISS / Qdrant service / pgvector | Keep service-mode candidate generation above `0.95` recall@10 and below 10 ms average query latency at 50000 vectors. |
 | Production load profile | 100k and 1M service-backed candidate-index checks with p95/p99 latency. | implemented | Qdrant service / pgvector HNSW / FAISS persisted | Keep 100k at recall@10 `1.000`; push 1M p99 below 100 ms with recall@10 >= 0.95. |
 | Qdrant 1M HNSW ef sweep | One 1M Qdrant collection queried with multiple `hnsw_ef` values. | implemented | Qdrant service | Repeat with 100+ queries and collection-level HNSW build parameters before claiming a stable 1M SLO. |
-| Scale readiness profile | Cluster placement, node/zone-loss simulation, quorum report, replicated runtime, active-active delta sync, replicated snapshot/restore, hot-cache behavior, and structured/multimodal payload retrieval. | implemented | Mem0 / Zep / LangGraph persistent memory / GraphRAG target adapters | Keep quorum replication, namespace-delta sync, repair, and restore drills green while adding larger service-backed 10M load tests. |
+| Scale readiness profile | Cluster placement, node/zone-loss simulation, quorum report, replicated runtime, active-active delta sync, replicated snapshot/restore with offsite verification, hot-cache behavior, and structured/multimodal payload retrieval. | implemented | Mem0 / Zep / LangGraph persistent memory / GraphRAG target adapters | Keep quorum replication, namespace-delta sync, repair, offsite backup, and restore drills green while adding larger service-backed 10M load tests. |
 | Memory competitor adapter profile | Dynamic-memory scenario wired for external memory frameworks. | implemented | Mem0 / Zep / LangGraph persistent memory | Report real competitor results only when their packages/services are explicitly configured. |
 | [BEIR](https://github.com/beir-cellar/beir) | Standard zero-shot information retrieval quality. | planned | Chroma / Qdrant / FAISS | Stay within 0.02 `nDCG@10` on identical embeddings. |
 | [MTEB Retrieval](https://github.com/embeddings-benchmark/mteb) | Separates encoder quality from retrieval-store quality. | planned | Chroma / Qdrant / FAISS | Prove WaveMind does not reduce same-embedding retrieval quality. |
@@ -1171,7 +1196,7 @@ For HA-style local or service-mode deployments, `ReplicatedWaveMind` writes each
 namespace to a deterministic replica set and enforces read/write quorum:
 
 ```python
-from wavemind import ReplicatedWaveMind
+from wavemind import ReplicatedSnapshotWorker, ReplicatedWaveMind
 
 memory = ReplicatedWaveMind(
     root_path="./state/wavemind-replicas",
@@ -1212,21 +1237,26 @@ region_b.import_namespace_delta(region_a.export_namespace_delta("tenant:a"))
 The delta contains active records plus tombstones. Import is idempotent and
 tombstone-aware, so a stale region export cannot resurrect a deleted memory.
 
-For operational recovery, `snapshot()` creates a checksummed replicated snapshot
-and `restore_snapshot()` restores it into a fresh replica root:
+For operational recovery, `ReplicatedSnapshotWorker` creates a checksummed
+replicated snapshot, verifies an optional offsite mirror, and
+`restore_snapshot()` restores it into a fresh replica root:
 
 ```python
-snapshot = memory.snapshot("./backups/replicated")
-health = ReplicatedWaveMind.verify_snapshot(snapshot.snapshot_path)
+job = ReplicatedSnapshotWorker(memory).run_once(
+    destination="./backups/replicated",
+    offsite_destination="./offsite/replicated",
+    keep_last=7,
+)
 restored, report = ReplicatedWaveMind.restore_snapshot(
-    snapshot.snapshot_path,
+    job.offsite_path,
     "./state/restored-replicas",
 )
 ```
 
-The checked-in scale-readiness profile verifies manifest checksums, restores
-three replica files, then disables the restored primary and confirms the memory
-is still recalled from the remaining replicas.
+The checked-in scale-readiness profile verifies manifest checksums, verifies the
+offsite mirror, restores three replica files from that offsite mirror, then
+disables the restored primary and confirms the memory is still recalled from the
+remaining replicas.
 
 Checked-in official LoCoMo retrieval result:
 
@@ -1616,9 +1646,10 @@ Near-term priorities:
   OpenClaw, and HTTP-only sidecar use.
 - Faster dynamic re-ranking through smaller candidate windows, caching, and
   background updates.
-- Better production operations: OpenTelemetry is optional and implemented;
-  richer latency histograms, index-health metrics, alerting examples, scheduled
-  offsite snapshots, and Postgres PITR runbooks are next.
+- Better production operations: OpenTelemetry and replicated offsite snapshot
+  jobs are implemented; richer latency histograms, index-health metrics,
+  alerting examples, object-store upload adapters, and Postgres PITR runbooks
+  are next.
 
 Longer-term direction:
 

{wavemind-2.2.7 → wavemind-2.2.8}/benchmarks/BENCHMARK_LEADERBOARD.md

@@ -21,7 +21,7 @@ This is a compact reader-facing view of checked-in benchmark results. It is not
 | Production load profile 100k | production-scale | Recall@k | WaveMind pgvector: 0.736 / 17.8 ms | Qdrant service: 1 / 10.3 ms | Baseline leads on quality |
 | Production load profile 1M | production-scale | Recall@k | - | Qdrant service: 0.984 / 116.8 ms | No WaveMind result |
 | Qdrant 1M HNSW ef sweep | production-scale | Recall@k | - | hnsw_ef=2048: 0.977 / 64.8 ms | No WaveMind result |
-| Scale readiness profile | production-scale | precision@1 | WaveMind structured payloads: 1 / 0.448 ms | - | WaveMind-only check |
+| Scale readiness profile | production-scale | precision@1 | WaveMind structured payloads: 1 / 0.401 ms | - | WaveMind-only check |
 | Memory competitor adapter profile | agent-memory | precision@1 | WaveMind: 0.8 / 0.554 ms | - | WaveMind-only check |
 | [LongMemEval answer generation](https://github.com/xiaowu0162/LongMemEval) | long-term-agent-memory | token F1 | WaveMind + qwen2.5:1.5b: 0.333 / - | Chroma static + qwen2.5:1.5b: 0.17 / - | WaveMind leads on quality |
 

{wavemind-2.2.7 → wavemind-2.2.8}/benchmarks/BENCHMARK_REPORT.md

@@ -24,7 +24,7 @@ Planned rows are not claimed wins. They are the public proof path WaveMind must
 | Production load profile 100k | production-scale | implemented | Qdrant service: Recall@k 1.00, avg latency 10.3, p95 latency 19.0, p99 latency ms 21.3, build ms 27439.3<br>WaveMind pgvector: Recall@k 0.74, avg latency 17.8, p95 latency 23.5, build ms 455703.7<br>WaveMind faiss-persisted: skipped - Set WAVEMIND_FAISS_PATH to use the persisted FAISS backend | Tune pgvector HNSW build/search parameters and add persisted FAISS from the Linux benchmark container. |
 | Production load profile 1M | production-scale | implemented | Qdrant service: Recall@k 0.98, avg latency 116.8, p95 latency 153.8, p99 latency ms 209.3, build ms 450674.6 | Tune Qdrant indexing/search params further, then add FAISS IVF/HNSW and pgvector 1M profiles on a larger disk. |
 | Qdrant 1M HNSW ef sweep | production-scale | implemented | hnsw_ef=512: Recall@k 0.75, avg latency 47.2, p95 latency 68.5, p99 latency ms 68.5, max latency ms 68.5<br>hnsw_ef=768: Recall@k 0.85, avg latency 44.0, p95 latency 69.1, p99 latency ms 69.8, max latency ms 69.8<br>hnsw_ef=1024: Recall@k 0.88, avg latency 62.9, p95 latency 81.1, p99 latency ms 85.5, max latency ms 85.5<br>hnsw_ef=1536: Recall@k 0.94, avg latency 65.6, p95 latency 111.2, p99 latency ms 119.7, max latency ms 119.7<br>hnsw_ef=2048: Recall@k 0.98, avg latency 64.8, p95 latency 91.2, p99 latency ms 103.8, max latency ms 103.8 | Repeat with 100+ queries and collection-level HNSW build parameters before claiming a stable production SLO. |
-| Scale readiness profile | production-scale | implemented | WaveMind cluster planner: simulated memories 1000000, namespaces 4096, nodes 4, replication factor 2, node loss min availability 1.00, zone loss min availability 1.00, read quorum 1, write quorum 2, placement ms 59.2<br>WaveMind hot cache: queries 2000, capacity 512, hit rate 0.92, evictions 0, p99 lookup ms 0.00<br>WaveMind replicated runtime: nodes 3, replication factor 3, write quorum 2, read quorum 1, recalled after node loss True, repair copied records 1, tombstone repair deleted records 1, p99 query after loss ms 1.29<br>WaveMind active-active delta sync: regions 2, replication factor per region 3, records imported 6, converged after bidirectional sync True, suppressed stale import after delete True, tombstone converged True, sync ms 112.5<br>WaveMind replicated snapshot: nodes 3, manifest healthy True, restored files 3, recalled after restore node loss True, snapshot ms 49.2, restore ms 11.4<br>WaveMind structured payloads: queries 4, precision@1 1.00, avg latency 0.45, p99 latency ms 0.67 | Move from local replicated runtime to service-backed replicated runs, scheduled/offsite snapshots, and larger 10M candidate-index load tests. |
+| Scale readiness profile | production-scale | implemented | WaveMind cluster planner: simulated memories 1000000, namespaces 4096, nodes 4, replication factor 2, node loss min availability 1.00, zone loss min availability 1.00, read quorum 1, write quorum 2, placement ms 77.2<br>WaveMind hot cache: queries 2000, capacity 512, hit rate 0.92, evictions 0, p99 lookup ms 0.00<br>WaveMind replicated runtime: nodes 3, replication factor 3, write quorum 2, read quorum 1, recalled after node loss True, repair copied records 1, tombstone repair deleted records 1, p99 query after loss ms 1.35<br>WaveMind active-active delta sync: regions 2, replication factor per region 3, records imported 6, converged after bidirectional sync True, suppressed stale import after delete True, tombstone converged True, sync ms 103.4<br>WaveMind replicated snapshot: nodes 3, manifest healthy True, offsite verified True, restored files 3, recalled after restore node loss True, snapshot ms 69.7, restore ms 7.10<br>WaveMind structured payloads: queries 4, precision@1 1.00, avg latency 0.40, p99 latency ms 0.59 | Move from local replicated runtime to service-backed replicated runs, object-store snapshot adapters, and larger 10M candidate-index load tests. |
 | Memory competitor adapter profile | agent-memory | implemented | WaveMind: precision@1 0.80, precision@3 1.00, stale suppression 1.00, avg latency 0.55, p95 latency 0.83<br>Mem0: skipped - Install Mem0 to run this adapter profile: pip install "mem0ai"<br>Zep: skipped - Install the Zep client package and set ZEP_API_KEY or ZEP_API_URL.<br>LangGraph persistent memory: skipped - Install LangGraph to run this adapter profile: pip install "langgraph" | Add documented setup commands for each competitor adapter and store checked-in results only when those real adapters run. |
 | [LongMemEval answer generation](https://github.com/xiaowu0162/LongMemEval) | long-term-agent-memory | implemented | extractive smoke: queries 20, evidence recall@k 1.00, exact match 0.00, contains answer 0.05, token f1 0.02, avg retrieval ms 3.79, avg generation ms 0.77<br>WaveMind + qwen2.5:0.5b: queries 50, evidence recall@k 0.92, exact match 0.12, contains answer 0.18, token f1 0.18, avg retrieval ms 2.98, avg generation ms 1428.2<br>Chroma static + qwen2.5:0.5b: queries 50, evidence recall@k 0.60, exact match 0.10, contains answer 0.12, token f1 0.13, avg retrieval ms 4.10, avg generation ms 1234.7<br>Qdrant static + qwen2.5:0.5b: queries 50, evidence recall@k 0.60, exact match 0.10, contains answer 0.12, token f1 0.13, avg retrieval ms 63.8, avg generation ms 893.5<br>WaveMind + qwen2.5:1.5b: queries 50, evidence recall@k 0.92, exact match 0.24, contains answer 0.38, token f1 0.33, avg retrieval ms 2.00, avg generation ms 2153.0<br>Chroma static + qwen2.5:1.5b: queries 50, evidence recall@k 0.60, exact match 0.12, contains answer 0.16, token f1 0.17, avg retrieval ms 7.05, avg generation ms 2082.4<br>Qdrant static + qwen2.5:1.5b: queries 50, evidence recall@k 0.60, exact match 0.12, contains answer 0.16, token f1 0.17, avg retrieval ms 100.2, avg generation ms 758.1 | Run all 470 non-abstention questions with a stronger local/API model and add faithfulness/abstention scoring. |
 

{wavemind-2.2.7 → wavemind-2.2.8}/benchmarks/benchmark_matrix_results.json

@@ -764,14 +764,14 @@
           "zone_loss_min_availability": 1.0,
           "read_quorum": 1,
           "write_quorum": 2,
-          "placement_ms": 59.205800003837794
+          "placement_ms": 77.1686999942176
         },
         "WaveMind hot cache": {
           "queries": 2000,
           "capacity": 512,
           "hit_rate": 0.92,
           "evictions": 0,
-          "p99_lookup_ms": 0.002700020559132099
+          "p99_lookup_ms": 0.0030999653972685337
         },
         "WaveMind replicated runtime": {
           "nodes": 3,
@@ -781,7 +781,7 @@
           "recalled_after_node_loss": true,
           "repair_copied_records": 1,
           "tombstone_repair_deleted_records": 1,
-          "p99_query_after_loss_ms": 1.2885000323876739
+          "p99_query_after_loss_ms": 1.35420000879094
         },
         "WaveMind active-active delta sync": {
           "regions": 2,
@@ -790,25 +790,26 @@
           "converged_after_bidirectional_sync": true,
           "suppressed_stale_import_after_delete": true,
           "tombstone_converged": true,
-          "sync_ms": 112.49550001230091
+          "sync_ms": 103.42070000478998
         },
         "WaveMind replicated snapshot": {
           "nodes": 3,
           "manifest_healthy": true,
+          "offsite_verified": true,
           "restored_files": 3,
           "recalled_after_restore_node_loss": true,
-          "snapshot_ms": 49.16400002548471,
-          "restore_ms": 11.4187000435777
+          "snapshot_ms": 69.7173000080511,
+          "restore_ms": 7.101800001692027
         },
         "WaveMind structured payloads": {
           "queries": 4,
           "precision_at_1": 1.0,
-          "avg_latency_ms": 0.44750000233761966,
-          "p99_latency_ms": 0.6680000224150717
+          "avg_latency_ms": 0.40072499541565776,
+          "p99_latency_ms": 0.5899000097997487
         }
       },
-      "target": "Prove the production foundation before heavier 100k, 1M, and 10M vector load tests: deterministic placement, survivable replicas, active-active sync, restore drills, hot-cache behavior, and structured payload recall.",
-      "next_step": "Move from local replicated runtime to service-backed replicated runs, scheduled/offsite snapshots, and larger 10M candidate-index load tests."
+      "target": "Prove the production foundation before heavier 100k, 1M, and 10M vector load tests: deterministic placement, survivable replicas, active-active sync, offsite-verified restore drills, hot-cache behavior, and structured payload recall.",
+      "next_step": "Move from local replicated runtime to service-backed replicated runs, object-store snapshot adapters, and larger 10M candidate-index load tests."
     },
     {
       "id": "memory_competitor_adapter_profile",

{wavemind-2.2.7 → wavemind-2.2.8}/benchmarks/benchmark_registry.py

@@ -765,6 +765,7 @@ def _implemented_entries(root: Path) -> list[dict[str, Any]]:
                     (
                         "nodes",
                         "manifest_healthy",
+                        "offsite_verified",
                         "restored_files",
                         "recalled_after_restore_node_loss",
                         "snapshot_ms",
@@ -781,8 +782,8 @@ def _implemented_entries(root: Path) -> list[dict[str, Any]]:
                     ),
                 ),
             },
-            "target": "Prove the production foundation before heavier 100k, 1M, and 10M vector load tests: deterministic placement, survivable replicas, active-active sync, restore drills, hot-cache behavior, and structured payload recall.",
-            "next_step": "Move from local replicated runtime to service-backed replicated runs, scheduled/offsite snapshots, and larger 10M candidate-index load tests.",
+            "target": "Prove the production foundation before heavier 100k, 1M, and 10M vector load tests: deterministic placement, survivable replicas, active-active sync, offsite-verified restore drills, hot-cache behavior, and structured payload recall.",
+            "next_step": "Move from local replicated runtime to service-backed replicated runs, object-store snapshot adapters, and larger 10M candidate-index load tests.",
         },
         {
             "id": "memory_competitor_adapter_profile",

{wavemind-2.2.7 → wavemind-2.2.8}/benchmarks/scale_readiness_benchmark.py

@@ -19,6 +19,7 @@ from wavemind import (
     HotMemoryCache,
     QueryResult,
     ReplicatedWaveMind,
+    ReplicatedSnapshotWorker,
     WaveMind,
     audio_payload,
     build_cluster_plan,
@@ -335,13 +336,17 @@ def run_replicated_snapshot_profile() -> dict[str, object]:
                 namespace=namespace,
             )
             snapshot_started = time.perf_counter()
-            snapshot = memory.snapshot(root / "snapshots")
+            snapshot_job = ReplicatedSnapshotWorker(memory).run_once(
+                destination=root / "snapshots",
+                offsite_destination=root / "offsite",
+                keep_last=2,
+            )
             snapshot_ms = (time.perf_counter() - snapshot_started) * 1000.0
-            health = ReplicatedWaveMind.verify_snapshot(snapshot.snapshot_path)
+            health = ReplicatedWaveMind.verify_snapshot(snapshot_job.snapshot_path)
 
             restore_started = time.perf_counter()
             restored, restore = ReplicatedWaveMind.restore_snapshot(
-                snapshot.snapshot_path,
+                snapshot_job.offsite_path,
                 root / "restored",
                 width=16,
                 height=16,
@@ -356,9 +361,10 @@ def run_replicated_snapshot_profile() -> dict[str, object]:
             )
             return {
                 "engine": "WaveMind replicated snapshot",
-                "nodes": len(snapshot.nodes),
+                "nodes": len(snapshot_job.nodes),
                 "manifest_healthy": health["healthy"],
-                "total_bytes": snapshot.total_bytes,
+                "offsite_verified": snapshot_job.offsite_verified,
+                "total_bytes": snapshot_job.total_bytes,
                 "snapshot_ms": snapshot_ms,
                 "restore_ms": restore_ms,
                 "restored_files": len(restore.restored_files),
@@ -519,6 +525,7 @@ def main() -> int:
             print(f"| active-active delta | tombstone_converged | {result['tombstone_converged']} |")
         elif result["engine"] == "WaveMind replicated snapshot":
             print(f"| replicated snapshot | manifest_healthy | {result['manifest_healthy']} |")
+            print(f"| replicated snapshot | offsite_verified | {result['offsite_verified']} |")
             print(f"| replicated snapshot | recalled_after_restore_node_loss | {result['recalled_after_restore_node_loss']} |")
         else:
             print(f"| structured payloads | precision@1 | {result['precision_at_1']:.3f} |")

{wavemind-2.2.7 → wavemind-2.2.8}/benchmarks/scale_readiness_results.json

@@ -14,7 +14,7 @@
       "namespaces": 4096,
       "nodes": 4,
       "replication_factor": 2,
-      "placement_ms": 59.205800003837794,
+      "placement_ms": 77.1686999942176,
       "max_replica_load": 2413,
       "min_replica_load": 1728,
       "replica_load_stdev": 316.54462560593254,
@@ -32,8 +32,8 @@
       "capacity": 512,
       "hit_rate": 0.92,
       "evictions": 0,
-      "avg_lookup_ms": 0.0014145502645988017,
-      "p99_lookup_ms": 0.002700020559132099
+      "avg_lookup_ms": 0.0014047000149730593,
+      "p99_lookup_ms": 0.0030999653972685337
     },
     {
       "engine": "WaveMind replicated runtime",
@@ -47,8 +47,8 @@
       "tombstone_suppressed_before_repair": true,
       "tombstone_suppressed_after_repair": true,
       "tombstone_repair_deleted_records": 1,
-      "avg_query_after_loss_ms": 1.2885000323876739,
-      "p99_query_after_loss_ms": 1.2885000323876739
+      "avg_query_after_loss_ms": 1.35420000879094,
+      "p99_query_after_loss_ms": 1.35420000879094
     },
     {
       "engine": "WaveMind active-active delta sync",
@@ -56,7 +56,7 @@
       "replication_factor_per_region": 3,
       "records_imported": 6,
       "converged_after_bidirectional_sync": true,
-      "sync_ms": 112.49550001230091,
+      "sync_ms": 103.42070000478998,
       "suppressed_stale_import_after_delete": true,
       "tombstone_deleted_records": 3,
       "tombstone_converged": true
@@ -65,9 +65,10 @@
       "engine": "WaveMind replicated snapshot",
       "nodes": 3,
       "manifest_healthy": true,
+      "offsite_verified": true,
       "total_bytes": 110592,
-      "snapshot_ms": 49.16400002548471,
-      "restore_ms": 11.4187000435777,
+      "snapshot_ms": 69.7173000080511,
+      "restore_ms": 7.101800001692027,
       "restored_files": 3,
       "recalled_after_restore_node_loss": true
     },
@@ -81,8 +82,8 @@
       ],
       "queries": 4,
       "precision_at_1": 1.0,
-      "avg_latency_ms": 0.44750000233761966,
-      "p99_latency_ms": 0.6680000224150717
+      "avg_latency_ms": 0.40072499541565776,
+      "p99_latency_ms": 0.5899000097997487
     }
   ]
 }

{wavemind-2.2.7 → wavemind-2.2.8}/docker-compose.yml

@@ -4,7 +4,7 @@ services:
       context: .
       args:
         INSTALL_OPTIONAL: "false"
-    image: wavemind:2.2.7
+    image: wavemind:2.2.8
     restart: unless-stopped
     environment:
       WAVEMIND_DB: /data/wavemind.sqlite3

{wavemind-2.2.7 → wavemind-2.2.8}/docs/BENCHMARK_BRIEF.md

@@ -31,7 +31,7 @@ purpose-built vector databases.
 | NoMIRACL Russian retrieval | WaveMind reaches `nDCG@10 0.434`; Chroma reaches `0.435`; Qdrant reaches `0.433`. Chroma is faster. | `benchmarks/nomiracl_russian_results.json` | `python benchmarks/nomiracl_russian_benchmark.py --engines wavemind chroma qdrant --output benchmarks/nomiracl_russian_results.json` |
 | Production index profile | At 50000 vectors, persisted FAISS and Qdrant service both reach `recall@10 1.000`; pgvector with `ef_search=400` reaches `0.811`. | `benchmarks/production_index_profile_results.json` | `docker compose -f examples/production-index-profile/docker-compose.yml run --rm benchmark` |
 | Production load profile | At 100000 vectors, Qdrant service reaches `recall@10 1.000`, avg `10.28 ms`, p99 `21.26 ms`. At 1M vectors, tuned Qdrant reaches `0.984`, avg `116.80 ms`, p99 `209.28 ms`; the best EF-sweep point reaches `0.977`, avg `64.76 ms`, p99 `103.77 ms`. | `benchmarks/production_load_qdrant_100k_tuned_results.json`, `benchmarks/production_load_qdrant_1m_tuned_results.json`, `benchmarks/production_load_qdrant_1m_ef_sweep_results.json` | `python benchmarks/production_load_benchmark.py --sizes 100000 --engines qdrant-service` |
-| Scale readiness profile | Deterministic 1M-memory simulation: namespace placement survives node loss and zone loss at `1.000`, hot-cache hit rate is `0.920`, replicated runtime survives node loss, active-active delta sync converges, replicated snapshot restore survives primary loss, structured payload precision@1 is `1.000`. | `benchmarks/scale_readiness_results.json` | `python benchmarks/scale_readiness_benchmark.py --simulated-memories 1000000 --output benchmarks/scale_readiness_results.json` |
+| Scale readiness profile | Deterministic 1M-memory simulation: namespace placement survives node loss and zone loss at `1.000`, hot-cache hit rate is `0.920`, replicated runtime survives node loss, active-active delta sync converges, replicated snapshot restore survives primary loss, offsite snapshot verification is `true`, structured payload precision@1 is `1.000`. | `benchmarks/scale_readiness_results.json` | `python benchmarks/scale_readiness_benchmark.py --simulated-memories 1000000 --output benchmarks/scale_readiness_results.json` |
 | Memory competitor adapter profile | WaveMind reaches `precision@1 0.80`, `precision@3 1.00`, stale suppression `1.00`; Mem0, Zep, and LangGraph are skipped until real packages/services are configured. | `benchmarks/memory_competitor_results.json` | `python benchmarks/memory_competitor_benchmark.py --engines wavemind mem0 zep langgraph` |
 
 The generated matrix view is in `benchmarks/BENCHMARK_REPORT.md`; the compact