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

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

@@ -2,6 +2,33 @@
 
 All notable Zaxy release changes are recorded here.
 
+## 2.3.2 - 2026-06-13
+
+- Closed the recall persistence gap with deterministic per-turn memory injection
+  on Claude Code. A new `UserPromptSubmit` hook (`zaxy hook-event
+  user-prompt-submit`) re-injects a terse, one-line declarative memory-state
+  nudge — session, staleness, and a recommended `memory_checkout` — into the
+  model's context when memory is stale, and stays silent when fresh to avoid
+  noise. Previously, staleness reminders were written to the event log but never
+  re-injected, so long sessions silently drifted away from memory use.
+- `render_hook_config("claude-code")` now emits the `UserPromptSubmit` hook
+  alongside the unchanged `Stop`/`PreCompact` hooks; `hook_event_type` maps the
+  new `user-prompt-submit` trigger to `hook.user_prompt_submitted`.
+- Per-turn injection is Claude Code-only — Codex/generic clients expose no
+  equivalent per-prompt hook and continue to rely on advisory reminders.
+- No changes to the embedded runtime, graph projection, or MCP tool APIs.
+
+## 2.3.1 - 2026-06-13
+
+- Added a `LICENSE` file (MIT) — the project declared MIT in metadata but
+  shipped no license text; it now ships in the source distribution.
+- Pre-seeded the LadybugDB `vector` extension into the Docker image so
+  containerized approximate (HNSW) search works with no runtime network fetch.
+- Published to the official MCP Registry: added an `mcp-name` ownership marker
+  to the README, a `server.json`, and a GitHub-OIDC `publish-mcp` workflow that
+  registers each release (PulseMCP and other aggregators mirror the registry).
+- No library code changes; the embedded runtime and APIs are identical to 2.3.0.
+
 ## 2.3.0 - 2026-06-13
 
 - Moved the default embedded projection engine from archived Kuzu to

{zaxy_memory-2.3.0 → zaxy_memory-2.3.2}/Dockerfile

@@ -26,6 +26,9 @@ FROM python:3.13-slim
 WORKDIR /app
 
 ENV ZAXY_ENV=production
+# Anchor HOME at the app dir so the LadybugDB extension cache (HOME/.lbdb)
+# lives under the writable, zaxy-owned tree at both build and runtime.
+ENV HOME=/app
 
 # Create non-root user
 RUN groupadd -r zaxy && useradd -r -g zaxy zaxy
