zaxy-memory 2.4.3__tar.gz → 2.4.4__tar.gz

{zaxy_memory-2.4.3 → zaxy_memory-2.4.4}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable Zaxy release changes are recorded here.
 
+## 2.4.4 - 2026-06-15
+
+- **The 2.4.2 incremental-retrieval win now reaches the MCP `memory_checkout`
+  front door.** The MCP checkout path (`ZaxyMCPServer._assemble_context`) rebuilt
+  retrieval state from the whole log on *every* call — `VerbatimIndex.from_event_logs(...)`
+  plus a full `session_manager.replay(...)` — so the per-session caches added in
+  2.4.2 (which live on `MemoryFabric`) never applied to checkout. On a large,
+  active session this is the dominant cost and the reason checkout still ran long
+  after 2.4.2/2.4.3.
+  - Extracted the incremental verbatim-index + verified-replay logic into a new
+    standalone `SessionRetrievalCache` (`zaxy.retrieval_cache`) that depends only
+    on a `SessionManager`. `MemoryFabric` now delegates to it (no behavior
+    change), and the MCP server holds its own long-lived instance so the cache
+    survives across checkouts.
+  - `_assemble_context` reads through the cache, extending only the appended log
+    tail instead of rebuilding. Checkout now also runs the **verified** replay
+    (previously `verify_integrity=False`); the hash-chain integrity guard and the
+    byte-identical-to-full-rebuild guarantee are preserved.
+  - The 2.4.3 single-flight `_checkout_lock` still serializes the off-loop
+    checkout body.
+  - No API or behavior change to results; same cited facts are surfaced.
+
 ## 2.4.3 - 2026-06-15
 
 - **`memory_checkout` no longer blocks the MCP event loop — interrupting an

