zaxy-memory 2.2.0__tar.gz → 2.3.0__tar.gz

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable Zaxy release changes are recorded here.
 
+## 2.3.0 - 2026-06-13
+
+- Moved the default embedded projection engine from archived Kuzu to
+  exact-pinned LadybugDB (`ladybug==0.17.1`), the maintained fork of the same
+  engine lineage. This keeps the local-first graph runtime on a wheel stream
+  that supports current Python releases while preserving the existing
+  `PROJECTION_BACKEND=embedded` contract.
+- Added derived-projection migration handling for pre-LadybugDB stores:
+  unreadable pre-fork projection files are moved aside to
+  `<path>.pre-ladybug.bak` without deleting data, a fresh projection store is
+  opened at the configured path, and operators are pointed to replay/reproject
+  from Eventloom, which remains the source of truth.
+- Re-verified and updated embedded vector-index handling against LadybugDB:
+  the store installs (once, network-cached under `~/.lbdb`) and loads the
+  `vector` extension — which LadybugDB ships as a downloadable extension
+  rather than bundling it as Kuzu did — keeps the unbound-parameter guard at
+  the execution choke point, continues atomic ANN generation swaps, and now
+  drops superseded ANN generations for full space reclaim where the fork
+  fixed the old drop-index corruption.
+- Local-first note: LadybugDB ships the vector index as a `vector` extension
+  fetched once on first ANN engagement (cached under `~/.lbdb`) and then run
+  entirely on-box, rather than bundled as Kuzu did. With no network and no
+  cache, ANN is unavailable and retrieval falls back to exact float search
+  (correct results, no error); the default exact path needs nothing fetched.
+  Air-gapped ANN deployments pre-install the extension and ship the cache.
+  See migration.md.
+- Added doctor coverage for leftover pre-LadybugDB backup artifacts so
+  operators can verify the rebuilt projection and remove obsolete backups
+  intentionally.
+- Refreshed current docs, API inventory, operational guidance, and packaging
+  tests to describe embedded LadybugDB as the default runtime while preserving
+  historical Kuzu references in archives and research artifacts.
+- Fixed an Eventloom v1 integrity edge case where replay and tail reads could
+  disagree on a tampered Zaxy-authored v1 event id. Replay now uses the sealed
+  sequence encoded in the v1 id consistently, so integrity verification reports
+  the same event identity that tail reads expose.
+
 ## 2.2.0 - 2026-06-11
 
 - Re-engineered the embedded ANN vector path end to end, every change backed

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zaxy-memory
-Version: 2.2.0
+Version: 2.3.0
 Summary: Coordinator memory for auditable multi-agent projects
 Project-URL: Homepage, https://syndicalt.github.io/zaxy/
 Project-URL: Documentation, https://syndicalt.github.io/zaxy/docs/getting-started.html
@@ -8,7 +8,7 @@ Project-URL: Repository, https://github.com/syndicalt/zaxy
 Project-URL: Issues, https://github.com/syndicalt/zaxy/issues
 Author: Zaxy Contributors
 License: MIT
-Keywords: agent-memory,auditable-memory,coordinator-memory,embedded-memory,event-sourcing,knowledge-graph,kuzu,local-first,mcp,multi-agent,temporal-graph
+Keywords: agent-memory,auditable-memory,coordinator-memory,embedded-memory,event-sourcing,knowledge-graph,ladybugdb,local-first,mcp,multi-agent,temporal-graph
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: kuzu>=0.11.0
+Requires-Dist: ladybug==0.17.1
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: numpy>=1.26.0
 Requires-Dist: prometheus-client>=0.20.0
@@ -75,13 +75,13 @@ review, approval packets, and accepted merge-back into one durable history that
 can be queried, replayed, and inspected.
 
 Under the hood, Zaxy uses Eventloom append-only JSONL as the source of truth and
-an embedded Kuzu graph projection for local reasoning. It is built for agents
+an embedded LadybugDB graph projection for local reasoning. It is built for agents
 that need to remember what happened, cite where it came from, and avoid turning
 project state into a pile of markdown files and vector chunks.
 
-The embedded Kuzu graph projection is the default local runtime.
+The embedded LadybugDB graph projection is the default local runtime.
 
-The plain install uses embedded Kuzu. Install `zaxy-memory[neo4j]` only for the
+The plain install uses embedded LadybugDB. Install `zaxy-memory[neo4j]` only for the
 optional Neo4j sidecar, and `zaxy-memory[pathlight]` only for Pathlight tracing.
 
 ## Why It Matters
