wavemind 2.2.6__tar.gz → 2.2.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavemind
-Version: 2.2.6
+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
@@ -542,16 +542,17 @@ Checked-in result:
 | profile | 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.01 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.33 ms`. |
-| Active-active delta sync | 2 regions, bidirectional convergence `true`, stale import suppressed after delete `true`, tombstone convergence `true`, sync `120.19 ms`. |
-| Structured payloads | image/audio/table/event retrieval, precision@1 `1.000`, p99 `0.62 ms`. |
+| 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.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, and structured payload handling.
-It is not a 10M-vector load test. Real 100k, 1M, and 10M latency claims should
-come from service-backed FAISS/Qdrant/pgvector load tests on production-like
-hardware.
+behavior, active-active namespace delta sync, replicated snapshot/restore, and
+structured payload handling. It is not a 10M-vector load test. Real 100k, 1M,
+and 10M latency claims should come from service-backed FAISS/Qdrant/pgvector
+load tests on production-like hardware.
 
 Cluster placement planning:
 
@@ -574,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:
 
@@ -670,6 +673,57 @@ For Postgres storage, use database-native backup tooling such as `pg_dump`,
 managed snapshots, or point-in-time recovery instead of WaveMind's SQLite file
 backup command.
 
+Replicated runtime snapshot/restore:
+
+```python
+from wavemind import HashingTextEncoder, ReplicatedSnapshotWorker, ReplicatedWaveMind
+
+memory = ReplicatedWaveMind(
+    root_path="./state/replicas",
+    nodes=["node-a", "node-b", "node-c"],
+    replication_factor=3,
+    encoder=HashingTextEncoder(vector_dim=64),
+)
+memory.remember("Tenant A prefers short support replies.", namespace="tenant:a")
+
+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_job.offsite_path,
+    "./state/restored-replicas",
+    encoder=HashingTextEncoder(vector_dim=64),
+)
+```
+
+The replicated snapshot job writes one SQLite backup per replica plus
+`manifest.json` with SHA-256 checksums, replica metadata, quorum settings, and
+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
 
 Run the local FastAPI server:
@@ -1043,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, and structured payload precision@1 `1.000`. | This proves routing, cache, payload, replicated-runtime, and namespace-delta 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. |
 
@@ -1062,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, hot-cache behavior, and structured/multimodal payload retrieval. | implemented | Mem0 / Zep / LangGraph persistent memory / GraphRAG target adapters | Keep quorum replication, namespace-delta sync, and repair 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. |
@@ -1195,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",
@@ -1236,6 +1290,27 @@ 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, `ReplicatedSnapshotWorker` creates a checksummed
+replicated snapshot, verifies an optional offsite mirror, and
+`restore_snapshot()` restores it into a fresh replica root:
+
+```python
+job = ReplicatedSnapshotWorker(memory).run_once(
+    destination="./backups/replicated",
+    offsite_destination="./offsite/replicated",
+    keep_last=7,
+)
+restored, report = ReplicatedWaveMind.restore_snapshot(
+    job.offsite_path,
+    "./state/restored-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:
 
 10 conversations, 5882 memory turns, 1977 evidence-labeled questions,
@@ -1584,8 +1659,9 @@ If you already use Chroma for local memory, see the practical migration guide:
 - The dynamic benchmark currently compares WaveMind against a static Chroma baseline. Chroma and Qdrant can implement similar behavior with extra application-layer metadata policy, deletes, filters, and reinforcement logic.
 - `MemoryFieldGraph` is a discrete graph over stored memories, not a continuous mathematical field. Its current build path should be optimized with incremental edge updates before large production use.
 - pgvector is a candidate-index backend. PostgreSQL source-of-truth storage is
-  also available separately, but migrations, PITR docs, and service benchmark
-  profiles still need more real deployment coverage.
+  also available separately, but migrations, PITR docs, scheduled backup
+  runbooks, and service benchmark profiles still need more real deployment
+  coverage.
 - The Qdrant backend is also a candidate-index backend. WaveMind rebuilds it
   from SQLite on load/build, so large service-mode deployments still need a
   measured rebuild strategy and index-health monitoring.
@@ -1623,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, and
-  restore drills 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.6 → wavemind-2.2.8}/README.md

