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

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

@@ -2,6 +2,37 @@
 
 All notable Zaxy release changes are recorded here.
 
+## 2.3.3 - 2026-06-13
+
+- Extended deterministic per-turn memory injection to **Codex**. Codex now ships
+  Claude-parity hooks, so its `UserPromptSubmit` event accepts the same
+  `additionalContext` schema. `render_hook_config("codex")` now emits a real
+  `hooks.json` carrying the `UserPromptSubmit` injection hook (plus
+  `SessionStart`/`Stop`/`PreCompact` lifecycle capture), for `.codex/hooks.json`
+  or a `[hooks]` table in `config.toml`. Install with
+  `zaxy hooks codex -o ~/.codex/hooks.json`.
+- Corrects the 2.3.2 note that per-turn injection was Claude Code-only: it now
+  works on Claude Code **and** Codex; only truly generic clients (with no
+  pre-prompt hook that re-injects output) remain advisory.
+- No runtime change — the `zaxy hook-event user-prompt-submit` CLI already
+  emitted the exact JSON both clients consume; this un-gates rendering/install.
+
+## 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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zaxy-memory
-Version: 2.3.1
+Version: 2.3.3
 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.3}/pyproject.toml

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

{zaxy_memory-2.3.1 → zaxy_memory-2.3.3}/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.3}/src/zaxy/hooks.py

@@ -28,6 +28,39 @@ HIGH_VALUE_OBSERVATION_TYPES = (
 )
 
 
+def _command_hook_config(
+    events: list[tuple[str, str, str | None]],
+    *,
+    eventloom_path: str,
+    session_id: str,
+    source: str,
+) -> str:
+    """Render a Claude-Code/Codex-style hooks JSON for the given (event, trigger, matcher) set.
+
+    Both Claude Code and Codex consume the same `{"hooks": {Event: [{"hooks": [...]}]}}`
+    schema, including `UserPromptSubmit` with `additionalContext` injection.
+    """
+    hooks: dict[str, Any] = {}
+    for event_name, trigger, matcher in events:
+        group: dict[str, Any] = {
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": _hook_command(
+                        trigger,
+                        eventloom_path=eventloom_path,
+                        session_id=session_id,
+                        source=source,
+                    ),
+                }
+            ]
+        }
+        if matcher is not None:
+            group["matcher"] = matcher
+        hooks[event_name] = [group]
+    return json.dumps({"hooks": hooks}, indent=2, sort_keys=True)
+
+
 def render_hook_config(
     client: HookClient | str,
     *,
@@ -41,45 +74,36 @@ def render_hook_config(
     session_id = domain_default_session(resolved_domain)
     hook_source = source or normalized
     if normalized == "claude-code":
-        return json.dumps(
-            {
-                "hooks": {
-                    "Stop": [
-                        {
-                            "matcher": "*",
-                            "hooks": [
-                                {
-                                    "type": "command",
-                                    "command": _hook_command(
-                                        "stop",
-                                        eventloom_path=eventloom_path,
-                                        session_id=session_id,
-                                        source=hook_source,
-                                    ),
-                                }
-                            ],
-                        }
-                    ],
-                    "PreCompact": [
-                        {
-                            "hooks": [
-                                {
-                                    "type": "command",
-                                    "command": _hook_command(
-                                        "precompact",
-                                        eventloom_path=eventloom_path,
-                                        session_id=session_id,
-                                        source=hook_source,
-                                    ),
-                                }
-                            ],
-                        }
-                    ],
-                }
-            },
-            indent=2,
-            sort_keys=True,
+        return _command_hook_config(
+            [
+                ("UserPromptSubmit", "user-prompt-submit", None),
+                ("Stop", "stop", "*"),
+                ("PreCompact", "precompact", None),
+            ],
+            eventloom_path=eventloom_path,
+            session_id=session_id,
+            source=hook_source,
+        )
+    if normalized == "codex":
+        # Codex ships Claude-parity hooks: its UserPromptSubmit accepts the same
+        # additionalContext schema, so the deterministic per-turn recall injection
+        # works here too. Config lives in .codex/hooks.json or a [hooks] table in
+        # config.toml. SessionStart/Stop/PreCompact add lifecycle capture boundaries.
+        return _command_hook_config(
+            [
+                ("UserPromptSubmit", "user-prompt-submit", None),
+                ("SessionStart", "session-start", None),
+                ("Stop", "stop", None),
+                ("PreCompact", "precompact", None),
+            ],
+            eventloom_path=eventloom_path,
+            session_id=session_id,
+            source=hook_source,
         )
+    # NOTE: per-turn recall injection (UserPromptSubmit -> additionalContext) needs a
+    # client that fires a pre-prompt hook and re-injects the hook's output -- Claude
+    # Code and Codex both do. Truly generic clients expose no such hook, so they get
+    # capture commands only and recall stays advisory there.
     return "\n".join(
         [
             "# Zaxy observer hook commands",
@@ -149,13 +173,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.3}/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.3/tests/test_memory_injection.py

@@ -0,0 +1,103 @@
+"""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
+    # UserPromptSubmit takes no matcher.
+    assert "matcher" not in hooks["UserPromptSubmit"][0]
+
+
+def test_render_hook_config_emits_user_prompt_submit_for_codex() -> None:
+    # Codex ships Claude-parity hooks with the same additionalContext schema, so the
+    # injection lever must render for Codex too (config -> .codex/hooks.json).
+    config = json.loads(render_hook_config("codex", eventloom_path=".eventloom", domain="zaxy"))
+    hooks = config["hooks"]
+    assert "UserPromptSubmit" in hooks
+    cmd = hooks["UserPromptSubmit"][0]["hooks"][0]["command"]
+    assert "hook-event user-prompt-submit" in cmd
+    assert "--source codex" in cmd
+    assert "zaxy-default" in cmd
+    # Codex omits matcher for non-tool events.
+    assert "matcher" not in hooks["UserPromptSubmit"][0]
+    # Lifecycle capture boundaries also present.
+    assert {"SessionStart", "Stop", "PreCompact"} <= set(hooks)
+
+
+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() == ""