@@ -89,7 +89,7 @@ optional Neo4j sidecar, and `zaxy-memory[pathlight]` only for Pathlight tracing.
 - **Auditable memory**: every accepted fact can point back to Eventloom history.
 - **Agent-team coordination**: parent and worker sessions stay isolated until
   findings are reviewed and merged.
-- **Local-first runtime**: the default path uses embedded Kuzu, no Neo4j sidecar.
+- **Local-first runtime**: the default path uses embedded LadybugDB, no Neo4j sidecar.
 - **MCP-native integration**: Codex, Claude Code, Cursor, VS Code, Hermes Agent,
   LangGraph, CrewAI, and AutoGen can use the same memory interface.
 - **External benchmark evidence**: on the full Harvey LAB legal-agent memory
@@ -193,7 +193,7 @@ Agent (LangGraph / Any MCP Client)
 MCP Server — memory_append / memory_query / memory_feedback / memory_replay / memory_invalidate
     |
     v
-Eventloom (immutable JSONL log)  →  Hybrid Extraction  →  Embedded Kuzu graph
+Eventloom (immutable JSONL log)  →  Hybrid Extraction  →  Embedded LadybugDB graph
     |                                                               |
     +—————— Optional Pathlight traces ———————————————→  Query Router
                                                               |
@@ -247,7 +247,7 @@ See [LLM Packet Analyzer](docs/packet-analyzer.md).
 |------|---------|
 | `src/zaxy/event.py` | Eventloom JSONL I/O + hash chain integrity |
 | `src/zaxy/extract.py` | Hybrid extraction engine + rule registry |
-| `src/zaxy/embedded_graph_store.py` | Embedded Kuzu projection store |
+| `src/zaxy/embedded_graph_store.py` | Embedded LadybugDB projection store |
 | `src/zaxy/graph.py` | Optional Neo4j bi-temporal wrapper via `zaxy-memory[neo4j]` |
 | `src/zaxy/query.py` | Hybrid retrieval router |
 | `src/zaxy/mcp_server.py` | MCP stdio/SSE server |

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/README.md

@@ -8,13 +8,13 @@ review, approval packets, and accepted merge-back into one durable history that
 can be queried, replayed, and inspected.
 
 Under the hood, Zaxy uses Eventloom append-only JSONL as the source of truth and
-an embedded Kuzu graph projection for local reasoning. It is built for agents
+an embedded LadybugDB graph projection for local reasoning. It is built for agents
 that need to remember what happened, cite where it came from, and avoid turning
 project state into a pile of markdown files and vector chunks.
 
-The embedded Kuzu graph projection is the default local runtime.
+The embedded LadybugDB graph projection is the default local runtime.
 
-The plain install uses embedded Kuzu. Install `zaxy-memory[neo4j]` only for the
+The plain install uses embedded LadybugDB. Install `zaxy-memory[neo4j]` only for the
 optional Neo4j sidecar, and `zaxy-memory[pathlight]` only for Pathlight tracing.
 
 ## Why It Matters
@@ -22,7 +22,7 @@ optional Neo4j sidecar, and `zaxy-memory[pathlight]` only for Pathlight tracing.
 - **Auditable memory**: every accepted fact can point back to Eventloom history.
 - **Agent-team coordination**: parent and worker sessions stay isolated until
   findings are reviewed and merged.
-- **Local-first runtime**: the default path uses embedded Kuzu, no Neo4j sidecar.
+- **Local-first runtime**: the default path uses embedded LadybugDB, no Neo4j sidecar.
 - **MCP-native integration**: Codex, Claude Code, Cursor, VS Code, Hermes Agent,
   LangGraph, CrewAI, and AutoGen can use the same memory interface.
 - **External benchmark evidence**: on the full Harvey LAB legal-agent memory
@@ -126,7 +126,7 @@ Agent (LangGraph / Any MCP Client)
 MCP Server — memory_append / memory_query / memory_feedback / memory_replay / memory_invalidate
     |
     v
-Eventloom (immutable JSONL log)  →  Hybrid Extraction  →  Embedded Kuzu graph
+Eventloom (immutable JSONL log)  →  Hybrid Extraction  →  Embedded LadybugDB graph
     |                                                               |
     +—————— Optional Pathlight traces ———————————————→  Query Router
                                                               |