@@ -39,7 +42,17 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY --from=builder /build/dist/*.whl /tmp/
 RUN pip install --no-cache-dir /tmp/*.whl && rm /tmp/*.whl
 
-# Create embedded Eventloom/projection directories
+# Pre-seed the LadybugDB `vector` extension into the image cache (HOME/.lbdb).
+# Since 2.3 the embedded engine is LadybugDB, which downloads this extension on
+# first use rather than bundling it; baking it into the image makes approximate
+# (HNSW) vector search work in the container with no runtime network fetch and
+# no writable-HOME surprise under the non-root user. Requires network at build
+# time and fails the build loudly if the extension cannot be fetched — so an
+# image that "builds" is always ANN-ready rather than silently exact-only.
+RUN python -c "import os, tempfile, ladybug; conn = ladybug.Connection(ladybug.Database(os.path.join(tempfile.mkdtemp(), 'seed'))); conn.execute('INSTALL vector'); conn.execute('LOAD vector'); print('LadybugDB vector extension pre-seeded to', os.path.join(os.environ['HOME'], '.lbdb'))"
+
+# Create embedded Eventloom/projection directories and hand the whole app tree
+# (including the pre-seeded HOME/.lbdb cache) to the non-root user.
 RUN mkdir -p /app/.eventloom/projections && \
     chown -R zaxy:zaxy /app
 

zaxy_memory-2.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zaxy Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zaxy-memory
-Version: 2.3.0
+Version: 2.3.2
 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,6 +8,7 @@ Project-URL: Repository, https://github.com/syndicalt/zaxy
 Project-URL: Issues, https://github.com/syndicalt/zaxy/issues
 Author: Zaxy Contributors
 License: MIT
+License-File: LICENSE
 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
@@ -69,6 +70,8 @@ Description-Content-Type: text/markdown
 
 **Production memory for agent teams that need receipts.**
 
+<!-- mcp-name: io.github.syndicalt/zaxy -->
+
 Zaxy turns agent context into an auditable project memory fabric. It captures
 parent missions, worker sessions, tool observations, cited findings, conflict
 review, approval packets, and accepted merge-back into one durable history that

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

@@ -2,6 +2,8 @@
 
 **Production memory for agent teams that need receipts.**
 
+<!-- mcp-name: io.github.syndicalt/zaxy -->
+
 Zaxy turns agent context into an auditable project memory fabric. It captures
 parent missions, worker sessions, tool observations, cited findings, conflict
 review, approval packets, and accepted merge-back into one durable history that

{zaxy_memory-2.3.0 → zaxy_memory-2.3.2}/pyproject.toml

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

{zaxy_memory-2.3.0 → zaxy_memory-2.3.2}/site/README.html

@@ -25,6 +25,7 @@
     <article class="doc-content">
       <h1 id="zaxy">Zaxy</h1>
       <p><strong>Production memory for agent teams that need receipts.</strong></p>
+      <p>&lt;!-- mcp-name: io.github.syndicalt/zaxy --&gt;</p>
       <p>Zaxy turns agent context into an auditable project memory fabric. It captures parent missions, worker sessions, tool observations, cited findings, conflict review, approval packets, and accepted merge-back into one durable history that can be queried, replayed, and inspected.</p>
       <p>Under the hood, Zaxy uses Eventloom append-only JSONL as the source of truth and 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.</p>
       <p>The embedded LadybugDB graph projection is the default local runtime.</p>

{zaxy_memory-2.3.0 → zaxy_memory-2.3.2}/site/index.html

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

{zaxy_memory-2.3.0 → zaxy_memory-2.3.2}/src/zaxy/cli/workspace.py

@@ -563,6 +563,26 @@ def hook_event(
 
     eventlog = SessionManager(base_path=eventloom_path).get(session_id).eventlog
     normalized_trigger = trigger.casefold().strip().replace("_", "-")
+    if normalized_trigger == "user-prompt-submit":
+        # Deterministic recall lever: re-inject terse-prose memory state into the
+        # model's context when memory is stale, and stay silent when fresh. For a
+        # Claude Code UserPromptSubmit hook, stdout is injected into the prompt, so
+        # this branch emits ONLY the structured JSON (no human-readable lines).
+        from zaxy.memory_persistence import build_injection_context
+
+        context = build_injection_context(eventloom_path, session_id=session_id)
+        if context:
+            typer.echo(
+                json.dumps(
+                    {
+                        "hookSpecificOutput": {
+                            "hookEventName": "UserPromptSubmit",
+                            "additionalContext": context,
+                        }
+                    }
+                )
+            )
+        return
     if normalized_trigger == "command":
         if command is None or exit_code is None:
             raise typer.BadParameter("command hooks require --command and --exit-code")

{zaxy_memory-2.3.0 → zaxy_memory-2.3.2}/src/zaxy/hooks.py

@@ -44,6 +44,21 @@ def render_hook_config(
         return json.dumps(
             {
                 "hooks": {
+                    "UserPromptSubmit": [
+                        {
+                            "hooks": [
+                                {
+                                    "type": "command",
+                                    "command": _hook_command(
+                                        "user-prompt-submit",
+                                        eventloom_path=eventloom_path,
+                                        session_id=session_id,
+                                        source=hook_source,
+                                    ),
+                                }
+                            ],
+                        }
+                    ],
                     "Stop": [
                         {
                             "matcher": "*",
@@ -80,6 +95,10 @@ def render_hook_config(
             indent=2,
             sort_keys=True,
         )
+    # NOTE: per-turn recall injection (UserPromptSubmit -> additionalContext) is
+    # Claude Code-only. Codex/generic clients expose no equivalent per-prompt hook,
+    # so they get capture (session-start/resume/stop/precompact) but NOT the
+    # deterministic re-injection lever; on those clients recall stays advisory.
     return "\n".join(
         [
             "# Zaxy observer hook commands",
@@ -149,13 +168,14 @@ def hook_event_type(trigger: str) -> str:
         "precompact": "hook.precompact",
         "checkpoint": "hook.checkpoint",
         "heartbeat": "hook.heartbeat",
+        "user-prompt-submit": "hook.user_prompt_submitted",
     }
     try:
         return event_types[normalized]
     except KeyError as exc:
         raise ValueError(
             "hook trigger must be one of: session-start, resume, session-resumed, "
-            "stop, precompact, checkpoint, heartbeat"
+            "stop, precompact, checkpoint, heartbeat, user-prompt-submit"
         ) from exc
 
 

{zaxy_memory-2.3.0 → zaxy_memory-2.3.2}/src/zaxy/memory_persistence.py

@@ -162,6 +162,41 @@ def build_memory_reminder(payload: dict[str, Any]) -> str:
     return _reminder_prompt(query=query)
 
 
+def build_injection_context(
+    eventloom_path: str | Path,
+    *,
+    session_id: str,
+    stale_event_threshold: int = DEFAULT_STALE_EVENT_THRESHOLD,
+) -> str | None:
+    """Terse-prose declarative memory-state line for per-turn context injection.
+
+    Returns ``None`` when memory is fresh, so a ``UserPromptSubmit`` hook stays
+    silent and adds no noise. When memory is stale, returns a single declarative
+    line naming the session, the staleness, and the recommended action. This is
+    the deterministic *recall* lever: capture hooks already log events, but nothing
+    re-injects the contract into the model's context, so it drifts after long
+    sessions. The terse-prose form (not JSON/glyph) is what the declarative-notation
+    experiment validated -- injection lifts adherence ~0.25 -> 1.0 on frontier
+    models, and structured forms gave no advantage.
+    """
+    sid = validate_session_id(session_id)
+    status = inspect_memory_persistence(
+        eventloom_path, session_id=sid, stale_event_threshold=stale_event_threshold
+    )
+    if not status["stale"]:
+        return None
+    since = status["events_since_memory_use"]
+    last_checkout = status["last_checkout_seq"]
+    checkpoint = (
+        f"last checkout at seq {last_checkout}" if last_checkout else "no checkout yet this session"
+    )
+    return (
+        f"Zaxy memory active for session {sid}: {since} events since last memory use "
+        f"({checkpoint}); memory is stale. Call memory_checkout(session_id='{sid}') before "
+        "answering and trust only cited current facts."
+    )
+
+
 def append_memory_reminder_if_needed(
     eventloom_path: str | Path,
     *,

{zaxy_memory-2.3.0 → zaxy_memory-2.3.2}/tests/test_compose.py

@@ -117,6 +117,22 @@ def test_dockerfile_creates_embedded_projection_directory_without_stale_volumes(
     assert "/app/.volumes" not in dockerfile
 
 
+def test_dockerfile_preseeds_ladybugdb_vector_extension_into_cache() -> None:
+    """The image should bake the LadybugDB vector extension so containerized ANN
+    works without a runtime network fetch (2.3 LadybugDB downloads it on first use)."""
+    dockerfile = Path("Dockerfile").read_text(encoding="utf-8")
+
+    # HOME anchored under the writable app tree so HOME/.lbdb is zaxy-owned.
+    assert "ENV HOME=/app" in dockerfile
+    # Extension pre-seeded at build time...
+    assert "INSTALL vector" in dockerfile
+    assert "LOAD vector" in dockerfile
+    # ...before the chown, so the pre-seeded cache is handed to the non-root user.
+    assert dockerfile.index("INSTALL vector") < dockerfile.index("chown -R zaxy:zaxy /app")
+    # ...and the pre-seed happens after the package (which provides ladybug) installs.
+    assert dockerfile.index("pip install --no-cache-dir /tmp/*.whl") < dockerfile.index("INSTALL vector")
+
+
 def test_sse_transport_host_is_configurable() -> None:
     """Container deployments need the SSE listener host to be explicit."""
     cli = "\n".join(

{zaxy_memory-2.3.0 → zaxy_memory-2.3.2}/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.3.0" in html
+    assert "PyPI 2.3.1" 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.3.2/tests/test_memory_injection.py

@@ -0,0 +1,85 @@
+"""Tests for per-turn memory-state injection (the UserPromptSubmit recall lever)."""
+
+from __future__ import annotations
+
+import json
+
+from typer.testing import CliRunner
+
+from zaxy.__main__ import app
+from zaxy.event import EventLog
+from zaxy.hooks import hook_event_type, render_hook_config
+from zaxy.memory_persistence import build_injection_context, record_memory_activity
+
+runner = CliRunner()
+
+
+def _make_stale(tmp_path):  # type: ignore[no-untyped-def]
+    eventloom = tmp_path / ".eventloom"
+    log = EventLog(eventloom / "agent.jsonl")
+    for index in range(12):
+        log.append("transcript.turn", actor="codex", payload={"content": f"turn {index}"}, thread="agent")
+    return eventloom
+
+
+def _make_fresh(tmp_path):  # type: ignore[no-untyped-def]
+    eventloom = tmp_path / ".eventloom"
+    log = EventLog(eventloom / "agent.jsonl")
+    for index in range(3):
+        log.append("transcript.turn", actor="codex", payload={"content": f"turn {index}"}, thread="agent")
+    record_memory_activity(eventloom, session_id="agent", activity="checkout", source="mcp")
+    return eventloom
+
+
+def test_injection_context_when_stale(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    eventloom = _make_stale(tmp_path)
+    ctx = build_injection_context(eventloom, session_id="agent")
+    assert ctx is not None
+    assert "agent" in ctx
+    assert "memory_checkout" in ctx
+    assert "stale" in ctx
+
+
+def test_injection_silent_when_fresh(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    eventloom = _make_fresh(tmp_path)
+    assert build_injection_context(eventloom, session_id="agent") is None
+
+
+def test_hook_event_type_user_prompt_submit() -> None:
+    assert hook_event_type("user-prompt-submit") == "hook.user_prompt_submitted"
+    assert hook_event_type("user_prompt_submit") == "hook.user_prompt_submitted"
+
+
+def test_render_hook_config_emits_user_prompt_submit() -> None:
+    config = json.loads(render_hook_config("claude-code", eventloom_path=".eventloom", domain="zaxy"))
+    hooks = config["hooks"]
+    # New lever present, existing levers preserved.
+    assert "UserPromptSubmit" in hooks
+    assert "Stop" in hooks and "PreCompact" in hooks
+    cmd = hooks["UserPromptSubmit"][0]["hooks"][0]["command"]
+    assert "hook-event user-prompt-submit" in cmd
+    assert "zaxy-default" in cmd  # canonical session derived from domain
+
+
+def test_cli_emits_additional_context_when_stale(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    eventloom = _make_stale(tmp_path)
+    result = runner.invoke(
+        app,
+        ["hook-event", "user-prompt-submit", "--eventloom-path", str(eventloom),
+         "--session-id", "agent", "--source", "claude-code"],
+    )
+    assert result.exit_code == 0
+    payload = json.loads(result.stdout.strip())
+    assert payload["hookSpecificOutput"]["hookEventName"] == "UserPromptSubmit"
+    assert "memory_checkout" in payload["hookSpecificOutput"]["additionalContext"]
+
+
+def test_cli_silent_when_fresh(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    eventloom = _make_fresh(tmp_path)
+    result = runner.invoke(
+        app,
+        ["hook-event", "user-prompt-submit", "--eventloom-path", str(eventloom),
+         "--session-id", "agent", "--source", "claude-code"],
+    )
+    assert result.exit_code == 0
+    assert result.stdout.strip() == ""