zaxy-memory 2.3.3__tar.gz → 2.4.0__tar.gz

{zaxy_memory-2.3.3 → zaxy_memory-2.4.0}/AGENTS.md

@@ -184,7 +184,7 @@ Run with coverage: `pytest --cov` (default in pyproject.toml)
 | Neo4j upsert | <100ms | MERGE + index lookup |
 | Hybrid query | <200ms | Parallel exact + keyword + traversal |
 | Total context retrieval | <300ms | End-to-end |
-| Token reduction vs. chunk RAG | 70–90% | Structured paths vs. raw text |
+| Token reduction vs. chunk RAG | 70–90% (target; unvalidated) | Structured paths vs. raw text. Validate with `scripts/chunk_rag_token_compare.py` — quality-controlled (token reduction at *equal answer-bearing recall*, pinned chunk-RAG baseline) — driven by a gold-labeled QA dataset through the gated benchmark. |
 
 ## Current Status
 

{zaxy_memory-2.3.3 → zaxy_memory-2.4.0}/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable Zaxy release changes are recorded here.
 
+## 2.4.0 - 2026-06-14
+
+- **Portable signed memory export — EXPERIMENTAL / UNAUDITED, opt-in.** New
+  `zaxy.portable` module (install `zaxy-memory[export]`) for self-sovereign,
+  cryptographically-signed, verifiable memory export:
+  - Signed bundles: post-quantum **ML-DSA-65** (FIPS-204) primary, Ed25519
+    fallback; a domain-separated Merkle tree binds the entries and enables
+    **verifiable partial disclosure** (prove a subset without revealing the rest);
+    the signature binds the root and all metadata; public-key pinning.
+  - **Injection-resistant rehydration** of recalled content (data-not-instructions
+    fencing); opt-in `zaxy offload-get --fenced`.
+  - **Encryption envelope + cryptographic erasure** (per-cell AES-256-GCM, KEK
+    wrap, key-destruction erasure for GDPR Art.17) and capability-scoped sharing.
+  - Pluggable public anchor (offline stub + OpenTimestamps hook).
+  - CLI: `export-keygen`, `export`, `verify-export`.
+  > ⚠️ This is **experimental, unaudited** cryptographic code. It uses only vetted
+  > primitives (pyca/cryptography) and ships behind an opt-in extra with a loud
+  > import-time warning. **Do not rely on it for high-value secrets or compliance.**
+  > It has had an adversarial self-review (a layer, not a substitute for
+  > independent human review); see `docs/experimental/portable-export-security.md`.
+- No changes to the default runtime, capture, recall, or existing MCP tools;
+  nothing in core imports `zaxy.portable`.
+
+## 2.3.4 - 2026-06-14
+
+- **Opt-in full tool-I/O provenance (offload sink).** Default capture stays lean
+  (240-char excerpts, redacted args). With `ZAXY_OFFLOAD_TOOL_IO` enabled, the
+  full command output / tool arguments are also written to a content-addressed
+  blob under `<eventloom>/refs/`, and the lean event carries a `full_io_ref`
+  (`{ref, sha256, bytes}`). The blob id *is* its sha256 and lives inside the
+  Eventloom directory, so it is self-contained and tamper-evident (unlike the
+  foreign `codex_source_ref` pointers, which the hash chain can't attest to).
+  Context and `memory_checkout` still see only the summary; drill down on demand
+  with `zaxy offload-get <sha256>`. Arguments are secret-masked before offload.
+  This closes the provenance gap on tool I/O without touching token leanness.
+- **Chunk-RAG token-reduction methodology** (`scripts/chunk_rag_token_compare.py`):
+  a quality-controlled harness that measures token reduction at *equal
+  answer-bearing recall* against a pinned chunk-RAG baseline, so the AGENTS.md
+  "70–90% vs chunk RAG" figure can be validated (it is now labeled an unvalidated
+  target pending a gated QA-dataset run) instead of asserted.
+
 ## 2.3.3 - 2026-06-13
 
 - Extended deterministic per-turn memory injection to **Codex**. Codex now ships

{zaxy_memory-2.3.3 → zaxy_memory-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zaxy-memory
-Version: 2.3.3
+Version: 2.4.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
@@ -48,6 +48,8 @@ Requires-Dist: twine>=5.0.0; extra == 'dev'
 Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
 Requires-Dist: types-requests>=2.32.0; extra == 'dev'
 Provides-Extra: embedded
+Provides-Extra: export
+Requires-Dist: cryptography>=46.0; extra == 'export'
 Provides-Extra: frameworks
 Requires-Dist: autogen-agentchat>=0.7; extra == 'frameworks'
 Requires-Dist: crewai>=0.100; extra == 'frameworks'

zaxy_memory-2.4.0/docs/experimental/portable-export-conformance.md

@@ -0,0 +1,62 @@
+# Portable Export — W3C Interop Conformance Mapping (dev target #3)
+
+Status: **reference implementation, held for independent review. Not released.**
+
+This maps Zaxy's signed portable-export implementation to the scope of the W3C
+"AI Agent Memory Interoperability" Community Group (proposed 2026-05-18). **Full
+conformance is intentionally deferred until the CG spec is finalized** — you
+cannot conform to an unfinalized standard. The pieces below are built against the
+*announced scope* and will be reconciled to exact field names / serialization once
+the spec stabilizes.
+
+| W3C CG scope item | Zaxy implementation | Status |
+|---|---|---|
+| Identity binding (post-quantum signatures, ML-DSA-65 / FIPS-204 reference) | `portable/signing.py` — ML-DSA-65 primary, Ed25519 classical fallback (vetted pyca) | ✅ built |
+| Tamper-evident provenance | `portable/merkle.py` + `export.py` — domain-separated Merkle root, signed; verifiable subset disclosure | ✅ built |
+| Memory cell shape (encrypted unit + metadata) | `portable/envelope.py` — per-cell AES-256-GCM | ⚠️ primitive built; canonical cell schema pending spec |
+| Encryption envelope (per-cell DEK; KEK wrap; rotation) | `portable/envelope.py` — DEK + KEK wrap (local KEK; wallet-derived KEK deferred) | ⚠️ partial |
+| Cryptographic erasure (DEK destroy + tombstone + content-address blacklist; GDPR Art.17) | `portable/envelope.py::ErasureVault` | ✅ built |
+| Sharing contracts (temporary / permanent / syndicate + revocation) | `portable/envelope.py::Capability` | ✅ built (policy layer) |
+| Audit anchor (public-chain receipts; operator-independent verifiability) | `portable/anchor.py` — pluggable; deterministic stub + OpenTimestamps hook | ⚠️ interface built; real public-chain anchor not wired |
+| Serialization (JSON-first, optional CBOR) | JSON bundle implemented | ⚠️ CBOR deferred |
+
+## Trust model (no external authority required)
+Self-sovereign: the exporter holds its own keypair; the public key (or a DID) is
+the identity. No CA. Verifiers pin the key / trust-on-first-use. Operator-
+independent verification is provided by the public-chain anchor (OpenTimestamps),
+not a private signing authority. A managed "notary" service is a future product
+layer, never a dependency.
+
+## Adversarial self-review (2026-06-14)
+
+A structured red-team of the protocol logic (not a credentialed human audit).
+Held: domain-separated Merkle blocks the duplicate-leaf forgery class
+(CVE-2012-2459); the signature binds the root **and** all metadata; `verify_*`
+fails closed on exceptions; per-cell DEKs avoid AES-GCM nonce reuse; the fence
+escape prevents literal delimiter forgery.
+
+**Fixed by this pass:**
+- *Crypto-erasure invariant* — made explicit (see `ErasureVault` docstring): key
+  material must NEVER enter the immutable Eventloom, or erasure is a false claim.
+- *`temporary` capability without expiry* now fails **closed** (was grant-forever).
+- *`verify_*` now version-allow-lists* the bundle (rejects unknown versions).
+
+**Residual caveats (documented, not yet addressed — for human review / later phases):**
+- *Canonicalization*: signing uses sorted-key compact JSON; adopt JCS (RFC 8785)
+  and forbid floats/NaN to remove canonicalization ambiguity before production.
+- *KEK nonce volume*: random 96-bit nonces are safe per-DEK (used once) but a KEK
+  wrapping many DEKs should rotate or use counter nonces beyond ~2^32 wraps.
+- *Anchor stub*: `verify_anchor` on a `type: "stub"` anchor proves internal
+  consistency only — NOT external timestamping. Real assurance needs the
+  OpenTimestamps/public-chain hook.
+- *Subset proof length* leaks an approximate total entry count (tree depth).
+- *Rehydration (P2)* is defense-in-depth (semantic guard), explicitly NOT a
+  guarantee against indirect prompt injection.
+
+## Review gate
+This is security-critical reference code using vetted primitives only. The
+adversarial self-review above is a layer, **not** a substitute for independent
+human review. For a resource-constrained project the proportionate path is:
+ship clearly labeled `experimental / unaudited`, open it for community + W3C-CG
+scrutiny, and pursue a formal audit only when usage/stakes warrant. Until then,
+make no "audited/secure" claims. Nothing here has been published.

zaxy_memory-2.4.0/docs/experimental/portable-export-security.md

@@ -0,0 +1,95 @@
+# Portable Export — Security Status & Review Requests
+
+> ## ⚠️ EXPERIMENTAL · UNAUDITED
+> The portable signed-export / rehydration / envelope code (`src/zaxy/portable/`)
+> is a **reference implementation**. It has **not** had independent cryptographic
+> review. **Do not rely on it to protect high-value secrets or for compliance
+> guarantees.** No "audited" or "secure" claim is made. It lives on a feature
+> branch and has not been released.
+
+## What is and isn't assured
+
+**Assured by design / tests:**
+- Only **vetted primitives** (pyca/cryptography): ML-DSA-65, Ed25519, AES-256-GCM,
+  SHA-256. No homegrown cryptographic primitives.
+- Adversarial test suite (forge, tamper, drop, swapped-key, metadata-binding,
+  subset non-leakage, forged-proof, GCM auth-fail, key-destruction erasure,
+  capability expiry/revocation, anchor tamper-detection).
+- An **adversarial self-review** of the protocol/composition logic
+  (see `portable-export-conformance.md`). This is a *layer*, **not** a substitute
+  for independent human review.
+
+**Not assured (needs human review and/or later phases):**
+- Protocol composition beyond the tested cases.
+- Canonicalization is sorted-key compact JSON — not yet JCS (RFC 8785); floats
+  are a known canonicalization hazard.
+- KEK nonce management at high volume; wallet-derived KEK not implemented.
+- The public anchor ships as an offline **stub**; real OpenTimestamps/public-chain
+  anchoring is a hook, not wired. A stub anchor proves *consistency only*, not
+  external timestamping.
+- W3C interop conformance is deferred until the spec (CG proposed 2026-05-18)
+  finalizes.
+
+## What it provides (threat model summary)
+- **Authenticity + integrity** of an exported memory bundle (signature binds the
+  Merkle root and all metadata), with **self-sovereign** keys (no CA; pin the key
+  or use a DID; trust-on-first-use).
+- **Verifiable partial disclosure**: prove a subset of entries belongs to the
+  signed set without revealing the rest.
+- **Confidentiality + cryptographic erasure** of memory cells (per-cell DEK;
+  destroy-the-key erasure). **Invariant:** key material must never enter the
+  immutable Eventloom log, or erasure is void.
+- **Injection-resistant rehydration**: defense-in-depth fencing of recalled
+  untrusted content — explicitly **not** a guarantee against prompt injection.
+
+**Non-goals (v1):** CA/PKI federation, threshold/multi-party signing, confidential
+compute, replay/rollback prevention beyond per-bundle nonce + timestamp.
+
+## Reporting issues
+Found a flaw? Please open a private report (security contact / GitHub security
+advisory) rather than a public issue, and allow reasonable time to fix. Since this
+is pre-release experimental code, coordinated disclosure is appreciated but there
+is no production deployment at risk.
+
+---
+
+## Review request — W3C AI Agent Memory Interoperability CG
+
+> **Subject: Reference impl + review request — self-sovereign signed memory export (ML-DSA-65 + Merkle subset proofs)**
+>
+> Hi all — I've built an open, experimental reference implementation aligned with
+> the CG's announced scope (identity binding via ML-DSA-65/FIPS-204, Merkle
+> provenance with verifiable partial disclosure, per-cell encryption envelope,
+> cryptographic erasure for GDPR Art.17, capability-scoped sharing). It's
+> self-sovereign (no CA) with a public-chain anchor hook.
+>
+> It is **experimental and unaudited** — I'm a resource-constrained project and
+> can't commission a formal audit, so I'd hugely value eyes on the *protocol/
+> composition logic*: how the signature binds the Merkle root + metadata, the
+> subset-disclosure proofs, and the crypto-erasure model in an append-only store.
+> Vetted primitives only (pyca/cryptography); adversarial tests included.
+>
+> Repo + threat model: <link>. Happy to align field names/serialization to the
+> spec as it stabilizes, and to contribute findings back. What have I gotten wrong?
+
+## Review request — crypto.stackexchange
+
+> **Title: Is this composition sound? Signed Merkle-root memory bundle with verifiable subset disclosure + crypto-erasure**
+>
+> I have an experimental protocol for portable, signed agent-memory bundles and
+> want to sanity-check the *composition* (primitives are pyca: ML-DSA-65/Ed25519,
+> AES-256-GCM, SHA-256 — I'm not rolling my own).
+>
+> 1. A bundle's signature is computed over a canonical header that includes the
+>    Merkle root of the entries **plus** all metadata (version, alg, pubkey,
+>    session id, created-at, nonce). Is binding metadata-with-root this way
+>    sufficient to prevent metadata-swap / cross-bundle attacks?
+> 2. Subset disclosure reveals chosen entries + Merkle inclusion proofs (leaf
+>    prefix `0x00`, node prefix `0x01`, unpaired nodes promoted not duplicated).
+>    Any forgery/second-preimage concern, given the proofs aren't position-bound?
+> 3. "Cryptographic erasure" = destroy the (wrapped) DEK + tombstone + blacklist;
+>    ciphertext is otherwise immutable. Are there pitfalls beyond "ensure no other
+>    copy of the key survives"?
+>
+> Canonicalization is sorted-key compact JSON (I know JCS/RFC 8785 is the better
+> answer). Threat model + code: <link>. Where does this break?

{zaxy_memory-2.3.3 → zaxy_memory-2.4.0}/docs/hooks.md

@@ -138,6 +138,32 @@ session, long tool run, or roadmap/status question, Zaxy appends
 the agent: call `memory_bootstrap` if awareness is unclear, then call
 `memory_checkout` and trust only cited current checkout facts.
 
+## Per-Turn Memory Injection (`UserPromptSubmit`)
+
+Capture is deterministic, but recall used to be advisory: nothing re-injected the
+memory contract into the model's context, so long sessions drifted. The
+`UserPromptSubmit` hook closes that recall gap. On every turn it re-checks memory
+freshness and, when memory is stale, injects a single terse declarative line that
+names the session, how many events have passed since the last memory use, and the
+recommended `memory_checkout`. When memory is fresh it stays silent and adds no
+context noise. Wire it via:
+
+```bash
+zaxy hooks claude-code --eventloom-path .eventloom --domain my-project
+```
+
+Codex ships Claude-parity hooks, so the same `UserPromptSubmit` /
+`additionalContext` injection works there too. `render_hook_config("codex")`
+emits a `.codex/hooks.json` with the same per-turn recall behavior:
+
+```bash
+zaxy hooks codex --eventloom-path .eventloom --domain my-project
+```
+
+The injected line is plain prose rather than JSON or glyphs, and it is assembled
+read-only from Eventloom-backed state, so it stays small enough to prepend to the
+prompt verbatim without risking stale context after a checkout.
+
 Checkpoint hooks can include retrieval-useful metadata:
 
 ```bash
@@ -241,6 +267,23 @@ persist argument keys but not raw argument values. Transcript-turn observations
 sanitize content before append so they can serve as source-recall material
 without storing obvious secrets.
 
+### Tool-I/O Offload Provenance (`ZAXY_OFFLOAD_TOOL_IO`)
+
+Default capture stays lean, so it truncates command output and keeps only tool
+argument keys. When you need full, replayable provenance for tool I/O, set
+`ZAXY_OFFLOAD_TOOL_IO`. The full command output or tool arguments are then written
+to a content-addressed, tamper-evident blob under `<eventloom>/refs/` (the blob id
+is its own sha256), and the lean event carries a `full_io_ref` pointer. Context
+assembly and `memory_checkout` still see only the summary; drill down to the full
+text on demand:
+
+```bash
+zaxy offload-get <sha256>
+```
+
+Offload is opt-in, and secret-looking argument values are still masked before the
+blob is written, so the lean default and the privacy guarantees are preserved.
+
 ## Payload
 
 Hook events use actor `zaxy-hook` and append to the selected session log. The

{zaxy_memory-2.3.3 → zaxy_memory-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zaxy-memory"
-version = "2.3.3"
+version = "2.4.0"
 description = "Coordinator memory for auditable multi-agent projects"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -76,6 +76,11 @@ embedded = [
 latticedb = [
     "latticedb>=0.9.6",
 ]
+export = [
+    # Portable signed export. Ed25519 works with the cryptography that PyJWT[crypto]
+    # already pulls in; ML-DSA-65 (post-quantum) requires cryptography >= 46.
+    "cryptography>=46.0",
+]
 frameworks = [
     "langgraph>=0.6",
     "crewai>=0.100",

{zaxy_memory-2.3.3 → zaxy_memory-2.4.0}/scripts/build-site-docs.py

@@ -52,6 +52,10 @@ def main() -> int:
 
 def build_pages() -> list[RenderedPage]:
     sources = [ROOT / "README.md", *sorted(DOCS_ROOT.rglob("*.md"))]
+    # docs/experimental/ is contributor-only (e.g. unreleased/experimental crypto)
+    # and must never be rendered into the public site.
+    experimental = DOCS_ROOT / "experimental"
+    sources = [s for s in sources if not is_relative_to(s, experimental)]
     return [render_page(source) for source in sources]
 
 

zaxy_memory-2.4.0/scripts/chunk_rag_token_compare.py

@@ -0,0 +1,166 @@
+"""Quality-controlled token-reduction methodology: structured cited memory vs chunk-RAG.
+
+Dev target #2: the AGENTS.md Performance-Targets table states "Token reduction vs
+chunk RAG: 70-90% (structured paths vs raw text)". That is an *unvalidated target*.
+This module is the reproducible methodology to validate (or correct) it.
+
+The trap this avoids: a raw token ratio is meaningless, because you can always
+"save tokens" by retrieving less and answering worse. So every comparison is
+**quality-controlled** — measured at EQUAL ANSWER-BEARING RECALL: both arms must
+surface the gold answer span, and we count the tokens each needs to get there.
+
+  reduction = 1 - structured_tokens / chunkrag_tokens   (over cases where BOTH reach gold)
+
+The chunk-RAG baseline is pinned and reported (chunk size, ranking) so the ratio
+is not gameable by quietly weakening the baseline.
+
+Run `python3 scripts/chunk_rag_token_compare.py` for a self-test on a worked
+example. To produce a *publishable* number, drive `compare_corpus()` with a real
+QA dataset (e.g. LongMemEval) through the gated benchmark apparatus; the headline
+number depends on workload and must be reported with both.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+
+# Prefer a real BPE tokenizer when available (benchmark runs), but stay
+# dependency-free otherwise: the methodology only needs a *consistent* tokenizer,
+# since it compares token counts at equal recall between two arms.
+_encode: Callable[[str], list]
+_decode: Callable[[list], str]
+try:  # pragma: no cover - depends on optional install
+    import tiktoken
+
+    _ENC = tiktoken.get_encoding("cl100k_base")
+    _encode = _ENC.encode
+    _decode = _ENC.decode
+    TOKENIZER = "tiktoken/cl100k_base"
+except Exception:  # noqa: BLE001 - any import/runtime failure -> fallback
+    _encode = lambda s: s.split()  # noqa: E731 - whitespace tokens
+    _decode = lambda t: " ".join(t)  # noqa: E731
+    TOKENIZER = "whitespace-fallback"
+
+DEFAULT_CHUNK_TOKENS = 512
+
+
+def tokens(text: str) -> int:
+    return len(_encode(text))
+
+
+def chunk_text(text: str, chunk_tokens: int = DEFAULT_CHUNK_TOKENS) -> list[str]:
+    toks = _encode(text)
+    return [_decode(toks[i : i + chunk_tokens]) for i in range(0, len(toks), chunk_tokens)]
+
+
+def _kw(text: str) -> list[str]:
+    return re.findall(r"\w+", text.lower())
+
+
+def _score(passage: str, query: str) -> int:
+    q = set(_kw(query))
+    return sum(1 for w in _kw(passage) if w in q)
+
+
+def _tokens_to_gold(passages: list[str], query: str, gold: str) -> tuple[int, bool]:
+    """Greedily accumulate the highest-scoring passages until gold appears.
+
+    Returns (tokens_used, reached_gold). Pure keyword ranking — a standard,
+    embedding-free chunk-RAG baseline (note: vector-RAG could differ).
+    """
+    ranked = sorted(passages, key=lambda p: -_score(p, query))
+    used: list[str] = []
+    total = 0
+    gold_l = gold.lower()
+    for p in ranked:
+        used.append(p)
+        total += tokens(p)
+        if gold_l in " ".join(used).lower():
+            return total, True
+    return total, False
+
+
+@dataclass
+class CaseResult:
+    query: str
+    structured_tokens: int
+    chunkrag_tokens: int
+    both_reached: bool
+
+    @property
+    def reduction(self) -> float | None:
+        if not self.both_reached or self.chunkrag_tokens == 0:
+            return None
+        return 1 - self.structured_tokens / self.chunkrag_tokens
+
+
+def compare_case(
+    *, query: str, gold: str, facts: list[str], raw_text: str, chunk_tokens: int = DEFAULT_CHUNK_TOKENS
+) -> CaseResult:
+    """One query: structured-cited retrieval vs chunk-RAG over raw_text, at equal recall."""
+    s_tok, s_ok = _tokens_to_gold(facts, query, gold)
+    c_tok, c_ok = _tokens_to_gold(chunk_text(raw_text, chunk_tokens), query, gold)
+    return CaseResult(query, s_tok, c_tok, s_ok and c_ok)
+
+
+def compare_corpus(cases: list[dict], *, chunk_tokens: int = DEFAULT_CHUNK_TOKENS) -> dict:
+    """Run a corpus of {query, gold, facts, raw_text} cases. Returns aggregate stats.
+
+    Only cases where BOTH arms reach gold count toward the reduction (equal recall).
+    """
+    results = [compare_case(chunk_tokens=chunk_tokens, **c) for c in cases]
+    scored = [r for r in results if r.reduction is not None]
+    reductions = [r.reduction for r in scored]
+    return {
+        "baseline": {
+            "chunk_tokens": chunk_tokens,
+            "ranking": "keyword-overlap (embedding-free)",
+            "tokenizer": TOKENIZER,
+        },
+        "cases_total": len(results),
+        "cases_equal_recall": len(scored),
+        "median_reduction": (sorted(reductions)[len(reductions) // 2] if reductions else None),
+        "mean_reduction": (sum(reductions) / len(reductions) if reductions else None),
+        "per_case": [
+            {"query": r.query, "structured_tok": r.structured_tokens,
+             "chunkrag_tok": r.chunkrag_tokens, "reduction": r.reduction}
+            for r in results
+        ],
+    }
+
+
+def _self_test_corpus() -> list[dict]:
+    """A worked example: a fact buried in verbose tool/dialogue text vs a compact card.
+
+    Illustrative only — the magnitude depends on raw verbosity, which is exactly why
+    a real run needs a QA dataset + the gated apparatus.
+    """
+    noise = ("INFO build step ok; cache warm; 0 warnings; retrying; " * 60)
+    raw = (
+        noise
+        + " The team decided the canonical session id is zaxy-default and froze the legacy zaxy session. "
+        + noise
+        + " Unrelated: the default graph backend for beta is Neo4j. "
+        + noise
+    )
+    facts = [
+        "[decision] canonical session id = zaxy-default; legacy 'zaxy' frozen. (eventloom://zaxy-default/events/77848)",
+        "[decision] default graph backend (beta) = Neo4j. (eventloom://zaxy-default/events/1200)",
+        "[goal] ship per-turn memory injection. (eventloom://zaxy-default/events/77889)",
+    ]
+    return [
+        {"query": "which session id is canonical", "gold": "zaxy-default", "facts": facts, "raw_text": raw},
+        {"query": "default graph backend for beta", "gold": "Neo4j", "facts": facts, "raw_text": raw},
+    ]
+
+
+if __name__ == "__main__":
+    import json
+
+    out = compare_corpus(_self_test_corpus())
+    print(json.dumps(out, indent=2))
+    print("\nNOTE: self-test is illustrative. A publishable 'X% vs chunk-RAG' number "
+          "requires driving compare_corpus() with a real QA dataset (gold-labeled) "
+          "through the freeze/gate/audit apparatus, reported with workload + baseline.")

{zaxy_memory-2.3.3 → zaxy_memory-2.4.0}/site/docs/hooks.html

@@ -139,6 +139,12 @@ zaxy hook-event heartbeat --eventloom-path .eventloom --session-id my-project-de
       </table>
       <p>Unknown triggers are rejected before writing.</p>
       <p>Lifecycle hooks also run the memory persistence policy. If Zaxy has not been used recently, or the hook marks a session start, resume, compaction, long session, long tool run, or roadmap/status question, Zaxy appends <code>memory.reminder.suggested</code>. That event is intentionally read-only guidance for the agent: call <code>memory_bootstrap</code> if awareness is unclear, then call <code>memory_checkout</code> and trust only cited current checkout facts.</p>
+      <h2 id="per-turn-memory-injection-userpromptsubmit">Per-Turn Memory Injection (<code>UserPromptSubmit</code>)</h2>
+      <p>Capture is deterministic, but recall used to be advisory: nothing re-injected the memory contract into the model&#x27;s context, so long sessions drifted. The <code>UserPromptSubmit</code> hook closes that recall gap. On every turn it re-checks memory freshness and, when memory is stale, injects a single terse declarative line that names the session, how many events have passed since the last memory use, and the recommended <code>memory_checkout</code>. When memory is fresh it stays silent and adds no context noise. Wire it via:</p>
+      <pre><code class="language-bash">zaxy hooks claude-code --eventloom-path .eventloom --domain my-project</code></pre>
+      <p>Codex ships Claude-parity hooks, so the same <code>UserPromptSubmit</code> / <code>additionalContext</code> injection works there too. <code>render_hook_config(&quot;codex&quot;)</code> emits a <code>.codex/hooks.json</code> with the same per-turn recall behavior:</p>
+      <pre><code class="language-bash">zaxy hooks codex --eventloom-path .eventloom --domain my-project</code></pre>
+      <p>The injected line is plain prose rather than JSON or glyphs, and it is assembled read-only from Eventloom-backed state, so it stays small enough to prepend to the prompt verbatim without risking stale context after a checkout.</p>
       <p>Checkpoint hooks can include retrieval-useful metadata:</p>
       <pre><code class="language-bash">zaxy hook-event checkpoint \
   --eventloom-path .eventloom \
@@ -204,6 +210,10 @@ zaxy hook-event transcript-turn \
 }</code></pre>
       <p>Any harness with a post-compaction or resume hook can use the same command; the packet is plain text bracketed by <code>=== ZAXY RECOVERY PACKET ... ===</code> markers. <code>zaxy doctor</code> complements the loop with hash-chain, projection freshness, embedding-dimension, and vector-cache headroom checks so a resumed session can trust what it recovers.</p>
       <p>Command observations redact common secret-bearing arguments and bound stdout and stderr excerpts. File-edit observations persist path, operation, summary, and line count metadata; they do not persist source content. Tool-call observations persist argument keys but not raw argument values. Transcript-turn observations sanitize content before append so they can serve as source-recall material without storing obvious secrets.</p>
+      <h3 id="tool-io-offload-provenance-zaxyoffloadtoolio">Tool-I/O Offload Provenance (<code>ZAXY_OFFLOAD_TOOL_IO</code>)</h3>
+      <p>Default capture stays lean, so it truncates command output and keeps only tool argument keys. When you need full, replayable provenance for tool I/O, set <code>ZAXY_OFFLOAD_TOOL_IO</code>. The full command output or tool arguments are then written to a content-addressed, tamper-evident blob under <code>&lt;eventloom&gt;/refs/</code> (the blob id is its own sha256), and the lean event carries a <code>full_io_ref</code> pointer. Context assembly and <code>memory_checkout</code> still see only the summary; drill down to the full text on demand:</p>
+      <pre><code class="language-bash">zaxy offload-get &lt;sha256&gt;</code></pre>
+      <p>Offload is opt-in, and secret-looking argument values are still masked before the blob is written, so the lean default and the privacy guarantees are preserved.</p>
       <h2 id="payload">Payload</h2>
       <p>Hook events use actor <code>zaxy-hook</code> and append to the selected session log. The payload is intentionally small:</p>
       <pre><code class="language-json">{

{zaxy_memory-2.3.3 → zaxy_memory-2.4.0}/site/index.html

@@ -62,7 +62,7 @@
     </section>
 
     <section class="proof-strip" aria-label="Project status">
-      <span>PyPI 2.3.1</span>
+      <span>PyPI 2.4.0</span>
       <span>47 MCP tools, 8-tool core profile</span>
       <span>cognitive ranking default</span>
       <span>embedded local runtime</span>
@@ -334,7 +334,7 @@ zaxy coordinate checkout --mission auth-main</code></pre>
   </main>
 
   <footer>
-    <span>Zaxy v2.3.1 - MIT</span>
+    <span>Zaxy v2.4.0 - MIT</span>
     <span><a href="README.html">README</a> <a href="docs/runbook.html">Runbook</a></span>
   </footer>
 </body>