@@ -180,7 +180,7 @@ See [LLM Packet Analyzer](docs/packet-analyzer.md).
 |------|---------|
 | `src/zaxy/event.py` | Eventloom JSONL I/O + hash chain integrity |
 | `src/zaxy/extract.py` | Hybrid extraction engine + rule registry |
-| `src/zaxy/embedded_graph_store.py` | Embedded Kuzu projection store |
+| `src/zaxy/embedded_graph_store.py` | Embedded LadybugDB projection store |
 | `src/zaxy/graph.py` | Optional Neo4j bi-temporal wrapper via `zaxy-memory[neo4j]` |
 | `src/zaxy/query.py` | Hybrid retrieval router |
 | `src/zaxy/mcp_server.py` | MCP stdio/SSE server |

zaxy_memory-2.3.0/docs/announcements/zaxy-v2.2-x-article.md

@@ -0,0 +1,82 @@
+# X Article Draft: Zaxy 2.2.0
+
+![Zaxy 2.2 release header](../assets/zaxy-v2.2-header.png)
+
+Zaxy 2.2.0 is out: evidence-bounded vector search.
+
+The short version: in 2.1, our own benchmark caught our ANN path being worse
+than brute force — slower, less accurate, with 20-minute index builds — so we
+shipped it disabled. In 2.2 we fixed it, and the defaults moved exactly as far
+as the evidence extends and not one dimension further.
+
+That ordering matters. The standard failure mode for approximate
+nearest-neighbor search is shipping it because it is supposed to be fast,
+then discovering in production that recall quietly cratered or the index
+takes the better part of an hour to build. Zaxy's release rule is the
+opposite: a default changes only when an evaluation lane that ships in the
+repo proves the change at the scale it claims.
+
+What the lane said at the 2.1 baseline, at 100k vectors:
+
+| Metric | ANN (HNSW) | Exact |
+|--------|------------|-------|
+| Recall@10 | 0.8969, varying per rebuild | 1.000 |
+| Query p50 | 37.9 ms | 17.0 ms |
+| Full index build | ~20 minutes | seconds |
+
+What it says after 2.2, same scale, double-pass plus a confirmatory run:
+
+| Metric | ANN (HNSW) | Exact |
+|--------|------------|-------|
+| Recall@10 | 1.000, identical across rebuilds | 1.000 |
+| Query p50 | parity to better, in-run | — |
+| Full index build | 92 seconds (12.9x) | seconds |
+
+What ships:
+
+- an exact float64 rerank over approximate candidates, which both fixed
+  recall and made it deterministic across HNSW's nondeterministic builds;
+- bulk index builds through a COPY-based generation swap instead of row
+  inserts — 1,180 seconds down to 92 at 100k;
+- unfiltered direct-table queries via per-session shadow generations (the
+  real overhead was a 16 ms per-query filter scan, not what we suspected);
+- engagement defaults bounded to the measured envelope: ANN turns on at
+  100k+ vectors up to 64 dimensions. Above that, exact search remains the
+  recommendation — measured, not assumed;
+- a research paper with the full evidence chain, cited theory, explicit
+  math, and the negative results in the same tables as the wins.
+
+The plot twist is the part worth reading the paper for.
+
+At high dimension, recall looked catastrophic — 0.52 — and stayed broken
+through every fix. The diagnosis: it was the benchmark, not the index. Our
+synthetic test corpus at 1536 dimensions produces a median of 210 vectors
+*exactly tied* with the true top-10. When hundreds of candidates are equally
+correct, recall@10 against one arbitrary tie-break ordering is not a
+measurement; it is a coin flip the index cannot win. Even exact float32
+search scores 0.53 against it.
+
+So we fixed the metric in the open: tie-aware recall (standard
+ann-benchmarks practice) is now reported alongside the strict number — never
+instead of it — and a realistic-distribution control corpus confirmed the
+index is healthy at production dimensions. The same correction resurrected
+int8 quantization's high-dim score from 0.61 to 1.0. Benchmarks need the
+same skepticism as the systems they judge.
+
+Along the way we hit three undocumented crash-or-corrupt defects in our
+embedded graph engine — whose upstream is frozen, final release, archived
+repo — and designed around all three. They are documented in the paper with
+reproductions. That is what depending on frozen infrastructure honestly
+looks like.
+
+The claim boundary, because it always matters: every number above is from
+internal lanes on synthetic corpora, labeled as such, with raw artifacts
+versioned in the repo. Nothing here is an external benchmark claim.
+
+Paper: https://docs.zaxy.io/docs/research/ann-engineering-2026-06.html
+Release: https://github.com/syndicalt/zaxy/releases/tag/v2.2.0
+Install: `pip install zaxy-memory`
+
+Zaxy is event-sourced memory for agent work: a hash-chained append-only log
+as the source of truth, cited Memory Checkout as the trust contract, and
+defaults that move on lane evidence. https://docs.zaxy.io