@@ -489,16 +489,17 @@ Checked-in result:
 | profile | 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.01 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.33 ms`. |
-| Active-active delta sync | 2 regions, bidirectional convergence `true`, stale import suppressed after delete `true`, tombstone convergence `true`, sync `120.19 ms`. |
-| Structured payloads | image/audio/table/event retrieval, precision@1 `1.000`, p99 `0.62 ms`. |
+| 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.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, and structured payload handling.
-It is not a 10M-vector load test. Real 100k, 1M, and 10M latency claims should
-come from service-backed FAISS/Qdrant/pgvector load tests on production-like
-hardware.
+behavior, active-active namespace delta sync, replicated snapshot/restore, and
+structured payload handling. It is not a 10M-vector load test. Real 100k, 1M,
+and 10M latency claims should come from service-backed FAISS/Qdrant/pgvector
+load tests on production-like hardware.
 
 Cluster placement planning:
 
@@ -521,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:
 
@@ -617,6 +620,57 @@ For Postgres storage, use database-native backup tooling such as `pg_dump`,
 managed snapshots, or point-in-time recovery instead of WaveMind's SQLite file
 backup command.
 
+Replicated runtime snapshot/restore:
+
+```python
+from wavemind import HashingTextEncoder, ReplicatedSnapshotWorker, ReplicatedWaveMind
+
+memory = ReplicatedWaveMind(
+    root_path="./state/replicas",
+    nodes=["node-a", "node-b", "node-c"],
+    replication_factor=3,
+    encoder=HashingTextEncoder(vector_dim=64),
+)
+memory.remember("Tenant A prefers short support replies.", namespace="tenant:a")
+
+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_job.offsite_path,
+    "./state/restored-replicas",
+    encoder=HashingTextEncoder(vector_dim=64),
+)
+```
+
+The replicated snapshot job writes one SQLite backup per replica plus
+`manifest.json` with SHA-256 checksums, replica metadata, quorum settings, and
+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
 
 Run the local FastAPI server:
@@ -990,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, and structured payload precision@1 `1.000`. | This proves routing, cache, payload, replicated-runtime, and namespace-delta 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. |
 
@@ -1009,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, hot-cache behavior, and structured/multimodal payload retrieval. | implemented | Mem0 / Zep / LangGraph persistent memory / GraphRAG target adapters | Keep quorum replication, namespace-delta sync, and repair 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. |
@@ -1142,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",
@@ -1183,6 +1237,27 @@ 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, `ReplicatedSnapshotWorker` creates a checksummed
+replicated snapshot, verifies an optional offsite mirror, and
+`restore_snapshot()` restores it into a fresh replica root:
+
+```python
+job = ReplicatedSnapshotWorker(memory).run_once(
+    destination="./backups/replicated",
+    offsite_destination="./offsite/replicated",
+    keep_last=7,
+)
+restored, report = ReplicatedWaveMind.restore_snapshot(
+    job.offsite_path,
+    "./state/restored-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:
 
 10 conversations, 5882 memory turns, 1977 evidence-labeled questions,
@@ -1531,8 +1606,9 @@ If you already use Chroma for local memory, see the practical migration guide:
 - The dynamic benchmark currently compares WaveMind against a static Chroma baseline. Chroma and Qdrant can implement similar behavior with extra application-layer metadata policy, deletes, filters, and reinforcement logic.
 - `MemoryFieldGraph` is a discrete graph over stored memories, not a continuous mathematical field. Its current build path should be optimized with incremental edge updates before large production use.
 - pgvector is a candidate-index backend. PostgreSQL source-of-truth storage is
-  also available separately, but migrations, PITR docs, and service benchmark
-  profiles still need more real deployment coverage.
+  also available separately, but migrations, PITR docs, scheduled backup
+  runbooks, and service benchmark profiles still need more real deployment
+  coverage.
 - The Qdrant backend is also a candidate-index backend. WaveMind rebuilds it
   from SQLite on load/build, so large service-mode deployments still need a
   measured rebuild strategy and index-health monitoring.
@@ -1570,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, and
-  restore drills 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.6 → 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.837 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.6 → 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 115.8<br>WaveMind hot cache: queries 2000, capacity 512, hit rate 0.92, evictions 0, p99 lookup ms 0.00<br>WaveMind structured payloads: queries 4, precision@1 1.00, avg latency 0.84, p99 latency ms 1.07 | Move from single-node service profiles to namespace sharding and replicated service runs. |
+| 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.6 → wavemind-2.2.8}/benchmarks/benchmark_matrix_results.json

