Retention Metadata Extraction Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [x]) syntax for tracking.

Goal: Project retention metadata and reinforcement events into graph entities so existing decay-aware retrieval policies have useful signals.

Architecture: Add a small extractor helper for safe retention fields, apply it to high-value built-in memory entities and fallback events, and add a typed memory.reinforced extractor. Retrieval logic remains unchanged and consumes the projected properties it already understands.

Tech Stack: Python 3.11, pytest, ruff, mypy.

---

Task 1: Extractor Tests

Files:

Modify: tests/test_extract.py

[x] Add failing coverage for retention metadata on fallback events.
[x] Add failing coverage for retention metadata on task.completed.
[x] Add failing coverage for memory.reinforced.
[x] Run focused tests and confirm they fail before implementation.

Task 2: Extractor Implementation

Files:

Modify: src/zaxy/extract.py

[x] Add _retention_properties() for expires_at, importance, last_reinforced_at, and reinforcement_count.
[x] Add _merge_properties() for existing extractor property maps.
[x] Project retention metadata on fallback events and selected memory entities.
[x] Add memory.reinforced projection with last_reinforced_at and reinforcement_count.
[x] Run focused tests and confirm they pass.

Task 3: Docs And Roadmap

Files:

Modify: docs/agent-events.md
Modify: docs/retrieval.md
Modify: AGENTS.md

[x] Document retention metadata projection and memory.reinforced.
[x] Mark roadmap item complete and update metrics after verification.
[x] Run docs validation.

Task 4: Full Verification And Commit

Files:

All changed files.

[x] Run ruff check src tests.
[x] Run mypy src.
[x] Run pytest -m "not integration" --benchmark-disable --no-cov -q.
[x] Commit with feat: project retention metadata from agent events.