zaxy_memory-2.3.0/docs/announcements/zaxy-v2.3-x-article.md

@@ -0,0 +1,75 @@
+# X Article Draft: Zaxy 2.3.0
+
+![Zaxy 2.3 release header](../assets/zaxy-v2.3-header.png)
+
+Zaxy 2.3.0 is out: the embedded engine moves off archived infrastructure, and
+nothing you rely on moves with it.
+
+The short version: Zaxy's default local graph runtime was built on Kuzu, which
+shipped its final release and archived its repository — no more fixes, no more
+wheels for new Python versions. 2.3 moves the embedded backend to LadybugDB,
+the maintained fork of the same engine lineage, and keeps the
+`PROJECTION_BACKEND=embedded` contract, the schema, query semantics, and the
+ANN engagement defaults exactly where 2.2 left them.
+
+Depending on a dead dependency is a slow-motion outage. But swapping the engine
+under a memory system is also exactly how you lose someone's data if you are
+careless about it. So the rule for this release was: the source of truth never
+moves, and the migration deletes nothing.
+
+How the move works:
+
+- Eventloom — the append-only, hash-chained log — is untouched. It was always
+  the source of truth; projections were always rebuildable from it. That design
+  is what makes an engine swap a projection-layer change instead of a data
+  migration.
+- On first open of a pre-fork projection file LadybugDB cannot read, Zaxy moves
+  it (and its WAL) aside to `<path>.pre-ladybug.bak` — **no data deleted** —
+  opens a fresh store, and rebuilds from the log via `zaxy reproject`. `zaxy
+  doctor` reports the leftover backup until you have verified the rebuild and
+  chosen to delete it.
+- The move also collects a dividend: LadybugDB fixed the upstream
+  `DROP_VECTOR_INDEX` corruption defect 2.2 had to work around, so superseded
+  ANN index generations are now dropped for full space reclaim.
+
+Now the part that is the reason to trust the rest of it.
+
+The release branch arrived with a confident comment in the code: the vector
+index extension was "statically linked, offline-safe, no INSTALL needed." It
+was wrong. LadybugDB ships the vector index as a downloadable extension, not a
+bundled one. It happened to work on the machine that built the release —
+because that machine had the extension cached from earlier use — and it would
+have silently failed on every fresh install, disabling approximate search for
+new users while swallowing the error.
+
+Nothing in a human read of the diff would have caught that. What caught it was
+the coverage ratchet: on a clean CI runner the extension was absent, the native
+vector tests skipped, and total coverage slipped 0.02% under the floor. A
+two-hundredths-of-a-percent tripwire is the only thing standing between "looks
+done" and a marquee feature that is dead on arrival. We traced the skip to the
+missing extension, reproduced the fresh-machine condition locally, and fixed
+the cause: the store now installs-then-loads the extension, cached after first
+use, and degrades to exact search with a clear warning when it genuinely
+cannot.
+
+A note on framing, because we got it wrong first and corrected it: this is
+*local-first*, not offline-only. A one-time extension fetch that then runs
+entirely on-box is no more a network dependency than `pip install` itself — the
+data, the engine, and the compute all stay local. The default exact-search path
+is pure NumPy and fetches nothing. Air-gapped deployments that want approximate
+search pre-seed the extension cache; everyone else never notices.
+
+The claim boundary, as always: the engine swap was gated on a readiness-research
+pass and lane reruns that reproduced 2.2's deterministic evidence — identical
+corpus hashes and recall — with raw artifacts versioned in the repo. The fork is
+single-maintainer and the dependency pin is exact on purpose; that is what
+depending on infrastructure honestly looks like, archived or forked.
+
+Release: https://github.com/syndicalt/zaxy/releases/tag/v2.3.0
+Migration: https://docs.zaxy.io/docs/migration.html
+Install: `pip install zaxy-memory`
+
+Zaxy is event-sourced memory for agent work: a hash-chained append-only log as
+the source of truth, cited Memory Checkout as the trust contract, and a runtime
+where the engine is replaceable because the log is authoritative.
+https://docs.zaxy.io

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/api-inventory.md

