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

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

@@ -2,6 +2,22 @@
 
 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

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

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

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

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

{zaxy_memory-2.3.1 → 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.1 → 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.1 → 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.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() == ""