{zaxy_memory-2.4.3 → zaxy_memory-2.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zaxy-memory
-Version: 2.4.3
+Version: 2.4.4
 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

{zaxy_memory-2.4.3 → zaxy_memory-2.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zaxy-memory"
-version = "2.4.3"
+version = "2.4.4"
 description = "Coordinator memory for auditable multi-agent projects"
 readme = "README.md"
 requires-python = ">=3.11"

{zaxy_memory-2.4.3 → zaxy_memory-2.4.4}/site/index.html

@@ -62,7 +62,7 @@
     </section>
 
     <section class="proof-strip" aria-label="Project status">
-      <span>PyPI 2.4.3</span>
+      <span>PyPI 2.4.4</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.4.3 - MIT</span>
+    <span>Zaxy v2.4.4 - MIT</span>
     <span><a href="README.html">README</a> <a href="docs/runbook.html">Runbook</a></span>
   </footer>
 </body>

{zaxy_memory-2.4.3 → zaxy_memory-2.4.4}/src/zaxy/core.py

@@ -85,6 +85,7 @@ from zaxy.reasoning_primitives import (
 )
 from zaxy.recall import RecallCandidateSet, build_recall_candidate_set, empty_recall_candidate_set
 from zaxy.refs import MemoryRef, MemoryRefStore
+from zaxy.retrieval_cache import SessionRetrievalCache, _eventlog_file_signature
 from zaxy.retrieval_intent import classify_retrieval_intent
 from zaxy.retrieval_plan import (
     absence_check_bundle,
@@ -143,7 +144,7 @@ from zaxy.synthesis_artifact import (
 from zaxy.synthesis_packet import synthesis_packet_from_items
 from zaxy.trace import MemoryTracer
 from zaxy.transcripts import collect_transcript_events
-from zaxy.verbatim import VerbatimIndex, _chunks_from_events
+from zaxy.verbatim import VerbatimIndex
 from zaxy.working_set import build_working_set, format_working_set
 from zaxy.workspace import (
     WorkspaceProfile,
@@ -409,8 +410,7 @@ class MemoryFabric:
             packet_memory_enabled=resolved_settings.context_packet_memory_enabled,
             packet_memory_slots=resolved_settings.context_packet_memory_slots,
         )
-        self._verbatim_index_cache: dict[str, tuple[tuple[int, int], VerbatimIndex, int]] = {}
-        self._replay_cache: dict[str, tuple[tuple[int, int], ReplayResult, int]] = {}
+        self._retrieval_cache = SessionRetrievalCache(self.session_manager)
         self._event_ref_index_cache: dict[str, tuple[tuple[int, int], dict[int, tuple[str, str]]]] = {}
         self._session_cue_index_cache: dict[str, tuple[tuple[int, int], dict[int, frozenset[str]]]] = {}
         self._query_page_cache: dict[
@@ -437,7 +437,7 @@ class MemoryFabric:
         """Close all connections. Idempotent."""
         await self.graph.close()
         await self.tracer.close()
-        self._verbatim_index_cache = {}
+        self._retrieval_cache.invalidate()
         self._event_ref_index_cache = {}
         self._session_cue_index_cache = {}
         self._query_page_cache = {}
@@ -2162,31 +2162,11 @@ class MemoryFabric:
         return contexts
 
     def _verbatim_index(self, session_id: str) -> VerbatimIndex:
-        """Return a verbatim index for the current Eventloom file state.
-
-        The index is cached per session and extended incrementally: when the
-        append-only log has only grown, just the newly appended events are read
-        and tokenized (:meth:`VerbatimIndex.append_chunks`) instead of
-        rebuilding the BM25 index over the whole corpus on every change. The
-        stored cursor is the exact byte offset that was indexed, so concurrent
-        appends during a build never cause missed or duplicated events. A full
-        rebuild only happens on a cold cache or if the log shrank / was
-        rewritten (e.g. compaction).
+        """Return a per-session verbatim index (cached, incrementally extended).
+
+        Delegates to :class:`SessionRetrievalCache`; see its ``verbatim_index``.
         """
-        eventlog = self.session_manager.get(session_id).eventlog
-        signature = _eventlog_file_signature(eventlog)
-        cached = self._verbatim_index_cache.get(session_id)
-        if cached is not None and cached[0] == signature:
-            return cached[1]
-        if cached is not None and signature[1] > cached[2]:
-            new_events, end_offset = eventlog.read_from_offset(cached[2])
-            index = cached[1].append_chunks(_chunks_from_events(new_events))
-            self._verbatim_index_cache[session_id] = (signature, index, end_offset)
-            return index
-        events, end_offset = eventlog.read_from_offset(0)
-        index = VerbatimIndex.from_events(events)
-        self._verbatim_index_cache[session_id] = (signature, index, end_offset)
-        return index
+        return self._retrieval_cache.verbatim_index(session_id)
 
     def _session_event_ref_index(self, session_id: str) -> dict[int, tuple[str, str]]:
         """Return a cached seq -> (hash, type) index for the current log state.
@@ -2419,69 +2399,7 @@ class MemoryFabric:
         log on every call. A full re-verify happens on a cold cache, if the log
         shrank / was rewritten, or if incremental verification detects a break.
         """
-        result = self._cached_full_replay(session_id)
-        if from_seq <= 1:
-            return result
-        filtered = [event for event in result.events if event.seq >= from_seq]
-        return ReplayResult.model_construct(events=filtered, integrity=result.integrity)
-
-    def _cached_full_replay(self, session_id: str) -> ReplayResult:
-        """Return the full verified replay for a session, cached + incremental.
-
-        The cold/full path delegates to ``session_manager.replay`` (the
-        authoritative read + full integrity verify). When the cached log has
-        only grown, the appended tail is read and verified against the cached
-        prefix instead. The tail verification doubles as a consistency guard:
-        any offset skew (a concurrent append during the cold read, a rewrite)
-        surfaces as a seq/hash mismatch and falls back to a full replay, so the
-        fast path can never silently miss, duplicate, or trust a bad event.
-        """
-        eventlog = self.session_manager.get(session_id).eventlog
-        signature = _eventlog_file_signature(eventlog)
-        cached = self._replay_cache.get(session_id)
-        if cached is not None and cached[0] == signature:
-            return cached[1]
-        if (
-            cached is not None
-            and isinstance(cached[2], int)
-            and isinstance(signature[1], int)
-            and signature[1] > cached[2]
-            and cached[1].integrity is not None
-            and cached[1].integrity.ok
-        ):
-            new_events, end_offset = eventlog.read_from_offset(cached[2])
-            extended = self._extend_replay(cached[1], new_events)
-            if extended is not None:
-                self._replay_cache[session_id] = (signature, extended, end_offset)
-                return extended
-        result = cast(ReplayResult, self.session_manager.replay(session_id, from_seq=1))
-        offset = _eventlog_file_signature(eventlog)[1]
-        self._replay_cache[session_id] = (signature, result, offset)
-        return result
-
-    @staticmethod
-    def _extend_replay(cached: ReplayResult, new_events: list[Any]) -> ReplayResult | None:
-        """Extend a verified replay with appended events, or None to rebuild.
-
-        Verifies only the new tail against the cached prefix's last event.
-        Returns ``None`` (signalling a full re-verify) when the tail fails
-        verification, so a tampered or reordered append never silently passes.
-        """
-        if not new_events:
-            return cached
-        last = cached.events[-1] if cached.events else None
-        tail = verify_event_chain(
-            new_events,
-            first_seq=(last.seq + 1) if last is not None else 1,
-            prev_hash=last.hash if last is not None else None,
-        )
-        if not tail.ok:
-            return None
-        combined = [*cached.events, *new_events]
-        return ReplayResult(
-            events=combined,
-            integrity=IntegrityReport(ok=True, total_events=len(combined)),
-        )
+        return self._retrieval_cache.verified_replay(session_id, from_seq)
 
     async def propose_consolidation_candidates(
         self,
@@ -5430,15 +5348,6 @@ def _compaction_projection_paths(
     return tuple(unique.values())
 
 
-def _eventlog_file_signature(eventlog: EventLog) -> tuple[int, int]:
-    """Return a cheap invalidation signature for a local Eventloom log."""
-    try:
-        stat = eventlog.path.stat()
-    except FileNotFoundError:
-        return (0, 0)
-    return (stat.st_mtime_ns, stat.st_size)
-
-
 def _consolidation_candidate_ids(events: list[Any]) -> set[str]:
     candidate_ids: set[str] = set()
     for event in events:

{zaxy_memory-2.4.3 → zaxy_memory-2.4.4}/src/zaxy/mcp_server.py

@@ -93,6 +93,7 @@ from zaxy.purpose import purpose_profile
 from zaxy.query import QueryRouter, build_retention_policy
 from zaxy.refs import MemoryRef, MemoryRefStore
 from zaxy.remote_security import AuditEventExporter, RemoteAuditEvent, SessionRateLimiter
+from zaxy.retrieval_cache import SessionRetrievalCache
 from zaxy.runtime import LocalEmbeddedGraphRuntime, LocalNeo4jRuntime, LocalPgGraphRuntime
 from zaxy.salience import (
     build_confirmed_reinforcement_event,
@@ -1390,6 +1391,14 @@ class ZaxyMCPServer:
         self._checkout_lock = asyncio.Lock()
         self._eventloom_path = eventloom_path or settings.eventloom_path
         self.session_manager = SessionManager(base_path=self._eventloom_path)
+        # Per-session verbatim-index + verified-replay caches, extended
+        # incrementally as the log grows. The checkout front door
+        # (_assemble_context) reads through this instead of rebuilding from the
+        # full log every call, so the 2.4.2 incremental-retrieval win actually
+        # reaches MCP checkout. Lives on the long-lived server so the cache
+        # survives across calls; the _checkout_lock keeps reads/extends
+        # single-flight.
+        self._retrieval_cache = SessionRetrievalCache(self.session_manager)
         self.refs = MemoryRefStore(self._eventloom_path)
         self._neo4j_uri = neo4j_uri or settings.neo4j_uri
         self._neo4j_user = neo4j_user or settings.neo4j_user
@@ -3086,10 +3095,9 @@ class ZaxyMCPServer:
         salience without an extra log scan.
         """
         replay = await asyncio.to_thread(
-            self.session_manager.replay,
+            self._retrieval_cache.verified_replay,
             session_id,
-            from_seq=replay_from_seq,
-            verify_integrity=False,
+            replay_from_seq,
         )
         events = list(replay.events)
         if as_of_seq is not None:
@@ -3105,9 +3113,9 @@ class ZaxyMCPServer:
         graph_contexts = [_context_from_query_result(result) for result in results]
         verbatim_hits = (
             await asyncio.to_thread(
-                lambda: VerbatimIndex.from_event_logs(
-                    [self.session_manager.get(session_id).eventlog]
-                ).query(query, limit=limit)
+                lambda: self._retrieval_cache.verbatim_index(session_id).query(
+                    query, limit=limit
+                )
             )
             if self.context_assembly_policy.should_query_verbatim(limit=limit)
             else []

zaxy_memory-2.4.4/src/zaxy/retrieval_cache.py

@@ -0,0 +1,159 @@
+"""Per-session, incrementally-extended retrieval caches.
+
+Both the verbatim BM25 index and the verified replay scale with the whole log
+if rebuilt from scratch on every read. This module owns the cache state and the
+incremental-extension logic so any long-lived holder (the :class:`MemoryFabric`
+and the MCP server's checkout front door) can share a single, byte-identical
+implementation instead of re-reading and re-hashing the entire log per call.
+
+The two guarantees the callers depend on live here:
+
+- ``verbatim_index`` extends a cached index with only the newly appended events
+  (:meth:`VerbatimIndex.append_chunks`); the result is identical to a full
+  rebuild over the combined corpus.
+- ``verified_replay`` verifies only the appended tail against the cached,
+  already-verified prefix. The tail check doubles as a consistency guard: any
+  offset skew or log rewrite surfaces as a seq/hash mismatch and falls back to a
+  full verified replay, so the fast path never silently misses, duplicates, or
+  trusts a bad event. The hash-chain integrity guarantee is preserved.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from zaxy.event import EventLog, IntegrityReport, ReplayResult, verify_event_chain
+from zaxy.verbatim import VerbatimIndex, _chunks_from_events
+
+if TYPE_CHECKING:
+    from zaxy.session import SessionManager
+
+
+def _eventlog_file_signature(eventlog: EventLog) -> tuple[int, int]:
+    """Return a cheap invalidation signature for a local Eventloom log."""
+    try:
+        stat = eventlog.path.stat()
+    except FileNotFoundError:
+        return (0, 0)
+    return (stat.st_mtime_ns, stat.st_size)
+
+
+class SessionRetrievalCache:
+    """Cache verbatim indexes and verified replays per session, incrementally.
+
+    Holds no projection/graph state: it depends only on a ``SessionManager`` and
+    the append-only Eventloom logs, so it is cheap to instantiate anywhere that
+    needs warm, cited retrieval without standing up a full :class:`MemoryFabric`.
+    """
+
+    def __init__(self, session_manager: SessionManager) -> None:
+        self.session_manager = session_manager
+        self._verbatim_index_cache: dict[str, tuple[tuple[int, int], VerbatimIndex, int]] = {}
+        self._replay_cache: dict[str, tuple[tuple[int, int], ReplayResult, int]] = {}
+
+    def invalidate(self, session_id: str | None = None) -> None:
+        """Drop cached state for one session, or all sessions when ``None``."""
+        if session_id is None:
+            self._verbatim_index_cache = {}
+            self._replay_cache = {}
+            return
+        self._verbatim_index_cache.pop(session_id, None)
+        self._replay_cache.pop(session_id, None)
+
+    def verbatim_index(self, session_id: str) -> VerbatimIndex:
+        """Return a verbatim index for the current Eventloom file state.
+
+        The index is cached per session and extended incrementally: when the
+        append-only log has only grown, just the newly appended events are read
+        and tokenized (:meth:`VerbatimIndex.append_chunks`) instead of
+        rebuilding the BM25 index over the whole corpus on every change. The
+        stored cursor is the exact byte offset that was indexed, so concurrent
+        appends during a build never cause missed or duplicated events. A full
+        rebuild only happens on a cold cache or if the log shrank / was
+        rewritten (e.g. compaction).
+        """
+        eventlog = self.session_manager.get(session_id).eventlog
+        signature = _eventlog_file_signature(eventlog)
+        cached = self._verbatim_index_cache.get(session_id)
+        if cached is not None and cached[0] == signature:
+            return cached[1]
+        if cached is not None and signature[1] > cached[2]:
+            new_events, end_offset = eventlog.read_from_offset(cached[2])
+            index = cached[1].append_chunks(_chunks_from_events(new_events))
+            self._verbatim_index_cache[session_id] = (signature, index, end_offset)
+            return index
+        events, end_offset = eventlog.read_from_offset(0)
+        index = VerbatimIndex.from_events(events)
+        self._verbatim_index_cache[session_id] = (signature, index, end_offset)
+        return index
+
+    def verified_replay(self, session_id: str, from_seq: int = 1) -> ReplayResult:
+        """Return the verified replay for a session, cached + incremental.
+
+        Returns the full replay result including integrity verification, sliced
+        to ``from_seq`` when requested. See module docstring for the integrity
+        guard on the incremental tail path.
+        """
+        result = self._cached_full_replay(session_id)
+        if from_seq <= 1:
+            return result
+        filtered = [event for event in result.events if event.seq >= from_seq]
+        return ReplayResult.model_construct(events=filtered, integrity=result.integrity)
+
+    def _cached_full_replay(self, session_id: str) -> ReplayResult:
+        """Return the full verified replay for a session, cached + incremental.
+
+        The cold/full path delegates to ``session_manager.replay`` (the
+        authoritative read + full integrity verify). When the cached log has
+        only grown, the appended tail is read and verified against the cached
+        prefix instead. The tail verification doubles as a consistency guard:
+        any offset skew (a concurrent append during the cold read, a rewrite)
+        surfaces as a seq/hash mismatch and falls back to a full replay, so the
+        fast path can never silently miss, duplicate, or trust a bad event.
+        """
+        eventlog = self.session_manager.get(session_id).eventlog
+        signature = _eventlog_file_signature(eventlog)
+        cached = self._replay_cache.get(session_id)
+        if cached is not None and cached[0] == signature:
+            return cached[1]
+        if (
+            cached is not None
+            and isinstance(cached[2], int)
+            and isinstance(signature[1], int)
+            and signature[1] > cached[2]
+            and cached[1].integrity is not None
+            and cached[1].integrity.ok
+        ):
+            new_events, end_offset = eventlog.read_from_offset(cached[2])
+            extended = self._extend_replay(cached[1], new_events)
+            if extended is not None:
+                self._replay_cache[session_id] = (signature, extended, end_offset)
+                return extended
+        result = cast(ReplayResult, self.session_manager.replay(session_id, from_seq=1))
+        offset = _eventlog_file_signature(eventlog)[1]
+        self._replay_cache[session_id] = (signature, result, offset)
+        return result
+
+    @staticmethod
+    def _extend_replay(cached: ReplayResult, new_events: list[Any]) -> ReplayResult | None:
+        """Extend a verified replay with appended events, or None to rebuild.
+
+        Verifies only the new tail against the cached prefix's last event.
+        Returns ``None`` (signalling a full re-verify) when the tail fails
+        verification, so a tampered or reordered append never silently passes.
+        """
+        if not new_events:
+            return cached
+        last = cached.events[-1] if cached.events else None
+        tail = verify_event_chain(
+            new_events,
+            first_seq=(last.seq + 1) if last is not None else 1,
+            prev_hash=last.hash if last is not None else None,
+        )
+        if not tail.ok:
+            return None
+        combined = [*cached.events, *new_events]
+        return ReplayResult(
+            events=combined,
+            integrity=IntegrityReport(ok=True, total_events=len(combined)),
+        )

{zaxy_memory-2.4.3 → zaxy_memory-2.4.4}/tests/test_docs_site.py

@@ -102,7 +102,7 @@ def test_public_site_has_product_positioning_and_required_sections() -> None:
     assert "Eventloom source of truth" in html
     assert "Pathlight" in html
     assert "embedded LadybugDB" in html
-    assert "PyPI 2.4.3" in html
+    assert "PyPI 2.4.4" in html
     assert "Harvey LAB 10/10 tasks" in html
     assert "Harvey LAB mean 0.788" in html
     assert "Headline 500 R@5 1.000" in html

{zaxy_memory-2.4.3 → zaxy_memory-2.4.4}/tests/test_mcp.py

@@ -173,6 +173,11 @@ def server() -> ZaxyMCPServer:
         mock_log = MagicMock()
         mock_event = MagicMock(seq=1, hash="a" * 64)
         mock_log.append.return_value = mock_event
+        # The checkout retrieval cache reads through read_from_offset(); return a
+        # well-formed (events, end_offset) tuple so the incremental verbatim/replay
+        # paths unpack cleanly. Replay results are still driven per-test via
+        # session_manager.replay.return_value.
+        mock_log.read_from_offset.return_value = ([], 0)
         mock_session_mgr = MagicMock()
         mock_session_mgr.get.return_value.eventlog = mock_log
         mock_session_cls.return_value = mock_session_mgr
@@ -3291,11 +3296,9 @@ class TestContextLifecycleTools:
 
         output = json_loads(result[0].text)
         assert output["session_id"] == "zaxy-default"
-        server.session_manager.replay.assert_called_with(
-            "zaxy-default",
-            from_seq=1,
-            verify_integrity=False,
-        )
+        # Checkout now reads through the incremental retrieval cache, whose cold
+        # path runs the authoritative verified replay (from_seq=1) and slices.
+        server.session_manager.replay.assert_called_with("zaxy-default", from_seq=1)
 
     async def test_memory_checkout_head_uses_tail_event(
         self,
@@ -3324,11 +3327,39 @@ class TestContextLifecycleTools:
         assert output["ref"]["name"] == "HEAD"
         assert output["ref"]["target_seq"] == 7
         server.session_manager.get.return_value.eventlog.last_event.assert_called_once_with()
-        server.session_manager.replay.assert_called_once_with(
-            "agent-1",
-            from_seq=1,
-            verify_integrity=False,
-        )
+        server.session_manager.replay.assert_called_once_with("agent-1", from_seq=1)
+
+    async def test_memory_checkout_reuses_incremental_retrieval_cache(
+        self,
+        server: ZaxyMCPServer,
+    ) -> None:
+        """Repeat checkouts read through the per-session cache, not a full rebuild.
+
+        Regression guard for the front door wiring: the verified replay and the
+        verbatim index are cached on the long-lived server and reused while the
+        log signature is unchanged, so the 2.4.2 incremental-retrieval win
+        actually reaches MCP checkout instead of rebuilding from the whole log
+        on every call.
+        """
+        server.session_manager.replay.return_value = MagicMock(events=[])
+        eventlog = server.session_manager.get.return_value.eventlog
+        args = {"query": "current state", "session_id": "agent-1", "limit": 5}
+        with (
+            patch("zaxy.mcp_server.QueryRouter") as mock_router_cls,
+            patch("zaxy.mcp_server.record_memory_activity"),
+        ):
+            router = AsyncMock()
+            router.query.return_value = []
+            mock_router_cls.return_value = router
+
+            await server.handle_memory_checkout(dict(args))
+            await server.handle_memory_checkout(dict(args))
+
+        # Cold build on the first checkout populates both caches; the second
+        # checkout hits them (same file signature) without a second verified
+        # replay or a second verbatim read of the log.
+        assert server.session_manager.replay.call_count == 1
+        assert eventlog.read_from_offset.call_count == 1
 
     async def test_context_after_turn_appends_and_assembles(self, server: ZaxyMCPServer) -> None:
         """context_after_turn should persist the latest turn before assembly."""

zaxy_memory-2.4.4/tests/test_retrieval_cache.py

@@ -0,0 +1,80 @@
+"""Unit tests for the shared per-session retrieval cache."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from zaxy.retrieval_cache import SessionRetrievalCache
+from zaxy.session import SessionManager
+from zaxy.verbatim import VerbatimIndex
+
+
+def _append(manager: SessionManager, session_id: str, content: str, turn: int) -> None:
+    manager.get(session_id).eventlog.append(
+        "transcript.turn",
+        actor="assistant",
+        payload={"source": "codex", "turn_index": turn, "role": "assistant", "content": content},
+        thread=session_id,
+    )
+
+
+def test_verbatim_index_reuses_then_extends_byte_identically(tmp_path: Path) -> None:
+    """The index is cached on an unchanged log and extended (not rebuilt) on growth.
+
+    The incrementally-extended index must produce the same ranking as a full
+    rebuild over the combined corpus.
+    """
+    manager = SessionManager(base_path=str(tmp_path / ".eventloom"))
+    cache = SessionRetrievalCache(manager)
+    _append(manager, "agent", "Cached verbatim recall keeps answer assembly fast.", 1)
+
+    first = cache.verbatim_index("agent")
+    # Unchanged log returns the very same cached object, not a rebuild.
+    assert cache.verbatim_index("agent") is first
+
+    _append(manager, "agent", "A new event should extend the cached verbatim index.", 2)
+    extended = cache.verbatim_index("agent")
+    assert extended is not first  # the append was reflected
+
+    events = manager.get("agent").eventlog.read_all()
+    full = VerbatimIndex.from_events(events)
+    query = "extend cached verbatim index"
+    inc_hits = [(h.citation, round(h.score, 9)) for h in extended.query(query, limit=5)]
+    full_hits = [(h.citation, round(h.score, 9)) for h in full.query(query, limit=5)]
+    assert inc_hits == full_hits
+    assert inc_hits  # the new content is retrievable
+
+
+def test_verified_replay_is_cached_and_integrity_holds(tmp_path: Path) -> None:
+    """Verified replay returns a passing integrity report and caches the result."""
+    manager = SessionManager(base_path=str(tmp_path / ".eventloom"))
+    cache = SessionRetrievalCache(manager)
+    _append(manager, "agent", "first", 1)
+    _append(manager, "agent", "second", 2)
+
+    result = cache.verified_replay("agent")
+    assert result.integrity is not None and result.integrity.ok
+    assert [event.seq for event in result.events] == [1, 2]
+    # Unchanged log: same cached result object is returned.
+    assert cache.verified_replay("agent") is result
+
+    # from_seq slices the cached replay without re-reading.
+    sliced = cache.verified_replay("agent", from_seq=2)
+    assert [event.seq for event in sliced.events] == [2]
+
+
+def test_invalidate_forces_a_cold_rebuild(tmp_path: Path) -> None:
+    """invalidate() drops cached state so the next read rebuilds from the log."""
+    manager = SessionManager(base_path=str(tmp_path / ".eventloom"))
+    cache = SessionRetrievalCache(manager)
+    _append(manager, "agent", "only event", 1)
+
+    first = cache.verbatim_index("agent")
+    cache.invalidate("agent")
+    rebuilt = cache.verbatim_index("agent")
+    assert rebuilt is not first
+    # Same corpus -> same ranking after the forced rebuild.
+    query = "only event"
+    assert [h.citation for h in rebuilt.query(query, limit=5)] == [
+        h.citation for h in first.query(query, limit=5)
+    ]