@@ -111,7 +111,7 @@ operation gates.
 | Neo4j backend | `Beta` | Optional sidecar and control backend. |
 | Embedded graph backend | `Beta` | Default sidecar-free runtime path. |
 | pgGraph and LatticeDB adapters | `Experimental` | Benchmark candidates, not default release promises. |
-| Direct Cypher/Kuzu implementation helpers | `Internal` | Backend internals may change without public migration guarantees. |
+| Direct Cypher/LadybugDB implementation helpers | `Internal` | Backend internals may change without public migration guarantees. |
 
 ## Benchmark Artifact Schemas
 

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/api.md

@@ -367,7 +367,7 @@ Lower-level modules are public enough for advanced integration but should be
 used carefully: `EventLog` for direct JSONL operations, `extract` for rule-based
 projection, projection backends for graph operations, `QueryRouter` for
 retrieval, and `MemoryTracer` for Pathlight spans. The plain install uses
-embedded Kuzu; install `zaxy-memory[neo4j]` for the optional Neo4j sidecar and
+embedded LadybugDB; install `zaxy-memory[neo4j]` for the optional Neo4j sidecar and
 `zaxy-memory[pathlight]` for Pathlight tracing. Prefer `MemoryFabric` unless you
 are building tests, migrations, or specialized tooling.
 

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/architecture.md

@@ -36,9 +36,12 @@ needs to be rebuilt, replay the log and re-run extraction. This is the reason
 Zaxy does not silently overwrite facts: graph entities carry `valid_from` and
 `valid_to` windows, and reasserted facts become new versions.
 
-The embedded Kuzu projection is the default graph backend because it preserves
+The embedded LadybugDB projection is the default graph backend because it preserves
 graph-native traversal, citations, temporal versioning, and replay without a
-separate graph service. Neo4j remains the quality and performance control
+separate graph service. LadybugDB is the actively maintained fork of the
+archived Kuzu engine; Zaxy 2.3 moved the embedded store to it (exact-pinned)
+after verifying the fork against Zaxy's own defect reproductions and scale
+lanes. Neo4j remains the quality and performance control
 backend, and pgGraph remains an experimental Postgres-native projection backend.
 See [zero-friction-runtime-roadmap.md](archive/zero-friction-runtime-roadmap.md) for the
 embedded runtime gates and backend lifecycle.

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/benchmarks.md

@@ -337,7 +337,7 @@ zaxy graph-scale-lanes --lanes all
 - **Vector-scale lane**: builds deterministic synthetic corpora directly
   against `EmbeddedGraphStore` (default sizes `1000,10000`; `100000` opt-in
   via `--scale-sizes`) and measures, per size, the exact float64 path, the
-  Kuzu-native HNSW path (with a lowered `vector_ann_threshold`), and the
+  engine-native (LadybugDB) HNSW path (with a lowered `vector_ann_threshold`), and the
   int8-quantized path: recall@10 versus the exact ground truth, p50/p95 query
   latency, resident index bytes, and the exact matrix's byte-budget fraction
   against the store's vector-cache ceiling. The lane lowers the count
@@ -365,7 +365,7 @@ zaxy graph-scale-lanes --lanes all
   high-dimension gate corpus, since hash value distributions are
   adversarially tie-dense at high dimension). Corpus hashes, exact/quantized
   recall (both metrics), bytes, and byte budgets are two-run reproducible;
-  ANN recall is reported under `measurements` because Kuzu's HNSW graph
+  ANN recall is reported under `measurements` because the engine's HNSW graph
   construction is not run-to-run reproducible, and all timings are
   environment-dependent. The roadmap exit criterion (>= 0.95 tie-aware
   recall@10 with latency and byte improvements) is defined at 10^5 vectors;

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/configuration.md

@@ -9,7 +9,7 @@ secrets in environment dumps.
 Projection settings are `PROJECTION_BACKEND`, `EMBEDDED_GRAPH_PATH`,
 `LATTICEDB_PATH`, `PGGRAPH_DSN`, and the Neo4j settings used only when
 `PROJECTION_BACKEND=neo4j`. The default backend is `embedded`, which stores the