@@ -741,7 +741,7 @@
       "category": "production-scale",
       "status": "implemented",
       "source": "benchmarks/scale_readiness_benchmark.py",
-      "dataset": "Deterministic 1M-memory simulation for namespace placement plus hot-cache and structured-payload retrieval checks.",
+      "dataset": "Deterministic 1M-memory simulation for namespace placement, quorum runtime, active-active delta sync, replicated snapshot/restore, hot-cache, and structured-payload retrieval checks.",
       "competitors": [
         "Mem0",
         "Zep",
@@ -764,24 +764,52 @@
           "zone_loss_min_availability": 1.0,
           "read_quorum": 1,
           "write_quorum": 2,
-          "placement_ms": 115.80999998841435
+          "placement_ms": 77.1686999942176
         },
         "WaveMind hot cache": {
           "queries": 2000,
           "capacity": 512,
           "hit_rate": 0.92,
           "evictions": 0,
-          "p99_lookup_ms": 0.003500026650726795
+          "p99_lookup_ms": 0.0030999653972685337
+        },
+        "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.35420000879094
+        },
+        "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.42070000478998
+        },
+        "WaveMind replicated snapshot": {
+          "nodes": 3,
+          "manifest_healthy": true,
+          "offsite_verified": true,
+          "restored_files": 3,
+          "recalled_after_restore_node_loss": true,
+          "snapshot_ms": 69.7173000080511,
+          "restore_ms": 7.101800001692027
         },
         "WaveMind structured payloads": {
           "queries": 4,
           "precision_at_1": 1.0,
-          "avg_latency_ms": 0.8370749856112525,
-          "p99_latency_ms": 1.0724000167101622
+          "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, hot-cache behavior, and structured payload recall.",
-      "next_step": "Move from single-node service profiles to namespace sharding and replicated service runs."
+      "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.6 → wavemind-2.2.8}/benchmarks/benchmark_registry.py

@@ -702,7 +702,7 @@ def _implemented_entries(root: Path) -> list[dict[str, Any]]:
             "category": "production-scale",
             "status": "implemented",
             "source": "benchmarks/scale_readiness_benchmark.py",
-            "dataset": "Deterministic 1M-memory simulation for namespace placement plus hot-cache and structured-payload retrieval checks.",
+            "dataset": "Deterministic 1M-memory simulation for namespace placement, quorum runtime, active-active delta sync, replicated snapshot/restore, hot-cache, and structured-payload retrieval checks.",
             "competitors": ["Mem0", "Zep", "LangGraph persistent memory", "GraphRAG"],
             "metrics": [
                 "node_loss_min_availability",
@@ -735,6 +735,43 @@ def _implemented_entries(root: Path) -> list[dict[str, Any]]:
                         "p99_lookup_ms",
                     ),
                 ),
+                "WaveMind replicated runtime": _metric_summary(
+                    scale_readiness_results.get("WaveMind replicated runtime"),
+                    (
+                        "nodes",
+                        "replication_factor",
+                        "write_quorum",
+                        "read_quorum",
+                        "recalled_after_node_loss",
+                        "repair_copied_records",
+                        "tombstone_repair_deleted_records",
+                        "p99_query_after_loss_ms",
+                    ),
+                ),
+                "WaveMind active-active delta sync": _metric_summary(
+                    scale_readiness_results.get("WaveMind active-active delta sync"),
+                    (
+                        "regions",
+                        "replication_factor_per_region",
+                        "records_imported",
+                        "converged_after_bidirectional_sync",
+                        "suppressed_stale_import_after_delete",
+                        "tombstone_converged",
+                        "sync_ms",
+                    ),
+                ),
+                "WaveMind replicated snapshot": _metric_summary(
+                    scale_readiness_results.get("WaveMind replicated snapshot"),
+                    (
+                        "nodes",
+                        "manifest_healthy",
+                        "offsite_verified",
+                        "restored_files",
+                        "recalled_after_restore_node_loss",
+                        "snapshot_ms",
+                        "restore_ms",
+                    ),
+                ),
                 "WaveMind structured payloads": _metric_summary(
                     scale_readiness_results.get("WaveMind structured payloads"),
                     (
@@ -745,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, hot-cache behavior, and structured payload recall.",
-            "next_step": "Move from single-node service profiles to namespace sharding and replicated service runs.",
+            "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",