-repo-local Kuzu projection at `.eventloom/projections/embedded.kuzu` and does
+repo-local LadybugDB projection at `.eventloom/projections/embedded.kuzu` and does
 not start Docker or require a graph endpoint.
 
 Neo4j settings are `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`,
@@ -73,7 +73,7 @@ migrates stale-version vectors to the active provider.
 ANN engagement is a two-clause rule since 2.2, gated by a dimension ceiling.
 A (session, version) vector scope whose dimension is at or below
 `VECTOR_ANN_MAX_DIMENSION` (default `64`) switches from the exact dense
-matrix to a Kuzu-native HNSW index when **(a)** the scope's vector count
+matrix to an engine-native (LadybugDB) HNSW index when **(a)** the scope's vector count
 reaches `VECTOR_ANN_THRESHOLD` (default `100000`), or **(b)** the scope's
 exact float64 matrix (count × dimension × 8 bytes) would exceed the 256 MiB
 vector index cache byte budget. Scopes above the dimension ceiling always
@@ -202,7 +202,7 @@ scripts/release-check.sh --root .
 
 The deployment validator checks production mode, selected sidecar TLS posture,
 remote MCP auth, admin-token configuration, and secret-file permissions. Embedded
-Kuzu production deployments do not need Neo4j certificate material unless
+LadybugDB production deployments do not need Neo4j certificate material unless
 `PROJECTION_BACKEND=neo4j` is selected. The full release gate also runs tests,
 package validation, and documentation validation. See
 [deployment.md](deployment.md), [security.md](security.md), and

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/deployment.md

@@ -13,7 +13,7 @@ secrets are useful for validation and staging, but real deployments should
 replace them with platform-managed secrets or files mounted by Docker,
 Kubernetes, or a vault sidecar.
 
-The default production backend is the embedded Kuzu projection, which requires
+The default production backend is the embedded LadybugDB projection, which requires
 no graph service endpoint and does not start Neo4j. Optional sidecar backends
 must be configured explicitly. For Neo4j, install `zaxy-memory[neo4j]`, generate
 certificate material, and start the compose profile:

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/embeddings.md

@@ -83,10 +83,18 @@ therefore stay on exact float64 — or explicitly opted-in
 threshold and is exempt from clause (b) — unless the ceiling is raised
 explicitly with lane evidence. When ANN engages, the (session, version)
 vector group syncs
-into its own Kuzu-native HNSW shadow table that queries hit directly — no
+into its own engine-native HNSW shadow table (LadybugDB, the maintained
+fork of Kuzu — the vector index code is unchanged since the fork, so all
+2.2 lane evidence carries over) that queries hit directly — no
 per-query graph projection and no predicate scan; indexes are built and
 loaded only on engagement, so default-path users below the rule pay no
-cold-start cost. The HNSW query retrieves an
+cold-start cost. LadybugDB ships the vector index as an official `vector`
+extension fetched once on first ANN engagement (cached under `~/.lbdb`) and
+then run entirely on-box; Zaxy fetches it automatically. With no network and
+no cache, ANN is unavailable and retrieval falls back to exact float search —
+the default exact path is pure NumPy and needs nothing fetched. Air-gapped
+ANN deployments run `INSTALL vector` once on a networked host and ship the
+cache. The HNSW query retrieves an
 oversampled candidate set (`VECTOR_ANN_EFS`, default `400`, controls the
 index's query-time candidate list) and the store reranks those candidates
 with exact float64 scores from the resident entity vectors, so approximate

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/getting-started.md

@@ -2,7 +2,7 @@
 
 Zaxy is a local-first memory fabric for AI agents. It keeps the immutable
 work history in Eventloom JSONL files and projects structured facts into an
-embedded Kuzu graph so agents can retrieve connected, temporal context through MCP tools. The
+embedded LadybugDB graph so agents can retrieve connected, temporal context through MCP tools. The
 fastest path is to install the CLI, run one local onboarding command, and
 verify that Eventloom plus the model-facing bootstrap are readable. For the
 architecture tradeoffs behind this shape, see [why-zaxy.md](why-zaxy.md).
@@ -232,7 +232,7 @@ zaxy activate codex \
 Use `--dry-run` to inspect the exact `codex --cd ... <prompt>` command without
 starting Codex or managed capture.
 
-If a long-running `zaxy serve` process already owns the default embedded Kuzu
+If a long-running `zaxy serve` process already owns the default embedded LadybugDB
 projection, CLI checkout retries with a per-process isolated projection under
 `.eventloom/projections/checkout-<session>-<pid>.kuzu` and reports
 `diagnostics.projection_fallback`. This keeps memory activation from silently
@@ -342,7 +342,7 @@ you intentionally want to replace generated config. `--infra check` reports the
 selected local projection backend and Docker posture without starting
 containers. Use `--infra start` when you explicitly want onboarding to prepare
 the selected local runtime. The default embedded backend creates only the local
-projection directory and lazy Kuzu database. For experimental pgGraph bootstrap,
+projection directory and lazy LadybugDB database. For experimental pgGraph bootstrap,
 install the optional extra and point Zaxy at a local pgGraph checkout so it can
 run the extension installer instead of starting plain Postgres:
 
@@ -370,7 +370,7 @@ zaxy serve
 ```
 
 When stdio starts in local development mode, Zaxy checks the selected projection
-backend. With the default embedded backend, it opens the repo-local Kuzu
+backend. With the default embedded backend, it opens the repo-local LadybugDB
 projection path and does not start Docker. With `PROJECTION_BACKEND=neo4j`, it
 requires `pip install "zaxy-memory[neo4j]"` and checks
 `bolt://localhost:7687`. Set `NEO4J_AUTO_START=true` only when you want Zaxy to

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/graph-schema.md

@@ -1,7 +1,7 @@
 # Graph Schema
 
 The graph projection is Zaxy's structured reasoning layer. It is not the source
-of truth; the Eventloom log is. The default implementation is embedded Kuzu,
+of truth; the Eventloom log is. The default implementation is embedded LadybugDB,
 with Neo4j retained as an optional sidecar and control backend. The graph stores
 projections that make memory queryable by entity, relation, keyword, vector
 similarity, and temporal validity.
@@ -295,7 +295,7 @@ LIMIT 25;
 
 The manual Cypher file under `scripts/setup_neo4j_indexes.cypher` documents the
 optional Neo4j sidecar index setup for environments that apply Cypher
-separately. Embedded Kuzu creates its projection schema through the embedded
+separately. Embedded LadybugDB creates its projection schema through the embedded
 adapter and does not use that Cypher file.
 
 Invalidation does not delete nodes. `memory_invalidate` closes validity windows

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/mcp.md

@@ -640,10 +640,10 @@ or `ZAXY_DOMAIN`; `zaxy serve` derives those from the current workspace at
 startup.
 
 Embedded runtime ownership: when `PROJECTION_BACKEND=embedded`, one workspace
-`zaxy serve` process owns the repo-local Kuzu graph in read-write mode. Additional
+`zaxy serve` process owns the repo-local LadybugDB graph in read-write mode. Additional
 stdio `zaxy serve` processes, including worker/subagent MCP launches, proxy to
 that owner through `.eventloom/runtime/zaxy-embedded-owner.sock` instead of
-opening Kuzu themselves. This preserves full graph-backed checkout without
+opening LadybugDB themselves. This preserves full graph-backed checkout without
 starting in degraded mode.
 
 `zaxy init` and `zaxy doctor` clean stale embedded owner records when no live
@@ -719,7 +719,7 @@ derive those values from the active project. For remote SSE configs, the same
 default is sent through the session header.
 
 For local stdio clients, the generated config is intentionally self-contained:
-it forces development-mode local settings and defaults to the embedded Kuzu
+it forces development-mode local settings and defaults to the embedded LadybugDB
 projection. Generated stdio configs set `startup_timeout_sec` to `90` so MCP
 clients do not kill startup while local indexes are opening or optional
 sidecars are warming. If you explicitly choose the optional Neo4j sidecar, Zaxy

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/migration.md

@@ -196,7 +196,7 @@ New settings (all documented in [configuration.md](configuration.md)):
   hash-chained regardless.
 - `VECTOR_ANN_THRESHOLD` (default `1000000` in 2.1.0, lowered to `100000` in
   2.2 — see the 2.2 subsection below): per-scope vector count at which the
-  embedded backend uses a Kuzu-native HNSW index; results from the
+  embedded backend uses an engine-native HNSW index; results from the
   approximate path report `exact: false`.
 - `VECTOR_QUANTIZATION` (`none` default, or `int8`): opt-in quantized vector
   storage with exact float rerank of oversampled candidates.
@@ -285,6 +285,54 @@ budget bounds multi-scope cache totals). An explicit
 threshold and is exempt from the byte clause. `memory_capabilities` reports
 the effective rule under `vector_search`.
 
+## From 2.2 to 2.3: embedded engine moves to LadybugDB
+
+2.3 replaces the embedded projection engine. The Kuzu project was archived
+upstream in October 2025 with 0.11.3 as its final release: it already ships
+no macOS or Windows wheels for Python 3.14, and no Python 3.15 wheels will
+ever exist (3.15 lands ~October 2026), so staying was a countdown, not an
+option — **there is no opt-out**. Zaxy now exact-pins
+[LadybugDB](https://github.com/LadybugDB/ladybug) (`ladybug==0.17.1`), the
+actively maintained fork of the same engine. The adoption was gated on
+re-running Zaxy's own defect reproductions and the full vector-scale and
+graph-walk lanes against the fork.
+
+What changes for you:
+
+- **Storage format.** LadybugDB cannot read a projection file written by the
+  pre-fork engine. On first open of an old `embedded.kuzu`, Zaxy
+  automatically moves it (and its `.wal`) aside to
+  `<path>.pre-ladybug.bak` — **no data is deleted** — opens a fresh store at
+  the same path, and logs the rebuild instructions. Projections are derived
+  state: replay full history with `zaxy reproject <eventloom log>`, or let
+  new checkins project incrementally. `zaxy doctor` reports a leftover
+  `.pre-ladybug.bak` with a remediation line; it is safe to delete once the
+  rebuilt projection is verified. Eventloom logs — the source of truth — are
+  untouched.
+- **Paths stay put.** The default projection path remains
+  `.eventloom/projections/embedded.kuzu`; the extension is cosmetic and
+  changing the default would orphan configured paths.
+- **Dependency.** `pip install "zaxy-memory"` now pulls `ladybug==0.17.1`
+  instead of `kuzu`. The pin is exact on purpose (single-maintainer fork;
+  every defect verdict was verified against this version) — and pins the
+  `ladybug` PyPI name, not the stale pre-rename `real-ladybug`.
+- **Behavior.** Query semantics, schema, retrieval results, and the ANN
+  engagement defaults are unchanged; the vector index code is unchanged
+  since the fork, and the 2.3 lane reruns reproduced the 2.2 deterministic
+  blocks (identical corpus hashes and recall). Superseded ANN shadow
+  generations are now dropped instead of emptied (full space reclaim,
+  enabled by an upstream fix verified through Zaxy's own rebuild cycle).
+- **Vector extension fetch (local-first, one-time).** Kuzu 0.11.3 bundled the
+  vector index; LadybugDB ships it as an official `vector` extension fetched
+  on first use (a small one-time download cached under `~/.lbdb`), much like
+  installing the package itself. Zaxy fetches it automatically the first time
+  the ANN path engages, then it runs entirely on-box. Air-gapped deployments
+  that want ANN run `INSTALL vector` once on a networked host and ship the
+  `~/.lbdb` cache; with no network and no cache, approximate (HNSW) search is
+  simply unavailable and retrieval falls back to **exact** float search —
+  correct results, no error, fully on-box. The default exact path is pure
+  NumPy and needs nothing fetched.
+
 ## Compatibility Tests
 
 The compatibility suite should prove that old public behavior still works or

{zaxy_memory-2.2.0 → zaxy_memory-2.3.0}/docs/operations.md

@@ -1,13 +1,13 @@
 # Operations
 
 Zaxy operations center on four tasks: keep Eventloom logs durable, keep the
-embedded Kuzu projection rebuildable, validate deployments before exposure, and
+embedded LadybugDB projection rebuildable, validate deployments before exposure, and
 preserve enough observability to debug memory behavior. The full incident checklist remains in
 [runbook.md](runbook.md); this page is the day-to-day operator summary.
 
 Backups should include Eventloom logs, relevant configuration, and only the
 projection data that is expensive to rebuild. Eventloom is the required source
-of truth. The embedded Kuzu projection and optional sidecar projections can be
+of truth. The embedded LadybugDB projection and optional sidecar projections can be
 rebuilt by replay, but backing them up can reduce recovery time for large
 deployments. Use `scripts/backup.sh` and `scripts/restore.sh` for tested local
 archive flows.